[CLAUDE] Docs+Tests: chốt final session 5 — 77 test (Phase 3 mini PE WF) + 3 gotcha CI + 8 doc updates

Final close session 5 — bao gồm:

==== Tests Phase 3 mini (NEW) ====
tests/SolutionErp.Infrastructure.Tests/Application/PeWorkflowAdminTests.cs
- 6 test CreatePeWorkflowDefinitionCommandHandler:
  - First version → IsActive=true, Version=1, ActivatedAt set
  - Second version same Code → auto-increment v2 + deactivate v1 (atomic)
  - Different EvaluationType (A vs B) → independent active state
  - Persists steps ordered by Order field
  - Persists approvers per step
  - Third version → v1 + v2 deactivate, v3 active

Total tests: 71 → 77 pass / ~2s (54 Domain + 23 Infra).
Skip Phase 3 full (UpsertOpinion + Budget link validation) — cần
Identity UserManager DI helper, defer session sau.

==== 3 gotcha CI mới (#39 #40 #41) ====
- #39 act_runner github.com TCP timeout 21s → manual checkout fix (run #108/#109 fail, #110 pass)
- #40 npm junction cache `tsc not found` after Move-Item — rolled back, hypothesis nested junctions
  trong node_modules disrupt .bin/ paths. TODO debug session sau với robocopy hoặc act_runner cache.host
- #41 Gitea Actions paths-ignore behavior — workflow file change vẫn trigger (correct), commit
  MD-only skip 100% (verify 512880c → no run #113)
+ Checklist debug bug mới items 18-20 referencing 3 gotcha trên.

==== Doc updates (8 file) ====
- STATUS.md: header Phase 8 update + 3 row Recently Done CI fixes + cumulative test 71→77
- HANDOFF.md: TL;DR + CI optimize section + Phase status + gotcha count 38→41
- migration-todos.md: Phase 8 §E updated với Phase 3 mini done + CI fixes
- rules.md §7 Testing: rewrite full — stack + test pyramid + quy tắc bổ sung mỗi feature +
  workflow user end-of-task (`dotnet test` local trước push) + CI gate behavior
- architecture.md §11: update test pyramid + phased priority + CI optimization sub-section
  (3 fix manual checkout / path filter / npm cache rollback) + tốc độ deploy table
- gotchas.md: + #39 #40 #41 đầy đủ (triệu chứng + nguyên nhân + fix + reference)
- ef-core-migration SKILL: Phase 8 update note thêm CI fixes + 77 test
- CLAUDE.md root: test count 71→77 + folder structure + CI/CD pipeline 3 fix section
- memory project_solution_erp.md: session 5 summary + workflow user mới
- session log 2026-04-29-2300-chot-final-ci-tests-gotchas.md (NEW — 9 section detail)

==== Skill audit cron ====
`solution-erp-skill-audit-monthly` next fire 2026-05-01 (2 ngày sau).
Cron survives across sessions (setup commit b904a25). Khi fire sẽ:
- Cross-check 6 skill với STATUS/gotchas/migration-todos
- Auto-refresh stale + đề xuất add/archive cho human approve
- Log vào docs/changelog/skill-audit-2026-05.md
- ABORT nếu repo dirty

==== Verify ====
- dotnet test SolutionErp.slnx → 77 pass / ~2s (54 Domain + 23 Infra)
- git status clean sau commit này
- CI: commit này chứa code (test + workflow) → trigger CI test gate

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

docs/gotchas.md

@@ -463,6 +463,111 @@ await userManager.UpdateAsync(u);
 **Bonus:** Check conflict trước khi rename (user khác đã có email mới) →
 skip để tránh duplicate.
 
+### 39. act_runner v0.2.13 fetch `actions/checkout` từ github.com timeout 21s
+
+**Triệu chứng:** Run #108/#109 fail trong **22s** với:
+```
+Get "https://github.com/actions/checkout/info/refs?service=git-upload-pack":
+  dial tcp 20.205.243.166:443: connectex: A connection attempt failed
+  because the connected party did not properly respond...
+```
+
+Test gate (Domain + Infra) chưa kịp chạy. Build/deploy không tới.
+
+**Nguyên nhân:** act_runner mỗi run đều `git fetch` action source code từ
+github.com (kiểm tra update `actions/checkout@v4`). Khi VPS → github.com
+TCP có vấn đề (intermittent firewall/network), 21s timeout → toàn job fail
+TRƯỚC step nào của workflow chạy.
+
+**Fix:** Thay `uses: actions/checkout@v4` bằng manual git checkout từ Gitea
+internal — bypass github.com hoàn toàn.
+
+```yaml
+- name: Checkout (manual git, bypass github.com)
+  shell: powershell
+  run: |
+    git config --global --add safe.directory '*'
+    git init -q
+    git remote add origin "https://gitea-actions:${{ github.token }}@git.baocaogiaoduc.vn/${{ github.repository }}.git"
+    $ref = "${{ github.ref }}"
+    if ($ref -like "refs/heads/*") { $ref = $ref.Substring(11) }
+    git fetch --depth=30 origin $ref
+    git checkout --quiet "${{ github.sha }}"
+```
+
+Tương tự với `actions/upload-artifact@v4` — bỏ vì cũng phụ thuộc github.com.
+TRX file vẫn save local trong `test-results/` cho debug.
+
+**Long-term option:** config `github_mirror` trong gitea-runner config.yaml
+mirror github.com → Gitea internal repo. Hoặc pre-cache `.cache/act/<hash>/`
+manually 1 lần.
+
+**Reference:** Run #108 commit `52999f3` fail, run #110 commit `14b7d18` fix pass.
+
+### 40. npm junction cache `tsc not found` sau Move-Item — chưa xác định root cause
+
+**Triệu chứng:** Implement npm cache strategy bằng junction (mklink /J) +
+Move-Item node_modules → cache dir → fail `'tsc' is not recognized` ở step
+`npm run build`. Log NO Write-Host "cache MISS" output, NO npm install
+output. Timing 1.6s từ end-of-BE-build → start-of-fe-admin npm run build
+(impossible cho npm install 49s).
+
+**Hypothesis:**
+- (A) Move-Item của `node_modules` chứa nested junctions/symlinks → .bin/
+  relative paths broken sau move
+- (B) act_runner PowerShell stream capture có quirk với cache MISS branch →
+  output bị silenced
+- (C) `Test-Path` trả về stale TRUE từ một state khác
+
+**Workaround tạm:** Rollback về fresh `npm install` mỗi run (49s + 33s = 82s).
+Path filter docs-only skip CI là alternative win lớn hơn.
+
+**TODO khi debug session sau:**
+- Thử `robocopy /MIR` thay `Move-Item` (handle symlinks tốt hơn)
+- Hoặc Copy-Item với `-Force -Recurse` (slower nhưng safer)
+- Hoặc dùng act_runner built-in `cache.host` server (có sẵn trong config.yaml)
+
+**Reference:** Run #111 commit `29eb5d9` fail, rollback ở `a21790d`.
+
+### 41. Gitea Actions `paths-ignore` — workflow file change vẫn trigger
+
+**Triệu chứng:** Setup `paths-ignore: ['docs/**', '**/*.md']` để skip CI
+khi commit MD-only. Tự nhiên commit `.gitea/workflows/deploy.yml` (chính
+workflow file) cũng bị skip → không thể test workflow change.
+
+**Nguyên nhân:** `paths-ignore` evaluate set của file thay đổi. Nếu TẤT CẢ
+file thay đổi match patterns → skip. Workflow file `.gitea/workflows/**`
+không trong list ignore → trigger normal. **OK behavior.**
+
+**Edge case ngược:** commit thay đổi cả `docs/STATUS.md` + `src/Backend/...cs`
+→ NOT skip vì có file ngoài ignore patterns. **Cũng OK.**
+
+**Verify:** Commit chỉ touch `docs/STATUS.md` → check Gitea Actions UI →
+phải KHÔNG có run mới trigger. Test với `curl /api/v1/.../runs/<id>`
+trả `Not found` cho run-id tiếp theo.
+
+**Pattern hiện áp dụng:**
+```yaml
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - 'docs/**'
+      - '**/*.md'
+      - '.claude/skills/**'
+      - '.gitignore'
+      - 'scripts/**.md'
+```
+
+KHÔNG ignore: `.gitea/workflows/**`, `*.cs`, `*.tsx`, `*.ts`, `*.csproj`,
+`*.json`, `*.slnx`, `tests/**`.
+
+**Saving:** ~196s/commit cho ~30% commit thuộc loại docs-only (chốt MD,
+session log, etc).
+
+**Reference:** Commit `29eb5d9` add filter, verify ở commit `512880c`
+(docs-only) → Gitea NO trigger run #113.
+
 ## Checklist debug bug mới
 
 1. Build pass không? → fail → check using + package version compat
@@ -482,3 +587,6 @@ skip để tránh duplicate.
 15. Nếu FE gọi API sai URL sau đổi env → rebuild + clear bundle cache (#36)
 16. Nếu .ps1 fail parser trên PS 5.1 → ASCII-only, grep multi-byte chars (#30, #37)
 17. Nếu rename email Identity vẫn 401 → update 4 field NormalizedEmail/UserName (#38)
+18. Nếu CI fail TCP timeout 21s ở "Set up job" → bypass github.com, manual checkout từ Gitea (#39)
+19. Nếu npm install caching fail `tsc not found` → KHÔNG dùng junction Move-Item, thử robocopy/Copy-Item (#40)
+20. Nếu CI vẫn trigger khi commit MD-only → paths-ignore trong on:push không match patterns đúng (#41)