lcbp3/docs/2_Backend_Plan_V1_4_4.Phase6A.md

“Phase 6A + Technical Design Document : Workflow DSL (Mini-Language)”**

ออกแบบสำหรับระบบ Workflow Engine กลางของโครงการ ไม่มีโค้ดผูกกับ Framework เพื่อให้สามารถนำไป Implement ใน NestJS หรือ Microservice ใด ๆ ได้

---

📌 Phase 6A – Workflow DSL Implementation Plan

🎯 เป้าหมายของ Phase 6A

ใน Phase นี้ จะเริ่มสร้าง “Workflow DSL (Domain-Specific Language)” สำหรับนิยามกฎการเดินงาน (Workflow Transition Rules) ให้สามารถ:

• แยก Business Workflow Logic ออกจาก Source Code

• แก้ไขกฎ Workflow ได้โดย ไม่ต้องแก้โค้ดและไม่ต้อง Deploy ใหม่

• รองรับ Document หลายประเภท เช่น

  • Correspondence
  • RFA
  • Internal Circulation
  • Document Transmittal

• รองรับ Multi-step routing, skip, reject, rollback, parallel assignments

• สามารถนำไปใช้งานทั้งใน

  • Backend (NestJS)
  • Frontend (UI Driven)
  • External Microservices

---

📅 ระยะเวลา

1 สัปดาห์ (หลัง Phase 6.5)

---

🧩 Output ของ Phase 6A

• DSL Specification (Grammar)
• JSON Schema for Workflow Definition
• Workflow Rule Interpreter (Parser + Executor)
• Validation Engine (Compile-time and Runtime)
• Storage (DB Table / Registry)
• Execution API:

Action	Description
compile()	ตรวจ DSL → สร้าง Execution Tree
evaluate(state, action, context)	ประมวลผลและส่งสถานะใหม่
preview(state)	คำนวณ Next Possible Transitions
validate()	ตรวจว่า DSL ถูกต้อง

---

📘 Technical Specification – Workflow DSL

---

1️⃣ Requirements

Functional Requirements

• นิยาม Workflow เป็นภาษาคล้าย State Machine

• แต่ละเอกสารมี State, Actions, Entry/Exit Events

• สามารถมี:

  • Required approvals
  • Conditional transition
  • Auto-transition
  • Parallel approval
  • Return/rollback

• Running time: < 20ms ต่อคำสั่ง
• Hot reload ไม่ต้อง Compile ใหม่ทั้ง Backend
• DSL ต้อง Debug ได้ง่าย
• ต้อง Versioned
• ต้องรองรับ Audit 100%

---

2️⃣ DSL Format (Human Friendly)

workflow: RFA
version: 1.0

states:
  - name: DRAFT
    initial: true
    on:
      SUBMIT:
        to: IN_REVIEW
        require:
          - role: ENGINEER
        events:
          - notify: reviewer

  - name: IN_REVIEW
    on:
      APPROVE:
        to: APPROVED
      REJECT:
        to: DRAFT
        events:
          - notify: creator

  - name: APPROVED
    terminal: true

---

3️⃣ Compiled Execution Model (Normalized JSON)

{
  "workflow": "RFA",
  "version": "1.0",
  "states": {
    "DRAFT": {
      "initial": true,
      "transitions": {
        "SUBMIT": {
          "to": "IN_REVIEW",
          "requirements": [
            { "role": "ENGINEER" }
          ],
          "events": [
            { "type": "notify", "target": "reviewer" }
          ]
        }
      }
    },
    "IN_REVIEW": {
      "transitions": {
        "APPROVE": { "to": "APPROVED" },
        "REJECT": {
          "to": "DRAFT",
          "events": [
            { "type": "notify", "target": "creator" }
          ]
        }
      }
    },
    "APPROVED": {
      "terminal": true
    }
  }
}

Frontend และ Backend สามารถแชร์ JSON นี้ร่วมกันได้

---

4️⃣ DSL Grammar Definition (EBNF)

workflow     = "workflow" ":" identifier ;
version      = "version" ":" number ;

states       = "states:" state_list ;
state_list   = { state } ;

state        = "- name:" identifier 
               [ "initial:" boolean ] 
               [ "terminal:" boolean ]
               [ "on:" transition_list ] ;

transition_list = { transition } ;

transition   = action ":" 
                indent "to:" identifier
                [ indent "require:" requirements ]
                [ indent "events:" event_list ] ;

requirements = "- role:" identifier | "- user:" identifier ;

event_list   = { event } ;
event        = "- notify:" identifier ;

---

5️⃣ Validation Rules (Compile-Time)

5.1 State Rules

