solution-erp/docs/changelog/sessions/2026-05-21-s26-pe-tree-view-rag-setup.md

# Session 26 — 2026-05-21 — PE List tree view UI iteration + RAG Global MCP setup

**Dev:** Claude (em main + 4 sub-agents Investigator/Implementer/Reviewer/CICD Monitor) + bro pqhuy
**Duration:** ~5h (start ~17:00 → end ~22:00 GMT+7)
**Base commit:** `506cada` (S25 chốt cuối Plan AF)
**Final commits cumulative:** `0bf6c7e..d99069a` (6 commits Plan AG series push remote)
**+ Infrastructure:** `D:\.claude-rag\` RAG global server setup (out-of-tree, không commit)

---

## 🎯 Làm được

### Plan AG series — PE List tree view UI iteration (UAT bro Tra Sol)

#### Plan AG (`0bf6c7e`) — Phase 1 tree view 2-level Project > Gói thầu > PE

Trigger UAT 2026-05-21 screenshot bro Tra Sol + anh Kenny: UI Duyệt NCC PE List "đám rừng" flat list + đề xuất "khoanh sẵn thư mục gói thầu như mail".

🟦 **Investigator audit 5Q** (~30K spawn) confirm: Project entity ready Phase 2 ProjectPackage table, PE.TenGoiThau text free-form (variation risk), shadcn fe-user thiếu Accordion/Collapsible (fallback HTML `<details>/<summary>` native), Mig 31 stable, Phase 2 naming `AddProjectPackageTable`.

🟨 **Implementer Case 2 cookie-cutter mirror 2 app** (~16K spawn) deliver:
- Chunk A useMemo group nested `ProjectGroup{goiThauList[]}` + sort vi locale + fallback "(Dự án đã xoá)" + "(Chưa phân loại)"
- Chunk B UI `<details>/<summary>` HTML native 2-level + Tailwind named groups `group/proj` + `group/gt` chevron rotation + `[&::-webkit-details-marker]:hidden`
- Chunk C localStorage Set<string> persist key `pe_list_expanded_groups`

🟥 **Reviewer pre-commit** (~25K spawn) verify 5-category + 12 adversarial deep checks PASS 0 blocker.

🟩 **CICD Monitor Run #222** (~12K spawn) bundle hash 2 app rotated `C8TvDy7r→CWHIdoFo` admin + `BvcWrq2z→Bg2FNeIz` user. Stage 4c API shape preserved.

#### Plan AG2 (`c5429c0`) — Simplify 1-level + widen Panel 1

Bro feedback "Plan AG 2-level cầu kỳ quá, gói thầu thì ko cần thiết phải treedow". Em main solo refactor:
- Drop `GoiThauGroup` nested type
- useMemo group 1-level: `Map<projectId, ProjectGroup{items[]}>`
- Panel 1 widen `lg:grid-cols-[340px_1fr_360px]` → `[400px_1fr_360px]`
- Single PE project → flat card (no `<details>`); Multi PE → tree
- localStorage key rename `pe_list_expanded_projects`

#### Plan AG3 (`fbad4a9`) — Drop single-PE flat consistent UI

Bro screenshot follow-up "nếu có 1 thì cũng để tương tự luôn nhé, đừng để khác các thằng kia". Em main solo drop `if (pg.items.length === 1)` branch → mọi dự án dù 1/N phiếu đều render `<details>` folder collapsed. Diff -110 LOC (clean).

#### Plan AG4 (`2bf0118`) — BE+FE bổ sung Drafter + Department

Bro feedback "bổ sung thêm người tạo + phòng ban tạo vào danh sách phiếu". Em main solo cross-stack:

**BE 4 file:**
- `PurchaseEvaluationDtos.cs` DTO +4 fields `DrafterUserId/DrafterName/DepartmentId/DepartmentName`
- `PurchaseEvaluationFeatures.cs` ListHandler + InboxHandler projections JOIN Users + Departments LEFT (cả 2 nullable theo PE entity)
- `CreateContractFromEvaluationFeatures.cs` ApprovedHandler mirror JOIN

**FE 4 file × 2 app mirror §3.9:**
- `types/purchaseEvaluation.ts` PeListItem +4 fields
- `PurchaseEvaluationsListPage.tsx` PE card row render `👤 {drafterName} · {departmentName}` giữa Mã phiếu và Supplier

Verify: `dotnet test SolutionErp.slnx` 111/111 PASS unchanged. `npm build` × 2 app clean 0 TS err.

#### Plan AG5 (`083b601`) — Extend tree 3-level Project > Năm > NCC > PE

Bro chốt "Folder cấp dưới dự án là theo năm và dưới năm là theo NCC nhé". Em main solo refactor:
- `type SupplierGroup{supplierId, supplierName, items[]}` (italic "(Chưa chọn NCC)" cho PE chưa DaDuyet)
- `type YearGroup{year, suppliers[], totalCount}` extract `new Date(p.createdAt).getFullYear()`
- `type ProjectGroup{projectId, projectName, years[], totalCount}`
- 3 cấp nested `<details>` với Tailwind named groups `group/proj` + `group/year` + `group/sup`
- Sort: Project A-Z vi · Year DESC · NCC A-Z vi · PE createdAt DESC
- localStorage 3-level key format `projectId / projectId::y{year} / projectId::y{year}::s{supplierId}`

#### Plan AG6 (`d99069a`) — Compact card 3-row gọn đẹp

Bro feedback "Cho thông tin bên trong này nó gọn đẹp lại nhé". Em main solo:
- `py-2.5` → `py-2` (compact vertical padding)
- Drop Type label "Duyệt NCC" badge (redundant với page header)
- Combine row mã phiếu + time `PE/2026/A/035 · 10:40 19/05/2026`
- Combine row drafter + department + contract `👤 Drafter · Phòng ban   [✓ HĐ]` (conditional)
- Separator `slate-300` nhẹ hơn để mắt không bị rối

### Plan AI — RAG User-level Global MCP setup (Approach A)

Bro plan setup RAG cho 5 dự án cùng máy localhost share infrastructure. Em main + Investigator deep research 4 study cases (Cursor + Cline + Continue + Sourcegraph) → kết luận User-level Global MCP pattern (1 dev N project, không phải team VPS pattern).

#### Phase 0 — Pre-flight check (15 phút)

✅ Python 3.11.3 OK · ✅ Docker installed nhưng SKIP per bro chốt no Docker · ❌ VOYAGE_API_KEY chưa set → bro set User scope length 46 prefix pa-Mi... · ✅ Disk D:\\ 32GB free (acceptable) · ✅ pip packages install fastmcp 3.3.1 + voyageai 0.3.7 + qdrant-client 1.18.0 + watchdog 6.0.0 + chromadb 1.5.9 (bonus) + python-dotenv 1.2.2.

#### Phase 1 — Qdrant Windows native binary (30 phút)

Bro chốt KHÔNG Docker → em verify Qdrant GitHub releases qua WebFetch:
- ✅ Qdrant v1.18.0 (released 2026-05-11) **CÓ Windows native binary** `qdrant-x86_64-pc-windows-msvc.zip` 28.3 MB chính thức
- Download + extract `D:\.claude-rag\qdrant-bin\qdrant.exe`
- Tạo config.yaml: storage_path `D:\.claude-rag\data\qdrant-storage`, http_port 6333, on_disk_payload true, telemetry_disabled true
- Start background hidden: PID 67240, health check 200 "healthz check passed"

#### Phase 2 — FastMCP server code ~1100 LOC Python 9 file

```
D:\.claude-rag\
├── server.py (210 LOC) — FastMCP entry + 6 tool handlers
├── bootstrap.py (150 LOC) — initial corpus embed CLI
├── README.md
└── lib/
    ├── __init__.py
    ├── projects.py (140 LOC) — auto-detect cwd → project_id từ .claude/rag.json + registry tracking
    ├── chunking.py (120 LOC) — Markdown chunking + Anthropic Contextual Retrieval prepend "From <doc> > <heading>:"
    ├── embed.py (140 LOC) — Voyage AI wrapper (embed + rerank + retry exponential backoff + SHA256 cache)
    ├── retrieval.py (230 LOC) — 3-layer pipeline (Vector Qdrant + BM25 SQLite FTS5 + RRF k=60 + Voyage rerank-2.5)
    └── watcher.py (100 LOC) — Watchdog file watcher với debounce 2s
