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

Task B: Foundation Layer Implementation

ALLA OS CRM vNext (Organization-Based)

คุณคือ Senior Full-stack Engineer

โปรด implement Foundation Layer สำหรับ ALLA OS CRM vNext โดยอ้างอิงผลจาก:

• docs/implementation/task-a-template-audit.md
• Layout.md
• .agents/skills/kiranism-shadcn-dashboard

เป้าหมาย

สร้าง Foundation Layer ที่ทุก module ในอนาคตสามารถใช้ร่วมกันได้

Task B นี้ยังไม่ใช่ CRM Module

ยังไม่ต้องสร้าง:

• Customer
• Contact
• Enquiry
• Quotation
• Approval
• Dashboard KPI
• Report
• PDF Generator

---

สิ่งที่ต้องอ่านก่อน

อ่านและยึดตาม:

docs/implementation/task-a-template-audit.md
Layout.md
.agents/skills/kiranism-shadcn-dashboard
src/auth.ts
src/lib/auth/**
src/db/schema.ts
src/features/products/**
src/features/users/**

ใช้ products และ users เป็น production reference

ห้ามใช้:

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

เป็น reference หลัก

---

Scope 1: Current User Context

สร้าง shared helper

getCurrentUser()
requireCurrentUser()
getCurrentUserContext()

Expected output:

{
  user,
  activeOrganization,
  membership,
  permissions,
  businessRole
}

Requirements:

• ใช้ Auth.js ของระบบ
• ใช้ session helper ที่มีอยู่แล้ว
• ห้าม duplicate auth logic
• ใช้ shared auth layer ของโปรเจ็ค

---

Scope 2: Organization Context

สร้าง shared helper

getCurrentOrganization()
getActiveOrganizationId()
requireOrganizationAccess()

Requirements:

• ใช้ activeOrganizationId จากระบบเดิม
• ใช้ membership เดิม
• ใช้ organization เป็น tenant boundary

Business Rule:

ทุก CRM entity ในอนาคต
ต้องอยู่ภายใต้ organizationId

---

Scope 3: Permission Layer

สร้าง helper

hasPermission(permission)
requirePermission(permission)
hasBusinessRole(role)

ตัวอย่าง:

hasPermission("crm.customer.create")
hasPermission("crm.quotation.approve")

Requirements:

• ใช้ memberships.permissions
• ใช้ businessRole
• ไม่สร้าง RBAC ใหม่

---

Scope 4: Branch Scope

สร้าง helper

getUserBranches()
getActiveBranch()
validateBranchAccess()

Business Rule:

organization
 ├─ branch A
 ├─ branch B
 └─ branch C

branch เป็น business scope

ไม่ใช่ tenant

Requirements:

• ยังไม่ต้องสร้าง CRM branch UI
• ยังไม่ต้อง migrate schema
• สร้างเฉพาะ abstraction layer

---

Scope 5: Master Options Service

สร้าง service

getOptionsByCategory()
getActiveOptionsByCategory()

รองรับ category เช่น:

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

Requirements:

• ใช้ ms_options schema
• รองรับ parent/child option
• รองรับ soft delete
• CRM module ในอนาคตห้าม hardcode status

---

Scope 6: Document Sequence Service

สร้าง service

previewNextDocumentCode()
generateNextDocumentCode()

ตัวอย่าง:

CUS2606-001
ENQ2606-001
QT2606-001

Requirements:

• ใช้ document_sequences
• preview ห้าม increment
• generate ต้อง increment
• transaction-safe
• ห้าม generate code ฝั่ง client

---

Scope 7: Audit Log Helper

สร้าง helper

auditCreate()
auditUpdate()
auditDelete()
auditAction()

Requirements:

• ใช้ tr_audit_logs
• รองรับ beforeData
• รองรับ afterData
• รองรับ requestId
• ทุก future mutation ต้องเรียกผ่าน helper นี้

---

Folder Convention

ยึดตาม Task A

ถ้าไม่มี convention ที่ชัดเจน:

src/features/foundation/
├── auth-context/
├── organization-context/
├── permission/
├── branch-scope/
├── master-options/
├── document-sequence/
└── audit-log/

และทุก feature ใช้รูปแบบ:

api/
 ├── types.ts
 ├── service.ts
 ├── queries.ts
 └── mutations.ts

ตาม kiranism-shadcn-dashboard

---

UI Scope

ถ้าจำเป็นเท่านั้น

สร้างได้แค่:

/ dashboard/settings/master-options

สำหรับทดสอบ foundation

และต้อง:

• ใช้ PageContainer
• ใช้ Layout.md
• ใช้ theme token เดิม
• ใช้ DataTable เดิม
• ใช้ Sheet/Dialog เดิม

ห้ามสร้าง dashboard ใหม่

---

ห้ามทำ

Customer CRUD
Contact CRUD
Enquiry CRUD
Quotation CRUD
Approval Workflow
Dashboard KPI
PDF Generator
Reporting
Notification

---

Output

หลังเสร็จให้สรุป:

1. ไฟล์ที่เพิ่ม
2. ไฟล์ที่แก้ไข
3. Helper ที่สร้าง
4. Service ที่สร้าง
5. จุดที่ reuse จาก template
6. จุดที่ต้อง migration ในอนาคต
7. Risk
8. Task C readiness

---

Definition of Done

Task B ถือว่าเสร็จเมื่อ:

✔ Current User Context ใช้งานได้

✔ Organization Context ใช้งานได้

✔ Permission Layer ใช้งานได้

✔ Branch Scope abstraction พร้อม

✔ Master Options Service พร้อม

✔ Document Sequence Service พร้อม

✔ Audit Log Helper พร้อม

✔ ยังไม่มี CRM business module ถูกสร้าง

✔ ไม่แก้ auth architecture เดิม

✔ ไม่สร้าง design system ใหม่

✔ พร้อมเริ่ม Task C: Customer + Contact