alla-allaos-fullstack/docs/implementation/task-c-customer-contact.md

Task C: Customer + Contact Production Module

1. Files Added

• src/app/api/crm/customers/route.ts
• src/app/api/crm/customers/[id]/route.ts
• src/app/api/crm/customers/[id]/contacts/route.ts
• src/app/api/crm/customers/[id]/contacts/[contactId]/route.ts
• src/features/crm/customers/api/types.ts
• src/features/crm/customers/api/service.ts
• src/features/crm/customers/api/queries.ts
• src/features/crm/customers/api/mutations.ts
• src/features/crm/customers/schemas/customer.schema.ts
• src/features/crm/customers/server/service.ts
• src/features/crm/customers/components/customer-status-badge.tsx
• src/features/crm/customers/components/customer-form-sheet.tsx
• src/features/crm/customers/components/contact-form-sheet.tsx
• src/features/crm/customers/components/customer-cell-action.tsx
• src/features/crm/customers/components/customer-columns.tsx
• src/features/crm/customers/components/customers-table.tsx
• src/features/crm/customers/components/customer-listing.tsx
• src/features/crm/customers/components/customer-contacts-tab.tsx
• src/features/crm/customers/components/customer-detail.tsx
• drizzle/0002_plain_anthem.sql
• drizzle/meta/0002_snapshot.json

2. Files Modified

• src/app/dashboard/crm/customers/page.tsx
• src/app/dashboard/crm/customers/[id]/page.tsx
• src/db/schema.ts
• src/db/seeds/foundation.seed.ts
• src/features/foundation/audit-log/service.ts
• src/features/foundation/audit-log/types.ts
• src/lib/auth/rbac.ts
• src/lib/searchparams.ts
• drizzle/meta/_journal.json

3. Schema Added

• crm_customers
  • organization-scoped customer master with unique (organization_id, code)
  • branch, CRM classification, contact channels, notes, soft-delete, and audit actor columns
• crm_customer_contacts
  • organization-scoped child contacts under customer
  • primary contact flag, soft-delete, and audit actor columns

4. API Routes Added

• GET /api/crm/customers
• POST /api/crm/customers
• GET /api/crm/customers/[id]
• PATCH /api/crm/customers/[id]
• DELETE /api/crm/customers/[id]
• GET /api/crm/customers/[id]/contacts
• POST /api/crm/customers/[id]/contacts
• PATCH /api/crm/customers/[id]/contacts/[contactId]
• DELETE /api/crm/customers/[id]/contacts/[contactId]

5. UI Routes Completed

• /dashboard/crm/customers
  • production list with React Query, nuqs filters, create button, edit/view/delete actions
• /dashboard/crm/customers/[id]
  • detail page with Template A style structure
  • tabs: Overview, Contacts, Activity, Related Documents Placeholder

6. Permissions Used

• crm.customer.read
• crm.customer.create
• crm.customer.update
• crm.customer.delete
• crm.contact.read
• crm.contact.create
• crm.contact.update
• crm.contact.delete

Admin defaults now include the CRM customer/contact permissions. Regular users inherit read permissions only unless additional permissions are granted.

7. Audit Integration

• customer create/update/delete writes to tr_audit_logs with entityType = crm_customer
• contact create/update/delete writes to tr_audit_logs with entityType = crm_customer_contact
• activity tab reads audit log entries for the current customer and resolves actor names from users

8. Document Sequence Integration

• customer create uses generateNextDocumentCode({ documentType: 'customer' })
• branch-specific sequence is honored when branchId is provided
• foundation seed now also prepares crm_customer_group options for form-driven classification

9. Remaining Risks

• there are no database foreign keys yet between crm_customers, crm_customer_contacts, and master option rows; organization filtering is enforced in application code
• branch scope currently resolves from seeded crm_branch options only; if branch ownership becomes role-sensitive later, branch-scope will need stronger membership-aware rules
• contact primary uniqueness is enforced in transaction logic, not via a database partial unique index
• list/detail UI depends on seeded master options being present for customer status/type/group/channel labels

10. Task D Readiness

• customer and contact production backbone is ready for enquiry linkage
• activity timeline is already in place for future downstream CRM entities
• customer detail route now has a stable home for related document tabs
• foundation permissions, sequence, branch scope, and audit plumbing are reusable for enquiry and quotation modules