Module Overview — Complaint Case Lifecycle

1. Complaint workflow thực tế đang được tách thành 3 lớp

Lớp	Thành phần	Vai trò
FE shell	Overview, Create, Detail + dialog components	Render list, create form, detail/timeline và action dialogs
Lifecycle engine	complaintScheduleResolve, complaintScheduleApprove, complaintScheduleReject, complaintScheduleRequestSupplement, complaintScheduleSupplement	Validate trạng thái và ghi transition thật
Audit + permission	complaint_schedule_history, complaint_permission_*, complaintScheduleList, complaintScheduleDetail	Quyết định ai thấy gì, ai làm gì, timeline ghi thế nào

Điểm quan trọng là complaint create chưa nằm trong lifecycle engine. FE tạo trực tiếp bản ghi complaint_schedule, sau đó các action backend mới tiếp quản vòng đời hồ sơ.

2. Surface map

FE routes

Route	Dạng UI	Vai trò
/complaint	page	List, filter, search
/complaint/create	dialog route	Tạo complaint mới
/complaint/:id	dialog route	Xem detail, timeline và thao tác tiếp theo

Backend actions

Action	Vai trò
complaintScheduleList	Trả list theo creator / branch permission / full-view role
complaintScheduleDetail	Trả detail + timeline + complaint_action_role
complaintScheduleResolve	Resolver tiếp nhận và giải trình
complaintScheduleRequestSupplement	Approver yêu cầu bổ sung
complaintScheduleSupplement	Resolver gửi bổ sung
complaintScheduleApprove	Approver duyệt
complaintScheduleReject	Approver từ chối

Bảng dữ liệu chính

Table	Vai trò
complaint_schedule	Bản ghi complaint trung tâm
complaint_schedule_history	Timeline/audit trail của từng bước
complaint_permission_branch	Bật/tắt permission theo branch
complaint_permission_resolver	Resolver theo branch
complaint_permission_approver	Approver theo branch

3. State machine chuẩn theo code

Create complaint
  -> status = new_complaint
  -> history = new_history_complaint

new_complaint
  -> resolve
  -> pending_inspection_complaint
  -> history = receive_history_complaint

pending_inspection_complaint
  -> approve
  -> approved_complaint
  -> history = approved_history_complaint

pending_inspection_complaint
  -> reject
  -> rejected_complaint
  -> history = rejected_history_complaint

pending_inspection_complaint
  -> request supplement
  -> pending_supplement_complaint
  -> history = request_supplement_history_complaint

pending_supplement_complaint
  -> supplement
  -> pending_inspection_complaint
  -> history = process_supplement_history_complaint

Step UI mapping ở FE

Complaint status	Step bar
new_complaint	Step 0
pending_inspection_complaint	Step 1
pending_supplement_complaint	Step 1
approved_complaint	Step 2
rejected_complaint	Step 2

Điều này cho thấy FE coi pending_inspection và pending_supplement là cùng một pha "đang xử lý", dù business semantics khác nhau.

4. Permission model tổng quát

List/detail visibility

Complaint được xem nếu thỏa một trong các điều kiện:

1. user là người tạo complaint,
2. user có branch permission qua complaint_permission_resolver hoặc complaint_permission_approver,
3. user thuộc full-view role.

Full-view roles

• it_leader
• it_staff
• audit_leader
• audit_staff
• accountant_leader
• accountant_staff
• customer_service_leader
• customer_service_staff
• bod

Action role trong detail

complaint_action_role	Điều kiện business
resolve	complaint đang new_complaint và user là resolver của branch
approve	complaint đang pending_inspection_complaint và user là approver của branch
supplement	complaint đang pending_supplement_complaint và user là resolver của branch
view	các trường hợp còn lại

FE không tự tính role này. Detail dialog render nút theo contract backend trả về.

5. Runtime facts dễ bị bỏ sót

Create path là direct insert

• CreateNewComplaintTicket là mutation insert_complaint_schedule.
• FE đồng thời insert một dòng history với new_history_complaint.
• Không có backend action chuyên biệt để validate create semantics ngoài constraint ở FE/DB.

Detail có 2 nguồn dữ liệu

Source	Khi nào dùng	Ghi chú
complaintScheduleDetail	complaint management flow	Có permission guard + timeline + complaint_action_role
ComplaintDetail(where)	customer context	FE ép complaint_action_role = view

Điều này có nghĩa cùng một complaint nhưng ở customer workspace có thể được hiển thị theo semantics read-only khác detail của module complaint.

Timeline là first-class surface

• ComplaintTimeline render complaint_schedule_history.
• Các action backend đều insert history riêng sau khi update complaint.
• QA nếu chỉ test status cuối mà không test history.contents/files sẽ bỏ sót audit correctness.

6. Findings nổi bật

ID	Finding
MO-F01	Complaint create path bypass backend action layer, nên validation create hiện bị chia giữa FE và DB.
MO-F02	complaint_action_role là contract trung tâm; nếu drift với backend permission guard thì FE sẽ hiện nút không chạy được hoặc ẩn sai nút.
MO-F03	pending_supplement được FE gộp vào cùng step với pending_inspection, có thể che mất nuance "chờ resolver phản hồi".
MO-F04	Nhiều action backend đang check quyền theo logic khác complaintScheduleDetail, có dấu hiệu bug thật ở guard layer.