Complaint Case Lifecycle Deep Dive

Bộ tài liệu này đào sâu flow complaint-case-lifecycle theo code thực tế hiện tại. Đây là package reverse-engineer trong docs/modules, không phải PRD/spec delivery. Mục tiêu là chốt một mental model rõ ràng cho 4 lớp rất dễ bị lẫn:

• complaint create ở FE đang đi thẳng qua insert Hasura, không có action create riêng,
• backend actions mới là lifecycle engine thật cho resolve, approve, reject và supplement,
• quyền thao tác phụ thuộc đồng thời vào branch permission tables và full-view/full-permission roles,
• timeline/audit sống ở complaint_schedule_history, không chỉ là dữ liệu phụ của dialog detail.

Đọc file nào?

Bạn là ai?	Nên đọc trước	Mục tiêu
PO / BA	shared-rules.md	Chốt thuật ngữ, status matrix, role boundary, invariant
FE Dev	type-complaint-lifecycle-and-status.md, type-timeline-notification-and-role-boundary.md	Hiểu dialog shell, create path, step bar, action role
BE Dev	type-supplement-approval-and-resolution.md, shared-rules.md	Hiểu transition actions, permission guard, history contract
QA	shared-rules.md, type-supplement-approval-and-resolution.md	Thiết kế test theo state machine, role matrix, bug permission
Người mới vào hệ thống	module-overview.md	Có bản đồ tổng trước khi đi sâu

Files

File	Vai trò
module-overview.md	Bản đồ tổng: route families, state machine, backend boundary, permission model
shared-rules.md	Thuật ngữ chuẩn, status/history matrix, actor matrix, invariants
type-complaint-lifecycle-and-status.md	Deep dive cho create/list/detail, step mapping và action role
type-supplement-approval-and-resolution.md	Deep dive cho resolve, request supplement, supplement, approve, reject
type-timeline-notification-and-role-boundary.md	Deep dive cho timeline, branch permission, full-view roles và boundary liên module

Kết luận ngắn

1. Complaint workflow là state machine nhỏ nhưng chặt, không phải CRUD dialog đơn thuần.
2. FE create path đang bypass backend action layer; lifecycle chỉ bắt đầu thật từ các action resolve/approve/reject/supplement.
3. complaint_action_role là contract quan trọng nhất giữa detail FE và backend permission engine.
4. Có drift thật ở permission guard: nhiều action backend đang yêu cầu vừa có branch permission vừa có full-permission role, trái với detail logic và có khả năng chặn user hợp lệ.

Liên kết tài liệu liên quan

• docs/modules/complaint/overview.md
• docs/modules/complaint/complaint.md
• docs/modules/complaint/complaint.technical.md
• docs/modules/settings/workflow-governance.md
• docs/modules/report/org-performance-and-compliance.md
• docs/modules/user/customer-workspace.md
• docs/modules/phase-2-backlog.md

Phạm vi của bộ docs này

• Bám theo code hiện tại của diva-admin, ecommerce-api, Hasura metadata và các table domain ecommerce.
• Ưu tiên mô tả hệ thống đang chạy như thế nào thay vì flow lý tưởng.
• Chủ động ghi các drift hoặc dấu hiệu bug ở FE, backend, metadata và permission runtime.