```

**6 MCP tools exposed:**
- `search_memory(query, scope, top_k, use_rerank)` — current project + shared_global hybrid search
- `cross_project_search(query, top_k)` — search ALL registered project collections
- `search_code(query, file_pattern, top_k)` — BM25-heavy code symbol search
- `store_memory(content, source_path, tags)` — add on-the-fly memory chunk
- `promote_to_shared(chunk_id)` — promote project-local → shared_global (v0 stub)
- `list_projects()` — registry overview + Qdrant collection stats

#### Phase 3 — Register MCP user-level (15 phút trial 5 lần)

**Trick CLI `claude mcp add` syntax:** `-e KEY=VAL` flag là variadic — phải có `--` separator ngay sau env list trước `<name>` để terminate parsing.

Final command working:
```bash
claude mcp add -s user -e "VOYAGE_API_KEY=$VK" -- rag-unified python "D:\.claude-rag\server.py"
```

Output: `rag-unified: python D:\.claude-rag\server.py - ✓ Connected`.

#### Phase 4 — Bootstrap SOLUTION_ERP corpus (5 phút)

`.claude/rag.json` ở SOLUTION_ERP project root:
```json
{
  "project_id": "solution_erp",
  "display_name": "SOLUTION_ERP — Quản lý HĐ NCC",
  "corpus_paths": ["docs/**/*.md", ".claude/agent-memory/**/MEMORY.md", ".claude/skills/**/SKILL.md"],
  "extra_corpus": ["C:\\Users\\pqhuy\\.claude\\projects\\D--Dropbox-CONG-VIEC-SOLUTION\\memory\\*.md"],
  "share_to_global": true,
  "search_scope_default": ["self", "shared_global"],
  "contextual_retrieval": true
}
```

Bootstrap output:
```
[1/4] Scanning corpus... Found 126 files
[2/4] Chunking + contextual prepend... Total chunks: 2392
      Estimated tokens: ~484,508 (Voyage free tier: 200M/month)
