solution-erp/.claude/agent-memory/implementer-frontend/MEMORY.md

Implementer-Frontend Agent — Persistent Memory

Persistent diary cross-session. Auto-injected first ~200 lines at spawn (L1 HOT). Update BEFORE every stop. Tiered Memory v1: L1 HOT soft-cap ~30KB · L2 archive/ on-demand · L3 RAG search_memory just-in-time. Keep entry ≤ 1.5K chars (gotcha #53). NEW agent S39 (2026-05-29) — split từ implementer (FE 2 app half). Backend scaffold history ở implementer-backend.

---

🎯 Role baseline

WRITE specialist FE 2 app (fe-admin + fe-user). Cookie-cutter mirror SHA256 IDENTICAL + Pattern 16-bis 4-place + declarative KIND_CONFIG + npm build × 2. Case 1+2 only. Tools: Read, Edit, Write, Bash, Skill, Grep, Glob + 5 RAG. Skill: permission-matrix.

🚫 Split boundary

• ✅ MINE: fe-admin/src/** + fe-user/src/**
• ❌ NOT: src/Backend/** → implementer-backend (chỉ Read DTO shape) · tests/ → test-specialist
• ❌ NOT: UX flow decision (drawer/tab/modal) → em main solo

📋 Patterns proven (apply confidently)

Pattern 16-bis 4-place mirror (9× cumulative — BLESSED FOUNDATION)

Add/move page cross-app MUST mirror 4 places:

1. Page/types file · 2. App.tsx Route · 3. lib/menuKeys.ts const · 4. ⚠️ components/Layout.tsx resolvePath staticMap (DỄ MISS → silent sidebar drop gotcha #50) Verified clean S33/S34/S35/S36/S37/S38 = 9× cumulative. Spec MUST list 4 places explicit.

SHA256 IDENTICAL × 2 app

Viết fe-admin → cp fe-user → sha256sum verify. Khác UX (admin full sidebar vs user filter) → mirror tay + diff. Proven S36 (3 pair) + S37 (4 pair) + S38 (5 pair).

Declarative KIND_CONFIG Record (S35, 3× proven)

Single-page multi-kind CRUD URL :kind param + Record<Kind, {fields, columns, icon, label}> + renderField switch FieldType. Reuse: HrmConfigs (S35) + WorkflowApps (S38) + HrmConfigs +2 kind (S51). ADD-KIND playbook: union type + KIND_CONFIG entry + KINDS array + renderCells branch (before fallback) + import icon — :kind-driven page = NO new App.tsx route.

Pattern 14 Tailwind JIT palette

Dynamic class purged. PALETTE array full literal as const cycle index % length.

TS6 / convention

• erasableSyntaxOnly cấm enum → const X = {...} as const + type X = typeof X[keyof typeof X]
• Named export only (trừ App). UI 100% tiếng Việt.
• PageHeader signature (S37): title/description/actions only — KHÔNG icon / children prop (build fail TS2322)
• fe-user thiếu Card/Badge shadcn → fallback inline <div className="rounded-lg border bg-card">

✅ Verify protocol

cd fe-admin && npm run build + cd fe-user && npm run build BOTH 0 TS error + sha256sum mirror proof. Bundle >500KB warning OK pre-existing.

📅 Recent activity (last 10 FIFO)

• 2026-06-16 (S65 PE mục E "Link hồ sơ" FE ×2 app — em-main PROXY, PE-Workflow FE-stage died-empty #53): Thêm mục "e. Link hồ sơ" hyperlink NAS dưới mục "d. Bản so sánh" + rename "Dự trù PRO"→"Ngân sách PRO". 4-file ×{user,admin} SHA256-mirror: PeDetailTabs.tsx (HoSoLinkRow :1353/1386 — useState(ev.hoSoLink), PUT echo required+hoSoLink, readOnly→<a target=_blank rel=noopener noreferrer> null-safe) + PeWorkspaceCreateView.tsx + types/purchaseEvaluation.ts (+hoSoLink). Ship Run #293 PASS, bundle both-rotate, GET phiếu thật "hoSoLink":null backward-compat ✓. SURPRISE: render landed on disk despite empty-return — work COMPLETE, chỉ MEMORY-update bị cắt (#53, lần này trong Workflow fan-out); em main self-gate bắt badge "DỰ TRÙ PRO" sót rename (agent chỉ đổi row label 1120/1126, sót badge 1078) → vá nốt ×2 app. Tag [s65, pe-section-e-link-FE, hosolink-row, em-main-proxy-truncated-53, workflow-fanout].
• 2026-06-16 (Department parentId — cây tổ chức, fe-admin ONLY): Case 1 master-data enrich (NO 4-place, NO menu/route/Layout — chỉ Place-1 page+type). BE đã sẵn (local 0f44d97): DepartmentDto.parentId:Guid? + POST/PUT nhận parentId? + cycle-guard 409 ConflictException. fe-admin ONLY (intentional — KHÔNG fe-user, KHÔNG SHA256). 2 file: (1) types/master.ts Department +parentId:string|null (sau name, trước managerUserId) — DepartmentInput auto-inherit via Omit · (2) DepartmentsPage.tsx: import Select + FormState/emptyForm +parentId:string ('' khi rỗng) + load-all query ['departments-all'] pageSize:200 (reuse pattern proven UsersPage/Workflows/AttendanceReport) + deptNameById Map từ allDepts cho cột "Thuộc" + mutate payload parentId:d.parentId||null + openEdit parentId:d.parentId??'' + Dialog <Select> "Phòng cha (Thuộc khối/phòng)" sau Tên trước Ghi chú: option đầu value="" "— Không có (cấp gốc) —" + .filter(d=>d.id!==form.id) exclude-self khi Edit (chống tự-làm-cha; cycle sâu BE guard 409) + table column "Thuộc" giữa name↔note (d.parentId?deptNameById.get()??'—':'—'). Select = native <select> passthrough, value='' ↔ null sentinel (proven UsersPage departmentId). Build PASS (1941 mod, 0 TS err — tsc -b clean trước vite). NO ambiguity, full precedent (S55 enrich + UsersPage Select).
• 2026-06-11 (S57bis PE WorkItem FE ×2 app — PARTIAL, on-behalf em main ghi hộ, H2-proposed): Task = PeWorkspaceCreateView select "c. Hạng mục công việc *" sau Dự án + PeHeaderForm (select + load existing + PUT/POST workItemId) + PeDetailTabs (subtitle "Dự án – Hạng mục" + FormRow + inline-edit khóa) + types +3 field. Return-truncated #53 GIỮA mirror fe-admin → em main solo mirror 7 edits PeHeaderForm + 3 edits PeDetailTabs ×2 app; PeHeaderForm SHA256 IDENTICAL. LEARNED: mirror đo bằng SHA256 (không diff mắt); option label [Category] Code — Name + canSubmit require; route reuse /catalogs/work-items (KHÔNG endpoint mới). SURPRISE: điểm gãy lặp tại mirror-2-app-trong-1-spawn → cân nhắc per-app stage khi slice lớn. Tag [s57bis, truncated-53, sha256-mirror, on-behalf].
• 2026-06-09 (S55 HMW P2 — Project +4 optional master fields): Case 1 master-data enrich (NO 4-place, NO menu/route/Layout — chỉ Place-1 page+type). BE adds 4 nullable Project fields parallel (implementer-backend). 2 file × 2 app: (1) types/master.ts Project +year:number|null+investor/location/package:string|null (sau note) +ProjectInput auto-inherit via Omit · (2) ProjectsPage.tsx (single-Dialog CRUD, NO separate pages): FormState +4 string (form dùng string, convert on submit) + emptyForm +4 '' + mutate payload year:d.year?Number():null, investor/location/package:d.x||null + openEdit year:p.year?.toString()??'', x:p.x??'' + Dialog 4 Input sau "Ngày kết thúc" trước "Ghi chú" (Năm type=number, Chủ đầu tư, Địa điểm col-span-2, Gói thầu col-span-2) + table column "Chủ đầu tư" (p.investor??'—') giữa name↔startDate. package = valid TS object KEY (reserved chỉ khi binding-identifier) → form.package/{...form,package:x} build sạch, KHÔNG cần rename. cp admin→user SHA256 IDENTICAL: master.ts 93ac1b0f…, ProjectsPage b002061…. Build PASS ×2 (admin 1945mod, user 1934mod, 0 TS err — tsc -b clean trước vite). Reuse S42 enrich-pattern (string-form + convert-on-submit). NO ambiguity, full precedent.
• 2026-06-08 (S54 ItTicket reassign → CONVERGE 2 app, REVERSE S53 divergence) [harvested by em main — agent MEMORY write mis-landed, B2/B3]: S53 đã tách fe-admin-only (admin reassign). S54 cho tổ IT tự reassign → cả 2 app cần nút. Pattern mới: BE capability-flag gate thay vì FE đoán role. Dropdown đổi GET /users → GET /it-tickets/assignable-staff trả {canReassign:bool, staff:[{id,fullName}]} ([Authorize] any-auth, KHÔNG 403 → chống gotcha #44). canReassign = staffQ.data?.canReassign ?? false (fetch on mount, KHÔNG enabled) → nút Pencil bọc {canReassign && …}. types/workflowApps.ts +AssignableStaff+AssignableStaffResult (mirror cả 2). fe-admin rewrite (bỏ UserOption/Paged) + fe-user full-add → SHA256 IDENTICAL 4bcaf2f… (viết admin canonical → cp → verify; cùng @/... import + shadcn Dialog/Select/Button identical 2 app). Build PASS ×2 (0 TS err). Gotcha (pre-existing, NOT từ change này): types/workflowApps.ts 2 app NOT SHA-identical — fe-admin có AttendanceReportDto (P11-E) mà fe-user thiếu; 2 type S54 mirror đúng cả 2. Lesson: BE-computed capability flag = single-source → 2 app converge lại sau intentional divergence.
• 2026-06-08 (S52 Task C+D-FE — ItTicket admin reassign + AttendanceReport menu, fe-admin ONLY): Both intentional mirror-break (admin-only, NO fe-user touch, NO SHA256). Task D-FE menu wiring: Page+App.tsx route /attendance/report ALREADY exist (S52 prior). Only 2 of 4-place needed: (1) menuKeys.ts +OffAttendanceReport='Off_AttendanceReport' (mirror BE string exact, after OffChamCong) · (2) Layout.tsx staticMap +Off_AttendanceReport:'/attendance/report' (4th place gotcha #50). types/menu.ts = MenuNode tree type, key:string NOT typed-union → NO mirror there (resolvePath(key:string)). Leaf perm-gated via BE All[]→admin auto. Task C reassign: ItTicketsPage.tsx top-comment updated DIVERGES fe-user. Per-card Pencil button (cạnh 👤 assignee) → Dialog (size sm) + Select user. Users source = GET /users {params:{page:1,pageSize:200}}→{items:UserOption{id,fullName,email}} (reuse, proven PeWorkflows/Workflows/MeetingCalendar — enabled:target!==null lazy fetch). useMutation api.put(/it-tickets/${id}/assign,{assignedToUserId})→204 (NO json read)→invalidate['it-tickets']+toast.success+close. preselect t.assignedToUserId. UI deps: Dialog(open/onClose/title/children/footer?/size) + Select(native passthrough) + Button(variant=outline) + toast(sonner) + getErrorMessage(@/lib/apiError). Build PASS (0 err, 1945 mod). git: only 3 fe-admin file, fe-user untouched.
• 2026-06-08 (P11-E Wave 1 — AttendanceReportPage fe-admin ONLY): Report endpoint [Authorize(Roles=Admin)] → KHÔNG fe-user page → NO SHA256 mirror (intentional). 4 FE file: (1) types/workflowApps.ts +AttendanceReportRowDto{userId,fullName,departmentName?,daysPresent,totalWorkHours,otRaw,otWeekday,otWeekend,otHoliday,otWeighted}+AttendanceReportDto{year,month,rows,grandTotalWorkHours,grandTotalOtWeighted} (decimal→number) · (2) pages/office/AttendanceReportPage.tsx NEW: PageHeader+filter(Year Input number / Month Select 1-12 / Phòng ban Select fetch /departments) + TanStack key ['attendance-report',year,month,deptId] GET /attendances/report + Table 9 col STT/Họ tên/Phòng ban/Ngày công/Tổng giờ/OT thường/OT cuối tuần/OT lễ/OT quy đổi + tfoot Tổng(colSpan trick) + fmtNum vi-VN · (3) App.tsx import+route /attendance/report · (4) MyAttendancePage.tsx +button "Báo cáo" admin-only (user?.roles.includes('Admin')) navigate → DIVERGED fe-user (header comment cảnh báo). Download Excel: api.get(url,{params,responseType:'blob'}) (api instance inject JWT interceptor + refresh-retry — CHUẨN HƠN raw fetch spec gợi ý; proven ReportsPage/FormsPage/PeDetailTabs) → blob → createObjectURL → anchor.download.click → revoke. Filename content-disposition regex, fallback BaoCao-ChamCong-{Y}-{MM}.xlsx. Build PASS (0 err, 1945 mod). KHÔNG menu key (button-reachable MVP).

---

⚠️ Anti-patterns (DO NOT)

1. ❌ Touch BE files · 2. ❌ Miss 4th Layout staticMap · 3. ❌ Skip npm build × 2 · 4. ❌ git add -A · 5. ❌ Push remote · 6. ❌ UX decision autonomous → REFUSE

🔄 Curate trigger

Size > ~30KB → archive to L2 (tiered v1). Commit scope (em main commits): FE-Admin · FE-User.