solution-erp/docs/forms-spec.md

Forms Specification — SOLUTION_ERP

Nguồn: D:\Dropbox\CONG_VIEC\SOLUTION\FORM\ (8 file) Raw dump: forms-spec-raw.md — text gốc extract từ docx/xlsx Phase 2 deliverable: parse từng form → template engine (điền field tự động → export .docx/.xlsx giống 100% mẫu)

Danh mục 8 form

Mã form	Tên	Loại file	Mục đích	Trạng thái parse
SOL-CCM-FO-002.01	Bảng kiểm tra hợp đồng	.docx	Checklist 4 bộ phận (Đề xuất / Cung ứng / CCM / Giám đốc) review HĐ trước ký	✅ Parsed — table 40×13
SOL-CCM-FO-002.02	Hợp đồng trọn gói (nhân công + vật tư)	.doc	Template HĐ thầu phụ trọn gói cung cấp cả NC + VT	⚠️ Cần convert .doc → .docx (COM/LibreOffice) ở Phase 2
SOL-CCM-FO-002.03	Hợp đồng trọn gói (nhân công + thiết bị)	.doc	Template HĐ thầu phụ trọn gói cung cấp NC + TB	⚠️ Cần convert .doc → .docx ở Phase 2
SOL-CCM-FO-002.04	Điều kiện chung hợp đồng trọn gói	.docx	Phần điều khoản chung (5+ điều: am hiểu TL, nội dung CV, tiến độ, xử lý tranh chấp, sửa đổi HĐ)	✅ Parsed — narrative text
SOL-CCM-FO-002.05	Hợp đồng Giao khoán	.docx	Template HĐ giao khoán NC/Tổ đội — 10 table (thông tin, giá trị, hạng mục, nghiệm thu, thanh toán)	✅ Parsed — 10 tables
SOL-CCM-FO-002.06	Hợp đồng mua bán	.doc	Template HĐ mua bán (NCC cấp vật tư, thiết bị)	⚠️ Cần convert .doc → .docx ở Phase 2
SOL-CCM-FO-002.07	Đơn đặt hàng (PO)	.xlsx	3 sheet: (F.01)_SS GIA (so sánh giá NCC), PO (đơn đặt hàng chính), Po01 NLT (sua) (PO nguyên liệu)	✅ Parsed — 3 sheets
SOL-CCM-RG-001	Quy định mã số hợp đồng	.docx	Regex + convention đánh mã HĐ và PO (bảng ví dụ)	✅ Parsed

---

Detail — các form đã parse được

SOL-CCM-FO-002.01 — Bảng kiểm tra hợp đồng

Nhóm field thông tin HĐ (phần trên bảng):

• phong_ban_du_an (Phòng ban / Dự án) — string
• loai_hop_dong — enum: ChuDauTu | NCC | ThauPhu | ToDoi | ThietBiThue | Khac
• ten_doi_tac — string
• noi_dung_hop_dong — text

Nhóm field checklist theo bộ phận (mỗi row = 1 bộ phận × nội dung × ý kiến):

Bộ phận	Nội dung kiểm tra (check)	Field dữ liệu
PHÒNG BAN/DỰ ÁN (Đề xuất)	Soạn thảo (✓), Nội dung HĐ	de_xuat_soan_thao: bool, de_xuat_noi_dung_ok: bool, de_xuat_ho_ten, de_xuat_ngay, de_xuat_y_kien: text
PHÒNG CUNG ỨNG	Điều khoản HĐ, Điều khoản t/toán, Rủi ro pháp lý HĐ	cung_ung_dieu_khoan: bool, cung_ung_thanh_toan: bool, cung_ung_rui_ro: bool, cung_ung_ho_ten, cung_ung_ngay, cung_ung_y_kien: text
PHÒNG CCM	G/trị HĐ so với NS, Rủi ro pháp lý HĐ	ccm_gia_tri_so_ns: bool, ccm_rui_ro: bool, ccm_ho_ten, ccm_ngay, ccm_y_kien: text
GIÁM ĐỐC (hoặc ủy quyền)	Ký kết, phát hành	gd_ky_ket: bool, gd_ho_ten, gd_ngay, gd_y_kien: text

Business rule (từ ghi chú cuối bảng):

• HĐ với Chủ đầu tư → Đơn vị đề xuất có thể bypass Cung ứng + CCM, chuyển thẳng Giám đốc.
• Các loại khác → PHẢI qua Cung ứng + CCM trước.
• Mỗi bộ phận 01 ngày xử lý. Quá 1 ngày không phản hồi → auto approve ("xem như đã thông qua").
• Nếu cần kéo dài → phải ghi chú vào "Ý kiến" + thông báo cho Đề xuất.

