feat(customers): a shelf folder number the office can hand back out

The office files every customer in a numbered paper folder and reuses the
number once an account closes. That number was the legacy NUMid, which is
also an import key and the portal login, so reusing it meant re-pointing an
identity. It is now customers.folderNumber: a plain label nothing joins on.

- Unique only among non-archived customers, checked in CustomersService
  (create, update, restore). Archived customers keep theirs as history.
- GET /customers/folder/next suggests the lowest free number; the new
  customer form pre-fills it.
- Backfilled from the utilities NUMid (dev: 1,171 folders, 0 shared); the
  importer copies it on load. Insurance-only customers start without one.
- Reports, the printed statement and the customer file show "Carpeta"
  instead of NUMid. The list searches by it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

apps/api/src/customers/create-customer.dto.ts

@@ -2,9 +2,11 @@ import {
   IsBoolean,
   IsEmail,
   IsEnum,
+  IsInt,
   IsNumber,
   IsOptional,
   IsString,
+  Min,
   MinLength,
 } from "class-validator";
 import { Currency } from "@jorgecuadros/database";
@@ -19,6 +21,8 @@ export class CreateCustomerDto {
   @MinLength(1)
   name!: string;
 
+  /** Shelf folder number; null clears it. Unique among non-archived customers. */
+  @IsOptional() @IsInt() @Min(1) folderNumber?: number | null;
   @IsOptional() @IsString() addressLine1?: string;
   @IsOptional() @IsString() addressLine2?: string;
   @IsOptional() @IsString() city?: string;

apps/api/src/customers/customer-folder.spec.ts

@@ -0,0 +1,71 @@
+import { ConflictException } from "@nestjs/common";
+import { CustomersService } from "./customers.service";
+
+/**
+ * A folder number belongs to one open account at a time, and an archived
+ * customer's number is history, not a claim. The nextFolderNumber SQL is
+ * checked against real data, not here.
+ */
+
+function build(opts: { holder?: { name: string } | null; archived?: boolean; folder?: number | null }) {
+  const prisma = {
+    customer: {
+      findFirst: jest.fn().mockResolvedValue(opts.holder ?? null),
+      findUnique: jest.fn().mockResolvedValue({
+        id: "c1",
+        archivedAt: opts.archived ? new Date() : null,
+        folderNumber: opts.folder ?? null,
+      }),
+      create: jest.fn().mockImplementation(({ data }) => Promise.resolve(data)),
+      update: jest.fn().mockImplementation(({ data }) => Promise.resolve(data)),
+    },
+  };
+  return { service: new CustomersService(prisma as never), prisma };
+}
+
+describe("customer folder numbers", () => {
+  it("refuses a number an open account already holds", async () => {
+    const { service, prisma } = build({ holder: { name: "SWEET, DONALD E." } });
+
+    await expect(service.create({ name: "Nuevo", folderNumber: 214 })).rejects.toThrow(
+      new ConflictException("La carpeta 214 ya la tiene SWEET, DONALD E."),
+    );
+    expect(prisma.customer.create).not.toHaveBeenCalled();
+    // Only open accounts count as holders.
+    expect(prisma.customer.findFirst.mock.calls[0][0].where).toMatchObject({
+      folderNumber: 214,
+      archivedAt: null,
+    });
+  });
+
+  it("does not count the customer being edited as the holder", async () => {
+    const { service, prisma } = build({});
+
+    await service.update("c1", { folderNumber: 214 });
+    expect(prisma.customer.findFirst.mock.calls[0][0].where).toMatchObject({
+      id: { not: "c1" },
+    });
+  });
+
+  it("lets an archived customer keep a number someone else now holds", async () => {
+    const { service, prisma } = build({ archived: true, holder: { name: "X" } });
+
+    await expect(service.update("c1", { folderNumber: 214 })).resolves.toBeDefined();
+    expect(prisma.customer.findFirst).not.toHaveBeenCalled();
+  });
+
+  it("will not reopen an account whose folder was handed out meanwhile", async () => {
+    const { service, prisma } = build({ archived: true, folder: 214, holder: { name: "X" } });
+
+    await expect(service.restore("c1")).rejects.toBeInstanceOf(ConflictException);
+    expect(prisma.customer.update).not.toHaveBeenCalled();
+  });
+
+  it("skips the check when no number is given", async () => {
+    const { service, prisma } = build({ holder: { name: "X" } });
+
+    await service.create({ name: "Nuevo" });
+    await service.update("c1", { folderNumber: null });
+    expect(prisma.customer.findFirst).not.toHaveBeenCalled();
+  });
+});

apps/api/src/customers/customers.controller.ts

@@ -45,6 +45,12 @@ export class CustomersController {
     return { candidates: await this.numids.emptyCandidates() };
   }
 
+  /** Suggested folder number for a new customer. Above `:id` like the rest. */
+  @Get("folder/next")
+  async nextFolder() {
+    return { folderNumber: await this.customers.nextFolderNumber() };
+  }
+
   @Get()
   list(
     @Query("query") query?: string,

apps/api/src/customers/customers.service.ts

@@ -1,4 +1,4 @@
-import { Injectable, NotFoundException } from "@nestjs/common";
+import { ConflictException, Injectable, NotFoundException } from "@nestjs/common";
 import { Prisma } from "@jorgecuadros/database";
 import { PrismaService } from "../prisma/prisma.service";
 import { CreateCustomerDto } from "./create-customer.dto";
@@ -68,6 +68,7 @@ export class CustomersService {
         { mobile: { contains: q } },
         { city: { contains: q } },
         { legacyRefs: { some: { legacyId: { contains: q } } } },
+        ...(/^\d+$/.test(q) ? [{ folderNumber: Number(q) }] : []),
       ];
     }
     if (line === "utility") where.properties = { some: {} };
@@ -90,6 +91,7 @@ export class CustomersService {
           id: true,
           name: true,
           nameSource: true,
+          folderNumber: true,
           city: true,
           state: true,
           email: true,
@@ -106,6 +108,7 @@ export class CustomersService {
       id: r.id,
       name: r.name,
       nameSource: r.nameSource,
+      folderNumber: r.folderNumber,
       city: r.city,
       state: r.state,
       email: r.email,
@@ -248,6 +251,7 @@ export class CustomersService {
   }
 
   async create(dto: CreateCustomerDto) {
+    await this.assertFolderFree(dto.folderNumber);
     return this.prisma.customer.create({
       // App-created rows: nameMissing false (name is required), no legacy
       // provenance — those columns stay null, marking a native record.
@@ -256,7 +260,9 @@ export class CustomersService {
   }
 
   async update(id: string, dto: UpdateCustomerDto) {
-    await this.ensureExists(id);
+    const current = await this.ensureExists(id);
+    // An archived customer's number is history, not a claim on the shelf.
+    if (!current.archivedAt) await this.assertFolderFree(dto.folderNumber, id);
     return this.prisma.customer.update({ where: { id }, data: this.toData(dto) });
   }
 
@@ -270,7 +276,9 @@ export class CustomersService {
   }
 
   async restore(id: string) {
-    await this.ensureExists(id);
+    const current = await this.ensureExists(id);
+    // Its folder may have been handed to someone else while it was closed.
+    await this.assertFolderFree(current.folderNumber, id);
     return this.prisma.customer.update({
       where: { id },
       data: { archivedAt: null },
@@ -280,9 +288,46 @@ export class CustomersService {
   private async ensureExists(id: string) {
     const found = await this.prisma.customer.findUnique({
       where: { id },
-      select: { id: true },
+      select: { id: true, archivedAt: true, folderNumber: true },
     });
     if (!found) throw new NotFoundException(`Customer ${id} not found`);
+    return found;
+  }
+
+  // --- folder numbers ---------------------------------------------------------
+
+  /**
+   * A folder number belongs to one open account at a time. Archived customers
+   * keep theirs as a record of which folder they used, without holding it.
+   *
+   * ponytail: check-then-write, not a constraint — two staff saving the same
+   * number in the same instant both win. A functional unique index on
+   * IF(archivedAt IS NULL, folderNumber, NULL) closes it, if Prisma ever models one.
+   */
+  private async assertFolderFree(folderNumber: number | null | undefined, exceptId?: string) {
+    if (folderNumber == null) return;
+    const holder = await this.prisma.customer.findFirst({
+      where: { folderNumber, archivedAt: null, ...(exceptId ? { id: { not: exceptId } } : {}) },
+      select: { name: true },
+    });
+    if (holder) {
+      throw new ConflictException(`La carpeta ${folderNumber} ya la tiene ${holder.name}`);
+    }
+  }
+
+  /** Lowest folder number no open account holds — how the office reuses them. */
+  async nextFolderNumber(): Promise<number> {
+    const [row] = await this.prisma.$queryRaw<{ n: bigint | number }[]>`
+      SELECT MIN(c.n) AS n FROM (
+        SELECT 1 AS n
+        UNION SELECT folderNumber + 1 FROM customers
+        WHERE archivedAt IS NULL AND folderNumber IS NOT NULL
+      ) c
+      WHERE c.n NOT IN (
+        SELECT folderNumber FROM customers
+        WHERE archivedAt IS NULL AND folderNumber IS NOT NULL
+      )`;
+    return Number(row.n);
   }
 
   /** Top-line counts for a dashboard header. */

apps/api/src/customers/update-customer.dto.ts

@@ -2,9 +2,11 @@ import {
   IsBoolean,
   IsEmail,
   IsEnum,
+  IsInt,
   IsNumber,
   IsOptional,
   IsString,
+  Min,
   MinLength,
 } from "class-validator";
 import { Currency } from "@jorgecuadros/database";
@@ -12,6 +14,7 @@ import { Currency } from "@jorgecuadros/database";
 /** Same editable fields as create, all optional. */
 export class UpdateCustomerDto {
   @IsOptional() @IsString() @MinLength(1) name?: string;
+  @IsOptional() @IsInt() @Min(1) folderNumber?: number | null;
   @IsOptional() @IsString() addressLine1?: string;
   @IsOptional() @IsString() addressLine2?: string;
   @IsOptional() @IsString() city?: string;

apps/api/src/reports/reports.registry.ts

@@ -23,10 +23,7 @@ import {
   notCashJournal,
   periodSourceTable,
 } from "../billing/billing.service";
-import {
-  UTILITIES_SYSTEM,
-  UTILITIES_TABLE,
-} from "../customers/numid.service";
+import { UTILITIES_TABLE } from "../customers/numid.service";
 import type { PrismaService } from "../prisma/prisma.service";
 import { CONCEPT_BY_KIND } from "../statements/statements.service";
 import {
@@ -50,8 +47,8 @@ function nameOf(c: { name: string; nameMissing: boolean }): string {
 const isoDay = (d: Date | null | undefined) =>
   d ? d.toISOString().slice(0, 10) : "—";
 
-/** Every report leads with the legacy customer number (2026-10 meeting). */
-const NUMID_COLUMN: ColumnDef = { key: "numid", label: "NUMid", type: "text" };
+/** Every report leads with the customer's shelf folder number (2026-10 meeting). */
+const FOLDER_COLUMN: ColumnDef = { key: "folder", label: "Carpeta", type: "text" };
 /** Policy reports add the insurance file number beside it. */
 const INSURANCE_NO_COLUMN: ColumnDef = {
   key: "insuranceNo",
@@ -60,38 +57,42 @@ const INSURANCE_NO_COLUMN: ColumnDef = {
 };
 
 /**
- * Legacy customer numbers for a page of report rows. The office files,
- * captures and talks in NUMids, not platform ids.
+ * Customer numbers for a page of report rows. The office files, captures and
+ * talks in folder numbers, not platform ids.
  *
- * The utilities NUMid is the portal number, one per customer. insurance/DATGRAL
- * is a separate id space under the same table name, so it is read on its own
- * and never shown as a NUMid; 16 customers hold more than one.
+ * The insurance file number is the legacy insurance/DATGRAL id, a separate id
+ * space under the same table name as the utilities NUMid; 16 customers hold
+ * more than one.
  */
 async function legacyNumbers(prisma: PrismaService, customerIds: string[]) {
   const ids = [...new Set(customerIds)];
-  const refs = ids.length
-    ? await prisma.customerLegacyRef.findMany({
-        where: {
-          customerId: { in: ids },
-          sourceTable: UTILITIES_TABLE,
-          sourceSystem: { in: [UTILITIES_SYSTEM, "insurance"] },
-        },
-        select: { customerId: true, sourceSystem: true, legacyId: true },
-      })
-    : [];
-  const byCustomer = new Map<string, { numid?: string; insurance: string[] }>();
+  const [customers, refs] = ids.length
+    ? await Promise.all([
+        prisma.customer.findMany({
+          where: { id: { in: ids } },
+          select: { id: true, folderNumber: true },
+        }),
+        prisma.customerLegacyRef.findMany({
+          where: {
+            customerId: { in: ids },
+            sourceTable: UTILITIES_TABLE,
+            sourceSystem: "insurance",
+          },
+          select: { customerId: true, legacyId: true },
+        }),
+      ])
+    : [[], []];
+  const folders = new Map(customers.map((c) => [c.id, c.folderNumber]));
+  const insurance = new Map<string, string[]>();
   for (const r of refs) {
-    const e = byCustomer.get(r.customerId) ?? { insurance: [] };
-    if (r.sourceSystem === UTILITIES_SYSTEM) e.numid = r.legacyId;
-    else e.insurance.push(r.legacyId);
-    byCustomer.set(r.customerId, e);
+    insurance.set(r.customerId, [...(insurance.get(r.customerId) ?? []), r.legacyId]);
   }
   return {
-    numid: (id: string) => byCustomer.get(id)?.numid ?? "—",
+    folder: (id: string) => String(folders.get(id) ?? "—"),
     insurance: (id: string) =>
-      byCustomer
+      insurance
         .get(id)
-        ?.insurance.sort((a, b) => Number(a) - Number(b))
+        ?.sort((a, b) => Number(a) - Number(b))
         .join(", ") || "—",
   };
 }
@@ -182,7 +183,7 @@ const listadoEnRojo: ReportDef = {
     },
   ],
   columns: [
-    NUMID_COLUMN,
+    FOLDER_COLUMN,
     { key: "name", label: "Cliente", type: "text" },
     { key: "city", label: "Ciudad", type: "text" },
     { key: "lastMovement", label: "Último movimiento", type: "date" },
@@ -258,7 +259,7 @@ const listadoEnRojo: ReportDef = {
       const b = r.balance ?? new Prisma.Decimal(0);
       totalBalance = totalBalance.plus(b);
       return {
-        numid: nums.numid(r.id),
+        folder: nums.folder(r.id),
         name: nameOf(r),
         city: r.city ?? "—",
         lastMovement: isoDay(r.lastMovement),
@@ -348,7 +349,7 @@ const pagosNoEfectuados: ReportDef = {
     },
   ],
   columns: [
-    NUMID_COLUMN,
+    FOLDER_COLUMN,
     { key: "customerName", label: "Cliente", type: "text" },
     { key: "propertyAddress", label: "Dirección", type: "text" },
     { key: "accountNumber", label: "Cuenta", type: "text" },
@@ -418,7 +419,7 @@ const pagosNoEfectuados: ReportDef = {
     const out = rows.map((r) => {
       if (Number(r.unfunded)) unfunded++;
       return {
-        numid: nums.numid(r.customerId),
+        folder: nums.folder(r.customerId),
         customerName: nameOf({ name: r.customerName, nameMissing: r.nameMissing }),
         propertyAddress: r.addresses ?? "—",
         accountNumber: r.accounts ?? "—",
@@ -481,7 +482,7 @@ const faltantes: ReportDef = {
     },
   ],
   columns: [
-    NUMID_COLUMN,
+    FOLDER_COLUMN,
     { key: "customerName", label: "Cliente", type: "text" },
     { key: "propertyAddress", label: "Dirección", type: "text" },
     { key: "missing", label: "Faltante", type: "text" },
@@ -525,7 +526,7 @@ const faltantes: ReportDef = {
 
     const nums = await legacyNumbers(prisma, rows.map((r) => r.customerId));
     const out = rows.map((r) => ({
-      numid: nums.numid(r.customerId),
+      folder: nums.folder(r.customerId),
       customerName: nameOf({ name: r.customerName, nameMissing: r.nameMissing }),
       propertyAddress: r.propertyAddress ?? "—",
       missing: r.missing,
@@ -571,7 +572,7 @@ const reporteDeEfectivo: ReportDef = {
   ],
   columns: [
     { key: "date", label: "Fecha", type: "date" },
-    NUMID_COLUMN,
+    FOLDER_COLUMN,
     { key: "customerName", label: "Cliente", type: "text" },
     { key: "concept", label: "Concepto", type: "text" },
     { key: "source", label: "Origen", type: "text" },
@@ -630,7 +631,7 @@ const reporteDeEfectivo: ReportDef = {
       total = total.plus(r.amount);
       return {
         date: r.transactionDate.toISOString().slice(0, 10),
-        numid: nums.numid(r.customer.id),
+        folder: nums.folder(r.customer.id),
         customerName: nameOf(r.customer),
         concept: r.message ?? r.type?.nameEs ?? r.type?.nameEn ?? "—",
         source: r.legacySourceTable ?? "—",
@@ -695,7 +696,7 @@ const vigente: ReportDef = {
   ],
   columns: [
     { key: "policyNumber", label: "Póliza", type: "text" },
-    NUMID_COLUMN,
+    FOLDER_COLUMN,
     INSURANCE_NO_COLUMN,
     { key: "customerName", label: "Cliente", type: "text" },
     { key: "provider", label: "Aseguradora", type: "text" },
@@ -743,7 +744,7 @@ const vigente: ReportDef = {
       if (r.netPremium) totalPremium = totalPremium.plus(r.netPremium);
       return {
         policyNumber: r.policyNumber,
-        numid: nums.numid(r.customer.id),
+        folder: nums.folder(r.customer.id),
         insuranceNo: nums.insurance(r.customer.id),
         customerName: nameOf(r.customer),
         provider: r.insuranceProvider?.name ?? "—",
@@ -848,7 +849,7 @@ const avisoRenovacion: ReportDef = {
   // ReportRunner.tsx) — same trade-off edoCuentaDatos makes for "statement".
   columns: [
     { key: "policyNumber", label: "Póliza", type: "text" },
-    NUMID_COLUMN,
+    FOLDER_COLUMN,
     INSURANCE_NO_COLUMN,
     { key: "customerName", label: "Cliente", type: "text" },
     { key: "provider", label: "Aseguradora", type: "text" },
@@ -888,7 +889,7 @@ const avisoRenovacion: ReportDef = {
       if (r.netPremium) totalPremium = totalPremium.plus(r.netPremium);
       const letter = {
         ...toRenewalLetterRow(r, generation),
-        numid: nums.numid(r.customer.id),
+        folder: nums.folder(r.customer.id),
         insuranceNo: nums.insurance(r.customer.id),
       };
       if (letter.sentAt) sentCount++;
@@ -968,7 +969,7 @@ const edoCuentaDatos: ReportDef = {
       },
     });
     if (!customer) return { rows: [], subtitle: "Cliente no encontrado" };
-    const numid = (await legacyNumbers(prisma, [customer.id])).numid(customer.id);
+    const folder = (await legacyNumbers(prisma, [customer.id])).folder(customer.id);
 
     // The source-table exclusion, the balance floor and the year scope below
     // are BillingService.statement's, because this report and
@@ -1133,7 +1134,7 @@ const edoCuentaDatos: ReportDef = {
         {
           __kind: "header",
           name: nameOf(customer),
-          numid,
+          folder,
           address: customer.addressLine1 ?? "",
           city: [customer.city, customer.state].filter(Boolean).join(", "),
           phone: customer.phone ?? "",
@@ -1151,7 +1152,7 @@ const edoCuentaDatos: ReportDef = {
         ...carried,
         ...movements,
       ],
-      subtitle: `NUMid ${numid} · ${nameOf(customer)} · ${year} · ${visible.length} movimientos`,
+      subtitle: `Carpeta ${folder} · ${nameOf(customer)} · ${year} · ${visible.length} movimientos`,
     };
   },
 };
@@ -1189,7 +1190,7 @@ const chequeCount: ReportDef = {
     },
   ],
   columns: [
-    NUMID_COLUMN,
+    FOLDER_COLUMN,
     { key: "customerName", label: "Cliente", type: "text" },
     { key: "reference", label: "Referencia", type: "text" },
     { key: "period", label: "Periodo", type: "text" },
@@ -1248,7 +1249,7 @@ const chequeCount: ReportDef = {
     const nums = await legacyNumbers(prisma, rows.map((r) => r.customer.id));
     return {
       rows: rows.map((r) => ({
-        numid: nums.numid(r.customer.id),
+        folder: nums.folder(r.customer.id),
         customerName: nameOf(r.customer),
         reference: r.reference ?? "—",
         period: r.period ?? "—",