• ต้องมีอย่างน้อย 1 state ที่ initial: true
• หาก terminal: true → ต้องไม่มี transition ต่อไป

5.2 Transition Rules

ตรวจสอบว่า:

• to ชี้ไปยัง state ที่มีอยู่
• require.role ต้องเป็น role ที่ระบบรู้จัก
• Action name ต้องเป็น UPPER_CASE

5.3 Version Safety

• ทุกชุด Workflow DSL ต้องขึ้นกับ version
• แก้ไขต้องสร้าง version ใหม่
• ไม่ overwrite version เก่า
• “Document ที่กำลังอยู่ใน step เดิมยังต้องใช้กฎเดิมได้”

---

6️⃣ Runtime Validation Rules

เมื่อ execute(action):

input: current_state, action, context

1) ตรวจว่า state มี transition "action"
2) ตรวจว่าผู้ใช้มีสิทธิ์ตาม require[]
3) Compute next state
4) Execute events[]
5) Return next_state

---

7️⃣ Context Model

interface WorkflowContext {
  userId: string;
  roles: string[];
  documentId: string;
  now: Date;
  payload?: any;
}

---

8️⃣ Execution API (Abstract)

class WorkflowEngine {
  
  load(dsl: string | object): CompiledWorkflow

  compile(dsl: string | object): CompiledWorkflow

  evaluate(state: string, action: string, context: WorkflowContext): EvalResult

  getAvailableActions(state: string, context: WorkflowContext): string[]
}

---

9️⃣ Interpreter Execution Flow

flowchart TD
    A[Receive Action] --> B[Load Compiled Workflow]
    B --> C[Check allowed actions]
    C -->|Invalid| E[Return Error]
    C --> D[Evaluate Requirements]
    D --> F[Transition to Next State]
    F --> G[Run Events]
    G --> H[Return Success]

---

🔟 Events System

รองรับ event หลายประเภท:

event.type	ตัวอย่าง
notify	ส่ง Email/Line
assign	เปลี่ยนผู้รับผิดชอบ
webhook	ยิง Webhook ไปยังระบบอื่น
auto_action	ทำ action ซ้ำโดยอัตโนมัติ

---

11️⃣ Database Schema

Table: workflow_definition

Field	Type	Description
id	UUID	PK
workflow_code	varchar(50)	เช่น RFA, CORR
version	int	Version number
dsl	JSON	YAML/JSON DSL เก็บดิบ
compiled	JSON	JSON ที่ Compile แล้ว
created_at	timestamp
is_active	boolean	ใช้อยู่หรือไม่

Table: workflow_history

เก็บ audit แบบ immutable append-only

Field	Description
workflow	Document Type
document_id	เอกสารไหน
from_state	เดิม
to_state	ใหม่
action	คำสั่ง
user	ใครเป็นคนทำ
timestamp	เวลา
metadata	เหตุการณ์อื่น ๆ

---

12️⃣ Error Codes

Code	Meaning
WF_NO_TRANSITION	Action นี้ไม่ถูกต้อง
WF_RESTRICTED	User ไม่มีสิทธิ์
WF_MISSING_REQUIREMENTS	ไม่ผ่านเงื่อนไข
WF_STATE_NOT_FOUND	ไม่มี state ที่อ้างอิง
WF_SYNTAX_ERROR	DSL ผิดรูปแบบ

---

13️⃣ Testing Strategy

Unit Tests

• Parse DSL → JSON
• Invalid syntax → throw error
• Invalid transitions → throw error

Integration Tests

• Evaluate() ผ่าน 20+ cases
• RFA ย้อนกลับ
• Approve chain
• Parallel review

Load Tests

• 1,000 documents running workflow
• Evaluate < 20ms ต่อ action

---

14️⃣ Deployment Strategy

Hot Reload Options

• DSL stored in DB
• Cache in Redis
• Touched timestamp triggers:

invalidate cache → recompile

No downtime required

---

15️⃣ Microservice-Ready

DSL Engine แยกเป็น:

• workflow-engine-core → Pure JS library
• workflow-service → NestJS module
• API public:

POST /workflow/evaluate
GET /workflow/preview
POST /workflow/compile

ภายหลังสามารถนำไปวางบน:

• Kubernetes
• Worker Node
• API Gateway

---

🎉 Summary

สิ่งที่ Phase 6A เพิ่มเข้าในระบบ

✔ Workflow DSL ที่แก้ไขได้โดยไม่ต้อง Deploy ✔ Parser + Validator + Runtime Interpreter ✔ Database storage + Versioning ✔ Execution API สำหรับ Backend และ Frontend ✔ รองรับ Business Workflow ซับซ้อนทั้งหมด ✔ Ready สำหรับ Microservice model ในอนาคต