# Forms Specification — SOLUTION_ERP

> **Nguồn:** `D:\Dropbox\CONG_VIEC\SOLUTION\FORM\` (8 file)
> **Raw dump:** [`forms-spec-raw.md`](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