Appearance
Tóm tắt quyết định (Decision Brief) — Tổng hợp tài chính đơn hàng
Phiên bản: 3.0 | Ngày: 30/04/2026 | Độ phức tạp: M | Module: ecommerce + settings | Trạng thái: Sẵn sàng review
Mục đích: cửa vào full package — PO, Sếp, Tech Lead, Delivery đọc file này trước. Văn phong: theo
templates/_LANGUAGE_RULES.md+_STYLE_GUIDE.md. Canonical: nếu xung đột vớisource-of-truth.md, ưu tiên SoT. Brief chỉ tóm tắt, không duplicate execution detail.
Tài liệu đầu vào chuẩn
| File | Vai trò |
|---|---|
source-of-truth.md | Truth chuẩn + Phương án đã chốt |
evidence-pack.md | Bằng chứng code/screen/config |
prd.md / ui-spec.md / dev-spec.md / qa-test-plan.md / handoff.md | Owner cho chi tiết |
1) Tóm tắt 5 phút
- Vấn đề: Lễ tân/Manager đang phải mở 3-4 tab (Thanh toán + Hoa hồng + Vật tư + Ghi chú) để biết 1 đơn thu/nợ/chi/lãi bao nhiêu — mỗi đơn mất 3-5 phút.
- Giải pháp: Thêm section "Tài chính" trong sidebar trái chi tiết đơn dịch vụ (
/e/service-order/:id), tổng hợp doanh thu + đã thu + còn nợ + chi phí + lợi nhuận tạm tính từ action backendGetOrderFinancialSummary. - Giá trị: Giảm thời gian xem tài chính đơn từ 3-5 phút xuống dưới 5 giây cho 100% đơn dịch vụ.
- Phân quyền: 2 action mới —
view_financial_summary(Manager/Lễ tân/Kế toán) vàview_financial_pnl(Admin/BOD), thay đổi được qua Dynamic Permission UI hiện có. - Rủi ro lớn nhất: Negative invoice / refund sign behavior cần test kỹ —
customer_paid_amountcó thể có dấu sai làm số "Đã thu" lệch.
2) Bản đồ package
| File | Đọc khi cần | Phụ trách |
|---|---|---|
source-of-truth.md | Đối chiếu canonical truth / conflict | PO/BA + TL |
evidence-pack.md | Xem bằng chứng code/screen/db | PO/BA + TL |
prd.md | Duyệt phạm vi nghiệp vụ, DEC, FR/AC, công thức | PO/BA |
ui-spec.md | Thiết kế/triển khai màn hình | UI/UX + FE |
dev-spec.md | Triển khai action/migration/permission | TL + BE/FE |
qa-test-plan.md | Test oracle + regression scope | QA |
handoff.md | Giao việc, timeline, RACI | TL + Delivery |
3) Khóa phạm vi
Trong phạm vi
| # | Nội dung | Tham chiếu |
|---|---|---|
| 1 | Section "Tài chính" trong sidebar /e/service-order/:id | prd.md FR-001 |
| 2 | Action backend GetOrderFinancialSummary aggregate cross-source | prd.md FR-002 |
| 3 | App Settings: nhóm fixed_cost { rate } | prd.md FR-003 |
| 4 | Snapshot fixed_cost_rate + fixed_cost_amount vào order mới | prd.md FR-004 |
| 5 | Hook invoice_complete cập nhật fixed cost high-water mark | prd.md FR-005 |
| 6 | 2 permission action view_financial_summary, view_financial_pnl | prd.md FR-006 |
| 7 | Cảnh báo đơn lỗ (cho user có view_financial_pnl) | prd.md FR-007 |
Ngoài phạm vi
| # | Không làm | Lý do |
|---|---|---|
| 1 | Chi phí vật tư cộng vào P&L | Định lượng vật tư chưa khóa — Phase 2 |
| 2 | Báo cáo tài chính tổng (BCTC) | Khác mục đích — feature này per-order |
| 3 | Tài chính cho đơn product/prepaid/internal | Day-1 chỉ service order |
| 4 | Export Excel financial summary | Phase 2 |
| 5 | Notification cảnh báo lỗ qua SMS/Email | Phase 2 |
| 6 | Per-branch fixed cost rate | Day-1 system-wide; Phase 2 nếu cần |
| 7 | Backfill fixed_cost_rate cho order cũ | Tránh đảo P&L lịch sử |
4) Quyết định đã khóa (highlight)
| Quyết định | Ý nghĩa nghiệp vụ | Ref |
|---|---|---|
| Build action backend, KHÔNG aggregate FE | Cross-DB + nhiều nguồn dữ liệu, FE không đủ context | source-of-truth.md DEC-001 |
| Phân quyền qua Dynamic Permission v2 | POS/CRM có thể được cấp action sau, không hard-code role | DEC-003 |
fixed_cost_amount là high-water mark | Tránh refund làm giảm overhead đã phát sinh | DEC-012 |
Vật tư trạng thái Đang phát triển, không cộng P&L | Định lượng chưa khóa, tránh số sai | DEC-006 |
| Cảnh báo lỗ ghi rõ "Chưa gồm chi phí vật tư" | Minh bạch với user, tránh hiểu nhầm | DEC-015 |
5) Bản đồ ảnh hưởng
| Khu vực | Reuse / Extend / Build mới | Chú ý chính | Ref |
|---|---|---|---|
| UI sidebar | 🔧 Extend OrderReceiverInfo | Chèn section TÀI CHÍNH trước DỮ LIỆU | ui-spec.md |
| App Settings UI | 🔧 Extend SystemTable order group | Thêm field Tỷ lệ chi phí cố định (%) | ui-spec.md |
| Backend action | 🆕 Build mới GetOrderFinancialSummary (theo pattern GetListTourLimit) | Aggregate parent invoice + commission + tour + (vật tư pending) + fixed cost | dev-spec.md |
| DB schema | 🔧 Extend ecommerce.order | Thêm fixed_cost_rate NUMERIC, fixed_cost_amount BIGINT | dev-spec.md C4 |
| Hasura metadata | 🔧 Extend | Thêm action permission + 2 module action | dev-spec.md C5 |
| Permission seed | 🔧 Extend | Migration insert module_permission_action + default role_module.actions | dev-spec.md C8 |
| Event handler | 🔧 Extend invoice_complete.go | Update fixed cost high-water mark | dev-spec.md C5 |
| QA / Regression | Manager/Admin xem đơn hiện có; thanh toán + hoàn tiền; permission revoke | Negative invoice sign bug | qa-test-plan.md |
6) Rủi ro và blocker
| Mức | Rủi ro / blocker | Phụ trách | Cách xử lý |
|---|---|---|---|
| Cao | Negative invoice customer_paid_amount sign behavior chưa rõ | BE Dev | QA blocker test 4 case: thanh toán → hoàn 1 phần → hoàn full → thanh toán lại |
| Trung bình | Order cũ chưa có fixed_cost_rate | TL | UI ẩn dòng fixed cost nếu rate=NULL; document trong handoff |
| Trung bình | Permission revoke không có hiệu lực ngay | FE Dev | Refetch sau permission change; document UX rõ "cần refresh trang" |
| Thấp | Sidebar overflow trên màn nhỏ | UI/UX | CSS max-height + overflow-y cho left side |
7) Tóm tắt bàn giao
| Nhóm | Việc chính | File cần đọc |
|---|---|---|
| PO/BA | Chốt phạm vi, DEC, công thức, PD | decision-brief.md, prd.md |
| UI/UX | Wireframe section TÀI CHÍNH, copy state, cảnh báo lỗ | ui-spec.md |
| FE | Mount component sidebar, state machine, permission gating | ui-spec.md, dev-spec.md |
| BE | Action handler, migration, hook invoice_complete, permission seed | dev-spec.md |
| QA | Test theo FR/AC + 4 negative invoice case + permission matrix | qa-test-plan.md |
| TL / Delivery | Chia việc, theo dõi blocker, sign-off | handoff.md |
8) Điểm còn mở
| ID | Câu hỏi | Phụ trách | Hạn | Ảnh hưởng nếu chưa chốt |
|---|---|---|---|---|
| PD-001 | Đơn đã hủy có cộng tỷ suất lợi nhuận chi nhánh không? | PO + BOD | 02/05/2026 | Day-1 mặc định KHÔNG cộng — block report tỷ suất chi nhánh nếu đổi |
| PD-002 | Tour cost include phần đã trả KTV chưa? | TL + Kế toán | 03/05/2026 | Day-1 include theo tour_money — block formula nếu đổi |