Complaint - Technical Map

Auto-generated bởi codebase-doc-generator ngày 2026-03-23 (verified từ code thực). Không chỉnh sửa thủ công.

Routes

Route	Path	Mục đích
ROUTE_COMPLAINT	/complaint	Root list và shell của module
ROUTE_COMPLAINT_DETAIL	/complaint/:id	Mở detail complaint dưới dạng dialog route
ROUTE_COMPLAINT_CREATE	/complaint/create	Mở dialog tạo complaint

Navigation & Permission

Item	Giá trị
Sidebar title	route./complaint-left-menu
moduleId	complaint_management
Permissions	ITLeader, ITStaff, BranchPOS
Platforms	Admin, CRM, POS

FE Pages (3)

Page	File	Vai trò
Overview	pages/overview/Overview.tsx	Cấp ComplaintRefetchContext, render table và router dialog
Create	pages/create/Create.tsx	Tạo complaint mới qua insert_complaint_schedule
Detail	pages/detail/Detail.tsx	Mở ComplaintDetailDialog, xử lý đóng dialog và refresh list

FE Components (11)

Core workflow

Component	Vai trò
ComplaintTable	Bảng danh sách, search, filter, pagination
ComplaintDetailDialog	Detail chính, hiển thị status/step/timeline và action footer
CreateComplaintDialog	Form tạo complaint
ComplaintTimeline	Timeline từ complaint_schedule_history
ComplaintStepBar	Step UI 3 bước: tiếp nhận, bổ sung, kết quả

Action dialogs

Component	Vai trò
ComplaintResolveDialog	Resolver nhập giải trình + phương án xử lý + file
ComplaintResolveConfirmDialog	Xác nhận trước khi gửi giải trình
ComplaintReasonDialog	Approver nhập lý do cho request supplement / approve / reject
ComplaintSupplementDialog	Resolver gửi nội dung bổ sung

Detail sections

Component	Vai trò
ComplaintInfoSection	Thông tin hồ sơ khiếu nại
ComplaintExplanationSection	Khu vực explanation / solution / files

GraphQL Operations

File: diva-admin/src/modules/complaint/graphql/complaint.graphql

Permission settings

Operation	Mục đích
GetComplaintPermissionBranch	Lấy branch complaint permissions
UpdateComplaintPermissionBranchDisabled	Disable/enable branch permission
CreateComplaintPermissions	Tạo mới rule branch + approver + resolver
DeleteComplaintRules	Xóa rule branch
BulkUpsertComplaintPermissions	Upsert hàng loạt rule complaint
EditComplaintPermissions	Sửa approver/resolver của branch

Complaint runtime

Operation	Mục đích
GetComplaintTableData	List complaint qua Hasura action complaintScheduleList
ComplaintScheduleDetail	Detail complaint qua action complaintScheduleDetail
ComplaintDetail	Raw query complaint_schedule cho customer context
CreateNewComplaintTicket	Insert complaint_schedule trực tiếp
ComplaintResolve	Action complaintScheduleResolve
complaintRequestSupplement	Action complaintScheduleRequestSupplement
complaintSupplement	Action complaintScheduleSupplement
complaintReject	Action complaintScheduleReject
complaintApprove	Action complaintScheduleApprove
GetComplainLevelData, GetComplainKindData, GetComplainStatusData	Master data
GetRecentTicket	Tìm ticket completed gần nhất để gắn complaint

FE Runtime logic

Overview/list

Logic	Ghi chú
ComplaintRefetchContext	Overview provide một refreshToken để create/detail trigger refetch list
Search debounce	keywords debounce 800ms trước khi gọi list action
List input	limit, offset, search, branch_ids, complaint_level, status
Branch filter	Query branch đang disabled = false

Create flow

Logic	Ghi chú
Customer select	Dùng UserSelect với role CUSTOMER
Contact select	Auto-fill từ address của customer; field bị disable={true} nhưng có thể add contact mới
Created time	Không cho chọn thời gian trong tương lai
Services	Dùng search_product_nearby để chọn dịch vụ
Ticket	Chỉ lấy ticket completed trong 10 ngày gần nhất, source ticket_source_6
Submit	Convert thời gian sang ISO timezone offset rồi insert_complaint_schedule

Detail flow

Logic	Ghi chú
Default source	Dùng action complaintScheduleDetail(data)
Customer source	Dùng raw query ComplaintDetail(where) và ép complaint_action_role = view
Step mapping	new -> step 0, pending_inspection/pending_supplement -> step 1, approved/rejected -> step 2
Footer actions	Phụ thuộc complaint_action_role backend trả về

