task-p.7.1.1

docs/implementation/task-d.4.6-quotation-document-sequence-fix-2026-06-30.md

@@ -0,0 +1,54 @@
+# Task D.4.6 Implementation Report - 2026-06-30
+
+## Scope
+- Fix `POST /api/crm/quotations` returning `400` during document-number generation.
+- Preserve existing quotation, sequence, branch, organization, and approval rules.
+- Improve frontend propagation of backend error messages.
+
+## Root Cause
+- Quotation create sends `payload.quotationType` as a master-option `id` from category `crm_quotation_type`.
+- Document-sequence resolution was looking up only `crm_product_type` options.
+- Because `crm_quotation_type.id` and `crm_product_type.id` are different records, valid quotation-type ids never resolved to a product-type code even though the codes and document-sequence rows already existed.
+- Result: document-sequence generation failed before quotation insert with message `Missing product type code configuration for quotation type.`
+
+## Implementation
+- Added shared resolver [product-type-resolver.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-sequence/product-type-resolver.ts) to normalize and resolve:
+  - product-type option ids
+  - product-type codes
+  - document-sequence aliases such as `dock_door` and `solar`
+  - quotation-type ids/codes via reference-option translation into product-type codes
+- Updated [service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-sequence/service.ts) so quotation document-sequence generation now resolves:
+  - `crm_quotation_type` option -> code
+  - code -> matching `crm_product_type`
+  - product type -> document sequence / prefix
+- Added internal diagnostic details to failed document-sequence audit payloads:
+  - requested product type
+  - normalized requested value
+  - available product-type ids/codes
+  - available quotation-type ids/codes
+- Updated [api-client.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/lib/api-client.ts) to surface backend `message`/`error` payloads instead of always throwing generic `API error: 400 Bad Request`.
+
+## Tests
+- Added [product-type-resolver.test.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-sequence/product-type-resolver.test.ts) covering:
+  - quotation-type id resolution
+  - direct code resolution
+  - alias resolution
+  - non-quotation fallback
+  - unresolved input handling
+
+## Verification
+- `npm exec tsc --noEmit`
+- `node --import tsx --test src/features/foundation/document-sequence/config.test.ts src/features/foundation/document-sequence/product-type-resolver.test.ts`
+- Live API verification against local app on `http://localhost:3000` on `2026-06-30` with authenticated UAT admin session:
+  - `crane` -> `CRA2606-002`
+  - `dockdoor` -> `DKA2606-001`
+  - `solarcell` -> `SCA2606-001`
+  - `service` -> `SVA2606-001`
+
+## Regression Notes
+- No schema changes
+- No seed changes
+- No duplicate `ms_options`
+- No duplicate `document_sequences`
+- Existing organization and branch scoping preserved
+- Existing document prefix format preserved