Shared Rules — Projects Task Lifecycle And Tour Income

1. Thuật ngữ chuẩn

Thuật ngữ	Tên kỹ thuật	Ý nghĩa
Board dự án	project	Shell tổ chức task, workflow, members
Công việc cha	project_task với parent_id IS NULL	Task cấp board
Công việc con / subtask	project_task với parent_id IS NOT NULL	Task con của service/task cha
Người thực hiện chính	main_assignee	Chủ thể chính để KPI workload và overdue gắn vào
Người giao việc	assigner	Người phân công
Người giám sát	supervisor	Chủ thể theo dõi/supervise
Người hỗ trợ	supporter, trong code hay ghi supportor	Assignee không phải main/supervisor/assigner
Tour fee / tour money	tour_money	Giá trị tour gắn theo assignee, dùng cho report/salary/customer note
Commission bác sĩ	request_doctor_commissions	Quan hệ từ task sang request_working_schedule qua reference_id = project_task.id

2. Status matrix

Automate board

Status	Source	Ghi chú
new_branch	types.ts:79	Default create cho automate board
waiting_branch	project_task_insert.go:193	Có thể phát sinh khi tạo request doctor commission
accepted_branch	types.ts:81	Status trung gian theo workflow
inprogress_branch	types.ts:82	Task đang chạy
done_branch	types.ts:83	Trigger nhiều side effect hậu kỳ
canceled_branch	types.ts:84	Status hủy

Personal / my-task

Status	Source	Ghi chú
new	MyTaskItem.tsx:118	Mapped từ new_%
reopen	MyTaskItem.tsx:172	Mapped từ reopen_%
inprogress	MyTaskItem.tsx:158	Dựa is_inprogress
reviewing	MyTaskItem.tsx:128	Mapped từ pending_%
completed	MyTaskItem.tsx:138	Mapped từ done_%
cancelled	types.ts:102	Chỉ có ở enum FE
missed	types.ts:102	Pseudo-status dựa field computed missed

3. Role matrix của assignee

Role	Dấu hiệu	Side effect chính
Main assignee	main_assignee = true	KPI workload, overdue KPI, quick-view status guard, salary/tour runtime
Assigner	assigner = true	Hiện diện trong UI phân công, nhưng helper ids hiện đang bug
Supervisor	supervisor = true	Được loại khỏi overdue notification user list (notification_task_expired.go:88)
Supporter	không phải 3 role trên	Bị naming drift supportor/supporter ở FE

4. Invariants đang ngầm được hệ thống dùng

1. Task automate mới tạo sẽ rơi vào new_branch, không dựa status đầu của workflow (TaskCreate.tsx:243).
2. Quick view không cho đổi trạng thái nếu chưa có main assignee (QuickViewTaskDetail.tsx:44).
3. project_task_assignee là runtime entrypoint quan trọng. Insert/update/delete đều có event triggers (public_project_task_assignee.yaml:143).
4. request_doctor_commissions được map từ project_task.id -> request_working_schedule.reference_id (public_project_task.yaml:237).
5. tour_money là data contract liên module, không được xem như UI-only field.

5. Scheduler matrix

Runtime	Input	Output	Rủi ro
reset_task	automate task due hôm qua, status inprogress_branch/new_branch	reset status về new_branch và delete assignees	mất assignment, đổi workload expectation đột ngột
task_expired	task overdue chưa done, chưa disabled	gửi notification + ghi KPI overdue	có thể chồng semantics với reset_task vì cùng chạy 18:00

6. Rules cho tour income

1. Tour limit report chỉ đếm task done có project_task_assignee.tour_money > 0 ở một số phép đếm (get_list_tour_limit_task_info.go:199).
2. Nếu main assignee được thêm vào task không phải reopen, hệ thống ghi KPI MetricTotalWorkload (project_task_assignee_insert.go:118).
3. Nếu xóa main assignee, hệ thống ghi KPI workload âm (project_task_assignee_delete.go:62).
4. Nếu đổi tour_money, hệ thống cố sync ecommerce_task_log, salary và customer note metadata (project_task_assignee_update.go:164).

7. Findings ưu tiên cao

ID	Mức độ	Mô tả
SR-F01	Cao	filterTaskAssignerIds() map nhầm qua filterTaskManagers(), khiến mọi flow dựa vào danh sách assigner ids có nguy cơ sai (useTaskHelper.ts:115).
SR-F02	Cao	TaskForm dùng e?.assinger thay vì e?.assigner khi xác định supporter, có thể làm lệch phân loại role ở edit form (TaskForm/index.tsx:577).
SR-F03	Cao	Naming drift POSITION_SUPORTOR, supportor, MY_TASK_STATUES cho thấy FE constants đã nợ kỹ thuật lâu ngày và len vào query/UI (types.ts:67, types.ts:102).
SR-F04	Rất cao	Doctor commission cancel path có khả năng không cancel đúng request đang mở (project_task_insert.go:229).
SR-F05	Rất cao	Customer visit insert sau done_branch dùng time.Now() thay vì DoneAt, có thể làm sai data visit/report theo ngày (project_task_update_1.go:242).

8. QA checklist tối thiểu cho batch này

• Tạo task automate mới, thêm main assignee, xác nhận parent task auto-advance và KPI workload tăng.
• Đổi tour_money trên task đã có customer_note, xác nhận ecommerce_task_log, salary và metadata customer note cùng đổi.
• Chuyển task service sang done_branch với done_at backdate, kiểm tra all_customer_visits.visit_date có bám done_at hay bám ngày hiện tại.
• Tạo doctor task làm tổng surgery_money nhỏ hơn và lớn hơn order.paid_amount, kiểm tra request doctor commission insert/update/cancel có trúng record.
• Chạy mô phỏng 18:00 cho reset_task và task_expired, kiểm tra thứ tự tác động tới assignee, KPI overdue và notification.