Backend Actions

complaint_schedule_list.go

Hành vi	Ghi chú
Tính branch permissions	Gom branch từ cả approver và resolver, loại trùng
View scope	Cho xem complaint do chính user tạo hoặc complaint thuộc branch có quyền
Full-view roles	it_*, audit_*, accountant_*, customer_service_*, bod
Filters	Search theo code/customer, filter branch/status/level

complaint_schedule_detail.go

Hành vi	Ghi chú
Load complaint detail	Query complaint_schedule theo id
Permission guard	Chặn nếu user không phải creator, không có branch permission và không có full-view role
Timeline	Query complaint_schedule_history order by created_at desc
Action role	Trả resolve, approve, supplement hoặc view tùy status và permission

complaint_schedule_resolve.go

Hành vi	Ghi chú
Preconditions	Complaint phải ở new_complaint
Update	Ghi explanation, solution, files, đổi status sang pending_inspection_complaint
History	Insert receive_history_complaint

complaint_schedule_approve.go

Hành vi	Ghi chú
Preconditions	Complaint phải ở pending_inspection_complaint
Update	Đổi status sang approved_complaint
History	Insert approved_history_complaint với content Kết luận thanh tra

complaint_schedule_reject.go

Hành vi	Ghi chú
Preconditions	Complaint phải ở pending_inspection_complaint
Update	Đổi status sang rejected_complaint
History	Insert rejected_history_complaint với content Lý do

complaint_schedule_request_supplement.go

Hành vi	Ghi chú
Preconditions	Complaint phải ở pending_inspection_complaint
Update	Đổi status sang pending_supplement_complaint
History	Insert request_supplement_history_complaint với content Lý do

complaint_schedule_supplement.go

Hành vi	Ghi chú
Preconditions	Complaint phải ở pending_supplement_complaint
Update	Đổi status về pending_inspection_complaint
History	Insert process_supplement_history_complaint với 2 content item + files

Store / Data model

complaint_schedule

Field	Ý nghĩa
id	UUID của complaint
code	Mã complaint sinh tự động theo format #KN000001
number	Sequence number nền để sinh code
branch_id	Chi nhánh phát sinh complaint
customer_id	Khách hàng khiếu nại
account_address_id	Liên hệ/địa chỉ gắn complaint
complaint_kind	Loại complaint
complaint_level	Cấp độ complaint
status	Trạng thái workflow
ticket_code	Ticket liên quan
complaint_content	Nội dung complaint ban đầu
product_sku	JSONB SKU dịch vụ/sản phẩm liên quan
product_name	Snapshot tên dịch vụ/sản phẩm
explanation	Nội dung giải trình
solution	Phương án xử lý
files	Danh sách file đính kèm
session_created_by / session_updated_by	Người thao tác thực tế trong phiên

complaint_schedule_history

Field	Ý nghĩa
complaint_schedule_id	Liên kết complaint cha
user_id	Người thực hiện activity
status	Loại hoạt động
contents	JSONB mô tả lý do/kết luận/nội dung bổ sung
files	File đính kèm của activity

Permission tables

Table	Vai trò
complaint_permission_branch	Bật/tắt permission theo branch
complaint_permission_resolver	Danh sách resolver theo branch
complaint_permission_approver	Danh sách approver theo branch

DB Triggers / Functions

Object	Vai trò
complaint_schedule_number_seq	Sequence sinh số complaint
generate_code_complaint_schedule()	Tạo code theo #KN + number và normalize session fields khi insert
generate_session_updated_by_complaint_schedule()	Đồng bộ session_updated_by khi update
dashboard_complaint_report(_branch_ids, _from, _to)	Aggregate report complaint theo level/status

Report function

dashboard_complaint_report

Output	Ý nghĩa
total	Tổng số complaint trong khoảng thời gian lọc
complaint_level	JSON aggregate số lượng và tỷ lệ theo level
complaint_status	JSON aggregate số lượng và tỷ lệ theo status

Công thức tỷ lệ

percent = ROUND(count * 100.0 / NULLIF(total, 0), 2)

Rủi ro / Findings kỹ thuật

#	Note
1	FE tạo complaint bằng Hasura insert trực tiếp, còn các bước xử lý sau mới đi qua ecommerce-api actions.
2	ComplaintDetailDialog có 2 chế độ data source: default action mode và customer read-only mode.
3	Các action backend xử lý quyền bằng biểu thức `len(permission) == 0
4	complaint_schedule_history trong store có field struct cũ là File string, nhưng insert/runtime hiện dùng mảng files []string; cần cẩn trọng khi mở rộng typed queries cho history.