# 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

---

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

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

```txt
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

ห้ามใช้:

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

เป็น reference หลัก

---

# Scope 1: Current User Context

สร้าง shared helper

```ts
getCurrentUser()
requireCurrentUser()
getCurrentUserContext()
```

Expected output:

```ts
{
  user,
  activeOrganization,
  membership,
  permissions,
  businessRole
}
```

Requirements:

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

---

# Scope 2: Organization Context

สร้าง shared helper

```ts
getCurrentOrganization()
getActiveOrganizationId()
requireOrganizationAccess()
```

Requirements:

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

Business Rule:

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

---

# Scope 3: Permission Layer

สร้าง helper

```ts
hasPermission(permission)
requirePermission(permission)
hasBusinessRole(role)
```

ตัวอย่าง:

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

Requirements:

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

---

# Scope 4: Branch Scope

สร้าง helper

```ts
getUserBranches()
getActiveBranch()
validateBranchAccess()
```

Business Rule:

```txt
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

```ts
getOptionsByCategory()
getActiveOptionsByCategory()
```

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

```txt
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

```ts
previewNextDocumentCode()
generateNextDocumentCode()
```

ตัวอย่าง:

```txt
CUS2606-001
ENQ2606-001
QT2606-001
```

Requirements:

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

---

# Scope 7: Audit Log Helper

สร้าง helper

```ts
auditCreate()
auditUpdate()
auditDelete()
auditAction()
```

Requirements:

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

---

# Folder Convention

ยึดตาม Task A

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

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

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

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

ตาม kiranism-shadcn-dashboard

---

# UI Scope

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

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

```txt
/ dashboard/settings/master-options
```

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

และต้อง:

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

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

---

# ห้ามทำ

```txt
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