alla-allaos-fullstack/plans/task-c.md

Task C: Customer + Contact Production Module

ALLA OS CRM vNext

คุณคือ Senior Full-stack Engineer ให้เริ่ม implement Customer + Contact production module โดยอิง foundation ที่เสร็จแล้วจาก Task A, Task B, Task B.1

ต้องอ่านก่อน

docs/implementation/task-a-template-audit.md
docs/implementation/task-b-template-audit.md
docs/implementation/task-b1-foundation-stabilization.md

Layout.md
AGENTS.md
.agents/skills/kiranism-shadcn-dashboard

src/db/schema.ts
src/features/foundation/**
src/features/products/**
src/features/users/**
src/app/dashboard/crm/**

เป้าหมาย

สร้าง production module สำหรับ:

Customer
Customer Contact

ยังไม่ทำ:

Enquiry
Quotation
Approval
Dashboard KPI
PDF Generator
Report
Notification

Core Rules

organizationId = tenant boundary
branchId = business sub-scope

ทุก customer ต้องมี organizationId

branchId ใช้เป็น optional business scope เท่านั้น

ห้ามใช้ mock CRM service

ห้าม import จาก:

src/features/crm-demo/**
src/constants/mock-api*

Scope C1: Customer Schema

เพิ่ม production schema ใน src/db/schema.ts

ตารางแนะนำ:

crm_customers

Fields ขั้นต่ำ:

id
organizationId
branchId
code
name
abbr
taxId
customerType
customerStatus
address
province
district
subDistrict
postalCode
country
phone
fax
email
website
leadChannel
customerGroup
notes
isActive
createdAt
updatedAt
deletedAt
createdBy
updatedBy

Rules:

• organizationId required
• code unique ภายใน organization
• customer status/type ใช้ master options
• code ใช้ document sequence customer -> CUS
• mutation ต้อง audit log

Scope C2: Customer API

สร้าง route handlers:

src/app/api/crm/customers/route.ts
src/app/api/crm/customers/[id]/route.ts

รองรับ:

GET list
POST create
GET detail
PATCH update
DELETE soft delete

Rules:

• ใช้ requireOrganizationAccess
• ใช้ permission helper
• filter ด้วย organizationId เสมอ
• ห้าม query ข้าม organization
• create ต้อง generate customer code
• create/update/delete ต้อง audit

Permissions แนะนำ:

crm.customer.read
crm.customer.create
crm.customer.update
crm.customer.delete

Scope C3: Customer Feature Layer

สร้าง:

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/components/**

ใช้ pattern จาก:

src/features/products/**
src/features/users/**

Scope C4: Customer UI

แทน placeholder routes:

/dashboard/crm/customers
/dashboard/crm/customers/[id]

List page ต้องมี:

PageContainer
DataTable
search
status filter
type filter
branch filter
create button
edit action
view action
soft delete action

Detail page ใช้ Layout.md Template A

Tabs:

Overview
Contacts
Activity
Related Documents Placeholder

Scope C5: Customer Form

ใช้:

useAppForm
Zod
Sheet/Dialog pattern
React Query mutation

Create/Edit fields:

name
abbr
taxId
customerType
customerStatus
branchId
address
province
district
subDistrict
postalCode
phone
fax
email
website
leadChannel
customerGroup
notes

Rules:

• customerType/status ดึงจาก master options
• branch ดึงจาก branch scope/master options
• ห้าม hardcode option ใน form

Scope C6: Contact Schema

เพิ่มตาราง:

crm_customer_contacts

Fields ขั้นต่ำ:

id
organizationId
customerId
name
position
department
phone
mobile
email
isPrimary
notes
isActive
createdAt
updatedAt
deletedAt
createdBy
updatedBy

Rules:

• contact ต้องอยู่ใน organization เดียวกับ customer
• customerId required
• primary contact มีได้ 1 คนต่อ customer ถ้าทำได้ใน MVP
• mutation ต้อง audit

Scope C7: Contact API + UI

Route handlers:

src/app/api/crm/customers/[id]/contacts/route.ts
src/app/api/crm/customers/[id]/contacts/[contactId]/route.ts

รองรับ:

GET contacts by customer
POST create contact
PATCH update contact
DELETE soft delete contact

UI:

• แสดงใน Customer Detail tab: Contacts
• Create/Edit contact ด้วย Sheet
• Primary badge
• Action edit/delete

Permissions แนะนำ:

crm.contact.read
crm.contact.create
crm.contact.update
crm.contact.delete

Scope C8: Activity Timeline

ใน Customer Detail เพิ่ม Activity tab แบบ production-ready placeholder

ให้แสดง audit log ของ customer จาก tr_audit_logs

ถ้ายังไม่มี query helper ให้สร้าง minimal service ได้

ห้ามทำใน Task C

Enquiry schema
Quotation schema
Approval schema
Quotation item
PDF generation
Dashboard KPI
Report
Notification

Output หลังทำเสร็จ

สรุป:

1. Files Added
2. Files Modified
3. Schema Added
4. API Routes Added
5. UI Routes Completed
6. Permissions Used
7. Audit Integration
8. Document Sequence Integration
9. Remaining Risks
10. Task D Readiness

Definition of Done

Task C ผ่านเมื่อ:

• Customer schema พร้อม
• Contact schema พร้อม
• Customer list ใช้งาน production data
• Customer detail ใช้งาน production data
• Customer create/edit/delete ใช้งานได้
• Contact create/edit/delete ใช้งานได้
• ใช้ organizationId ทุก query
• ใช้ master options ใน status/type
• ใช้ document sequence ตอนสร้าง customer
• ใช้ audit log ทุก mutation
• ไม่ import mock CRM
• ไม่ทำ Enquiry/Quotation/Approval