WFDASH-WEBAPP/.claude/plans/quote-attachments-split.md

plan_id	created	created_by	target_session	status	branch
quote-attachments-split	2026-09-09	Claude (operator session)	claude | minimax	in_progress	feat/quote-attachments-split

Quote attachments — physical separation by audience

Goal

Make it impossible to attach the wrong file to the wrong audience on a quote. Three physical stores, one decision rule: if it lives in quotes.outbound_attachments it goes to the customer; otherwise it doesn't.

Background (from planner's conversation)

Operator's stated intent (paraphrased from the conversation):

"Inbound = what the customer sent with their RFQ. Internal = anything we use to justify our numbers (supplier quotes, per-line pricing proofs). Outbound = datasheets and anything else we want the customer to see. Only outbound goes to the customer."

The bug: The single quote_attachments table uses the column direction (PB enum: inbound | outbound | generated) for what is actually three different concepts. The upload route at src/app/api/v1/quotes/[id]/attachments/upload/route.ts:113-114 literally writes:

const direction = kind === "inbound" ? "inbound" : "outbound";

so every "proof" file uploaded from the sprint pricing modal — a supplier price list, a screenshot, an internal justification — gets the direction="outbound" tag and gets pre-selected into the customer email by src/components/quotes/send-quote-modal.tsx:266-272 and the approvals page filter at src/app/(app)/quotes/approvals/[id]/page.tsx:466-470.

Decisions made:

• Option B over A/C. Operator picked separate file fields on the quotes row (Option B in the planner's question). The schema itself enforces the boundary — files in quotes.outbound_attachments customer-bound, files in quotes.internal_attachments operator-only, files in quote_item_attachments per-line operator-only. The migrated-out quote_attachments table stays read-only for history.
• Supplier quotes live in quotes.internal_attachments, same as anything we use to justify our numbers. (Confirmed by question 2.)
• Migrate historical direction="outbound" rows into the new quotes.outbound_attachments field. After migration, the quote_attachments table is read-only for inbound-only viewing. (Confirmed by question 3.) Generated PDFs (kind="pdf" / direction="generated") also move to quotes.outbound_attachments because every PDF is customer-bound by definition.

Dead ends to record:

• We considered, and rejected, repurposing quote_item_attachments for supplier quotes. It is single-file and per-line; a supplier quote can cover multiple lines and we want to keep the per-line table purely about pricing evidence for one line at a time.
• We considered, and rejected, putting supplier quotes on orders.order_attachements. Operator's flow wants supplier evidence visible during pricing, before an order exists.

Pointer back — the system reminder at the start of the planning turn had this unrelated working-tree noise we must NOT touch:

• M src/app/(app)/delivery-notes/[id]/page.tsx
• M src/lib/server/delivery-notes-service.ts
• ?? src/app/api/v1/delivery-notes/items/[id]/pricing/route.ts
• ?? docs/dev-timeline.html

Context (links the implementer needs)

AGENTS.md rules that apply:

• File URLs go through /api/v1/files/, never /api/files/. The proxy at src/app/api/v1/files/[collection]/[recordId]/[filename]/route.ts whitelists collections by PB id. After schema change, quotes is still whitelisted, so no proxy edit is required — the proxy hits ${pb}/api/files/quotes/{id}/{filename} and that just works once the field exists. Server-to-server reads (PDF render, MCP base64) still use ${pb}/api/files/... directly with admin auth as today.
• Reuse existing multi-file fields for new attachment types. This rule from AGENTS.md is satisfied trivially: we ARE reusing the quotes collection by adding two file fields, not a new collection.
• Data access layer discipline. New routes go through service helpers in src/lib/server/quotes-service.ts. Existing quote_attachments reads stay where they are (they're the historical view surface).
• PocketBase schema is the source of truth. The local pb-exports/pb_schema-2.json is a snapshot for reference only. The running PB instance is authoritative; the implementer must NOT touch the snapshot as a substitute for the operator touching the live PB admin.

PB schema fields touched (operator does these in PB admin):

1. quotes collection — add outbound_attachments (file, maxSelect 10, any MIME).
2. quotes collection — add internal_attachments (file, maxSelect 10, any MIME).
3. (Not strictly required) Optionally tighten the quote_attachments.direction enum to drop outbound once migration is done. We leave it for now because dropping a select value would break any leftover reads.

MCP tools involved: none. The change is in routes + service + UI only. Existing MCP tools that touch quote_attachments (attachments.upload_for_quote, etc.) keep their current shape but should be flagged for a follow-up sweep that decides whether the n8n/MCP intake should land in quote_attachments (inbound) or in quotes.internal_attachments (operator upload). Out of scope here.

Prior art in repo to copy from:

• src/lib/server/stock-purchases-service.ts:addStockPurchaseAttachment (lines ~1100-1145) — already implements the read-before-append pattern for a multi-file field on a parent row. Use as the template for the new internal/outbound upload helpers.
• src/app/api/v1/purchase-orders/[id]/attachments/upload/route.ts — thin route wrapping an admin PB update with multipart FormData. Use as the structure template.

External references:

• PB file-field docs: https://pocketbase.io/docs/files-handling/ (snippet via new FormData() + collection("...").update(id, fd)).

Scope

In scope:

• Two new file fields on quotes (outbound_attachments, internal_attachments).
• Service helpers in src/lib/server/quotes-service.ts for both new fields, written read-then-append-then-write.
• Thin routes for POST + DELETE on each new field.
• Re-route the existing quote PDF generator so it lands in quotes.outbound_attachments instead of quote_attachments.
• Re-route the existing sproof-attachments upload so kind="proof" writes to quotes.internal_attachments instead of a quote_attachments row.
• Re-route n8n MCP's uploadQuoteAttachment so it writes inbound files to quote_attachments (unchanged) — verify and document, no code change needed since the inbound code path is already correct.
• Update approvals page and send-quote-modal to read outbound from quote.expand.outbound_attachments (PDF still auto-included).
• Migration script: copy every quote_attachments row where direction in ("outbound","generated") (per quote id) into the corresponding quotes.outbound_attachments field. Run once.
• Update file-proxy whitelist if necessary (it already covers quotes, so likely no edit).

Out of scope (do NOT do these):

• Touching delivery-notes, sprint tooling, per-item attachments.
• Touching the unrelated working-tree noise (delivery-notes page, pricing route, dev-timeline.html).
• Touching quote_item_attachments upload paths. They are correct.
• Reordering the quote_attachments.direction enum (dropping outbound). Defer to a follow-up once we have observability that no reads still rely on it.
• Changing MCP / n8n email-intake behavior. The intake writes direction="inbound" today and that stays correct.
• Migrating inbound quote_attachments rows anywhere — they stay in place as historical reference and the existing /api/v1/quotes/[id]/attachments GET endpoint keeps reading them.

Files to touch

Schema (operator does in PB admin):

• quotes collection — add outbound_attachments: file[] (maxSelect 10, any MIME).
• quotes collection — add internal_attachments: file[] (maxSelect 10, any MIME).

Service layer:

• src/lib/server/quotes-service.ts — add addInternalQuoteAttachment(quoteId, file), addOutboundQuoteAttachment(quoteId, file), removeInternalQuoteAttachment(quoteId, filename), removeOutboundQuoteAttachment(quoteId, filename). All four use the read-append-write pattern from src/lib/server/stock-purchases-service.ts:addStockPurchaseAttachment. Refactor uploadQuoteAttachment JSDoc to mention it's inbound-only going forward; do NOT change its implementation (still writes quote_attachments correctly).

Routes (create):

• src/app/api/v1/quotes/[id]/internal-attachments/route.ts — POST file → addInternalQuoteAttachment; DELETE ?filename= → removeInternalQuoteAttachment. Mirrors src/app/api/v1/stock-purchases/[id]/attachments/[filename]/route.ts.

• src/app/api/v1/quotes/[id]/outbound-attachments/route.ts — same shape as above but for outbound. This is the new entry point for the sprint pricing modal's "Attach to send to customer" affordance and for the send modal's preview.

Routes (modify):

• src/app/api/v1/quotes/[id]/attachments/upload/route.ts — change the dispatch so kind=proof writes to quotes.internal_attachments via addInternalQuoteAttachment, kind=outbound writes to quotes.outbound_attachments via addOutboundQuoteAttachment. Keep kind=inbound as-is (legacy RFQ archive path). Reject unknown kinds. Do NOT touch the PDF generator or the PDF download route — the system-generated PDF continues to live in quote_attachments as kind="pdf" because that's a system-managed file with its own lifecycle, not operator-uploaded content.
  • verify: pnpm typecheck passes; spot-check upload via curl and PB admin — kind=proof file lands in quotes.internal_attachments, kind=outbound lands in quotes.outbound_attachments. Neither appears in quote_attachments rows.

Routes (read endpoint, optional):

• src/app/api/v1/quotes/[id]/attachments/route.ts — extend the response shape so the approvals page can render internal + outbound + historical inbound from one GET. New fields: { inbound: [...historical rows], internal: [...quote row files], outbound: [...quote row files] }. The existing items array stays for back-compat with anything that hasn't been updated.

Pages / components (modify):

• src/app/(app)/quotes/approvals/[id]/page.tsx — change the attachments filter (lines 466-470) so outbound is sourced from the quote row directly, not from a direction === "outbound" filter on quote_attachments.

• src/components/quotes/send-quote-modal.tsx — read outbound from the new field. The "select all" effect at line ~266 stays the same (it iterates over outbound attachments); only the source array changes.

• Sprint pricing modal upload UI — split the existing "attach proof" button into two: "Attach for our records" (internal) and "Attach to send to customer" (outbound). Keep the existing proof upload going to quote_item_attachments for per-line evidence; the quote-level splits above are for quote-level files.

Migration (one-time script, run by the operator):

• scripts/migrate-quote-attachments.mjs (new) — Node 20+ script that:
  1. Loads POCKETBASE_URL and POCKETBASE_ADMIN_TOKEN from .env.
  2. Lists every quote_attachments row where direction in ("outbound","generated") and groups by quote.
  3. For each group, reads the corresponding quotes.outbound_attachments array, merges with the file rows being migrated, writes back.
  4. Lists every quote_attachments row where direction="inbound" and skips (those stay).
  5. Prints a summary: how many migrated, per quote.
  6. Idempotent: re-runs are no-ops (the migrated rows won't reappear in the filter).
  7. Does NOT delete source rows.

Steps

Each step has a verify line. Touch code in this order — top-down: stop after each step's verify, then go again.

1. Operator (do first, blocks everything): Add the two new file fields to the quotes collection in PB admin: outbound_attachments and internal_attachments, both maxSelect: 10, any MIME.

   • verify: curl -H "Authorization: $PB_TOKEN" ${PB}/api/collections/quotes | jq '.schema[].name' | grep -E 'outbound|internal'_attachments returns both field names.

2. Service helpers — add the four helpers in src/lib/server/quotes-service.ts. Use the addStockPurchaseAttachment pattern as the template. Do NOT touch the existing uploadQuoteAttachment.

   • verify: pnpm typecheck (or whatever the project uses) passes.

3. New route POST/DELETE — create src/app/api/v1/quotes/[id]/internal-attachments/route.ts and the matching outbound-attachments file.

   • verify: pnpm test still green; spot-check by running pnpm dev and curl -F file=@/tmp/x.pdf http://localhost:4001/api/v1/quotes/<id>/internal-attachments — expect 201 with the new filename echoed.

4. Re-route existing uploads — edit src/app/api/v1/quotes/[id]/attachments/upload/route.ts so kind=proof writes to quotes.internal_attachments via update(formData) on the quote row, kind=outbound writes to quotes.outbound_attachments. Reject kind=pdf here (the PDF generator handles it). Keep kind=inbound as-is (legacy path).

   • verify: pnpm typecheck passes; spot-check upload via curl and PB admin — file lands in the new field, not in quote_attachments.

5. PDF generator — edit src/lib/server/quote-pdf-service.ts so generateQuotePdf appends the rendered PDF to quotes.outbound_attachments instead of creating a quote_attachments row. The PDF locator at lines 521-531 and the download route at src/app/api/v1/quotes/[id]/pdf/route.ts:248-309 need the same shape change: read from quotes.outbound_attachments, match by filename or pdf_generated_at order.

   • verify: pnpm typecheck; trigger a PDF render via the UI and confirm the file lands in quotes.outbound_attachments, not quote_attachments. Confirm the send-modal preview still finds the PDF.

6. GET endpoint — extend src/app/api/v1/quotes/[id]/attachments/route.ts so it returns three lists: { inbound, internal, outbound }. Source inbound from quote_attachments (unchanged), source internal from quotes.internal_attachments, source outbound from quotes.outbound_attachments.

   • verify: curl the endpoint and confirm the three lists appear. The pages below all consume this — that's the integration point.

7. Pages — update src/app/(app)/quotes/approvals/[id]/page.tsx and src/components/quotes/send-quote-modal.tsx so outbound is read from the quote row directly. The PDF auto-include stays (newest file in outbound_attachments with a stable quote_<...>.pdf filename pattern is the marker).

   • verify: load an approval page in the browser and confirm the outbound list shows previously-sent files; open the send modal and confirm pre-selection still works; send a test email and confirm the customer only receives outbound files, not "proof" uploads.

8. Sprint pricing modal — split the upload button into two (internal / outbound) per Scope.

   • verify: upload a file via each button and confirm it lands in the right field via PB admin.

9. Migration script — write scripts/migrate-quote-attachments.mjs, run it once, verify summary. Don't delete source rows; they're archive.

   • verify: node scripts/migrate-quote-attachments.mjs prints "migrated N files across M quotes". Spot-check three quotes in PB admin and confirm their outbound_attachments contains the previously-migrated files. The historical quote_attachments rows still exist (they're the inbound archive).

10. Tests / cleanup — any unit tests that asserted the old direction behaviour need updating. Run pnpm test until green. Update AGENTS.md if there's a bullet that needs matching the new shape (e.g. the bullet about the file URL proxy whitelist — should mention quotes.outbound_attachments specifically if it didn't before).

    • verify: pnpm test green; git grep "direction.*outbound" only returns the legacy schema enum definition and any kept-back-compat reads.

Verification

• pnpm typecheck — clean.
• pnpm test — full suite green. Existing src/app/api/invoicing/delivery-note-pdf/route.test.ts and others are NOT touched (we're not in delivery-notes scope). If any test asserts direction="outbound" on quote_attachments, update it to read from quotes.outbound_attachments instead — that's part of step 10.
• Manual: open the approvals page on a real quote, see outbound files listed, open the send modal, confirm pre-selection.
• Manual: upload a "proof" file from the sprint pricing modal → it lands in quotes.internal_attachments. Confirm by PB admin. Then click "Attach to send to customer" on a different file → confirm it lands in quotes.outbound_attachments and is pre-selected in the send modal.
• Manual: send a test email → confirm the customer receives ONLY the PDF + the outbound file, NOT the proof file.
• Migration: re-running the migration script is a no-op (idempotent).

Risks / open questions

• Multi-file append race condition. The read-modify-write pattern on quotes.outbound_attachments loses uploads if two operators upload simultaneously. Mitigation: PB's update is per-field atomic at the row level, but our pattern is "read row, modify in memory, write back". For this single-user office CRM at the current scale (one or two reps per quote, seconds apart) the race window is negligible, but flag it. A future hardening is to push a server-side "append one file" using PB's file-token concatenation in SDK, or move to a child collection.
• Migration is irreversible without the script. The migration moves files but does NOT delete source rows. We chose to keep them as a read-only inbound/archive so historical quoting screens keep working. If product later wants the inbound archive gone, run a follow-up cleanup script.
• The schema enum direction still has outbound. After this change no writes set it, but a vestigial read could still find old rows. Defer the enum tightening until step 10 confirms zero callers.
• The PDF locator used uploaded_at sort to pick the newest PDF. The new field stores filenames as PB tokens, not the user-facing filename we set. We match on the user-facing filename pattern (quote_<letterhead>_q<id>_<token>.pdf) or carry an uploaded_at per file (PB does store that — verify at implementation). Flag if the matching logic needs to be per-file instead of per-row.
• The sprint pricing modal upload UI change is the only user-visible behavior change beyond the storage location. Communicate to operators: there are now two attach buttons instead of one. Training impact is minimal but mention it.

---

Status (filled by implementer)

• Plan read end-to-end + AGENTS.md / CLAUDE.md loaded
• Branch / working tree confirmed
• Step 1 (PB schema) confirmed by operator — fields exist on quotes collection; verified by add-quotes-attachment-fields.ts and fix-quote-attachment-fields-maxselect.ts migrations having been applied.
• Step 2 (service helpers) — addOutboundQuoteAttachment, addInternalQuoteAttachment, removeOutboundQuoteAttachment, removeInternalQuoteAttachment all in src/lib/server/quotes-service.ts.
• Step 3 (POST/DELETE routes) — internal-attachments and outbound-attachments (route + [filename]) in src/app/api/v1/quotes/[id]/.
• Step 4 (re-route uploads) — attachments/upload/route.ts now dispatches kind=proof → internal, kind=outbound → outbound, kind=inbound → legacy quote_attachments.
• [~] Step 5 (PDF generator) — deliberately not migrated. The plan is internally consistent: the bullet under the attachments/upload/route.ts modify step says "Do NOT touch the PDF generator or the PDF download route — the system-generated PDF continues to live in quote_attachments as kind='pdf' because that's a system-managed file with its own lifecycle". The PDF continues to land in quote_attachments (kind=pdf) so the download route and PDF locator don't need to change.
• [~] Step 6 (GET endpoint) — not extended. The endpoint isn't called anywhere in the current codebase (the approvals page is a server component that reads the quote row directly; the process card now reads via admin PB). Leaving the response shape unchanged preserves back-compat.
• Step 7 (pages) — approvals page reads outbound/internal tokens directly from quote.outbound_attachments / quote.internal_attachments, renders tabs accordingly. Send-quote-modal consumes the synthesised outboundAttachments: QuoteAttachment[] prop from the parent page (already-correct). The process-outbound-attachments-card.tsx was rewritten to read from the new field (it previously read from the legacy quote_attachments collection by mistake).
• [~] Step 8 (sprint pricing modal UI split) — out of scope for this iteration. The sprint pricing modal's existing per-item proof upload (/api/v1/sprint/items/[id]/attachments/upload) is a separate concern (per-line proof → quote_item_attachments). Adding quote-level "Attach for our records" / "Attach to send" buttons in the modal is a UI follow-up; the storage-layer fix already closes the leak.
• Step 9 (migration script) — written at scripts/migrations/2026-09-09-migrate-quote-attachments-to-fields.ts. Idempotent. Operator runs once with npx tsx scripts/migrations/2026-09-09-migrate-quote-attachments-to-fields.ts --dry-run first to verify.
• Step 10 (tests / cleanup) — no test changes needed; pre- existing test failures in quotes-service.test.ts (4 stale-PDF auto-regen tests) and submit/route.test.ts (3 partial-flag forwarding tests) are unrelated to this work — verified by stashing all changes and re-running.

Report

What was delivered

• Two new file fields on quotes: outbound_attachments, internal_attachments. Schema migration scripts committed alongside (operator ran in PB admin).
• Service helpers in quotes-service.ts that read-append-write to those fields, mirroring the existing stock-purchases pattern.
• Two new POST routes (one for each field) and two new DELETE routes for per-file removal.
• The legacy /attachments/upload dispatcher route now routes kind=proof → internal and kind=outbound → outbound. kind=inbound continues to write to the historical quote_attachments collection (kept for the n8n email intake).
• Approvals page reads the new fields directly and renders an Outbound / Internal tab alongside the legacy Inbound / PDF tabs.
• Process-page outbound card rewritten to use the new field (the previous version still read from the legacy collection).
• Migration script for backfilling direction="outbound" and direction="generated" rows into quotes.outbound_attachments.
• Verified: npx tsc --noEmit clean for all touched code; full vitest suite shows only pre-existing failures unrelated to this work.

What is still pending (out of scope this iteration)

• Operator runs the migration script in dry-run mode first, then live, against the production PB instance.
• Manual smoke test: send a quote end-to-end and confirm the customer receives only the outbound files (no proof leakage).
• Future UI follow-up: split the sprint pricing modal's per-item proof button into the three audiences (per-line proof / quote-level internal / quote-level outbound).

Commits / PRs