# PROJECT-MAP — Bản đồ toàn cảnh

> Đọc file này nếu cần deep context (~15 phút). Nếu chỉ cần snapshot → đọc [`STATUS.md`](STATUS.md).

## Module map

```
┌─────────────────────────────────────────────────────────────────┐
│                      SOLUTION_ERP                                │
└─────────────────────────────────────────────────────────────────┘

 ╔════════════════╗   ╔════════════════╗   ╔════════════════╗
 ║  IDENTITY      ║   ║  DANH MỤC      ║   ║  QUẢN LÝ HĐ    ║
 ║  (Phase 1)     ║   ║  (Phase 1)     ║   ║  (Phase 1-3)   ║
 ╠════════════════╣   ╠════════════════╣   ╠════════════════╣
 ║ User           ║   ║ Supplier       ║   ║ Contract       ║
 ║ Role           ║   ║ Project        ║   ║ ContractType   ║
 ║ Permission     ║   ║ Department     ║   ║ ContractForm   ║
 ║ MenuKey        ║   ║ ContractClause ║   ║ Approval       ║
 ║ AuditLog       ║   ║ (điều kiện     ║   ║ Comment        ║
 ║                ║   ║  chung - 002.04)║   ║ Attachment     ║
 ╚════════════════╝   ╚════════════════╝   ║ AuditTrail     ║
                                           ╚════════════════╝

 ╔════════════════╗   ╔════════════════╗   ╔════════════════╗
 ║  FORM ENGINE   ║   ║  WORKFLOW      ║   ║  BÁO CÁO       ║
 ║  (Phase 2)     ║   ║  (Phase 3)     ║   ║  (Phase 4)     ║
 ╠════════════════╣   ╠════════════════╣   ╠════════════════╣
 ║ Template       ║   ║ StateMachine   ║   ║ Dashboard      ║
 ║ Renderer       ║   ║ Transition     ║   ║ ExcelExport    ║
 ║ (DOCX/XLSX)    ║   ║ SlaTimer       ║   ║ FilterQuery    ║
 ║ Field mapping  ║   ║ Notification   ║   ║                ║
 ║ PO gen (F.07)  ║   ║ CodeGenerator  ║   ║                ║
 ║                ║   ║ (RG-001)       ║   ║                ║
 ╚════════════════╝   ╚════════════════╝   ╚════════════════╝
```

## Domain entities chính (dự kiến)

```
User ────< Role ────< Permission (Role × MenuKey × CRUD)
User ────< AuditLog

Supplier (NCC)
Project (Dự án)
Department (Phòng ban)

Contract
  ├── Type: HĐTP | HĐGK | NCC | HĐDV | HĐ Mua bán | ...
  ├── Phase (9 state — xem workflow-contract.md)
  ├── Supplier, Project, Drafter
  ├── MaHopDong (gen theo RG-001)
  ├── Approvals[] (audit ai ký phase nào)
  ├── Comments[] (thread góp ý Phase 3 của workflow)
  ├── Attachments[] (scan bản gốc, file export)
  └── TemplateData (JSON — field đã điền khi render form)

ContractTemplate (ánh xạ Type → File mẫu FO-002.xx)
ContractClause (điều khoản chung FO-002.04 — rich text)
PurchaseOrder (có thể đính với Contract hoặc standalone)
```

## API namespace dự kiến

```
/api/auth          — login, refresh, logout, register (admin gate)
/api/users         — CRUD user, assign role, reset password
/api/roles         — CRUD role, permission matrix
/api/menus         — menu tree + permission resolution

/api/suppliers     — CRUD NCC
/api/projects      — CRUD dự án
/api/departments   — CRUD phòng ban

/api/contracts     — CRUD + query by phase/project/supplier
/api/contracts/{id}/transitions  — state machine action
/api/contracts/{id}/comments     — thread góp ý
/api/contracts/{id}/attachments  — upload/download

/api/forms         — template catalog
/api/forms/{id}/render — render template → docx/xlsx (Phase 2)

/api/reports/dashboard  — KPI tổng hợp
/api/reports/export     — Excel download
```

## FE screens dự kiến

### fe-admin (:8082) — cho Admin + Role quản lý

- `/login`
- `/dashboard` — KPI system
- `/master/users` + `/master/roles` + `/master/permissions`
- `/master/suppliers` + `/master/projects` + `/master/departments`
- `/master/contract-templates` + `/master/contract-clauses`
- `/contracts` — danh sách toàn bộ, filter phase/dự án
- `/contracts/{id}` — detail + approval panel + audit log
- `/reports` + `/system/audit-log`

### fe-user (:8080) — cho Drafter, TBP, PD/PM, BOD, CCM, ...

- `/login`
- `/inbox` — HĐ đang chờ tôi xử lý (filter theo role × phase)
- `/contracts/new` — chọn template + điền form + submit
- `/contracts/{id}` — detail, comment, approve/reject
- `/my-contracts` — HĐ tôi đã tạo/tham gia

## Flow chính (Phase 3 — trình ký HĐ end-to-end)

```
Drafter (QS/NV.PB)
  ├─ [POST /api/contracts] tạo draft + chọn template
  ├─ [POST /api/forms/{id}/render] fill + preview
  ├─ [POST /api/contracts/{id}/transitions] DangSoanThao → DangGopY
  │
PD/PM/PRO/CCM/FIN/ACT  (song song)
  └─ [POST /api/contracts/{id}/comments] góp ý
  
Drafter
  ├─ [PATCH /api/contracts/{id}] revise
  ├─ [POST /api/contracts/{id}/transitions] DangGopY → DangDamPhan → DangInKy
  │
NTP/NCC/TĐ (external — Drafter update thay)
  └─ upload scan có chữ ký đối tác

Drafter
  └─ [POST /api/contracts/{id}/transitions] → DangKiemTraCCM

CCM
  └─ [POST /api/contracts/{id}/transitions] → DangTrinhKy

BOD/NĐUQ
  └─ [POST /api/contracts/{id}/transitions] → DangDongDau (GEN mã HĐ ở đây!)

HRA
  └─ [POST /api/contracts/{id}/transitions] → DaPhatHanh (upload scan có dấu)
```

## External dependencies

- **SQL Server** — chính thức, dev có thể LocalDB hoặc Docker (`docker-compose.yml`)
- **IIS** — deploy target (Windows Server 2019+)
- **Gitea** — git remote (URL chờ user cấp)
- **Aspose.Words / DocumentFormat.OpenXml** — render .docx (Phase 2, quyết định khi đó)
- **EPPlus hoặc ClosedXML** — render .xlsx (Phase 2)

## Non-goals (KHÔNG làm)

- ❌ Python AI service (user đã quyết gác vô thời hạn)
- ❌ Mobile app
- ❌ Multi-tenant (1 instance / 1 công ty)
- ❌ Tích hợp e-signature (Phase 6+ nếu có)
- ❌ Tích hợp SAP/Bravo ERP (Phase 6+ nếu có)
- ❌ Public API / external webhooks