Type — Complaint Lifecycle And Status

1. Create flow hiện tại

Complaint mới được tạo từ dialog FE bằng direct insert thay vì qua action backend chuyên biệt.

User mở /complaint/create
  -> chọn customer, contact, branch, loại complaint, cấp độ, thời gian, nội dung
  -> optional: chọn service / ticket gần nhất
  -> submit
  -> insert_complaint_schedule
  -> insert complaint_schedule_history(status = new_history_complaint)
  -> đóng dialog + refetch list

Dữ liệu tạo mới đáng chú ý

Field	Vai trò
customer_id	Khách hàng khiếu nại
account_address_id	Liên hệ gắn complaint
branch_id	Chi nhánh chịu trách nhiệm
complaint_kind	Loại complaint
complaint_level	Cấp độ complaint
ticket_code	Ticket liên quan nếu có
complaint_content	Nội dung khiếu nại
product_sku / product_name	Snapshot dịch vụ/sản phẩm liên quan
session_created_by	Người thao tác thực tế

Rules

ID	Rule
CLS-001	FE chặn thời gian tạo nằm ở tương lai.
CLS-002	Ticket gợi ý chỉ lấy ticket completed gần đây theo query FE.
CLS-003	Sau create luôn có một dòng new_history_complaint.
CLS-004	Validation create không được backend action chuẩn hóa lại trong flow hiện tại.

2. List flow không phải all-data query

complaintScheduleList là read engine thật cho complaint list.

Input chính

Input	Vai trò
limit, offset	Pagination
search	Tìm theo code / customer keyword
branch_ids	Lọc theo branch
complaint_level	Lọc theo cấp độ
status	Lọc theo trạng thái

Visibility logic

List complaint được trả về nếu user:

1. là người tạo complaint,
2. có branch permission qua resolver/approver tables,
3. hoặc có full-view role.

Điều này có nghĩa complaint list thực tế đã là permission-aware projection, không phải query trực tiếp lên bảng complaint_schedule.

3. Detail flow có 2 semantics

A. Complaint module detail

• Dùng action complaintScheduleDetail.
• Có permission guard.
• Trả về timeline từ complaint_schedule_history.
• Trả về complaint_action_role.

B. Customer context detail

• Dùng query raw ComplaintDetail.
• FE tự ép complaint_action_role = view.
• Phù hợp cho read-only context trong customer workspace.

4. Status transitions chuẩn

From	Action	To	History
create	direct insert	new_complaint	new_history_complaint
new_complaint	resolve	pending_inspection_complaint	receive_history_complaint
pending_inspection_complaint	approve	approved_complaint	approved_history_complaint
pending_inspection_complaint	reject	rejected_complaint	rejected_history_complaint
pending_inspection_complaint	request supplement	pending_supplement_complaint	request_supplement_history_complaint
pending_supplement_complaint	supplement	pending_inspection_complaint	process_supplement_history_complaint

Không thấy nhánh reopen hay cancel trong complaint workflow hiện tại.

5. FE step bar không đồng nhất hoàn toàn với status semantics

Status	Step UI	Ý nghĩa FE
new_complaint	0	Chưa giải trình
pending_inspection_complaint	1	Đang xử lý
pending_supplement_complaint	1	Đang xử lý
approved_complaint	2	Kết thúc
rejected_complaint	2	Kết thúc

Điểm đáng chú ý:

• FE không tách step riêng cho pha "chờ bổ sung".
• Người dùng chỉ thấy complaint đang ở pha xử lý chung, còn nuance ai đang nợ hành động phải đọc thêm status text và timeline.

6. Action role là contract quan trọng nhất

complaint_action_role	FE hành xử thế nào
resolve	Mở dialog giải trình
approve	Hiện các action duyệt / từ chối / yêu cầu bổ sung
supplement	Mở dialog bổ sung
view	Read-only, không hiện action mutating

Nếu backend trả role sai, FE sẽ sai ngay ở action footer. Complaint module do đó phụ thuộc mạnh vào correctness của complaintScheduleDetail.

7. Rủi ro / Findings

ID	Finding
CLS-F01	Create flow chưa được action layer chuẩn hóa nên business rule create không có single source ở backend.
CLS-F02	Cùng một complaint có thể vào detail qua 2 sources khác nhau, dẫn đến semantics action/read-only khác nhau.
CLS-F03	Step bar FE đang nén pending_inspection và pending_supplement vào cùng một bước, có thể làm BA/QA bỏ sót edge case bổ sung.