Tiến độ thực hiện

Module rp_progress quản lý nghiệm thu khối lượng từ HĐ nhà thầu, tự động tính progress weighted theo BOQ, trigger tạo hóa đơn thanh toán cho NT.

7.1 Tổng quan

BBN nghiệm thu (Biên bản nghiệm thu) là chứng từ trung tâm:

• Tạo từ milestone trên HĐ nhà thầu
• Mỗi BBN có nhiều lines = KL nghiệm thu theo hạng mục
• State workflow: draft → proposed → approved → trigger invoice

rp.contract.payment.milestone (Mốc thanh toán)
  └── action_create_acceptance
        ↓
        rp.progress.acceptance (BBN)
          ├── rp.progress.acceptance.line (dòng KL nghiệm thu)
          └── action_create_invoice → account.move (vendor bill)

Vai trò các bên ký

Vai trò	Trách nhiệm
PTDA (Project Director)	Kiểm tra KL nghiệm thu vs scope HĐ
KT trưởng	Kiểm soát chi phí + tax
GĐ điều hành	Phê duyệt cuối cùng
NT đại diện	Ký xác nhận KL thực hiện

7.2 BBN nghiệm thu

Từ HĐ nhà thầu → tab Lịch thanh toán → click “Tạo BBN” trên milestone → rp.progress.acceptance auto-create:

Field	Auto-fill
Số BBN	BBNT-{YYYY/MM}-{HĐ_code}-{seq} — vd BBNT-2026/06-PKG-MEP-001-HD-001
Ngày BBN	Hôm nay
HĐ	PKG-MEP-001-HD
Milestone	(mốc đã click)
Project	KĐT nghỉ dưỡng Dalat (auto từ HĐ)
Bên A	Cty mẹ
Bên B	NT-A (auto từ HĐ)

Mẹo

Sequence number 001 reset mỗi tháng theo prefix {YYYY/MM}, đảm bảo unique + dễ tra cứu chứng từ.

7.3 BBN lines (dòng nghiệm thu)

Mỗi BBN có nhiều lines = KL nghiệm thu chia theo cấu trúc HĐ:

Field	Mô tả
Hạng mục	rp.structure (link tới Tower S1, S1-PT…)
Mô tả	Free text
KL kỳ này	Khối lượng nghiệm thu đợt này (vd 0.4 gói)
KL lũy kế	Σ KL từ đầu HĐ tới đợt này
Đơn vị tính	rp.progress.uom (gói, m², m³, kg, viên)
Đơn giá	Auto từ BOQ HĐ (có thể override)
Giá trị	KL × đơn giá
% hoàn thành item	KL lũy kế / KL HĐ × 100

Demo: 2 lines mẫu

Hạng mục	Mô tả	KL kỳ này	Lũy kế	Đơn giá	Giá trị	%
Tower S1	Lắp đặt hệ điện chính (lũy kế 40%)	0.4	0.4	18.000.000.000	7.200.000.000	40%
S1-PT	Phần thân MEP (lũy kế 30%)	0.3	0.3	7.000.000.000	2.100.000.000	30%

Σ giá trị BBN = 9.300.000.000 ₫.

7.4 State machine

Nháp → Đề xuất → Đã duyệt → (trigger invoice)
                    ↓
              Bị từ chối → Nháp (sửa + đề xuất lại)

State	Hành động
draft	Soạn BBN — sửa lines free
proposed	Đã gửi đề xuất duyệt (PTDA → KT → GĐ)
approved	Phê duyệt cuối → cho phép tạo hóa đơn
rejected	Bị từ chối — revert về draft, fix sai → đề xuất lại

Auto-action khi approved

• BBN.state = approved → milestone.state = accepted (track nghiệm thu xong)
• Button “Tạo Hóa đơn” trên milestone hiện active
• Email notify Bên B (NT) BBN đã duyệt

7.5 Weighted progress

% hoàn thành dự án tính theo công thức weighted:

