task-j1

plans/task-j.1.md

@@ -0,0 +1,419 @@
+# 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
+
+```txt
+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:
+
+```txt
+/dashboard/crm/settings
+```
+
+Add/complete pages:
+
+```txt
+/dashboard/crm/settings/templates
+/dashboard/crm/settings/approval-workflows
+/dashboard/crm/settings/document-sequences
+```
+
+Use existing:
+
+```txt
+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:
+
+```txt
+Template Name
+Document Type
+Product Type
+File Type
+Default
+Active
+Latest Version
+Mapping Count
+Actions
+```
+
+Actions:
+
+```txt
+Create Template
+Edit Template Metadata
+Activate/Deactivate
+Set Default
+View Versions
+```
+
+## Template Version Management
+
+For each template:
+
+```txt
+Version
+Active
+File Path
+Schema JSON
+Preview Image URL
+Created By
+Created At
+```
+
+Actions:
+
+```txt
+Create Version
+View Version
+Activate Version
+Deactivate Version
+```
+
+## Template Mapping Management
+
+Add basic CRUD UI for mappings:
+
+```txt
+placeholderKey
+sourcePath
+dataType
+defaultValue
+formatMask
+sortOrder
+```
+
+For table mapping:
+
+```txt
+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:
+
+```txt
+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:
+
+```txt
+Workflow Code
+Workflow Name
+Entity Type
+Active
+Step Count
+Actions
+```
+
+Actions:
+
+```txt
+Create Workflow
+Edit Workflow
+Activate/Deactivate
+Manage Steps
+```
+
+## Workflow Step Management
+
+For each workflow:
+
+```txt
+Step Number
+Role Code
+Role Name
+Required
+```
+
+Actions:
+
+```txt
+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:
+
+```txt
+crm.approval.workflow.read
+crm.approval.workflow.create
+crm.approval.workflow.update
+crm.approval.workflow.delete
+```
+
+Audit:
+
+```txt
+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:
+
+```txt
+Document Type
+Prefix
+Period
+Branch
+Current Number
+Padding Length
+Next Preview
+Updated At
+Actions
+```
+
+Actions:
+
+```txt
+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:
+
+```txt
+crm.document_sequence.read
+crm.document_sequence.create
+crm.document_sequence.update
+crm.document_sequence.reset
+```
+
+Audit:
+
+```txt
+crm_document_sequence
+```
+
+---
+
+# Scope 5: Route Handlers
+
+Add or complete APIs:
+
+```txt
+/api/crm/settings/document-templates/**
+/api/crm/settings/approval-workflows/**
+/api/crm/settings/document-sequences/**
+```
+
+หรือถ้ามี route เดิมแล้ว ให้ reuse และเติม missing mutation
+
+All APIs must:
+
+```txt
+requireOrganizationAccess
+requirePermission
+filter by organizationId
+audit mutations
+return user-safe errors
+```
+
+---
+
+# Scope 6: Mutation Freshness Rule
+
+All CRUD pages must follow project hotfix rule:
+
+```txt
+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:
+
+```txt
+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