338 lines
8.5 KiB
Markdown
338 lines
8.5 KiB
Markdown
# 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
|