progress_project = Σ (item_weight × item_progress)
  where:
    item_weight   = item.estimate_total / project.estimate_total
    item_progress = Σ BBN_lines.KL_lũy_kế / item.scope_HD

Ví dụ tính

Dự án 100 tỷ tổng khái toán, 3 items chính:

Item	Weight	Khái toán	KL nghiệm thu lũy kế	Item progress
Tower S1	50%	50 tỷ	40% scope	40% × 50% = 20%
Tower S2	30%	30 tỷ	25% scope	25% × 30% = 7.5%
HT-DMT	20%	20 tỷ	60% scope	60% × 20% = 12%

→ Progress dự án = 20% + 7.5% + 12% = 39.5%

Hiển thị trên project header + Gantt + dashboard.

Fallback simple average

Nếu chưa seed cost categories / chưa nhập estimate → fallback simple average (Σ item_progress / N items). System log warning để KT bổ sung estimate.

7.6 Trigger invoice từ BBN approved

Khi BBN.state = approved → milestone show button “Tạo Hóa đơn”:

Click → wizard popup:
  ├── Pre-fill: NT (Bên B), số tiền (milestone amount), VAT lines từ BOQ
  ├── User pick: Journal kế toán (mặc định từ company config)
  ├── User confirm → account.move (vendor bill draft) tạo
  └── BBN.invoice_id = bill_id (link 2 chiều)

Vendor bill auto-fill

Field	Source
Nhà cung cấp	NT từ HĐ
Số HĐ tham chiếu	PKG-MEP-001-HD
Milestone ref	(đã click)
Số tiền untaxed	milestone.amount
Lines	1 line / milestone (hoặc split theo BOQ nếu config)
Thuế	VAT 10% (theo BOQ HĐ)
Journal	Account Payable mặc định
State	draft (KT validate → posted)

Sau khi KT post → journal entries auto-tạo theo TT 200/2014/TT-BTC, vào sổ kế toán tổng.

7.7 Gantt + Dashboard

Gantt progress visualization

Trên Gantt view, mỗi row hạng mục có progress bar overlay:

• Màu xanh = % hoàn thành (từ BBN lũy kế)
• Màu xám = chưa làm
• Vạch dọc đỏ = today line
• Tooltip hover: BBN gần nhất + KL + giá trị

Dashboard KPI

Project header tile:

• Tổng giá trị HĐ ký
• Σ giá trị BBN approved (= giá trị đã nghiệm thu)
• % hoàn thành weighted
• Số HĐ đang chạy / đã hoàn tất
• Σ giá trị hóa đơn đã thanh toán

7.8 Báo cáo tiến độ

Báo cáo	Output	Use case
Tiến độ HĐ chi tiết	Theo HĐ × milestone × BBN, có KL + giá trị + %	KT theo dõi hàng tuần
Tiến độ dự án tổng hợp	Theo hạng mục × item progress weighted	PTDA báo cáo BLĐ
So sánh thực tế vs baseline	Δ ngày + Δ giá trị	Risk mgmt — flag HĐ trễ
Lịch sử BBN theo NT	Theo NT × BBN approved	Đánh giá NT đáng tin

Tất cả export Excel + PDF.

7.9 Smoke test

1. HĐ PKG-MEP-001-HD đang executing
2. Milestone "Giữa kỳ 50%" → click Tạo BBN
   ✓ BBNT-2026/06-PKG-MEP-001-HD-001 draft tạo
3. Add 2 lines KL nghiệm thu (Tower S1 40%, S1-PT 30%)
4. State: draft → proposed → approved (qua 3 cấp ký)
   ✓ milestone state = accepted
   ✓ button "Tạo Hóa đơn" hiện
5. Click Tạo Hóa đơn → vendor bill draft tạo
6. KT validate → state = posted
   ✓ Journal entries tạo theo TT 200
7. Project header refresh: progress weighted update
   ✓ Gantt row Tower S1 hiển thị 40% bar

---

Tiếp: Quản lý Vay →