task-b
task-b.1 complere
This commit is contained in:
phaichayon
337
docs/implementation/task-b-template-audit.md
Normal file
337
docs/implementation/task-b-template-audit.md
Normal file
@@ -0,0 +1,337 @@
|
||||
# Task B Template Audit
|
||||
|
||||
## 1. Executive Summary
|
||||
|
||||
Task B implemented the shared foundation layer for ALLA OS CRM vNext without introducing CRM business modules such as Customer, Contact, Enquiry, Quotation, Approval, KPI, Report, or PDF generation.
|
||||
|
||||
The foundation now provides:
|
||||
|
||||
- Current user context helpers
|
||||
- Organization context helpers
|
||||
- Permission helpers
|
||||
- Branch scope abstraction
|
||||
- Master options service and API
|
||||
- Document sequence service
|
||||
- Audit log helper
|
||||
|
||||
This work follows the Task A convention freeze:
|
||||
|
||||
- `organizationId` remains the tenant boundary
|
||||
- membership and permissions remain organization-scoped
|
||||
- `branchId` is treated as business sub-scope only
|
||||
- existing Auth.js and shared auth helpers are reused rather than replaced
|
||||
|
||||
## 2. Files Added
|
||||
|
||||
### Documentation
|
||||
|
||||
- `docs/implementation/task-b-template-audit.md`
|
||||
|
||||
### Schema / Migration
|
||||
|
||||
- `drizzle/0001_orange_mandarin.sql`
|
||||
- `drizzle/meta/0001_snapshot.json`
|
||||
|
||||
### Foundation Helpers and Services
|
||||
|
||||
- `src/features/foundation/auth-context/types.ts`
|
||||
- `src/features/foundation/auth-context/service.ts`
|
||||
- `src/features/foundation/organization-context/service.ts`
|
||||
- `src/features/foundation/permission/service.ts`
|
||||
- `src/features/foundation/branch-scope/types.ts`
|
||||
- `src/features/foundation/branch-scope/service.ts`
|
||||
- `src/features/foundation/master-options/types.ts`
|
||||
- `src/features/foundation/master-options/service.ts`
|
||||
- `src/features/foundation/master-options/api/types.ts`
|
||||
- `src/features/foundation/master-options/api/service.ts`
|
||||
- `src/features/foundation/master-options/api/queries.ts`
|
||||
- `src/features/foundation/master-options/api/mutations.ts`
|
||||
- `src/features/foundation/master-options/components/columns.tsx`
|
||||
- `src/features/foundation/master-options/components/master-options-table.tsx`
|
||||
- `src/features/foundation/master-options/components/master-options-listing.tsx`
|
||||
- `src/features/foundation/document-sequence/types.ts`
|
||||
- `src/features/foundation/document-sequence/service.ts`
|
||||
- `src/features/foundation/audit-log/types.ts`
|
||||
- `src/features/foundation/audit-log/service.ts`
|
||||
|
||||
### API Route
|
||||
|
||||
- `src/app/api/foundation/master-options/route.ts`
|
||||
|
||||
## 3. Files Modified
|
||||
|
||||
- `src/db/schema.ts`
|
||||
- `src/app/dashboard/crm/settings/master-options/page.tsx`
|
||||
- `drizzle/meta/_journal.json`
|
||||
- `drizzle/meta/0000_snapshot.json`
|
||||
|
||||
## 4. Current User Context Output
|
||||
|
||||
Implemented in:
|
||||
|
||||
- `src/features/foundation/auth-context/service.ts`
|
||||
|
||||
Helpers added:
|
||||
|
||||
- `getCurrentUser()`
|
||||
- `requireCurrentUser()`
|
||||
- `getCurrentUserContext()`
|
||||
|
||||
Returned context shape:
|
||||
|
||||
- `user`
|
||||
- `activeOrganization`
|
||||
- `membership`
|
||||
- `permissions`
|
||||
- `businessRole`
|
||||
|
||||
Implementation notes:
|
||||
|
||||
- Reuses `auth()` from `src/auth.ts`
|
||||
- Reuses `requireSession()` from `src/lib/auth/session.ts`
|
||||
- Does not duplicate sign-in or session enrichment logic
|
||||
|
||||
## 5. Organization Context Output
|
||||
|
||||
Implemented in:
|
||||
|
||||
- `src/features/foundation/organization-context/service.ts`
|
||||
|
||||
Helpers added:
|
||||
|
||||
- `getCurrentOrganization()`
|
||||
- `getActiveOrganizationId()`
|
||||
- `requireOrganizationAccess()`
|
||||
|
||||
Implementation notes:
|
||||
|
||||
- Re-exports the existing shared `requireOrganizationAccess()` helper
|
||||
- Reuses current Auth.js active organization state
|
||||
- Preserves `organizationId` as the only tenant boundary
|
||||
|
||||
## 6. Permission Layer Output
|
||||
|
||||
Implemented in:
|
||||
|
||||
- `src/features/foundation/permission/service.ts`
|
||||
|
||||
Helpers added:
|
||||
|
||||
- `hasPermission(permission)`
|
||||
- `requirePermission(permission)`
|
||||
- `hasBusinessRole(role)`
|
||||
|
||||
Implementation notes:
|
||||
|
||||
- Reuses `memberships.permissions`
|
||||
- Reuses `activeBusinessRole`
|
||||
- Gives `super_admin` a bypass through existing session semantics
|
||||
- Does not introduce a second RBAC model
|
||||
|
||||
## 7. Branch Scope Output
|
||||
|
||||
Implemented in:
|
||||
|
||||
- `src/features/foundation/branch-scope/service.ts`
|
||||
|
||||
Helpers added:
|
||||
|
||||
- `getUserBranches()`
|
||||
- `getActiveBranch()`
|
||||
- `validateBranchAccess()`
|
||||
|
||||
Implementation notes:
|
||||
|
||||
- Branches are currently abstracted through master options category `crm_branch`
|
||||
- No CRM branch UI was added
|
||||
- No direct schema migration for a full branch domain model was added
|
||||
- Branch remains a business scope, not a tenant model
|
||||
|
||||
## 8. Master Options Output
|
||||
|
||||
Implemented in:
|
||||
|
||||
- `src/features/foundation/master-options/service.ts`
|
||||
- `src/features/foundation/master-options/api/**`
|
||||
- `src/app/api/foundation/master-options/route.ts`
|
||||
|
||||
Schema added in:
|
||||
|
||||
- `src/db/schema.ts` as `msOptions`
|
||||
|
||||
Helpers and services added:
|
||||
|
||||
- `listMasterOptions()`
|
||||
- `getOptionsByCategory()`
|
||||
- `getActiveOptionsByCategory()`
|
||||
|
||||
Supported characteristics:
|
||||
|
||||
- organization-scoped option records
|
||||
- category-based lookup
|
||||
- parent / child option structure
|
||||
- active / inactive state
|
||||
- soft delete via `deletedAt`
|
||||
- reusable query layer for future CRM modules
|
||||
|
||||
Supported category constants:
|
||||
|
||||
- `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`
|
||||
|
||||
## 9. Document Sequence Output
|
||||
|
||||
Implemented in:
|
||||
|
||||
- `src/features/foundation/document-sequence/service.ts`
|
||||
|
||||
Schema added in:
|
||||
|
||||
- `src/db/schema.ts` as `documentSequences`
|
||||
|
||||
Helpers added:
|
||||
|
||||
- `previewNextDocumentCode()`
|
||||
- `generateNextDocumentCode()`
|
||||
|
||||
Implementation notes:
|
||||
|
||||
- `preview` does not increment
|
||||
- `generate` increments
|
||||
- generation uses transaction plus row lock behavior
|
||||
- code generation stays on the server
|
||||
|
||||
Current default prefixes:
|
||||
|
||||
- `customer -> CUS`
|
||||
- `contact -> CON`
|
||||
- `enquiry -> ENQ`
|
||||
- `quotation -> QT`
|
||||
- `approval -> APV`
|
||||
|
||||
## 10. Audit Log Output
|
||||
|
||||
Implemented in:
|
||||
|
||||
- `src/features/foundation/audit-log/service.ts`
|
||||
|
||||
Schema added in:
|
||||
|
||||
- `src/db/schema.ts` as `trAuditLogs`
|
||||
|
||||
Helpers added:
|
||||
|
||||
- `auditCreate()`
|
||||
- `auditUpdate()`
|
||||
- `auditDelete()`
|
||||
- `auditAction()`
|
||||
|
||||
Supported fields:
|
||||
|
||||
- `beforeData`
|
||||
- `afterData`
|
||||
- `requestId`
|
||||
- `organizationId`
|
||||
- `branchId`
|
||||
- `userId`
|
||||
- `entityType`
|
||||
- `entityId`
|
||||
- `action`
|
||||
|
||||
## 11. UI Output
|
||||
|
||||
Task B only touched the allowed foundation testing page:
|
||||
|
||||
- `src/app/dashboard/crm/settings/master-options/page.tsx`
|
||||
|
||||
What changed:
|
||||
|
||||
- the page no longer points at the old CRM mock reference query
|
||||
- it now uses the new foundation master options listing flow
|
||||
- it keeps the existing dashboard shell and `PageContainer` pattern
|
||||
- it keeps the existing React Query plus DataTable pattern
|
||||
|
||||
What was intentionally not added:
|
||||
|
||||
- no new dashboard shell
|
||||
- no new design system
|
||||
- no CRM business forms or CRUD screens
|
||||
|
||||
## 12. Reuse From Template / Existing Repo
|
||||
|
||||
Reused foundation from the current repo:
|
||||
|
||||
- `src/auth.ts`
|
||||
- `src/lib/auth/session.ts`
|
||||
- `src/lib/auth/rbac.ts`
|
||||
- `src/lib/api-client.ts`
|
||||
- `src/lib/query-client.ts`
|
||||
- `src/lib/searchparams.ts`
|
||||
- `PageContainer`
|
||||
- existing DataTable primitives
|
||||
- existing React Query hydration pattern
|
||||
- existing Auth.js session enrichment
|
||||
|
||||
Production reference patterns reused:
|
||||
|
||||
- `src/features/products/**`
|
||||
- `src/features/users/**`
|
||||
|
||||
## 13. Migration Still Needed
|
||||
|
||||
Future work still required after Task B:
|
||||
|
||||
- seed data or admin flows for `ms_options`
|
||||
- seed or setup flows for `document_sequences`
|
||||
- actual CRM entity tables and route handlers
|
||||
- mutation-level integration that calls `auditCreate`, `auditUpdate`, `auditDelete`
|
||||
- branch-to-user assignment model if the product needs something stricter than option-based abstraction
|
||||
- replacement of remaining CRM mock services and pages under `src/features/crm/**`
|
||||
|
||||
## 14. Risks
|
||||
|
||||
Known risks after Task B:
|
||||
|
||||
- the foundation tables exist in schema and migration, but runtime depends on applying the migration
|
||||
- branch scope is still abstraction-only and not yet backed by a dedicated operational model
|
||||
- master options page is migrated, but the rest of CRM still points at mock data
|
||||
- some compile errors still exist in legacy CRM mock files outside the Task B foundation scope
|
||||
|
||||
## 15. Verification Notes
|
||||
|
||||
Completed during Task B:
|
||||
|
||||
- generated Drizzle migration for the new foundation tables
|
||||
- formatted the new and changed files
|
||||
- checked TypeScript compilation
|
||||
|
||||
Compilation note:
|
||||
|
||||
- foundation-layer code added for Task B was cleaned up against its own type issues
|
||||
- project-wide `tsc --noEmit` still reports existing errors in legacy CRM mock files outside the new foundation path
|
||||
|
||||
## 16. Task C Readiness
|
||||
|
||||
Task C can now start on top of this foundation with the following ready:
|
||||
|
||||
- shared user and organization context helpers
|
||||
- permission guard helpers
|
||||
- branch access abstraction
|
||||
- option lookup abstraction for statuses and enumerations
|
||||
- server-side document code generation
|
||||
- shared audit logging helper
|
||||
|
||||
Recommended Task C direction:
|
||||
|
||||
- build `Customer` and `Contact` on top of the new foundation services
|
||||
- keep `organizationId` mandatory on all new CRM entities
|
||||
- use `branchId` only as business sub-scope where needed
|
||||
- wire all mutations through sequence and audit helpers where relevant
|
||||
Reference in New Issue
Block a user