solution-erp/docs/changelog/sessions/2026-06-09-S55-master-data-import.md

# S55 (2026-06-09) — Nạp master data thật từ Excel + Project +4 cột (Mig 48) — HMW-mode ON, prod-verified

> **Commit `69cb393` → Gitea Run #377 PASS ~4m33s, prod-verified.** Anh: `/session-start` → giao file Excel "HẠNG MỤC CÔNG VIỆC DỰ ÁN" → "nạp master data vào đi nhé" → `/ultra-on "workflow làm xong hết đi nhé"`. HMW fan-out cross-stack, ship to prod.

## Yêu cầu
Nạp master data thật của công ty từ file Excel 7-sheet (`00- DATA- HẠNG MỤC CÔNG VIỆC DỰ ÁN - trình ký online (1).xlsx`) vào hệ thống.

## Quyết định (anh chốt qua AskUserQuestion)
- **Q1 schema:** Project thiếu 4 field (Năm/Chủ đầu tư/Địa điểm/Gói thầu) → **thêm cột thật + migration** (không gói Note).
- **Q2 target:** **Cả 3 entity → Dev rồi deploy prod** (coexist với demo master cũ).

## Data inventory (Excel 7 sheet → 3 nguồn loadable)
| Sheet | → Bảng | Số |
|---|---|---|
| `00- Project list` | `Project` | **62** dự án (Mã + Năm; ~6 có tên/CĐT/địa điểm/gói thầu đầy đủ) |
| `01_Final - Hạng mục` / `00- DATA` | `WorkItem` | **71** (Vật tư 16 · Thầu phụ 30 · MEP 9 · Thiết bị 16) |
| `00- Data list TP_NCC` | `Supplier` | **3** mẫu (TRUONGGIANG/TANPHU/TGN — template 40 cột) |

**Data-quality catch (em main):** sheet Hạng mục cột MEP **gộp 2 nhóm** (9 MEP Sub + divider "THIẾT BỊ" + 16 Equipment). Pass 1 lùa hết 26 vào "MEP" + bắt nhầm divider "THIẾT BỊ" làm item → **fix split** (col J label) → đúng 71 item / 4 category. Provenance: `scripts/master-import-data.generated.md` (generated, source-of-truth cho seed).

## HMW flow (8-agent roster, fan-out + sequential verify)
- **P0/P1 recon** — 🟦 investigator-codebase: map Master schema thật. KEY finding: `WorkItem` master **ĐÃ TỒN TẠI** (Code/Name/Category/IsActive) → Hạng mục resolves favorably (no new table). Seed pattern = `SeedDemoMasterDataAsync` per-code idempotent **UNGATED** (reaches prod by design).
- **P2 execute (parallel, file-disjoint):**
  - 🟨 implementer-backend: Project entity +4 (`Year int?` · `Investor/Location/Package string?` maxlen 250/500/300) + `ProjectConfiguration` + **Mig 48 `AddProjectMasterFields`** (3-file, applied Dev+Design) + `ProjectFeatures` DTO/Create/Update/validators/handlers/projections +4 + **`SeedRealMasterDataAsync`** (62+71+3, per-code idempotent, wired UNGATED line 118 sau SeedCatalogsAsync).
  - 🟧 implementer-frontend: `ProjectsPage.tsx` form +4 input (Năm/Chủ đầu tư/Địa điểm/Gói thầu) + bonus cột "Chủ đầu tư" + `types/master.ts` +4 — **2 app SHA256-identical** (`b0020610…` / `93ac1b0f…`). npm build ×2 PASS.
- **Runtime Dev proof (em main):** chạy API trên Dev → DbInitializer seed → sqlcmd verify: 62 proj/71 wi/3 sup landed, `CAL01.Investor` populates, 0 overflow/dup-crash.
- **P4 reviewer** 🟥: ran 293s/31-tools nhưng **truncated trước verdict** (gotcha #53) → em main hoàn tất đúng việc nó định (clean `dotnet test` = 216 PASS, giải tỏa cached-binary concern) + 10-dim verify.
- **P3 harvest** 👤: proxy-append 2 MEMORY truncated (implementer-backend + reviewer); FE+investigator self-appended. Containment: git-diff legit-only + Qdrant chunk 2418=2418 (0 rogue RAG-write).
- **commit → cicd** 🟩: Run #377 PASS prod-verified.

## Verification
- **Build 0-err · Test 216 PASS** (58 Domain + 158 Infra; +1 compile-fix dòng `MasterCatalogFilteredUniqueTests` thêm 4 null args cho CreateProjectCommand — necessary, không phải scope-creep).
- **Runtime Dev:** all real data landed, Investor col works.
- **Prod (Run #377 / run_number 263):** Mig 48 applied · Projects spot-6/6 (APVN01…ZOTE01) · WorkItems VT/TP/MEP/TB=71 · Suppliers 3 · CAL01.Investor="Công ty TNHH Calofic" (N-literal) · bundle admin `DmjI8Cmn`→`B-d6893W` / user `YxL_MljK`→`XdKzt9LL` · health 200/200 · /api/projects 401 wired. Prod totals: Projects=70 (62 real + 8 demo coexist), WorkItems=86.

## Key design facts
- **Ungated seed = reaches prod:** `SeedDemoMasterDataAsync` (suppliers/projects) + `SeedCatalogsAsync` (workitems) đều gọi NGOÀI gate `if(!demoSeedDisabled)` (line 108/115) — by design (DbInitializer:75 comment "GIỮ … SeedDemoMasterData/Catalogs" cả khi DemoSeed:Disabled=true). `SeedRealMasterDataAsync` mirror = wired ungated line 118 → real data tự lên prod khi deploy.
- **Per-code idempotent** (`existingCodes.Contains(code)→skip; else Add`) — re-run safe, coexist demo, expand-over-time. **FLOCK01 collision** (demo có sẵn) → real FLOCK01 skip (demo thắng; real code+year only, acceptable). Note cho công ty: sửa tên FLOCK01 qua UI nếu cần.
- **No new table** (Mig 48 = 4 AddColumn) → tables vẫn 92. Mig 47→**48**.

## Lessons
- **2 agent return truncated** (implementer-backend + reviewer, gotcha #53) → em main recover qua **disk/runtime truth** (build/test/sqlcmd/git), KHÔNG agent return-message (`feedback_agent_kill_recovery`). cicd verdict-FIRST brief → KHÔNG truncate (PASS clean) — reinforces "emit verdict early".
- **Real-data import discipline:** extract Excel → clean generated spec file (chống truncation khi nhồi 136 dòng vào brief) → implementer convert to C# → runtime Dev proof TRƯỚC prod (catch overflow/dup) → cicd sqlcmd spot-check real Codes + N-literal cho unicode field.
- **Data-quality:** đọc cấu trúc Excel THẬT (merged col, divider row) trước khi map — pass 1 nhầm divider "THIẾT BỊ" = item; split đúng theo label col.

## Files (17 committed `69cb393` + scratch)
BE: `Project.cs` · `ProjectConfiguration.cs` · `ProjectFeatures.cs` · `DbInitializer.cs` (+210, seed) · `Mig 48` 3-file. FE: `ProjectsPage.tsx` + `types/master.ts` ×2 app. Test: `MasterCatalogFilteredUniqueTests.cs` (compile-fix). Provenance: `scripts/master-import-data.generated.md`. Memory: 4 agent MEMORY (2 self + 2 proxy).