→ Mapping sang workflow state: file này chính là thể hiện UI của workflow bên workflow-contract.md.

SOL-CCM-FO-002.04 — Điều kiện chung

Pure narrative template — 5+ điều khoản cố định (AM HIỂU TÀI LIỆU, NỘI DUNG CV, TIẾN ĐỘ, XỬ LÝ TRANH CHẤP, SỬA ĐỔI HĐ). Không có field động — dùng làm appendix cố định đính kèm cho HĐ trọn gói.

→ Data model: lưu dạng ContractClauseTemplate với Content: text (markdown), version theo đợt cập nhật. Cho phép admin edit qua rich text editor.

SOL-CCM-FO-002.05 — Hợp đồng Giao khoán

10 bảng. Các nhóm field chính (suy từ số row/col):

• Thông tin 2 bên (Bên A + Bên B) — 4 row × 2 col
• Giá trị HĐ + hạng mục công việc — 8 row × 8 col (chi tiết hạng mục, đơn giá, khối lượng, thành tiền)
• Nghiệm thu + thanh toán — 6 row × 4 col
• Bảng tiến độ — 9 row × 11 col
• Ký tên 2 bên — 1 row × 2 col

→ Phase 2: parse từng table chi tiết sau khi có cấu trúc DB ổn định.

SOL-CCM-FO-002.07 — Đơn đặt hàng (xlsx)

Sheet	Rows × Cols	Mục đích
(F.01)_SS GIA	84 × 36	So sánh giá nhiều NCC cho cùng mặt hàng (chọn NCC tốt nhất)
PO	80 × 17	Đơn đặt hàng chính — template chuẩn
Po01 NLT (sua)	74 × 12	Variant PO cho NLT (nguyên liệu?)

→ Phase 2: implement xuất file Excel đúng format — dùng EPPlus hoặc ClosedXML thay vì OpenXml thủ công (giữ được style, formula, merged cells).

SOL-CCM-RG-001 — Quy định mã số hợp đồng ⭐ (critical — dùng ở Phase 3)

Contract code format:

Loại HĐ	Format	Ví dụ
HĐ Thầu phụ (TP)	{ProjectCode}/HĐTP/SOL&{PartnerAbbr}/{Seq}	FLOCK 01/HĐTP/SOL&HD/01
HĐ Giao khoán / Tổ đội / Nhân công cơ hữu	{ProjectCode}/HĐGK/SOL&{PartnerAbbr}/{Seq}	FLOCK 01/HĐGK/SOL&PVL/01
HĐ NCC (cấp riêng từng dự án)	{ProjectCode}/NCC/SOL&{PartnerAbbr}/{Seq}	FLOCK 01/NCC/SOL&CC1/01
HĐ nguyên tắc NCC	{Year}/NCC/SOL&{PartnerAbbr}/{Seq}	2026/NCC/SOL&AKATI/01
HĐ Dịch vụ (cấp riêng)	{ProjectCode}/HĐDV/SOL&{PartnerAbbr}/{Seq}	FLOCK 01/HĐDV/SOL&KG/01
HĐ nguyên tắc Dịch vụ	{Year}/HĐDV/SOL&{PartnerAbbr}/{Seq}	2026/HĐDV/SOL&TTL/01

PO code format:

Loại PO	Format	Ví dụ
PO vật tư, thiết bị (theo HĐ Nguyên tắc)	{ProjectCode}/{PartnerAbbr}/PO {Seq}	FLOCK 01/TRUNGDUNG/PO 01
PO với TP/NCC/ĐVDV (không theo HĐ Nguyên tắc)	{ProjectCode}/PO/SOL&{PartnerAbbr}/{Seq}	FLOCK 01/PO/SOL&PVL/01

Seq bắt đầu từ 01, tăng dần theo dự án + loại HĐ + đối tác.

→ Domain service Phase 3: IContractCodeGenerator.Generate(project, type, partner) → string — transactional để tránh race condition khi gen Seq.

---

TODO Phase 2 (form engine)

• Convert 3 file .doc (FO-002.02, 002.03, 002.06) sang .docx qua COM automation hoặc LibreOffice headless
• Parse chi tiết field của 5 file template HĐ (002.02, .03, .04, .05, .06) — mỗi form thành 1 spec JSON
• Xây template engine: Template + data → output .docx/.xlsx (dùng DocumentFormat.OpenXml hoặc Aspose.Words + EPPlus)
• UI form builder cho admin: gán template ↔ loại HĐ ↔ field layout
• Preview PDF trước khi export final