[CLAUDE] Docs: S55 closeout — master data import từ Excel (Run #377) + Mig 47→48 + ef-core skill

62 dự án + 71 hạng mục + 3 NCC real loaded prod (SeedRealMasterDataAsync ungated). Mig 48 AddProjectMasterFields. STATUS/HANDOFF/session log + CLAUDE.md root mig count + ef-core SKILL migration table. 2 agent return truncated (BE+reviewer) → em main disk/runtime-recover lesson.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

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

@@ -0,0 +1,47 @@
+# 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).