Shared Rules — Complaint Case Lifecycle

1. Thuật ngữ chuẩn

Thuật ngữ	Nghĩa trong code hiện tại	Ghi chú
Complaint	complaint_schedule	Hồ sơ khiếu nại trung tâm
Complaint history	complaint_schedule_history	Timeline hoạt động của complaint
Resolver	complaint_permission_resolver	Người tiếp nhận, giải trình, bổ sung
Approver	complaint_permission_approver	Người duyệt, từ chối, yêu cầu bổ sung
Branch permission	complaint_permission_branch	Config bật/tắt workflow complaint theo branch
Action role	complaint_action_role	Backend-computed role để FE quyết định hiện nút thao tác
Full-view role	một nhóm role cứng trong action list/detail	Được xem rộng hơn permission branch
Full-permission role	một nhóm role cứng trong các action mutate	Dùng để bypass một phần branch permission ở mutate paths

2. Status Matrix

Status	Ý nghĩa business	Actor tiếp theo
new_complaint	Complaint mới tạo, chưa có giải trình	Resolver
pending_inspection_complaint	Resolver đã gửi giải trình, chờ thanh tra đánh giá	Approver
pending_supplement_complaint	Approver cần thêm thông tin/phương án	Resolver
approved_complaint	Hồ sơ được chấp thuận	Không có bước tiếp theo trong flow hiện tại
rejected_complaint	Hồ sơ bị từ chối	Không có bước tiếp theo trong flow hiện tại

3. History Matrix

History status	Khi nào được ghi	Nội dung chính
new_history_complaint	Khi create complaint	Snapshot nội dung tạo mới
receive_history_complaint	Khi resolver resolve	Giải trình + phương án xử lý
request_supplement_history_complaint	Khi approver yêu cầu bổ sung	Lý do yêu cầu bổ sung
process_supplement_history_complaint	Khi resolver bổ sung	Nội dung bổ sung + phương án bổ sung
approved_history_complaint	Khi approver duyệt	Kết luận thanh tra
rejected_history_complaint	Khi approver từ chối	Lý do từ chối

4. Actor Matrix

Actor	Vai trò trong flow
Người tạo complaint	Khởi tạo hồ sơ, luôn có thể xem lại hồ sơ của mình
Resolver	Tiếp nhận complaint mới và trả lời bổ sung
Approver	Duyệt, từ chối hoặc yêu cầu bổ sung
Full-view roles	Xem complaint rộng trên toàn hệ thống
bod	Có full-view ở list/detail, nhưng không nằm trong full-permission mutate group

5. Invariants quan trọng

SR-001: Create complaint không đi qua backend action

• FE gọi insert_complaint_schedule trực tiếp.
• FE tự insert complaint_schedule_history đầu tiên.
• Mọi thay đổi sau create mới đi qua backend actions.

SR-002: Detail action role là source-of-truth của FE

• FE detail dialog không hard-code permission theo role tĩnh.
• Nút Giải trình, Yêu cầu bổ sung, Duyệt, Từ chối, Bổ sung đều suy ra từ complaint_action_role.

SR-003: Lifecycle mutate phải đi kèm history

Trong các action hiện tại, update status không đứng một mình. Mỗi transition hợp lệ đều phải:

1. update complaint_schedule,
2. update session_updated_by,
3. insert một dòng mới vào complaint_schedule_history.

SR-004: Branch permission chỉ có hiệu lực khi branch chưa bị disable

• complaint_permission_branch.disabled = false là điều kiện đầu tiên để resolver/approver branch được tính vào runtime.
• Nếu branch bị disable, user vẫn có thể xem case do mình tạo, nhưng không còn hưởng resolver/approver branch scope cho các case khác.

SR-005: Full-view và full-permission không hoàn toàn giống nhau

• List/detail có bod trong full-view roles.
• Mutate actions không dùng đúng cùng một tập role ở mọi file.
• Đây là nguồn drift quan trọng khi debug "thấy case nhưng bấm action không chạy".

6. Boundary Checklist

Khi phân tích bug hoặc change request trong vùng complaint, luôn hỏi:

1. Case này được tạo ở complaint module hay được xem từ customer workspace?
2. User đang fail ở bước list visibility, detail visibility hay mutate action?
3. Branch của complaint có đang bị disabled trong permission config không?
4. User đang được grant qua branch tables hay chỉ nhờ full-view/full-permission role?
5. Bug là do FE không hiện nút, hay FE hiện nút nhưng action backend từ chối?

7. Rủi ro / Findings

ID	Finding
SR-F01	Create path bypass action layer làm validation create bị phân tán giữa FE và DB.
SR-F02	complaint_action_role và mutate permission guard hiện không đồng nhất, dễ sinh false-positive UI action.
SR-F03	bod có thể xem rộng nhưng không rõ ràng có được mutate rộng như list/detail hay không; semantics hiện không nhất quán.
SR-F04	Complaint workflow không thấy notification-specific action/event riêng trong vùng code đã đọc; nếu business kỳ vọng gửi thông báo theo từng transition thì hiện logic đó không nằm cùng complaint surface này.