alla-allaos-fullstack/docs/implementation/task-b-template-audit.md

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