task-p.7.1.1

docs/implementation/quotation-create-400-investigation-2026-06-30.md

@@ -0,0 +1,56 @@
+# Quotation Create 400 Investigation - 2026-06-30
+
+## Scope
+Investigate why quotation creation fails with `POST /api/crm/quotations -> 400`.
+
+## Summary
+The failure is reproducible on the running local app and the API returns:
+
+```json
+{"message":"Missing product type code configuration quotation type."}
+```
+
+This happens inside the document-sequence layer during quotation code generation, not in the quotation form schema itself.
+
+## Reproduction
+1. Sign in with seeded UAT admin account:
+   - `admin.uat@alla.local`
+   - `UatDemo123!`
+2. Submit a valid-looking quotation payload to `POST /api/crm/quotations`.
+3. The API returns `400` with message:
+   - `Missing product type code configuration quotation type.`
+
+Reproduced against the local app at `http://localhost:3000` with authenticated session.
+
+## Findings
+1. Quotation creation reaches [createQuotation()](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/server/service.ts:1329), passes quotation payload validation, and then calls `generateNextDocumentCode()` for document code allocation.
+2. The failure occurs inside the document-sequence product-type resolution path in [src/features/foundation/document-sequence/service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-sequence/service.ts:152) and [generateNextDocumentCode()](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-sequence/service.ts:527).
+3. Database inspection shows the organization does have valid master options for both:
+   - `crm_quotation_type`: `crane`, `dockdoor`, `solarcell`, `service`, `other`
+   - `crm_product_type`: `crane`, `dockdoor`, `solarcell`, `service`, `sparepart`
+4. Database inspection also shows quotation document sequences already exist for:
+   - `crane`
+   - `dockdoor`
+   - `solarcell`
+   - `service`
+5. Because both option categories and document-sequence rows are present, the `400` is not caused by missing seed data in `ms_options` or missing quotation sequence rows.
+6. The remaining failure point is the runtime mapping logic that resolves a quotation type id/code into the product-type code used by document sequences. That logic is currently rejecting a valid quotation type before sequence generation completes.
+
+## Likely Root Cause
+The product-type map resolution in [src/features/foundation/document-sequence/service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-sequence/service.ts:152) is not successfully resolving the incoming quotation type id/code to a usable document-sequence product type, even though:
+- the quotation type option exists
+- the product type option exists
+- the document sequence row exists
+
+In other words, this is a mapping bug in the document-sequence resolution path, not a missing reference-data problem in the quotation form.
+
+## Secondary Observation
+The frontend currently surfaces quotation create failures through [apiClient](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/lib/api-client.ts:1) as generic `API error: 400 Bad Request`, which hides the backend message unless the request is inspected manually. That makes this class of failure harder to diagnose from the UI alone.
+
+## Status
+- Investigation completed
+- Root cause area identified
+- No production code fix applied in this investigation round
+
+## Recommended Next Step
+Patch the document-sequence product-type resolution so quotation type ids from quotation creation resolve consistently to the corresponding `crm_product_type` code before `generateNextDocumentCode()` runs.