ĐIỀU 15-16: LUẬT STATE MACHINE + CHECKPOINT

Ghi chú v4.0: Constitution mục lục liệt kê 2 file riêng (law-15, law-16). File này gộp tạm.

---

ĐIỀU 15: LUẬT STATE MACHINE — TẦNG 4

§1. Hai mô hình

	Quy trình tuyến tính	State Machine
Thứ tự	Cố định A→B→C	Linh hoạt, nhảy tự do
Trigger	Bước trước xong→sau bắt đầu	Sự kiện→chuyển trạng thái
Ví dụ	Duyệt công việc (M-002)	Phát triển khách hàng

§2. Tầng 4 dùng State Machine là CHÍNH

Khách hàng: Biết→Quan tâm→Mua→Giới thiệu→CTV. Nhưng có người nhảy cóc. Mỗi entity có trạng thái + nhiều mục tiêu song song.

Workflow Module hỗ trợ CẢ HAI: process mode (nội bộ, tuần tự) + state machine mode (linh hoạt).

§3. Schema hỗ trợ — KHÔNG CẦN REFACTOR

• workflow_steps: thêm step_type = "state". Thêm code field format ND-0001 (global unique). ✅ ĐÃ CÓ.
• workflow_step_relations: thêm relation_type = "state_transition" + condition_expression.
• workflows: thêm workflow_mode = "process" | "state_machine".

§4. Journey Templates — Tổ hợp trạng thái

Pattern thống nhất: entity → entity_set → entity_set_items (M2M).

workflow_steps/nodes (SSOT) → journey_templates (tổ hợp) → journey_template_steps (M2M)

Gán entity → journey_template → hệ thống TỰ BIẾT trạng thái + mục tiêu + checkpoints cần.

Design Pattern thống nhất (áp dụng MỌI loại tổ hợp):

Thực thể đơn lẻ	Tổ hợp	M2M	Prefix
checkpoint_types (CP)	checkpoint_sets (CPS)	checkpoint_set_items	CP/CPS
workflow_steps / nodes (ND)	journey_templates (JT)	journey_template_steps	ND/JT
Tương lai: fields, rules...	field_sets, rule_sets...	M2M tương ứng	...

Khi phát hiện loại thực thể cần tổ hợp → áp dụng cùng pattern. Không phát minh lại.

§5. Entity state tracking (khi bắt đầu Tầng 4)

• Field current_step_id trên collections có lifecycle (contacts, agents, deals...)
• Field journey_template_id trên cùng collections
• State history collection: ghi lại lịch sử chuyển trạng thái (từ node nào → node nào, khi nào, trigger gì)
• Multi-target: M2M relation — 1 entity → nhiều target steps (mục tiêu song song)

---

ĐIỀU 16: LUẬT CHECKPOINT

§1. Checkpoint = thực thể có ID, không phải text

3 tầng:

checkpoint_types (CP-NNN) — ĐỊNH NGHĨA SSOT duy nhất
  id, code (CP-001), name, description, layer, category,
  requires_evidence, auto_verifiable, status

checkpoint_sets (CPS-NNN) — TỔ HỢP gom types
  id, code (CPS-001), name, description, status,
  applicable_to (enum: process/state_machine/both),
  trigger_config (json)

checkpoint_set_items (M2M)
  id, set_id (FK), type_id (FK), sort_order, is_required,
  trigger_on_complete (json), override_config (json)

checkpoint_instances (CPI-NNNN) — THỰC TẾ ghi kết quả
  id, checkpoint_type_id, target_collection, target_item_id,
  set_id (FK), status, verified_by_type, verified_by_id,
  evidence, notes

§2. Tái sử dụng SSOT

1 CP-001 → nhiều sets → nhiều workflows. Sửa CP-001 = áp dụng mọi nơi. ĐÂY MỚI LÀ SSOT THỰC SỰ.

§3. Metadata checkpoint

Mỗi checkpoint type phải trả lời được:

• "CP này nằm trong tổ hợp nào?" → query checkpoint_set_items WHERE type_id = CP-001
• "CP này đang dùng ở đâu?" → query checkpoint_instances WHERE checkpoint_type_id = CP-001
• "CP này mồ côi không?" → type không trong set nào + không có instance → mồ côi → cảnh báo

§4. Liên kết Node ↔ Checkpoint

workflow_steps.checkpoint_set_id → FK. Entity đến node → hệ thống tạo instances từ set → hoàn thành → đủ điều kiện chuyển.

• Process mode: hoàn thành set → auto chuyển next step
• State machine mode: hoàn thành set = 1 điều kiện, có thể cần thêm trigger khác

✅ ĐÃ CÓ: checkpoint_types (31, CP-NNN), checkpoint_sets (2, CPS-NNN), checkpoint_set_items (M2M), workflow_steps.code (ND-0001, 70 records).