# Per-document custom-field print selection — Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Let each offer, issued order, and invoice choose — on its detail page — which company custom fields print in its PDF sender block; default none selected. **Architecture:** A new nullable `selected_custom_fields` column (JSON-array-in-VARCHAR) on `quotations`, `issued_orders`, `invoices`. A shared backend util encodes/decodes the index array. Create/update services persist it; detail services decode it to `number[]`. The PDF `buildAddressLines()` company-block builder gains an optional selected-indices filter. A shared React picker reused by the three detail pages drives the selection. **Tech Stack:** Prisma 7 / MySQL, Fastify 5, Zod 4, Vitest (real `app_test` DB), React 19 + MUI v7 + React Query. **Spec:** `docs/superpowers/specs/2026-06-16-per-document-custom-field-selection-design.md` --- ## Conventions for this plan - This shell is non-interactive — `prisma migrate dev` is forbidden. Use the `migrate diff` recipe (Task 1). - **Before the migration, ask the user to stop their dev server and wait for confirmation** (it holds DB connections). Do not run the migration until they confirm. - Server tests run against `app_test` via `.env.test` (`npm test`). Apply the migration to `app_test` too or the suite breaks. - `npm run typecheck` = `tsc -b --noEmit`. `npm run lint` must stay at 0 errors. - Selection semantics in `buildAddressLines`: param **omitted/`undefined`** ⇒ show ALL custom fields (unchanged behavior — used for customer/supplier blocks). Param is an **array** (possibly empty) ⇒ show ONLY those indices (used for the company/sender block; empty ⇒ none). --- ## File Structure - **Modify** `prisma/schema.prisma` — add `selected_custom_fields String?` to `quotations`, `issued_orders`, `invoices`. - **Create** `prisma/migrations/_add_selected_custom_fields/migration.sql`. - **Modify** `src/utils/custom-fields.ts` — add `encodeSelectedCustomFields` / `parseSelectedCustomFields`. - **Create** `src/__tests__/selected-custom-fields.test.ts` — util + integration coverage. - **Modify** `src/schemas/offers.schema.ts`, `issued-orders.schema.ts`, `invoices.schema.ts` — new optional array field. - **Modify** `src/services/offers.service.ts`, `issued-orders.service.ts`, `invoices.service.ts` — persist on create/update, decode in detail. - **Modify** `src/routes/admin/offers-pdf.ts`, `issued-orders-pdf.ts`, `invoices-pdf.ts` — filter company custom lines. - **Modify** `src/admin/lib/queries/offers.ts`, `issued-orders.ts`, `invoices.ts` — add `selected_custom_fields: number[]` to detail interfaces. - **Create** `src/admin/components/document/CustomFieldsPrintPicker.tsx` — shared picker. - **Modify** `src/admin/pages/OfferDetail.tsx`, `IssuedOrderDetail.tsx`, `InvoiceDetail.tsx` — render picker, wire into save payload. --- ## Task 1: Schema column + migration **Files:** - Modify: `prisma/schema.prisma` (models `quotations`, `issued_orders`, `invoices`) - Create: `prisma/migrations/_add_selected_custom_fields/migration.sql` - [ ] **Step 1: Ask the user to stop their dev server** Post: "Please stop your dev server so I can apply a migration, and tell me when it's stopped." Wait for confirmation before any later `migrate deploy` step. - [ ] **Step 2: Add the column to each model in `prisma/schema.prisma`** Add this line to the `quotations` model (near other scalar columns, e.g. after `language`): ```prisma selected_custom_fields String? @db.VarChar(255) ``` Add the identical line to the `issued_orders` model and to the `invoices` model. - [ ] **Step 3: Generate the migration SQL** Run (Git Bash): ```bash cd /d/cortex/boha-app-ts TS=$(date +%Y%m%d%H%M%S) mkdir -p "prisma/migrations/${TS}_add_selected_custom_fields" npx prisma migrate diff --from-config-datasource --to-schema prisma/schema.prisma --script \ > "prisma/migrations/${TS}_add_selected_custom_fields/migration.sql" ``` Expected: a `migration.sql` containing three `ALTER TABLE … ADD COLUMN selected_custom_fields VARCHAR(255) NULL` statements (one per table). Open it and confirm it touches ONLY `quotations`, `issued_orders`, `invoices` and adds nothing else (no BOM — if it was written via PowerShell, strip the BOM). - [ ] **Step 4: Apply to dev DB + regenerate client (after user confirmed server stopped)** ```bash npx prisma migrate deploy npx prisma generate ``` Expected: "All migrations have been applied" and a regenerated client. - [ ] **Step 5: Apply to the test DB** ```bash DATABASE_URL="$(grep -m1 '^DATABASE_URL' .env.test | cut -d= -f2- | tr -d '"')" npx prisma migrate deploy ``` Expected: the same migration applied to `app_test`. (If the env parsing is awkward on this shell, temporarily set `DATABASE_URL` to the app_test URL from `.env.test` and run `npx prisma migrate deploy`.) - [ ] **Step 6: Typecheck** Run: `npm run typecheck` Expected: PASS (the new Prisma field is now known to the client). - [ ] **Step 7: Commit** ```bash git add prisma/schema.prisma prisma/migrations git commit -m "feat(documents): add selected_custom_fields column to quotations/issued_orders/invoices" ``` --- ## Task 2: Backend encode/decode util (TDD) **Files:** - Modify: `src/utils/custom-fields.ts` - Test: `src/__tests__/selected-custom-fields.test.ts` - [ ] **Step 1: Write the failing test** Create `src/__tests__/selected-custom-fields.test.ts`: ```ts import { describe, it, expect } from "vitest"; import { encodeSelectedCustomFields, parseSelectedCustomFields, } from "../utils/custom-fields"; describe("selected custom fields encode/decode", () => { it("encodes a non-empty index array to a JSON string", () => { expect(encodeSelectedCustomFields([0, 2])).toBe("[0,2]"); }); it("encodes empty / non-array to null", () => { expect(encodeSelectedCustomFields([])).toBeNull(); expect(encodeSelectedCustomFields(undefined)).toBeNull(); expect(encodeSelectedCustomFields("nope")).toBeNull(); }); it("dedupes, sorts, and drops invalid entries before encoding", () => { expect(encodeSelectedCustomFields([2, 0, 2, -1, 1.5, 3])).toBe("[0,2,3]"); }); it("parses a stored string back to a number array", () => { expect(parseSelectedCustomFields("[0,2]")).toEqual([0, 2]); }); it("parses null / malformed to an empty array", () => { expect(parseSelectedCustomFields(null)).toEqual([]); expect(parseSelectedCustomFields("")).toEqual([]); expect(parseSelectedCustomFields("{garbage")).toEqual([]); expect(parseSelectedCustomFields('"x"')).toEqual([]); }); it("parses already-array input (defensive) and filters invalid", () => { expect(parseSelectedCustomFields([0, "1", 2, -3] as unknown)).toEqual([ 0, 2, ]); }); }); ``` - [ ] **Step 2: Run it to confirm failure** Run: `npm test -- selected-custom-fields` Expected: FAIL — `encodeSelectedCustomFields is not a function`. - [ ] **Step 3: Implement the helpers** Append to `src/utils/custom-fields.ts`: ```ts /** * Per-document selection of which COMPANY custom fields print on a PDF. * Stored positionally (matching the `custom_` keys the PDF builder emits) * as a JSON array string, e.g. "[0,2]". Null/empty means "none selected". */ export function encodeSelectedCustomFields(indices: unknown): string | null { const clean = normalizeIndices(indices); return clean.length > 0 ? JSON.stringify(clean) : null; } /** Decode the stored selection (string OR defensive array) into a clean number[]. */ export function parseSelectedCustomFields(raw: unknown): number[] { if (raw == null) return []; if (Array.isArray(raw)) return normalizeIndices(raw); if (typeof raw !== "string" || raw.trim() === "") return []; try { return normalizeIndices(JSON.parse(raw)); } catch { // Malformed JSON in a selection column degrades to "none" (expected // condition — a hand-edited/legacy row should never 500 a PDF render). return []; } } function normalizeIndices(input: unknown): number[] { if (!Array.isArray(input)) return []; const set = new Set(); for (const v of input) { if (typeof v === "number" && Number.isInteger(v) && v >= 0) set.add(v); } return [...set].sort((a, b) => a - b); } ``` - [ ] **Step 4: Run the test to confirm it passes** Run: `npm test -- selected-custom-fields` Expected: PASS (all util cases). - [ ] **Step 5: Commit** ```bash git add src/utils/custom-fields.ts src/__tests__/selected-custom-fields.test.ts git commit -m "feat(documents): selected-custom-fields encode/decode helpers" ``` --- ## Task 3: Zod schemas **Files:** - Modify: `src/schemas/offers.schema.ts` - Modify: `src/schemas/issued-orders.schema.ts` - Modify: `src/schemas/invoices.schema.ts` - [ ] **Step 1: Offers schema** In `src/schemas/offers.schema.ts`, inside `CreateQuotationSchema`, add after the `sections` line (line 50): ```ts // Positional indices of company custom fields to print on this document's // PDF. Omitted/empty ⇒ none. Update schema derives via .partial(). selected_custom_fields: z.array(z.number().int().nonnegative()).max(200).optional(), ``` (`UpdateQuotationSchema` already derives from this via `.partial().omit({ quotation_number: true })` — no change needed there.) - [ ] **Step 2: Issued-orders schema** In `src/schemas/issued-orders.schema.ts`, inside `CreateIssuedOrderSchema`, add after the `sections` field: ```ts selected_custom_fields: z.array(z.number().int().nonnegative()).max(200).optional(), ``` (`UpdateIssuedOrderSchema` derives via `.partial()` — no change.) - [ ] **Step 3: Invoices schema** In `src/schemas/invoices.schema.ts`, add the same line to BOTH `CreateInvoiceSchema` (after its `sections` field) and `UpdateInvoiceSchema` (after its `sections` field — invoices define the two schemas separately, so it must be added in both): ```ts selected_custom_fields: z.array(z.number().int().nonnegative()).max(200).optional(), ``` - [ ] **Step 4: Typecheck** Run: `npm run typecheck` Expected: PASS. - [ ] **Step 5: Commit** ```bash git add src/schemas/offers.schema.ts src/schemas/issued-orders.schema.ts src/schemas/invoices.schema.ts git commit -m "feat(documents): accept selected_custom_fields in document schemas" ``` --- ## Task 4: Services — persist on write, decode in detail (TDD) **Files:** - Modify: `src/services/offers.service.ts` - Modify: `src/services/issued-orders.service.ts` - Modify: `src/services/invoices.service.ts` - Test: `src/__tests__/selected-custom-fields.test.ts` (extend) - [ ] **Step 1: Add the import to all three services** At the top of each of the three service files, add (or extend the existing import from `../utils/custom-fields`): ```ts import { encodeSelectedCustomFields, parseSelectedCustomFields, } from "../utils/custom-fields"; ``` - [ ] **Step 2: Offers — persist on create** In `createOffer` (`src/services/offers.service.ts`), inside `tx.quotations.create({ data: { … } })`, add after `scope_description`: ```ts selected_custom_fields: encodeSelectedCustomFields( body.selected_custom_fields, ), ``` - [ ] **Step 3: Offers — persist on update** In `updateOffer`, inside the `const data = { … }` object (after `scope_description`, before `modified_at`), add: ```ts selected_custom_fields: body.selected_custom_fields !== undefined ? encodeSelectedCustomFields(body.selected_custom_fields) : undefined, ``` (`undefined` = "key absent in payload, leave column untouched" — matches the sibling header fields.) - [ ] **Step 4: Offers — decode in detail** In `getOffer`, in the returned object (after `valid_transitions`), add: ```ts selected_custom_fields: parseSelectedCustomFields(rest.selected_custom_fields), ``` - [ ] **Step 5: Issued orders — persist + decode** In `src/services/issued-orders.service.ts`: - In `createIssuedOrder`, inside `tx.issued_orders.create({ data: { … } })`, add: ```ts selected_custom_fields: encodeSelectedCustomFields( body.selected_custom_fields, ), ``` - In `updateIssuedOrder`, inside the header `data` object passed to `issued_orders.update`, add: ```ts selected_custom_fields: body.selected_custom_fields !== undefined ? encodeSelectedCustomFields(body.selected_custom_fields) : undefined, ``` - In `getIssuedOrder`, in the returned object (after `valid_transitions`), add: ```ts selected_custom_fields: parseSelectedCustomFields(rest.selected_custom_fields), ``` - [ ] **Step 6: Invoices — persist + decode** In `src/services/invoices.service.ts`: - In `createInvoice`, inside `tx.invoices.create({ data: { … } })`, add after `internal_notes`: ```ts selected_custom_fields: encodeSelectedCustomFields( body.selected_custom_fields, ), ``` - In `updateInvoice`, inside the first `if (editable) { … }` block (after the `tax_date` handling, still inside the block), add: ```ts if (body.selected_custom_fields !== undefined) data.selected_custom_fields = encodeSelectedCustomFields( body.selected_custom_fields, ); ``` - In `getInvoice`, in the returned object (after `valid_transitions`), add: ```ts selected_custom_fields: parseSelectedCustomFields(rest.selected_custom_fields), ``` - [ ] **Step 7: Extend the test with an offers round-trip (real DB)** Append to `src/__tests__/selected-custom-fields.test.ts`. Match the existing suite's fixture style — import the offers service directly and clean up. Use a far-future placeholder where the suite does; if an existing offers test helper exists, prefer it. Minimal version: ```ts import { createOffer, getOffer } from "../services/offers.service"; import { prisma } from "../config/prisma"; // adjust to the project's prisma export path describe("offers selected_custom_fields round-trip", () => { const created: number[] = []; afterAll(async () => { if (created.length) await prisma.quotations.deleteMany({ where: { id: { in: created } } }); }); it("persists selection on create and decodes it on detail", async () => { const res = (await createOffer({ status: "draft", selected_custom_fields: [2, 0, 0], })) as { id: number }; created.push(res.id); const row = await prisma.quotations.findUnique({ where: { id: res.id } }); expect(row?.selected_custom_fields).toBe("[0,2]"); const detail = await getOffer(res.id); expect(detail?.selected_custom_fields).toEqual([0, 2]); }); it("stores null when selection is empty", async () => { const res = (await createOffer({ status: "draft", selected_custom_fields: [], })) as { id: number }; created.push(res.id); const row = await prisma.quotations.findUnique({ where: { id: res.id } }); expect(row?.selected_custom_fields).toBeNull(); }); }); ``` > Before running: confirm the prisma import path (`../config/prisma` vs `../config/db` — grep an existing test). Adjust the import to match. - [ ] **Step 8: Run tests** Run: `npm test -- selected-custom-fields` Expected: PASS (util + offers round-trip). If FK constraints require a customer, the `customer_id`-less draft path above avoids them. - [ ] **Step 9: Typecheck + commit** ```bash npm run typecheck git add src/services/offers.service.ts src/services/issued-orders.service.ts src/services/invoices.service.ts src/__tests__/selected-custom-fields.test.ts git commit -m "feat(documents): persist & expose selected_custom_fields in services" ``` --- ## Task 5: PDF rendering — filter company custom lines (TDD) **Files:** - Modify: `src/routes/admin/offers-pdf.ts` - Modify: `src/routes/admin/issued-orders-pdf.ts` - Modify: `src/routes/admin/invoices-pdf.ts` - Test: `src/__tests__/selected-custom-fields.test.ts` (extend, if a PDF render is unit-testable; otherwise assert via the helper — see Step 6) - [ ] **Step 1: Offers PDF — add the filter param to `buildAddressLines`** In `src/routes/admin/offers-pdf.ts`, change the signature (line 28-32): ```ts function buildAddressLines( entity: Record | null, isSupplier: boolean, t: (key: string) => string, selectedCustomFields?: number[], ): AddressResult { ``` Then change the custom-field loop (lines 88-96) to skip non-selected indices when a selection array is provided: ```ts const filterCustom = Array.isArray(selectedCustomFields); cfData.forEach((cf, i) => { if (filterCustom && !selectedCustomFields!.includes(i)) return; const cfName = (cf.name || "").trim(); const cfValue = (cf.value || "").trim(); const showLabel = cf.showLabel !== false; if (cfValue) { fieldMap[`custom_${i}`] = showLabel && cfName ? `${cfName}: ${cfValue}` : cfValue; } }); ``` - [ ] **Step 2: Offers PDF — pass the document's selection into the COMPANY call** The offer's sender/company block is `supp` (`isSupplier: true` on `settings`). Update that call (lines 209-213) to pass the parsed selection; leave the customer call (`cust`) unchanged so customer custom fields still show in full: ```ts const supp = buildAddressLines( settings as unknown as Record, true, t, parseSelectedCustomFields( (quotation as { selected_custom_fields?: unknown }).selected_custom_fields, ), ); ``` Add the import at the top of the file: ```ts import { parseSelectedCustomFields } from "../../utils/custom-fields"; ``` > Confirm `quotation` (the `OfferForPdf` payload the render function receives) is selected with the default field set so `selected_custom_fields` is present. It's a scalar column on `quotations`, so the default `findUnique`/`include` returns it — no `select` narrowing to adjust here. - [ ] **Step 3: Issued-orders PDF — same change on the COMPANY (buyer) block** In `src/routes/admin/issued-orders-pdf.ts`: - Add `selectedCustomFields?: number[]` as the last param of `buildAddressLines` and apply the identical `filterCustom` guard in its custom-field loop. - The company block is `buyer = buildAddressLines(settings, true, t)` (line 316). Change to: ```ts const buyer = buildAddressLines( settings, true, t, parseSelectedCustomFields( (order as { selected_custom_fields?: unknown }).selected_custom_fields, ), ); ``` - Leave `buildSupplierLines(...)` untouched (supplier fields keep showing in full). - Add `import { parseSelectedCustomFields } from "../../utils/custom-fields";`. > Confirm the render function's `order` param carries `selected_custom_fields`. If the route fetches the order via a narrow `select`, add `selected_custom_fields: true` to it; if it uses `include`/default scalars, it's already present. Grep the route's `issued_orders.findUnique`/`findFirst` before assuming. - [ ] **Step 4: Invoices PDF — same change on the COMPANY (supplier-of-invoice) block** In `src/routes/admin/invoices-pdf.ts`: - Add `selectedCustomFields?: number[]` as the last param of `buildAddressLines` and apply the identical `filterCustom` guard. - The company block is `supp = buildAddressLines(settings, true, t)` (line 457). Change to: ```ts const supp = buildAddressLines( settings, true, t, parseSelectedCustomFields( (invoice as { selected_custom_fields?: unknown }).selected_custom_fields, ), ); ``` - Leave `cust = buildAddressLines(customer, false, t)` untouched. - Note the separate `settings.custom_fields` read lower down (the "supplier email/web" extraction near line 469) is a DIFFERENT concern (pulls an email for a header line) — **do not** filter that; leave it as-is. - Add `import { parseSelectedCustomFields } from "../../utils/custom-fields";`. > Confirm `invoice` is fetched with default scalars (it is — `prisma.invoices.findUnique` without a narrowing `select` in this route), so `selected_custom_fields` is present. - [ ] **Step 5: Typecheck + lint** Run: `npm run typecheck && npm run lint` Expected: PASS, 0 lint errors. - [ ] **Step 6: Add a focused render assertion (extend the test file)** If the three PDF modules export their HTML render function (e.g. offers exports `renderOfferHtml`), add a test that renders with a stubbed settings object carrying two company custom fields and asserts only the selected one appears. Mock `html-to-pdf` per the suite convention; you're asserting on the returned HTML string, not a real PDF. Example for offers (adapt names to the actual export): ```ts import { renderOfferHtml } from "../routes/admin/offers-pdf"; // confirm export name it("offer PDF prints only selected company custom fields", () => { const settings = { name: "Naše Firma s.r.o.", custom_fields: JSON.stringify({ fields: [ { name: "Tel.", value: "123", showLabel: true }, { name: "Web", value: "example.cz", showLabel: true }, ], field_order: [], }), }; const quotation = { customers: null, quotation_items: [], scope_sections: [], status: "draft", currency: "CZK", language: "cs", selected_custom_fields: "[0]", }; const html = renderOfferHtml(quotation as never, settings as never); expect(html).toContain("Tel.: 123"); expect(html).not.toContain("example.cz"); }); ``` If the render function is NOT exported / not unit-testable without a DB, SKIP this step rather than forcing it — the util test (Task 2) plus the service round-trip (Task 4) already cover the data path; note in the commit that PDF filtering was verified manually. Do not export internals solely to test them if that breaks the module's encapsulation; prefer a manual verification note. - [ ] **Step 7: Commit** ```bash git add src/routes/admin/offers-pdf.ts src/routes/admin/issued-orders-pdf.ts src/routes/admin/invoices-pdf.ts src/__tests__/selected-custom-fields.test.ts git commit -m "feat(documents): PDF prints only the document's selected company custom fields" ``` --- ## Task 6: Frontend — detail query types + shared picker **Files:** - Modify: `src/admin/lib/queries/offers.ts`, `issued-orders.ts`, `invoices.ts` - Create: `src/admin/components/document/CustomFieldsPrintPicker.tsx` - [ ] **Step 1: Add the field to the three detail interfaces** - `src/admin/lib/queries/offers.ts` — add to `OfferDetailData`: ```ts selected_custom_fields: number[]; ``` - `src/admin/lib/queries/issued-orders.ts` — add to `IssuedOrderDetail`: ```ts selected_custom_fields: number[]; ``` - `src/admin/lib/queries/invoices.ts` — add to `InvoiceDetail`: ```ts selected_custom_fields?: number[]; ``` - [ ] **Step 2: Create the shared picker component** Create `src/admin/components/document/CustomFieldsPrintPicker.tsx`: ```tsx import { FormControlLabel, Checkbox, Box, Typography } from "@mui/material"; import type { CompanySettingsCustomField } from "../../lib/queries/settings"; interface Props { /** Company custom field definitions, in positional order (index = print key). */ fields: CompanySettingsCustomField[]; /** Currently selected positional indices. */ selected: number[]; /** Read-only (document not editable / locked by another user). */ disabled?: boolean; onChange: (next: number[]) => void; } /** * Per-document picker: choose which COMPANY custom fields print on this * document's PDF. Selection is positional (matches the PDF `custom_` keys). * Renders nothing when the company has defined no custom fields. */ export default function CustomFieldsPrintPicker({ fields, selected, disabled = false, onChange, }: Props) { const printable = fields.filter((f) => (f.value || "").trim()); if (printable.length === 0) return null; const toggle = (idx: number, checked: boolean) => { const set = new Set(selected); if (checked) set.add(idx); else set.delete(idx); onChange([...set].sort((a, b) => a - b)); }; return ( Vlastní pole na PDF {fields.map((f, idx) => { if (!(f.value || "").trim()) return null; const label = (f.name || "").trim() ? `${f.name}: ${f.value}` : f.value; return ( toggle(idx, e.target.checked)} /> } label={{label}} /> ); })} ); } ``` > Note: indices are keyed off the FULL `fields` array (not the filtered `printable`) so they stay aligned with the PDF's `custom_`, which also enumerates the full array. Empty-value fields are skipped visually but still consume their index. - [ ] **Step 3: Typecheck** Run: `npm run typecheck` Expected: PASS. - [ ] **Step 4: Commit** ```bash git add src/admin/lib/queries/offers.ts src/admin/lib/queries/issued-orders.ts src/admin/lib/queries/invoices.ts src/admin/components/document/CustomFieldsPrintPicker.tsx git commit -m "feat(documents): shared CustomFieldsPrintPicker + detail query types" ``` --- ## Task 7: Frontend — wire the picker into the three detail pages **Files:** - Modify: `src/admin/pages/OfferDetail.tsx` - Modify: `src/admin/pages/IssuedOrderDetail.tsx` - Modify: `src/admin/pages/InvoiceDetail.tsx` For EACH page, the same four edits. Detail below uses OfferDetail; repeat the pattern for the other two (their company-settings query and edit-lock/editable flags already exist on the page — reuse them; do not add new queries). - [ ] **Step 1: Import the picker (all three pages)** ```ts import CustomFieldsPrintPicker from "../components/document/CustomFieldsPrintPicker"; ``` - [ ] **Step 2: Seed local state from the loaded document** Add state near the page's other editable-field state, and seed it when the document loads (follow the page's existing seeding pattern — if it copies server data into state in an effect or on query success, add this alongside; if it derives form state via `useState` initializers keyed on the query, match that): ```ts const [selectedCustomFields, setSelectedCustomFields] = useState([]); // when the detail query resolves (same place other fields are seeded): // setSelectedCustomFields(data.selected_custom_fields ?? []); ``` Respect Rules of Hooks: declare this `useState` with the other hooks, before any early `return`. - [ ] **Step 3: Render the picker in the editable header/meta area** Place near the other document-level settings (currency/language). `companySettings` is already loaded on the page via `companySettingsOptions()`. Use the page's existing "is this document editable / not locked by another user" boolean for `disabled` (e.g. `!canEdit` or the locked flag the page already computes): ```tsx ``` > Use whatever the page already calls its edit-gate (e.g. `canEdit`, `editable`, `isLockedByOther`). Do NOT invent a new permission — reuse the page's existing flag so the picker locks exactly when the rest of the form does. - [ ] **Step 4: Include the selection in the save payload** Find where the page builds its update/create payload (the object passed to the save mutation) and add: ```ts selected_custom_fields: selectedCustomFields, ``` - [ ] **Step 5: Repeat Steps 1-4 for `IssuedOrderDetail.tsx` and `InvoiceDetail.tsx`** Same edits; the company-settings query, edit-gate flag, and save payload all already exist on each page. - [ ] **Step 6: Typecheck + lint** Run: `npm run typecheck && npm run lint` Expected: PASS, 0 lint errors (watch `react-hooks/rules-of-hooks` — the new `useState` must precede any early return). - [ ] **Step 7: Commit** ```bash git add src/admin/pages/OfferDetail.tsx src/admin/pages/IssuedOrderDetail.tsx src/admin/pages/InvoiceDetail.tsx git commit -m "feat(documents): per-document custom-field print picker on offer/issued-order/invoice detail" ``` --- ## Task 8: Full verification - [ ] **Step 1: Run the whole server suite** Run: `npm test` Expected: PASS (no regressions; new selected-custom-fields cases green). - [ ] **Step 2: Typecheck + lint + build** ```bash npm run typecheck npm run lint npm run build ``` Expected: all PASS; client builds. - [ ] **Step 3: Manual smoke (user-driven, dev server is theirs)** Ask the user to: open an offer detail with company custom fields defined → tick one field → save → open its PDF and confirm only that field prints in the company block; confirm an untouched/older document prints no custom fields. Repeat for an issued order and an invoice. - [ ] **Step 4: Final state check** ```bash git status git log --oneline -8 ``` Expected: clean tree, the feature commits present. --- ## Self-review notes (addressed) - **Spec coverage:** storage column (T1), encode/decode (T2), schemas (T3), service persist+decode (T4), PDF filter (T5), frontend types+picker (T6), detail-page wiring (T7), tests throughout + full verify (T8). Order confirmations deliberately untouched. ✅ - **Default = none:** `buildAddressLines` filters only when passed an array; the company call always passes the parsed selection (default `[]`), so nothing prints until ticked. Customer/supplier calls omit the param ⇒ unchanged. ✅ - **Positional identity:** indices key off the full `fields` array on both render and picker sides (T5 note, T6 Step 2 note). ✅ - **Type consistency:** `encodeSelectedCustomFields` / `parseSelectedCustomFields` used with identical signatures across services and PDF routes; detail interfaces expose `number[]`. ✅ - **Open confirmations flagged inline** (prisma import path in tests; whether each PDF route narrows its document `select`) — each has a grep-first instruction rather than an assumption.