create-wakii-stack 0.0.0-stage → 0.1.0

package/stack-template/CLAUDE.md

@@ -0,0 +1,114 @@
+# CLAUDE.md — onboarding AI cho architecture-overview
+
+Boilerplate nội bộ copy-able (epic FI-62): mixed-stack services (Node/Spring/Go) + Module Federation FE (Rspack), demo e2e task management qua nginx gateway. Bản đồ structured cho agent parse: [orca.yaml](orca.yaml). Cho người mới: [docs/walkthrough.md](docs/walkthrough.md).
+
+## Nguyên tắc vàng (vi phạm = review fail)
+
+1. **Contracts là source of truth** — sửa spec/DDL/event contract TRƯỚC, code theo sau (`contracts/`).
+2. **Gateway :8080 là cổng duy nhất** browser/FE chạm vào; inter-service đi qua tên compose (`http://node-svc:3001`), không localhost.
+3. **Conventions bắt buộc** — `platform/conventions/01–09`: Dockerfile, healthcheck, logging JSON, error envelope, ports, config, CORS, gateway/remotes, async messaging.
+4. **Không sửa READ-LOCKED** ngoài story/epic được duyệt — xem bảng frontend bên dưới.
+
+## Bản đồ repo
+
+```
+contracts/    openapi (tasks·users·activity·auth) + db/tasks-schema.sql (canonical DDL)
+              + events/ (task-events.md + fixtures golden) + auth/users.json (id cố định)
+platform/     docker-compose.yml (10 services) · gateway/nginx ·
+              postgres/init · conventions/ (01–09)
+services/     node-svc :3001 (Fastify+TS+Drizzle — CRUD, outbox, compensation)
+              spring-svc :8081 (Boot 3 — users/teams) · go-svc :8082 (chi — activity, Kafka consumer, saga)
+              auth-svc :8090 (Fastify+TS+Drizzle — register/login/refresh/RBAC, epic auth-real)
+app/     shared (fe-shared — logic: api/token/error/MF) · ui-kit (38 components + Storybook + motion)
+              shell :3000 (MF host) · remotes/tasks :4001 · remotes/activity :4002 · spike (MF pins)
+scripts/      smoke/e2e.sh (2 chiều) · scaffold/scaffold.sh
+docs/         walkthrough · adr/0001–0009 · toolchain · superpowers/ (spec+plan+evidence theo story)
+```
+
+## Lệnh hằng ngày
+
+| Việc | Lệnh |
+|---|---|
+| Cài root (FE workspace) | `pnpm install --frozen-lockfile` |
+| node-svc cài riêng | `cd services/node-svc && pnpm install --frozen-lockfile --ignore-workspace` |
+| auth-svc cài riêng | `cd services/auth-svc && pnpm install --frozen-lockfile --ignore-workspace` |
+| Dev FE | `pnpm --filter <pkg> dev` (shell :3000, remotes :4001/:4002) |
+| Test shell (+typecheck) | `pnpm --filter shell test && pnpm --filter shell typecheck` |
+| Test node-svc / auth-svc | `pnpm --filter node-svc test` · `pnpm --filter auth-svc test` |
+| Test go / spring | `cd services/go-svc && go test ./...` · `cd services/spring-svc && ./mvnw test` |
+| Codegen types node-svc | `pnpm --filter node-svc generate:types` (từ `contracts/openapi/tasks.yaml`) |
+| Lint contracts | `pnpm lint:contracts` (spectral) |
+| Chạy full stack + e2e | xem `run.compose` trong [orca.yaml](orca.yaml) — tạo topic TRƯỚC khi boot |
+
+## Ports (nguồn sự thật: `platform/conventions/05-ports.md`)
+
+gateway **8080** · shell 3000 · remote tasks 4001 · remote activity 4002 · node-svc 3001 · spring-svc 8081 · go-svc 8082 · auth-svc 8090 · postgres 5432. Sửa port = 4 chỗ cùng commit (conventions/05 + .env.example + compose + README).
+
+## Workflow có contracts (sửa API)
+
+spec OpenAPI → `pnpm lint:contracts` → codegen node-svc types → impl → sync snapshot go-svc (`internal/api/openapi/` phải bit-identical — CI drift-guard) → fixtures golden nếu event đổi. Chi tiết từng service trong README của service đó.
+
+## READ-LOCKED (frontend)
+
+- `app/shared/src/{api-client,token-storage,error-envelope,mf-bootstrap}.ts` + `package.json#mfToolkit` — cấm sửa ngoài epic được duyệt (versions đã test thật: MF host :3000 load remote :4001).
+- Nâng cấp react/rspack/@module-federation/enhanced (catalog: trong `pnpm-workspace.yaml`) **phải re-spike** qua `app/spike` trước.
+- fe-shared consumed QUA SOURCE, không build riêng; remote standalone tự mang tokens (import tokens trong entry).
+- Design system (tokens/primitives) đã tách sang `app/ui-kit` (ADR-0009) — KHÔNG read-locked; đổi qua story thường + Storybook evidence.
+
+## Run demo
+
+Đường A (compose — khuyến nghị): lệnh đầy đủ trong `run.compose` của [orca.yaml](orca.yaml) → mở http://localhost:8080 → login `alice@demo.local` / `demo-password`. Saga demo: assign task cho `fail@demo.local` → badge "Gán thất bại" + event ở `task-events.dlq`. Verify: `bash scripts/smoke/e2e.sh` PASS 15 bước (happy + auth-real register/refresh/RBAC + saga + DLQ). Đường B native: `docs/walkthrough.md`.
+
+## Docs map — làm gì thì đọc gì TRƯỚC
+
+| Việc | Đọc |
+|---|---|
+| Onboard / chạy demo lần đầu | `docs/walkthrough.md` + `docs/toolchain.md` |
+| Code bất kỳ service nào | `platform/conventions/01–09` (+ README service đó) |
+| Sửa API/contract | `contracts/openapi/*.yaml` + `platform/conventions/04` (envelope) + skill `sync-contracts` |
+| Đụng Kafka/outbox/saga/DLQ | `platform/conventions/09` + `docs/adr/0008` + `contracts/events/task-events.md` |
+| Đụng FE/MF/design system | `docs/adr/0002` + `docs/adr/0009` + `app/ui-kit/README.md` + `app/shared/README.md` |
+| Vì sao kiến trúc vậy | `docs/adr/0001–0009` |
+| Tổ chức epic/story với Wakii | `docs/wakii-playbook.md` (4 archetype chia SF + gates) |
+| Tạo service mới | skill `add-service` (`.claude/skills/`) — thủ tục 4 SF + lệnh verify |
+| Mở PR / merge / branch | `docs/git-flow.md` — mọi thay đổi vào `main` qua PR (template `.github/pull_request_template.md`) |
+
+## CI (`.github/workflows/` — chạy mỗi push theo thư mục đổi)
+
+> ⚠️ **Trạng thái 2026-10: các workflow GitHub Actions hiện ĐANG DISABLE (billing).** Gate thực tế khi push là **`.husky/pre-push`** (cài sẵn qua `pnpm install` root): branch rule `wakii-dev/<loại>-<slug>` (mirror git-guard) + FE checks theo path package đổi — ui-kit (typecheck/test/build-storybook), shell (typecheck/test/build), remote-tasks/remote-activity (typecheck/test). Bảng dưới giữ làm mô tả các workflow để bật lại khi cần.
+
+| Workflow | Nội dung |
+|---|---|
+| `contracts` | spectral + gitleaks + compose config + boot auth-svc + schemathesis FULL |
+| `services-node-svc` / `services-go-svc` / `services-spring-svc` | build + test + docker build + boot-smoke (node/go có kafka) |
+| `shell` / `remotes-tasks` / `remotes-activity` | install + typecheck + test + build |
+| `ui-kit` | install + typecheck + test + coverage + **build-storybook** (ADR-0009 — không publish) |
+| `git-guard` | mọi PR — enforce branch name (`wakii-dev/<loại>-<slug>`) + commit message theo [git-flow.md](docs/git-flow.md); feedback sớm hơn = `git config core.hooksPath .githooks` |
+| `convergence` | mọi push — e2e 2 chiều trên compose 10 services (happy qua Kafka + saga → DLQ assert) + copy-dir standalone (fe-shared + ui-kit) + scaffold build được |
+
+## Gotchas (đầy đủ trong `gotchas:` của orca.yaml)
+
+- node-svc + auth-svc: standalone lockfile — `pnpm install` **--ignore-workspace**, trong thư mục service.
+- Vitest ranh giới ngày: TZ pin trong `vitest.config.ts` (`test.env`) — đừng bỏ.
+- pgdata volume cũ thiếu user saga-seed + role `auth_svc`/schema `auth` (auth-real SF-5) → `docker compose down -v` 1 lần rồi up lại; `.env` bản cũ thêm `AUTH_SVC_DB_PASSWORD`.
+- `assignment_failed` system-owned: re-assign không tự reset — PATCH `{assigneeId, status:"todo"}`.
+- `.env` không commit. Compose env luôn kèm `--env-file platform/.env`.
+
+## AI boilerplate
+
+- [orca.yaml](orca.yaml) — descriptor máy đọc (services/ports/commands/gotchas).
+- `.claude/agents/` — 4 agent miền: `fe-dev` · `be-dev` · `e2e-runner` · `contracts-keeper`.
+- Scaffold project mới: `bash scripts/scaffold/scaffold.sh <tên-mới>` (bộ AI files đi kèm).
+- Culture evidence: đổi behavior đáng kể → chụp test-run/screenshot vào `docs/superpowers/evidence/` khi làm theo story workflow.
+
+## Team protocol — ui-kit multi-agent (bắt buộc từ 2026-10-18)
+
+Khi làm worker trong terminal Orca của repo này (điều phối bởi ZCode lead):
+
+1. **Xong mission** → chạy verify theo brief → **BÁO CÁO tóm tắt + paste kết quả verify thật** → **DỪNG**, chờ lead giao việc kế. KHÔNG tự chuyển mission trừ khi brief ghi rõ chuỗi.
+2. Lead ACK mỗi report trong ~10s; mọi report + gate được log lên board chung `docs/team/TEAM.md` (roster + standup ~30 phút + report log) — PO đọc board là thấy nhịp team.
+3. **Quyền sở hữu file tách bạch**: chỉ đụng file trong scope brief; barrel `src/index.ts` thêm dòng alphabet, đọc trước khi sửa; check `git status` từng file trước khi đụng (tránh đụng WIP người khác).
+4. **Path an toàn**: mọi đường dẫn ghi file dùng tuyệt đối từ `app/ui-kit/...` — KHÔNG dùng relative `src/...` từ repo root (đã gây file lạc chỗ).
+5. **Gate độc lập**: lead tự chạy verify trên diff thật trước khi commit — report của worker là đầu vào, không phải chân lý.
+6. Session chết giữa chừng: lead cứu WIP từ git (commit ghi rõ "recovered by coordinator") — luôn giữ tree ở trạng gian test-xanh-được.
+- **Peer-to-peer**: cần gì ở teammate → `docs/team/inbox/<tên>.md` (format `[HH:MM] @<bạn> → nội dung`); lead giao thư mỗi chu kỳ; broadcast → `docs/team/CHANNEL.md`.

