alla-allaos-fullstack/plans/task-j.1.md

Task J.1: CRM Admin Configuration Center

Goal

สร้างหน้า Admin Configuration สำหรับจัดการ configuration สำคัญของ CRM ที่ปัจจุบันมี foundation แล้ว แต่ยังจัดการผ่าน UI ไม่สมบูรณ์

ครอบคลุม:

1. Document Templates
2. Approval Workflows
3. Document Sequences

ยังไม่ทำ:

• Template drag/drop designer เต็มรูปแบบ
• PDF visual designer
• Advanced conditional approval
• Report builder

---

Must Read

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

src/features/foundation/document-template/**
src/features/foundation/approval/**
src/features/foundation/document-sequence/**
src/features/foundation/master-options/**
src/features/foundation/storage/**
src/db/schema.ts

docs/adr/0009-approved-document-storage-lifecycle.md
docs/adr/0010-revenue-attribution-governance.md
docs/implementation/technical-debt.md

---

Scope 1: Admin Settings Navigation

Under:

/dashboard/crm/settings

Add/complete pages:

/dashboard/crm/settings/templates
/dashboard/crm/settings/approval-workflows
/dashboard/crm/settings/document-sequences

Use existing:

PageContainer
DataTable
Sheet/Dialog
Bento/Settings cards

No new design system.

---

Scope 2: Document Template Management

Current state:

• template schema exists
• template versions exist
• template mappings exist
• default pdfme template seed exists
• template settings page is mostly listing/read-focused

Need UI:

Template List

Show:

Template Name
Document Type
Product Type
File Type
Default
Active
Latest Version
Mapping Count
Actions

Actions:

Create Template
Edit Template Metadata
Activate/Deactivate
Set Default
View Versions

Template Version Management

For each template:

Version
Active
File Path
Schema JSON
Preview Image URL
Created By
Created At

Actions:

Create Version
View Version
Activate Version
Deactivate Version

Template Mapping Management

Add basic CRUD UI for mappings:

placeholderKey
sourcePath
dataType
defaultValue
formatMask
sortOrder

For table mapping:

columnName
sourceField
columnLetter
sortOrder
formatMask

Rules:

• role: admin only
• audit template mutations
• no drag/drop designer yet
• JSON textarea is acceptable for schemaJson in this task
• validate schemaJson is valid JSON

Permissions:

crm.document_template.read
crm.document_template.create
crm.document_template.update
crm.document_template.delete

---

Scope 3: Approval Workflow Management

Current state:

• approval schema exists
• seeded quotation standard workflow exists
• approval engine works
• no workflow management UI

Need UI:

Workflow List

Show:

Workflow Code
Workflow Name
Entity Type
Active
Step Count
Actions

Actions:

Create Workflow
Edit Workflow
Activate/Deactivate
Manage Steps

Workflow Step Management

For each workflow:

Step Number
Role Code
Role Name
Required

Actions:

Add Step
Edit Step
Remove Step
Reorder Steps

Rules:

• sequential approval only
• no parallel approval
• no conditional approval
• no delegation
• no escalation
• roleCode must match CRM businessRole or permission strategy
• do not break existing quotation approval flow

Permissions:

crm.approval.workflow.read
crm.approval.workflow.create
crm.approval.workflow.update
crm.approval.workflow.delete

Audit:

crm_approval_workflow
crm_approval_step

---

Scope 4: Document Sequence Management

Current state:

• document sequence service exists
• seed exists
• generate/preview works
• admin UI incomplete

Need UI:

Sequence List

Show:

Document Type
Prefix
Period
Branch
Current Number
Padding Length
Next Preview
Updated At
Actions

Actions:

Create Sequence
Edit Sequence
Preview Next Code
Reset Current Number
Deactivate/Delete if supported

Rules:

• reset requires confirmation
• changing prefix should not rewrite old document codes
• preview must not increment
• generation remains server-only
• organization scoped
• branch optional or from crm_branch options

Permissions:

crm.document_sequence.read
crm.document_sequence.create
crm.document_sequence.update
crm.document_sequence.reset

Audit:

crm_document_sequence

---

Scope 5: Route Handlers

Add or complete APIs:

/api/crm/settings/document-templates/**
/api/crm/settings/approval-workflows/**
/api/crm/settings/document-sequences/**

หรือถ้ามี route เดิมแล้ว ให้ reuse และเติม missing mutation

All APIs must:

requireOrganizationAccess
requirePermission
filter by organizationId
audit mutations
return user-safe errors

---

Scope 6: Mutation Freshness Rule

All CRUD pages must follow project hotfix rule:

mutation success
↓
invalidate list query
↓
invalidate detail query if relevant
↓
refresh table/detail immediately

No stale config table after save.

---

Scope 7: Safety Constraints

Do NOT implement:

visual template designer
drag/drop pdf designer
advanced approval engine
parallel approval
conditional workflow
notification
report builder
dashboard changes

---

Output

1. Files Added
2. Files Modified
3. Template Config UI Added
4. Approval Workflow UI Added
5. Document Sequence UI Added
6. API Routes Added
7. Permissions Added
8. Audit Integration
9. Remaining Risks
10. Task K Readiness

---

Definition of Done

✔ Admin can manage template metadata

✔ Admin can manage template versions

✔ Admin can manage template mappings

✔ Admin can manage approval workflows

✔ Admin can manage approval steps

✔ Admin can manage document sequences

✔ Preview next document code works

✔ All mutations refresh table data

✔ All settings routes are organization scoped

✔ Permission guard works

✔ Audit works

✔ No drag/drop designer

✔ No advanced approval logic