[3/4] Voyage-4-large embedding + Qdrant upsert + SQLite BM25... Upserted 2392 chunks in 60.9s
[4/4] Update registry...
✓ Bootstrap complete: solution_erp ready (2392 chunks)
```

### Bonus: File MD onboarding guide xuất

`docs/guides/multi-agent-setup-guide.md` (~750 lines markdown) — full guide cho 1 master README + 4 agent definition templates + MEMORY.md seed cho dự án mới. Bro paste vào dự án mới (NamGroup/DH Y Dược/Ashico/Vipix detected từ Claude Desktop config epitaxy) để setup 4 sub-agent + RAG infra.

---

## E2E verified

### Plan AG series verify

| Plan | Commit | BE test | FE build × 2 | SHA256 mirror | CICD Run |
|---|---|---|---|---|---|
| AG | `0bf6c7e` | 111/111 PASS unchanged | PASS 0 TS err | ✅ `21001E90...` | #222 PASS bundle rotate |
| AG2 | `c5429c0` | 111/111 unchanged | PASS | ✅ `37520D01...` | Run #223 PASS (em main verify) |
| AG3 | `fbad4a9` | 111/111 unchanged | PASS | ✅ `749FF703...` | Run #224 PASS |
| AG4 | `2bf0118` | **111/111 PASS** dotnet test verify cross-stack | PASS | ✅ verified | Run #225 PASS |
| AG5 | `083b601` | 111/111 unchanged | PASS | ✅ `E5FE4979...` | Run #226 PASS |
| AG6 | `d99069a` | 111/111 unchanged | PASS | ✅ `3645307C...` | Run #227 PASS |

### Plan AI RAG verify 4 query thực tế

```
Query 1: "gotcha 45 PE button TraLai mismatch"  → rerank 0.641 (Reviewer MEMORY Plan AB)
Query 2: "pattern admin opt-in per-NV flag"     → rerank 0.836 (Session 23 t1 Plan K)
Query 3: "EF migration backfill SQL reorder"    → rerank 0.766 (Session 21 t5 Refactor Allow)
Query 4: "multi-agent setup 4 sub-agents"       → rerank 0.879 (Session 21 t1 cicd-monitor + new guide)
```

---

## 🐛 Bug gặp + fix

| Bug | Fix |
|---|---|
| Bash shell không inherit User-scope env var từ PowerShell parent | Workaround: `VK=$(powershell -NoProfile -Command "...")` mỗi Bash command + `export VOYAGE_API_KEY="$VK"` |
| `claude mcp add -e KEY=VAL` 5 lần FAIL "Invalid environment variable format: rag-unified" | Trick: thêm `--` separator ngay sau env list trước `<name>` để terminate variadic `-e` flag |
| Qdrant upsert 2392 chunks batch lớn FAIL WinError 10053 "connection aborted host machine" | Batching 64 chunks/upsert + `wait=True` trong `lib/retrieval.py:UPSERT_BATCH` |
| SQLite FTS5 `sqlite3.OperationalError: no such column: in` cho query có dấu `-` ("opt-in") | `_sanitize_fts5_query()` strip non-alphanumeric + quote token-by-token `f'"{t}"'` + fallback empty result trên OperationalError |
| HuggingFace symlinks warning Windows non-developer mode | Non-critical (cache work OK degraded efficiency) — note `HF_HUB_DISABLE_SYMLINKS_WARNING=1` env var optional suppress |

---

## 📚 Docs updates

| File | Update |
|---|---|
| `docs/STATUS.md` | Last updated S26 chốt cuối (cumulative wrap 6 plan AG series + Plan AI Phase 0-4) |
| `docs/HANDOFF.md` | TL;DR S26 chốt cuối với 3 patterns NEW reusable cross-project |
| `docs/changelog/sessions/2026-05-21-s26-pe-tree-view-rag-setup.md` | File này — session log đầy đủ |
| `docs/guides/multi-agent-setup-guide.md` | NEW ~750 lines, onboarding 4 dự án future |
| `.claude/agent-memory/investigator/MEMORY.md` | +2 entry S26 (Plan AG audit 5Q + Plan AI RAG research 4 study cases) |
| `.claude/agent-memory/implementer/MEMORY.md` | +1 entry S26 (Plan AG Chunk A+B+C + Pattern 19 HTML details + Tailwind named groups + localStorage Set) |
| `.claude/agent-memory/reviewer/MEMORY.md` | +1 entry S26 (Plan AG pre-commit PASS 0 blocker + 5 polish em main solo self-review) |
| `.claude/agent-memory/cicd-monitor/MEMORY.md` | +1 entry S26 (Run #222 verify + Run #223-#227 em main self-verify pattern). Memory ~74KB CRITICAL CURATE next |
| Memory user-level `feedback_rag_hybrid_pattern.md` | Update section "Implementation actual achievements S26" với stack chốt + Phase 0-4 + 7 bài học extra |
| Memory user-level `MEMORY.md` index | Update entry RAG Hybrid với stack mới Voyage-4-large + rerank-2.5 + Qdrant Windows native |

---

## 🤝 Handoff S27+

### Pending priority HIGH

1. **Memory CRITICAL CURATE** 4 agent — cicd-monitor 74KB OVER 50KB hard threshold (archive Run #186-#221 verbose → `archive/2026-05-runs.md`)
2. **Plan AI Phase 5 bootstrap 4 project còn lại** (NamGroup + DH Y Dược + Ashico + Vipix) — ~30 phút/project, copy `.claude/rag.json` template + bootstrap.py CLI
3. **Plan B Contract V2 wire** (defer carryover từ S25) — mirror PE Mig 22-23 pattern proven 1× S17 + Investigator/Implementer Case 2 pre-allocated

### Pending priority MEDIUM

4. **Plan AI Phase 6** file watcher real-time auto re-embed + Windows Task Scheduler auto-start Qdrant khi boot
5. **Xuất `rag-onboarding-guide.md`** cho 4 project khác paste config (defer sau Phase 5 ổn 1-2 tuần UAT)
6. **Test debt catch-up Plan C bundle** (S22+1 + S25 + S26 bug fix chưa add regression test — UAT mode defer per §7)

### Pending priority LOW

7. Benchmark RAG recall@10 golden dataset 100 query thật (gap optional)
8. Disaster recovery weekly backup Qdrant data → Dropbox (gap optional)
9. Gotcha #48 SQLite tie-break + #49 dual-phase UI confusion add `docs/gotchas.md` (carry từ S25)

---

## 📊 Thông số cumulative S26

| Metric | S25 chốt | S26 chốt | Δ |
|---|---|---|---|
| DB tables | 59 | 59 | 0 |
| Migrations | 31 | 31 | 0 (no schema change) |
| Endpoints | ~146 | ~146 | 0 (same shape, +4 fields DTO ListItem) |
| FE pages | 35 | 35 | 0 (logic enhanced PE List) |
| Unit tests | 111 | 111 | 0 (UAT mode defer per §7) |
| Gotchas | 49 | 49 | 0 |
| Memory user-level | 23 | 23 | 0 (RAG entry updated stack mới) |
| Skills project-local | 6 | 6 | 0 |
| Sub-agents | 4 | 4 | 0 (5 spawn S26: Inv 2 + Imp 1 + Rev 1 + CICD 1) |
| Commits remote | `e23f51c..506cada` | `e23f51c..d99069a` | **+6** (`0bf6c7e..d99069a`) |
| Docs files | — | +1 | `multi-agent-setup-guide.md` |
| Infrastructure | — | +1 | `D:\.claude-rag\` RAG global (out-of-tree) |
| RAG corpus indexed | 0 | **2,392 chunks** | SOLUTION_ERP bootstrap |
| Voyage tokens used | 0 | ~484K | 0.24% free tier 200M/month |

### Multi-agent ROI S26

| Agent | Spawn | Token cost | Catch |
|---|---|---|---|
| 🟦 Investigator | 2× | ~70K | Plan AG audit 5Q + Plan AI RAG distribution research 4 study cases |
| 🟨 Implementer | 1× | ~16K | Plan AG Case 2 cookie-cutter mirror 2 app + Pattern 19 NEW |
| 🟥 Reviewer | 1× | ~25K | Plan AG pre-commit PASS 0 blocker + 5 polish em main solo verified |
| 🟩 CICD Monitor | 1× | ~12K | Run #222 PASS bundle hash 2 app rotate verified |
| 👤 Em main solo | continuous | ~280K (estimate) | Plan AG2-AG6 polish iteration + Plan AI Phase 0-4 setup + docs/MD writes |
| **Total** | **5 spawn** | **~403K** | ~28% solo equivalent — ROI tốt cho heavy session |