[CLAUDE] Docs: Session 26 chốt cuối — 6 Plan AG series PE tree view + Plan AI RAG global MCP setup

Update: - docs/STATUS.md: Last updated S26 cumulative wrap - docs/HANDOFF.md: TL;DR S26 chốt cuối với 3 pattern reusable NEW - docs/changelog/sessions/2026-05-21-s26-pe-tree-view-rag-setup.md: NEW session log đầy đủ - docs/guides/multi-agent-setup-guide.md: NEW ~750 lines onboarding 4 dự án future - .claude/agent-memory/*/MEMORY.md: 4 agent flush S26 entries - .claude/rag.json: NEW project config cho RAG bootstrap Plans done S26: - Plan AG/AG2/AG3/AG4/AG5/AG6 — 6 commits 0bf6c7e..d99069a PE List tree view UI iteration - Plan AI Phase 0-4 — RAG global MCP setup (Voyage-4-large + Qdrant Windows native binary v1.18.0 NO Docker + FastMCP 3.3.1 stdio + SQLite FTS5 BM25 + RRF k=60 + Anthropic Contextual Retrieval prepend) - SOLUTION_ERP bootstrap: 126 files → 2,392 chunks indexed 60.9s (~484K Voyage tokens = 0.24% free tier 200M/month) Multi-agent ROI S26: 5 spawn (Inv 2 audit 5Q + RAG distribution research 4 study cases + Imp 1 Case 2 + Rev 1 pre-commit + CICD 1 Run #222) ~123K + em main solo Plan AG2-AG6 polish + Plan AI Phase 0-4 ~280K = ~28% solo equivalent. 3 patterns reusable cross-project NEW S26: 1. Pattern 19 Implementer — HTML native <details>/<summary> + Tailwind named groups (group/proj+year+sup) + localStorage Set<string> cho hierarchical 3-level tree UI when no Accordion lib 2. RAG User-level Global MCP — 1 server localhost serve N project + per-project .claude/rag.json (Approach A — 1 dev solo scenario, không phải team VPS) 3. Qdrant Windows native binary deployment — no Docker overhead, qdrant-x86_64-pc-windows-msvc.zip 28.3MB chính thức GitHub release Pending S27+: - Memory CURATE 4 agent (cicd-monitor 74KB OVER 50KB hard threshold URGENT) - Plan AI Phase 5 bootstrap 4 project còn lại (NamGroup/DH Y Dược/Ashico/Vipix) - Plan AI Phase 6 file watcher + Windows Task Scheduler Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-22 02:27:36 +07:00
parent d99069a305
commit bf93abd467
8 changed files with 1259 additions and 2 deletions
--- a/docs/changelog/sessions/2026-05-21-s26-pe-tree-view-rag-setup.md
+++ b/docs/changelog/sessions/2026-05-21-s26-pe-tree-view-rag-setup.md
@ -0,0 +1,262 @@
+# 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 |