package/stack-template/README.md

@@ -0,0 +1,172 @@
+# __STACK_NAME__
+
+Template nội bộ **copy-able**: mixed-stack services (Node/Spring/Go) + Module Federation FE, demo e2e task management qua nginx gateway, Docker Compose + CI. Epic FI-62 — spec: `docs/superpowers/specs/2026-10-12-boilerplate-microservice-mfe.md` (rev 3).
+
+**Người mới bắt đầu:** đọc [docs/walkthrough.md](docs/walkthrough.md) (fresh-clone → demo) + [docs/adr/](docs/adr/) (8 quyết định kiến trúc) + [docs/toolchain.md](docs/toolchain.md) (tool cần ở đâu). Copy thành project mới: `bash scripts/scaffold/scaffold.sh <tên-mới>`.
+
+## 🎨 Design system — [@wakii/ui-kit](app/ui-kit)
+
+Bộ phận nổi bật nhất của boilerplate: design system **90+ components + 17 hooks** (antd × PrimeReact parity), tokens-first + Tailwind v4, dark theme, motion, a11y, 540 behavior tests.
+
+[![npm](https://img.shields.io/npm/v/@wakii/ui-kit?logo=npm&label=%40wakii%2Fui-kit)](https://www.npmjs.com/package/@wakii/ui-kit)
+[![Storybook](https://img.shields.io/badge/Storybook-301%20stories-ff4785?logo=storybook&logoColor=white)](https://storybook-static-khaki-two.vercel.app)
+[![tests](https://img.shields.io/badge/tests-540%20passing-brightgreen)](#)
+
+- 📖 **Storybook live:** https://storybook-static-khaki-two.vercel.app
+- 📦 **npmjs:** `npm i @wakii/ui-kit` · **GitHub Packages:** `@wakii/ui-kit` (org nội bộ)
+- 🖥️ **Admin showcase:** `app/admin` (Vite SPA — Sidebar+Menu, DataTable virtual, zod forms, upload, hooks demo; `pnpm --filter ./app/admin dev` → :5173)
+- Chi tiết + quickstart: [app/ui-kit/README.md](app/ui-kit/README.md)
+
+## Kiến trúc (đã dựng xong — 6 services gồm auth-svc + 3 FE + gateway + kafka broker)
+
+```mermaid
+graph TB
+    subgraph repo ["repo này (multi-repo convention — mỗi thư mục = repo-con)"]
+        subgraph contracts ["contracts/ — source of truth"]
+            openapi["openapi/ tasks·users·activity·auth.yaml"]
+            ddl["db/tasks-schema.sql — canonical DDL"]
+            authc["auth/ users.json + token-contract.md"]
+        end
+        subgraph platform ["platform/"]
+            compose["docker-compose.yml (10 services — kafka lazy-connect, không chặn chain)"]
+            pginit["postgres/init/ (schemas + roles + default privileges)"]
+            nginx["gateway/nginx (routing + JWT presence 401)"]
+            conv["conventions/ (9 docs)"]
+        end
+        subgraph services ["services/"]
+            node["node-svc :3001 (Fastify+TS) — task CRUD + outbox relay + compensation consumer"]
+            spring["spring-svc :8081 (Spring Boot 3) — users/teams + @Transactional demo"]
+            go["go-svc :8082 (Go 1.24+chi) — activity feed/stats + Kafka consumer + saga"]
+            authsvc["auth-svc :8090 (Fastify+TS — auth thật: register/refresh/RBAC)"]
+        end
+        subgraph app ["app/"]
+            shared["shared (fe-shared — api client, token, MF helper)"]
+            uikit["ui-kit — @wakii/ui-kit design system (90+ comps + 17 hooks, published npm/GH Packages)"]
+            admin["admin :5173 — showcase SPA (Sidebar+Menu, DataTable virtual, zod forms)"]
+            shell["shell :3000 — MF host (Rspack)"]
+            remotes["remotes/ tasks :4001 + activity :4002"]
+            spike["spike (MF pin versions — đã test, prune khi scaffold)"]
+        end
+        scripts["scripts/ smoke/e2e.sh + scaffold/"]
+    end
+
+    browser["Browser"] --> gw["nginx gateway :8080<br/>CỔNG DUY NHẤT"]
+    gw -- "/" --> shell
+    gw -- "/remotes/*" --> remotes
+    gw -- "/api/tasks/* + JWT" --> node
+    gw -- "/api/users/* + JWT" --> spring
+    gw -- "/api/activity/* + JWT" --> go
+    gw -- "/api/auth/* (mở)" --> authsvc
+    node -- "validate user (2s, fail-closed 503)" --> spring
+    node -- "outbox → Kafka task-events (relay 500ms)" --> kafka[("kafka :9092 compose-internal")]
+    kafka -- "consumer go-svc-activity" --> go
+    kafka -- "compensating task.assignment_failed" --> node
+    node -- "SQL (schema tasks + outbox)" --> db[("postgres :5432")]
+    spring -- "SQL (schema users)" --> db
+    go -- "readonly schema tasks + own activity" --> db
+    authsvc -- "seed fixture (giữ UUID) + ký JWT" --> authc
+    node -.-> openapi
+    spring -.-> openapi
+    go -.-> openapi
+    node -.-> ddl
+    go -.-> ddl
+```
+
+Chuỗi e2e chứng minh bởi: `scripts/smoke/e2e.sh` (local + CI job `convergence/e2e-smoke`) + browser walkthrough (human gate — [walkthrough.md](docs/walkthrough.md) mục 4).
+
+## Port table
+
+| Thành phần | Port | | Thành phần | Port |
+|---|---|---|---|---|
+| **nginx gateway** | **8080** | | node-svc | 3001 |
+| shell (MF host) | 3000 | | spring-svc | 8081 |
+| remote tasks | 4001 | | go-svc | 8082 |
+| remote activity | 4002 | | auth-svc | 8090 |
+| postgres | 5432 | | kafka (compose-internal) | 9092 — KHÔNG expose host |
+
+Nguồn sự thật: `platform/conventions/05-ports.md`. Đổi port = sửa 4 chỗ cùng commit (conventions + .env.example + compose + README).
+
+## Chạy
+
+### Compose (máy có Docker — CI chạy mode này)
+
+```bash
+cd platform
+cp .env.example .env        # điền JWT_SECRET (openssl rand -base64 48) + passwords
+# Bước 1 — kafka + topics TRƯỚC (kafka KHÔNG có data volume: mỗi compose down
+# là mất topics → tạo lại tường minh như CI convergence.yml, tránh 2 race:
+# consumer empty-assignment khi subscribe trước topic + DLQ Unknown Topic):
+docker compose up -d postgres kafka
+until docker compose exec -T kafka /opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server localhost:9092 >/dev/null 2>&1; do sleep 2; done
+for topic in task-events task-events.dlq; do
+  docker compose exec -T kafka /opt/kafka/bin/kafka-topics.sh --bootstrap-server localhost:9092 \
+    --create --if-not-exists --topic "$topic" --partitions 1 --replication-factor 1
+done
+# Bước 2 — phần còn lại của stack (health-gated chain: pg → auth-svc/spring → node → gateway)
+docker compose up -d --build
+bash ../scripts/smoke/e2e.sh   # PASS = 2 chiều: happy (login→task→feed qua Kafka) + saga (assign svc-fail → assignment_failed → DLQ assert)
+# shell + remotes: http://localhost:8080/ → login alice@demo.local / demo-password
+# swagger: các svc /api/<svc>/docs cần Bearer (auth-svc không serve /docs — auth.yaml v2)
+```
+
+> **Kafka lazy-connect** (ADR-0008, conventions/09): kafka compose-internal — 9092
+> không expose host, KHÔNG service nào `depends_on` kafka. Services connect retry
+> lúc boot (env `KAFKA_BROKERS`) — broker chưa lên không chặn health-gated chain.
+> Hợp đồng event: [contracts/events/task-events.md](contracts/events/task-events.md)
+> + golden fixtures `contracts/events/fixtures/`. SAGA demo: assign task cho
+> `fail@demo.local` → go consumer fail ×3 → task `assignment_failed` + event gốc
+> ở `task-events.dlq` (xem [walkthrough.md](docs/walkthrough.md) mục 4b).
+> ⚠️ Flyway V2 seed user `svc-fail`/`svc-activity` chạy 1 LẦN lúc volume mới —
+> pgdata volume TỪ bản cũ thiếu 2 user này → `docker compose down -v` sau pull.
+
+### Native (không Docker — từng service một)
+
+Xem [docs/walkthrough.md](docs/walkthrough.md) mục 3-đường B (đủ lệnh cho 4 service BE + 3 FE dev servers). Native không có nginx gateway — FE gọi thẳng service port (CORS dev-profile, conventions/07).
+
+### Scaffold project mới
+
+```bash
+bash scripts/scaffold/scaffold.sh my-project
+cd my-project && pnpm install --no-frozen-lockfile   # lần đầu non-frozen — xem SCAFFOLD.md
+```
+
+Copy + rename + prune thuần (không generator) — chi tiết [ADR 0007](docs/adr/0007-fork-not-upgrade.md).
+
+## Repo map
+
+```
+contracts/          # source of truth API/DB/auth — spectral lint trong CI
+  openapi/          # 4 specs (tasks/users/activity/auth)
+  db/               # canonical DDL bảng tasks (node migrate khớp, go query theo)
+  auth/             # users fixture + token contract
+platform/           # compose (health-gated), postgres init, nginx, conventions/
+services/           # node-svc / spring-svc / go-svc / auth-svc — impl hoàn chỉnh, README standalone từng svc
+app/
+  shared/           # fe-shared — LOGIC: api client, token storage, error envelope, MF bootstrap (READ-LOCKED)
+  ui-kit/           # @wakii/ui-kit (npm) = @wakii/ui-kit (GitHub Packages) — 90+ components + 17 hooks,
+                    #   tokens + Tailwind v4 + Storybook 9 (ADR-0009), dist CSS compiled, 540 behavior tests
+  admin/            # showcase SPA (Vite) — Sidebar+Menu đa cấp, DataTable virtual, zod forms, upload, hooks demo
+  shell/            # MF host (Rspack) — login, nav, remote slots
+  remotes/          # tasks + activity — 2 MF remote
+  spike/            # MF pin versions — đã test (prune khi scaffold)
+scripts/
+  smoke/e2e.sh      # e2e API-level 2 chiều: happy (login→task→feed qua Kafka) + saga (→ assignment_failed → DLQ)
+  scaffold/         # sinh project mới từ boilerplate
+.github/
+  workflows/        # contracts + per-service + convergence (e2e smoke, copy-dir, scaffold)
+  workflow-templates/ # services-ci.yml.example — template cho service mới (prune khi scaffold)
+docs/
+  adr/              # 8 quyết định kiến trúc
+  walkthrough.md    # fresh-clone → demo checklist
+  toolchain.md      # tool cần ở đâu (dev/CI/copy-user)
+docs/superpowers/   # spec, plans, evidence per SF (prune khi scaffold)
+```
+
+## Quy tắc quan trọng (ai copy boilerplate cũng phải biết)
+
+1. API đổi = sửa `contracts/openapi/*.yaml` TRƯỚC (contract-first — [ADR 0003](docs/adr/0003-contract-first.md)), spectral phải pass.
+2. JWT: gateway chỉ presence-check; **service tự verify** signature + expiry (`contracts/auth/token-contract.md` §4).
+3. auth-svc là auth DEMO (argon2id + refresh rotation CAS, `iss` pinned `"auth-mock"` — token-contract.md): copy dự án thật nên cắm OIDC/OAuth tại boundary này (upgrade path ghi trong token-contract.md).
+4. Compose health-gated: node/spring probe `/readyz`; go-svc `service_started` (distroless) — readiness chứng minh bằng smoke script (conventions/02 rule 3).
+5. fe-shared (logic) + ui-kit (design system) là workspace deps chung của shell/remotes — copy FE phải kèm cả `app/shared` + `app/ui-kit`.
+6. Đổi quyết định kiến trúc = đọc ADR tương ứng trước (mỗi ADR ghi Consequences + điểm cắm thay thế).

package/stack-template/app/admin/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="vi">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Wakii Admin — ui-kit showcase</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/stack-template/app/admin/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "admin",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "description": "App admin — Vite SPA showcase toàn bộ @wakii/ui-kit (batch ⑦ VU-53): layout Sidebar+Menu đa cấp, Dashboard/Users/Upload/Hooks/Settings, dark theme persist.",
+  "scripts": {
+    "dev": "vite --port 5173",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@wakii/ui-kit": "workspace:*",
+    "chart.js": "^4.5.1",
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "react-router": "catalog:",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.3.3",
+    "@testing-library/jest-dom": "6.9.0",
+    "@testing-library/react": "16.3.0",
+    "@testing-library/user-event": "14.6.1",
+    "@types/react": "19.2.2",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "^5.0.0",
+    "jsdom": "27.0.0",
+    "playwright": "^1.64.1",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^5.7.0",
+    "vite": "^7.0.0",
+    "vitest": "3.2.4"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/stack-template/app/admin/scripts/verify-chart.mjs

@@ -0,0 +1,49 @@
+// Probe headless — verify Dashboard chart vẽ thật + dark theme CSS var (batch ⑦-fix).
+// Chạy: vite build + preview (hoặc dev) rồi `node scripts/verify-chart.mjs <url>`.
+// CHART: canvas tồn tại + kích thước + số pixel không-trong suốt (>1000 = đã vẽ).
+// DARK: set data-bp-theme=dark trên documentElement → --c-canvas phải đổi giá trị
+// (dark.css được kéo thì var đổi; thiếu thì light === dark → toggle vô hiệu).
+import { chromium } from 'playwright';
+
+const url = process.argv[2] ?? 'http://localhost:4173/';
+const browser = await chromium.launch();
+const page = await browser.newPage();
+const messages = [];
+page.on('console', (msg) => messages.push(`[${msg.type()}] ${msg.text()}`));
+page.on('pageerror', (err) => messages.push(`[pageerror] ${err.message}`));
+
+await page.goto(url, { waitUntil: 'networkidle' });
+await page.waitForTimeout(2500); // chart.js lazy import + animation chạy xong
+
+const chartInfo = await page.evaluate(() => {
+  const canvas = document.querySelector('canvas');
+  if (!canvas) return { canvas: false };
+  let painted = 0;
+  const ctx = canvas.getContext('2d');
+  if (ctx && canvas.width > 0 && canvas.height > 0) {
+    const data = ctx.getImageData(0, 0, canvas.width, canvas.height).data;
+    for (let i = 3; i < data.length; i += 4) if (data[i] !== 0) painted++;
+  }
+  return {
+    canvas: true,
+    attr: `${canvas.width}x${canvas.height}`,
+    cssSize: `${canvas.style.width || '(auto)'} × ${canvas.style.height || '(auto)'}`,
+    paintedPixels: painted,
+  };
+});
+console.log('CHART:', JSON.stringify(chartInfo));
+
+const darkInfo = await page.evaluate(() => {
+  const readCanvasVar = () => getComputedStyle(document.documentElement).getPropertyValue('--c-canvas').trim();
+  const light = readCanvasVar();
+  document.documentElement.setAttribute('data-bp-theme', 'dark');
+  const dark = readCanvasVar();
+  document.documentElement.removeAttribute('data-bp-theme');
+  return { light, dark, changed: light !== dark && dark !== '' };
+});
+console.log('DARK:', JSON.stringify(darkInfo));
+
+const interesting = messages.filter((m) => m.includes('[error]') || m.includes('[warning]') || m.includes('[pageerror]'));
+console.log('CONSOLE:', interesting.length ? `\n${interesting.slice(0, 10).join('\n')}` : '(sạch)');
+
+await browser.close();

package/stack-template/app/admin/src/App.test.tsx

@@ -0,0 +1,70 @@
+// Tests routing admin (batch ⑦) — render 3 route qua MemoryRouter + AppRoutes.
+import { cleanup, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { MemoryRouter } from 'react-router';
+import { afterEach, describe, expect, it } from 'vitest';
+import { AppRoutes } from './App.js';
+
+afterEach(() => {
+  cleanup();
+  window.localStorage.clear();
+  document.documentElement.removeAttribute('data-bp-theme');
+});
+
+function renderAt(path: string) {
+  return render(
+    <MemoryRouter initialEntries={[path]}>
+      <AppRoutes />
+    </MemoryRouter>,
+  );
+}
+
+describe('Admin routing', () => {
+  it('/ → Dashboard: heading + 4 thẻ thống kê + sidebar menu', () => {
+    renderAt('/');
+
+    expect(screen.getByRole('heading', { name: 'Dashboard' })).toBeInTheDocument();
+    expect(screen.getByText('Người dùng')).toBeInTheDocument();
+    expect(screen.getByText('Tasks đang mở')).toBeInTheDocument();
+    expect(screen.getByText('File upload')).toBeInTheDocument();
+    expect(screen.getByText('Uptime')).toBeInTheDocument();
+    // sidebar đa cấp
+    expect(screen.getByText('Quản lý')).toBeInTheDocument();
+    expect(screen.getByText('Cài đặt')).toBeInTheDocument();
+  });
+
+  it('/users → bảng Users + nút Thêm user + dữ liệu mock', () => {
+    renderAt('/users');
+
+    expect(screen.getByRole('heading', { name: 'Users' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /Thêm user/ })).toBeInTheDocument();
+    expect(screen.getByText('alice@demo.local')).toBeInTheDocument();
+    // Select filter — trigger là role=combobox với aria-label (button+listbox pattern)
+    expect(screen.getByRole('combobox', { name: 'Lọc theo trạng thái' })).toBeInTheDocument();
+  });
+
+  it('/settings → Tabs Cài đặt với 2 tab', () => {
+    renderAt('/settings');
+
+    expect(screen.getByRole('heading', { name: 'Cài đặt' })).toBeInTheDocument();
+    expect(screen.getByText('Chung')).toBeInTheDocument();
+    expect(screen.getByText('Vùng & thông báo')).toBeInTheDocument();
+    // field tab Chung render mặc định (label có dấu * vì required → match regex)
+    expect(screen.getByLabelText(/^Tên site/)).toBeInTheDocument();
+  });
+
+  it('dark toggle → set data-bp-theme=dark + persist localStorage', async () => {
+    const user = userEvent.setup();
+    renderAt('/');
+
+    await user.click(screen.getByRole('button', { name: 'Bật dark mode' }));
+
+    // attr trên documentElement — CSS vars thật được verify bằng playwright probe
+    // (scripts/verify-chart.mjs: computed --c-canvas đổi khi attr set)
+    expect(document.documentElement.getAttribute('data-bp-theme')).toBe('dark');
+    expect(window.localStorage.getItem('admin-theme')).toContain('dark');
+
+    await user.click(screen.getByRole('button', { name: 'Tắt dark mode' }));
+    expect(document.documentElement.getAttribute('data-bp-theme')).toBe('light');
+  });
+});

package/stack-template/app/admin/src/App.tsx

@@ -0,0 +1,33 @@
+// App — routing admin (batch ⑦). AppRoutes tách riêng để test render với MemoryRouter.
+import { BrowserRouter, Route, Routes } from 'react-router';
+import { AdminLayout } from './layout/AdminLayout.js';
+import { Dashboard } from './pages/Dashboard.js';
+import { Users } from './pages/Users.js';
+import { UploadPage } from './pages/UploadPage.js';
+import { HooksDemo } from './pages/HooksDemo.js';
+import { ComponentsDemo } from './pages/ComponentsDemo.js';
+import { Settings } from './pages/Settings.js';
+
+export function AppRoutes() {
+  return (
+    <Routes>
+      <Route element={<AdminLayout />}>
+        <Route path="/" element={<Dashboard />} />
+        <Route path="/users" element={<Users />} />
+        <Route path="/upload" element={<UploadPage />} />
+        <Route path="/demo/hooks" element={<HooksDemo />} />
+        <Route path="/demo/components" element={<ComponentsDemo />} />
+        <Route path="/settings" element={<Settings />} />
+        <Route path="*" element={<Dashboard />} />
+      </Route>
+    </Routes>
+  );
+}
+
+export function App() {
+  return (
+    <BrowserRouter>
+      <AppRoutes />
+    </BrowserRouter>
+  );
+}

package/stack-template/app/admin/src/data/users.ts

@@ -0,0 +1,47 @@
+// Mock users — Users page (CRUD demo + filter + pagination). Email fail@demo.local
+// cố ý để demo luồng THẤT BẠI (mirror saga demo của boilerplate).
+export type UserRole = 'Admin' | 'Editor' | 'Viewer';
+export type UserStatus = 'active' | 'invited' | 'disabled';
+
+export interface AdminUser {
+  id: string;
+  name: string;
+  email: string;
+  role: UserRole;
+  status: UserStatus;
+}
+
+export const MOCK_USERS: AdminUser[] = [
+  { id: 'u-01', name: 'Alice Nguyen', email: 'alice@demo.local', role: 'Admin', status: 'active' },
+  { id: 'u-02', name: 'Bob Tran', email: 'bob@demo.local', role: 'Editor', status: 'active' },
+  { id: 'u-03', name: 'Carol Le', email: 'carol@demo.local', role: 'Viewer', status: 'invited' },
+  { id: 'u-04', name: 'David Pham', email: 'david@demo.local', role: 'Editor', status: 'active' },
+  { id: 'u-05', name: 'Eve Vu', email: 'eve@demo.local', role: 'Viewer', status: 'disabled' },
+  { id: 'u-06', name: 'Frank Hoang', email: 'frank@demo.local', role: 'Viewer', status: 'active' },
+  { id: 'u-07', name: 'Grace Dang', email: 'grace@demo.local', role: 'Editor', status: 'invited' },
+  { id: 'u-08', name: 'Heidi Bui', email: 'heidi@demo.local', role: 'Admin', status: 'active' },
+  { id: 'u-09', name: 'Ivan Do', email: 'ivan@demo.local', role: 'Viewer', status: 'disabled' },
+  { id: 'u-10', name: 'Judy Ngo', email: 'judy@demo.local', role: 'Editor', status: 'active' },
+  { id: 'u-11', name: 'Mallory Ly', email: 'mallory@demo.local', role: 'Viewer', status: 'invited' },
+  { id: 'u-12', name: 'Oscar Trinh', email: 'oscar@demo.local', role: 'Viewer', status: 'active' },
+];
+
+export const STATUS_OPTIONS = [
+  { label: 'Tất cả trạng thái', value: '' },
+  { label: 'Hoạt động', value: 'active' },
+  { label: 'Đang mời', value: 'invited' },
+  { label: 'Đã khoá', value: 'disabled' },
+];
+
+export const ROLE_OPTIONS = [
+  { label: 'Admin', value: 'Admin' },
+  { label: 'Editor', value: 'Editor' },
+  { label: 'Viewer', value: 'Viewer' },
+];
+
+/** Trạng thái → variant Badge (map task-status tokens: done xanh / doing vàng / todo xám). */
+export const STATUS_BADGE = {
+  active: { variant: 'done', label: 'Hoạt động' },
+  invited: { variant: 'doing', label: 'Đang mời' },
+  disabled: { variant: 'todo', label: 'Đã khoá' },
+} as const;