# Task B.1 Foundation Stabilization ## 1. Executive Summary Task B.1 completed two goals: 1. Foundation Stabilization 2. Production Isolation The foundation layer from Task B is now safer to use for Task C because: - foundation seed data now exists for master options and document sequences - production CRM routes no longer import legacy CRM mock services - legacy CRM demo code has been isolated under dedicated `crm-demo` paths - TypeScript compilation passes after the route and module isolation changes No Customer, Contact, Enquiry, Quotation, Approval, KPI, Report, PDF, or Notification production module was added in this task. ## 2. Foundation Review ### 2.1 Schema Review Reviewed tables introduced in Task B: - `ms_options` - `document_sequences` - `tr_audit_logs` Current strengths: - all three tables consistently use `organization_id` - `ms_options` supports soft delete through `deleted_at` - `ms_options` has a unique constraint on `(organization_id, category, code)` - `document_sequences` has a unique constraint on `(organization_id, document_type, period, branch_id)` - `tr_audit_logs` supports `before_data`, `after_data`, and `request_id` Current migration notes: - `ms_options` does not yet enforce a foreign key from `parent_id` back to `ms_options.id` - `document_sequences` does not yet enforce a foreign key to a branch model because branch is still abstraction-only - `tr_audit_logs` does not yet enforce foreign keys to `organizations` or `users` - `tr_audit_logs` could benefit from future read-oriented indexes such as `(organization_id, entity_type, entity_id)` once audit queries are introduced Decision: - no schema change was made in Task B.1 for the above notes because the task explicitly asked not to change schema unless necessary ### 2.2 Service Review Reviewed foundation services: - `auth-context` - `organization-context` - `permission` - `branch-scope` - `master-options` - `document-sequence` - `audit-log` Review summary: - naming is consistent with Task B expectations - return shapes are now stable enough for Task C - organization-first design is preserved across helpers - error handling is explicit in permission, organization, branch, and seed flows Implementation adjustments made in Task B.1: - `searchParams` was extended so isolated demo routes no longer break type checks - `crm-demo` compile issues were cleaned up without changing its business behavior - production CRM route tree now uses placeholder or foundation-safe pages only ## 3. Seed Review ### 3.1 Foundation Seed Added Seed script added: - `src/db/seeds/foundation.seed.ts` Package scripts updated: - `seed:foundation` - `setup:db` now includes `seed:foundation` Seed behavior: - loads `DATABASE_URL` from `.env.local` or `.env` - reads `organizations` from the database - throws a clear error if no organizations exist - seeds foundation data for every organization found ### 3.2 Master Options Seeded Seeded categories: - `crm_branch` - `crm_customer_status` - `crm_customer_type` - `crm_enquiry_status` - `crm_quotation_status` - `crm_product_type` - `crm_currency` - `crm_payment_term` - `crm_priority` - `crm_lead_channel` Important notes: - seeding is idempotent via `on conflict` - `crm_branch` options are seeded first and reused by document sequence seed - no organization id is hardcoded ### 3.3 Document Sequence Seeded Seeded sequence types: - `customer -> CUS` - `contact -> CON` - `enquiry -> ENQ` - `quotation -> QT` - `approval -> APV` Behavior: - seeded per organization - seeded per seeded branch option - idempotent via `on conflict` - uses the current `YYMM` period - throws clearly if required organization or branch data is unavailable ## 4. Production Isolation Review ### 4.1 Production-Ready Path Production-safe CRM route path now lives under: - `src/app/dashboard/crm/**` Current production-safe routes: - `/dashboard/crm` - `/dashboard/crm/customers` - `/dashboard/crm/customers/[id]` - `/dashboard/crm/enquiries` - `/dashboard/crm/enquiries/[id]` - `/dashboard/crm/quotations` - `/dashboard/crm/quotations/[id]` - `/dashboard/crm/approvals` - `/dashboard/crm/settings/document-sequences` - `/dashboard/crm/settings/templates` - `/dashboard/crm/settings/master-options` Production-safe behavior: - no route above imports `@/features/crm-demo/**` - no route above imports mock query/service layers - `master-options` remains connected to the real foundation path - all other CRM production routes are explicit placeholders until Task C and later tasks build real modules ### 4.2 Legacy Mock Path Legacy CRM mock module was moved to: - `src/features/crm-demo/**` Legacy demo route tree was moved to: - `src/app/dashboard/crm-demo/**` The old mock flow is still preserved for reference and manual comparison, but it is no longer the production path. ### 4.3 Route Separation Production route: - `/dashboard/crm` Demo route: - `/dashboard/crm-demo` Separation achieved: - production route tree does not import demo services - demo route tree imports `@/features/crm-demo/**` - demo links inside the moved module now point to `/dashboard/crm-demo/**` ## 5. Mock Modules Moved Moved feature module: - `src/features/crm` -> `src/features/crm-demo` Moved route tree: - `src/app/dashboard/crm` legacy implementation -> `src/app/dashboard/crm-demo` Then recreated: - `src/app/dashboard/crm/**` as production-safe placeholder/foundation routes ## 6. Files Added ### Documentation - `docs/implementation/task-b1-foundation-stabilization.md` ### Foundation Seed - `src/db/seeds/foundation.seed.ts` ### Production CRM Placeholder Support - `src/features/foundation/components/crm-production-placeholder.tsx` ### Production CRM Routes - `src/app/dashboard/crm/page.tsx` - `src/app/dashboard/crm/customers/page.tsx` - `src/app/dashboard/crm/customers/[id]/page.tsx` - `src/app/dashboard/crm/enquiries/page.tsx` - `src/app/dashboard/crm/enquiries/[id]/page.tsx` - `src/app/dashboard/crm/quotations/page.tsx` - `src/app/dashboard/crm/quotations/[id]/page.tsx` - `src/app/dashboard/crm/approvals/page.tsx` - `src/app/dashboard/crm/settings/document-sequences/page.tsx` - `src/app/dashboard/crm/settings/templates/page.tsx` - `src/app/dashboard/crm/settings/master-options/page.tsx` ### Demo Route / Feature Path Created By Move - `src/app/dashboard/crm-demo/**` - `src/features/crm-demo/**` ## 7. Files Modified - `package.json` - `src/lib/searchparams.ts` - `src/features/crm-demo/api/service.ts` - `src/features/crm-demo/components/customers-table.tsx` - `src/features/crm-demo/components/enquiries-table.tsx` - `src/features/crm-demo/components/quotations-table.tsx` ## 8. Production Routes Verified Verification result: - production `/dashboard/crm/**` no longer depends on legacy CRM mock service imports - `master-options` is the only CRM route currently wired to a real foundation-backed data path - all remaining production CRM routes are intentionally placeholders so Task C can start cleanly ## 9. Remaining Risks - production CRM modules still need real tables and route handlers before the placeholders can be replaced - `tr_audit_logs` has no foreign keys or query indexes yet - branch scope is still option-based abstraction and not a dedicated branch domain model - document sequences are seeded by branch option id, so future branch modeling must preserve or migrate that relationship carefully - `crm-demo` still contains legacy mock business logic by design, even though it is isolated from the production path ## 10. Task C Readiness Task C can begin safely now because: - production route tree is no longer tied to mock CRM state - foundation seed data can be created repeatably - document sequences can be initialized for real organizations - production CRM paths are reserved for organization-first implementation - TypeScript compilation passes after the isolation work Recommended Task C entry point: - build `Customer` and `Contact` on top of: - organization context - permission helpers - branch abstraction - master options - document sequence helper - audit log helper