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).

---

# S55 cont. — Phase 1 FE redesign fe-admin (density-first, giữ brand) — commit `7feb53e`, Run #378 prod-verified

## Yêu cầu
Sau `/check-email NAMGROUP` (nhận bộ quy ước UI density-first ERP của NAMGROUP), anh: *"thiết kế lại giao diện cho đẹp hơn, tham khảo NAMGROUP, cho designer làm đúng chức năng, workflow plan + làm luôn"*.

## Design direction
NAMGROUP density-first (button 12px font-semibold, input py-1.5 ≤36px rounded-lg, label uppercase tracking-wider, table actions always-visible, no font-bold/shadow trang trí) **GIỮ brand SOLUTION** (#1F7DC1 + Be Vietnam Pro — NAMGROUP nói rõ brand=Solution tự quyết, chỉ mượn cấu trúc).

## Workflow (phased — 68 trang không thể 1 lần)
- **Phase 1 (session này):** foundation + flagship · fe-admin · 🩷 frontend-designer. **Phase 2:** roll out trang chính. **Phase 3:** mirror fe-user.

## Done (Phase 1 — commit `7feb53e`, Run #378 PASS ~4m24s)
- **🩷 frontend-designer** 14 file fe-admin: `index.css` (density heading-ladder semibold + `.label-eyebrow` 11px uppercase + drop font-bold) · 6 UI primitive · 6 shell (DataTable/Layout/TopBar/PageHeader/PhaseBadge/EmptyState) · DashboardPage flagship. Build 0 TS err.
- **🟥 reviewer PASS** 0 blocker: regression all-preserved (variant/size keys stable, props/forwardRef intact, DataTable Column API unchanged, Layout nav/perm intact), brand-confirmed, exactly 14 file. 2 minor a11y defer (slate-400 hint nhỏ borderline WCAG-AA, hint-role OK).
- **🟩 cicd Run #378:** admin bundle `B-d6893W`→`4SUwDLD8` (redesign shipped) · user `XdKzt9LL` UNCHANGED (asymmetric FE-admin-only verify = scope-correct) · no new mig · health 200/200.

## Lessons
- **Dev auth-rig chặn authed-page screenshot** (designer rig-gotcha #3): API ép HTTPS :5443 (Program.cs override `ASPNETCORE_URLS`) vs Vite proxy `http://:5443` → mismatch → login fail; + Dashboard = ProtectedRoute cần JWT. → **đáng tin nhất = deploy prod rồi login thật xem authed pages** (đừng vật lộn dev-rig). Designer + em main đều bị chặn → user chọn commit+deploy.
- **2 agent return truncated** (designer + reviewer-#1, gotcha #53) → em main recover qua disk (build + login-visual `/login` screenshot on-brand + diff-review index.css/Button/DashboardPage high-quality). reviewer-#2 + cicd verdict-FIRST → KHÔNG truncate.
- **Asymmetric bundle verify** (single-app FE redesign): admin PHẢI rotate (proof shipped) + user PHẢI frozen (proof scope-correct) — user-unchanged = positive signal.

## Files (16 committed `7feb53e`)
13 fe-admin (index.css + 6 ui + 6 shell + DashboardPage) + 2 agent MEMORY (frontend-designer proxy + reviewer self).