# 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
