task-d complate

docs/implementation/task-d-enquiry-production.md

@@ -0,0 +1,118 @@
+# Task D: Enquiry Production Module
+
+## 1. Files Added
+
+- `src/app/api/crm/enquiries/route.ts`
+- `src/app/api/crm/enquiries/[id]/route.ts`
+- `src/app/api/crm/enquiries/[id]/followups/route.ts`
+- `src/app/api/crm/enquiries/[id]/followups/[followupId]/route.ts`
+- `src/features/crm/enquiries/api/types.ts`
+- `src/features/crm/enquiries/api/service.ts`
+- `src/features/crm/enquiries/api/queries.ts`
+- `src/features/crm/enquiries/api/mutations.ts`
+- `src/features/crm/enquiries/schemas/enquiry.schema.ts`
+- `src/features/crm/enquiries/server/service.ts`
+- `src/features/crm/enquiries/components/enquiry-status-badge.tsx`
+- `src/features/crm/enquiries/components/enquiry-form-sheet.tsx`
+- `src/features/crm/enquiries/components/followup-form-sheet.tsx`
+- `src/features/crm/enquiries/components/enquiry-cell-action.tsx`
+- `src/features/crm/enquiries/components/enquiry-columns.tsx`
+- `src/features/crm/enquiries/components/enquiries-table.tsx`
+- `src/features/crm/enquiries/components/enquiry-listing.tsx`
+- `src/features/crm/enquiries/components/enquiry-followups-tab.tsx`
+- `src/features/crm/enquiries/components/enquiry-detail.tsx`
+- `drizzle/0003_blushing_bruce_banner.sql`
+- `drizzle/meta/0003_snapshot.json`
+
+## 2. Files Modified
+
+- `src/app/dashboard/crm/enquiries/page.tsx`
+- `src/app/dashboard/crm/enquiries/[id]/page.tsx`
+- `src/app/dashboard/crm/customers/[id]/page.tsx`
+- `src/features/crm/customers/api/types.ts`
+- `src/features/crm/customers/components/customer-detail.tsx`
+- `src/db/schema.ts`
+- `src/db/seeds/foundation.seed.ts`
+- `src/lib/auth/rbac.ts`
+- `src/lib/searchparams.ts`
+- `drizzle/meta/_journal.json`
+
+## 3. Schema Added
+
+- `crm_enquiries`
+  - organization-scoped sales opportunity master
+  - customer/contact linkage, project context, pricing expectation, probability, hot-project flag, and soft-delete columns
+  - unique `(organization_id, code)` for document-sequenced enquiry codes
+- `crm_enquiry_followups`
+  - organization-scoped timeline items under enquiry
+  - follow-up type, contact linkage, outcome, next follow-up date, next action, and soft-delete columns
+
+## 4. API Routes Added
+
+- `GET /api/crm/enquiries`
+- `POST /api/crm/enquiries`
+- `GET /api/crm/enquiries/[id]`
+- `PATCH /api/crm/enquiries/[id]`
+- `DELETE /api/crm/enquiries/[id]`
+- `GET /api/crm/enquiries/[id]/followups`
+- `POST /api/crm/enquiries/[id]/followups`
+- `PATCH /api/crm/enquiries/[id]/followups/[followupId]`
+- `DELETE /api/crm/enquiries/[id]/followups/[followupId]`
+
+## 5. UI Routes Completed
+
+- `/dashboard/crm/enquiries`
+  - production list with React Query, nuqs filters, create button, edit/view/delete actions
+  - filters: search, status, product type, priority, branch, customer
+- `/dashboard/crm/enquiries/[id]`
+  - detail page with tabs: Overview, Follow-ups, Activity, Related Quotations Placeholder
+- `/dashboard/crm/customers/[id]`
+  - related documents tab now shows real linked enquiries for that customer
+
+## 6. Permissions Used
+
+- `crm.enquiry.read`
+- `crm.enquiry.create`
+- `crm.enquiry.update`
+- `crm.enquiry.delete`
+- `crm.enquiry.followup.read`
+- `crm.enquiry.followup.create`
+- `crm.enquiry.followup.update`
+- `crm.enquiry.followup.delete`
+
+Admin defaults now include enquiry and follow-up permissions. Regular users inherit read permissions only unless additional permissions are granted.
+
+## 7. Audit Integration
+
+- enquiry create/update/delete writes to `tr_audit_logs` with `entityType = crm_enquiry`
+- follow-up create/update/delete writes to `tr_audit_logs` with `entityType = crm_enquiry_followup`
+- enquiry detail activity tab merges enquiry audit and follow-up audit entries, then resolves actor names from `users`
+
+## 8. Document Sequence Integration
+
+- enquiry create uses `generateNextDocumentCode({ documentType: 'enquiry' })`
+- branch-specific sequence is honored when `branchId` is provided
+- foundation seed now includes `crm_followup_type` options so follow-up forms do not hardcode those values
+
+## 9. Customer/Contact Integration
+
+- enquiry create/update validates that customer belongs to the active organization
+- enquiry contact must belong to the same organization and selected customer
+- follow-up contact must belong to the same organization and the enquiry's customer
+- enquiry form customer dropdown is sourced from production customer data
+- contact dropdown is filtered by selected customer
+- customer detail route now shows related enquiries in the related-documents tab
+
+## 10. Remaining Risks
+
+- there are still no database foreign keys between enquiry tables and customer/contact tables; organization scoping is enforced in application logic
+- form date fields currently use `YYYY-MM-DD` text inputs because the project field wrapper does not expose a native date mode
+- customer detail shows linked enquiries, but there is not yet a dedicated customer-side enquiry table with pagination
+- follow-up activity relies on audit payload contents for relation tracing, not a dedicated combined activity view
+
+## 11. Task E Readiness
+
+- enquiry production backbone is ready for quotation creation and linkage
+- customer, contact, and enquiry lifecycles now share the same foundation patterns: org scope, branch validation, master options, document sequence, and audit logging
+- enquiry detail already has a stable placeholder tab for quotation integration
+- follow-up timeline and customer-related enquiry surfacing are in place for downstream sales workflow expansion