# 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
