task-b
task-b.1 complere
This commit is contained in:
phaichayon
279
docs/implementation/task-b1-foundation-stabilization.md
Normal file
279
docs/implementation/task-b1-foundation-stabilization.md
Normal file
@@ -0,0 +1,279 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user