create-wakii-stack 0.0.0-stage → 0.1.0

package/stack-template/docs/walkthrough.md

@@ -0,0 +1,204 @@
+# Fresh-clone walkthrough — từ clone đến demo chạy được
+
+Checklist cho người MỚI copy boilerplate. Mọi lệnh dưới đây là những gì đã chạy thật trong CI (evidence: `docs/superpowers/evidence/sf-5-convergence/test-run.txt` — convergence 10 services + e2e 2 chiều; các SF trước: `evidence/sf-*/`).
+
+## 0. Toolchain cần có
+
+Đọc [toolchain.md](toolchain.md). Tóm tắt: Node 22 + pnpm 9 (corepack) + JDK 21 + Go 1.24 + bash/curl. Docker TÙY CHỌN (không có vẫn xong được — chọn đường A hoặc B bên dưới). LƯU Ý: saga demo (mục 4b) + DLQ cần Kafka → đường A (compose); đường B chỉ chạy happy path (`SMOKE_SAGA=0`).
+
+## 1. Clone + cài đặt
+
+```bash
+git clone <repo> && cd <repo>
+pnpm install --frozen-lockfile     # FE workspace (app/*)
+cd services/node-svc && pnpm install --frozen-lockfile --ignore-workspace && cd ../..   # node-svc standalone lockfile
+cd services/auth-svc && pnpm install --frozen-lockfile --ignore-workspace && cd ../..   # auth-svc standalone lockfile
+```
+
+## 2. Postgres + seed
+
+Cần Postgres 16 chạy sẵn với init script của platform (schemas + roles + readonly grants):
+
+- **Có Docker (dễ nhất):** `cd platform && cp .env.example .env` (điền mật khẩu) → `docker compose up -d postgres` — init script `platform/postgres/init/01-init.sh` tự chạy lần đầu.
+- **Không Docker:** cài/portable Postgres 16, `initdb` một data dir rồi chạy nội dung `platform/postgres/init/01-init.sh` tay (tạo db `boilerplate`, roles `node_svc`/`spring_svc`/`go_svc`/`go_readonly`/`auth_svc` với mật khẩu khớp .env, schemas + default privileges).
+
+## 3. Chọn đường chạy demo
+
+### Đường A — Compose (có Docker — khuyến nghị)
+
+```bash
+cd platform
+cp .env.example .env                # điền JWT_SECRET (openssl rand -base64 48) + passwords
+docker compose down -v              # ⚠️ CHẠY 1 LẦN sau pull nếu máy có pgdata volume TỪ bản cũ:
+                                    #    (1) Flyway V2 seed user svc-fail/svc-activity + (2) init script tạo
+                                    #    schema `auth` + role `auth_svc` (auth-real SF-5) CHỈ chạy lúc volume
+                                    #    MỚI — volume cũ thiếu → saga chết ở auth/validate, auth-svc chết ở
+                                    #    DATABASE auth (healthcheck /readyz đỏ, gateway không lên được).
+                                    # ⚠️ `.env` tạo từ bản cũ: thêm `AUTH_SVC_DB_PASSWORD` (cp từ .env.example).
+# Kafka KHÔNG có data volume — topics mất sau mỗi `down` → tạo tường minh
+# TRƯỚC khi boot services (giống CI convergence.yml; tránh 2 race: go consumer
+# kẹt empty-assignment khi subscribe trước topic + DLQ publish 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
+docker compose up -d --build        # health-gated chain tự đợi đúng thứ tự (10 services, kafka lazy-connect)
+bash ../scripts/smoke/e2e.sh        # từ platform/ — script ở repo root. PASS = 15 bước, 3 luồng:
+                                    #   happy     : login→task→feed QUA KAFKA (outbox → topic → go consumer)
+                                    #   auth-real : register→refresh rotation→reuse→401→logout + RBAC (user DELETE 403, alice 204)
+                                    #   saga      : assign svc-fail → task assignment_failed + event gốc ở task-events.dlq
+# Mở browser: http://localhost:8080/ → login alice@demo.local / demo-password
+#             (hoặc tự register account mới — tab Register, mục 4a)
+```
+
+### Đường B — Native (không Docker — từng service một)
+
+```bash
+# 4 service BE — mỗi lệnh 1 terminal, env theo .env.example (placeholder dev):
+cd services/auth-svc && JWT_SECRET=<dev-secret> PORT=8090 \
+  DATABASE_URL="postgres://auth_svc:<pw>@localhost:5432/boilerplate" \
+  USERS_FIXTURE_PATH=$(pwd)/../../contracts/auth/users.json \
+  AUTH_DEV_PASSWORD=demo-password pnpm dev
+
+cd services/spring-svc && SPRING_DATASOURCE_URL="jdbc:postgresql://localhost:5432/boilerplate" \
+  SPRING_DATASOURCE_USERNAME=spring_svc SPRING_DATASOURCE_PASSWORD=<pw> \
+  JWT_SECRET=<dev-secret> SERVER_PORT=8081 USERS_FIXTURE_PATH=$(pwd)/../../contracts/auth/users.json \
+  ./mvnw spring-boot:run        # Windows: ./mvnw.cmd
+
+cd services/node-svc && JWT_SECRET=<dev-secret> PORT=3001 \
+  DATABASE_URL="postgres://node_svc:<pw>@localhost:5432/boilerplate" \
+  SPRING_SVC_URL=http://localhost:8081 GO_SVC_URL=http://localhost:8082 pnpm dev
+
+cd services/go-svc && JWT_SECRET=<dev-secret> PORT=8082 \
+  DATABASE_URL="postgres://go_svc:<pw>@localhost:5432/boilerplate" \
+  DATABASE_READONLY_URL="postgres://<owner-user>:<owner-pw>@localhost:5432/boilerplate" \
+  SPRING_SVC_URL=http://localhost:8081 go run ./cmd/server
+
+# FE (3 terminal):
+cd app/shell   && pnpm dev   # :3000
+cd app/remotes/tasks    && pnpm dev   # :4001
+cd app/remotes/activity && pnpm dev   # :4002
+```
+
+Native mode KHÔNG có nginx gateway — FE gọi thẳng service port theo conventions/07 (CORS dev đã mở). Chain 3 service "qua một cổng" là đặc tính của compose mode (đường A) + CI e2e-smoke job.
+
+### Verify chain bằng smoke script (cả hai đường)
+
+Script gọi qua prefix `/api/<svc>` (giống gateway routing — conventions/08):
+- Đường A (từ repo root, không cd platform): `bash scripts/smoke/e2e.sh` (mặc định `GATEWAY_URL=http://localhost:8080`). Mặc định chạy **2 chiều** — happy + saga kèm DLQ assert (cần docker để exec `kafka-console-consumer` trong container kafka).
+- Đường B (native, không Kafka): `SMOKE_SAGA=0 bash scripts/smoke/e2e.sh` — happy + auth-real (bỏ saga + DLQ). Không có gateway thật — chứng minh chain bằng cách gọi service trực tiếp, hoặc dựng proxy mapping `/api/*` (SF-7 dùng mini Node proxy cục bộ khi verify native — KHÔNG commit vì chỉ phục vụ verify).
+
+## 4. Browser walkthrough (human gate — KHÔNG trong CI)
+
+Trên máy có stack sống (đường A hoặc B + FE dev servers). UI theo light **antd-look** (decision 2026-10-17 — spec `docs/superpowers/specs/2026-10-17-antd-look-tokens.md`): nền canvas `#f5f5f5`, khối trắng `#ffffff`, 1 accent `#1677ff`, badge pill chấm-màu; dark (palette direction B cũ) là theme phụ qua `UiKitProvider` (`data-bp-theme`).
+
+1. Mở `http://localhost:8080/` (đường A) hoặc `http://localhost:3000/` (đường B) → thấy **dashboard chào** với quick links Tasks/Activity + box **TÀI KHOẢN DEMO** (`alice@demo.local / demo-password`, `fail@demo.local`). Login → nav phải hiện user chip (avatar + email) + nút **Đăng xuất**.
+2. Nav → **Tasks** (item nav active gạch accent): form **Tạo task** (Tiêu đề + Mô tả) → task mới xuất hiện đầu danh sách, heading **"Danh sách (x/total)"** cập nhật. Thử tiếp:
+   - **Sửa inline**: nút *Sửa* trên card → input inline tiêu đề/mô tả → *Lưu* (PATCH thật) / *Huỷ*.
+   - **Đổi status**: select trên card (`Cần làm` / `Đang làm` / `Xong`) — lúc PATCH đang bay item hiện spinner + select khoá (per-item busy).
+   - **Lọc**: chip `Tất cả` / `Cần làm` / `Đang làm` / `Xong` → danh sách + "x/total" lọc theo `?status=`.
+   - **Tải thêm**: nếu total > số đã tải, nút *Tải thêm* cuối danh sách nạp trang kế (limit/offset thật), "x/total" tăng dần tới đủ.
+   - **Xoá**: nút *Xoá* → xác nhận inline ("Xoá task này?" → *Xác nhận xoá* / *Huỷ*) — xoá thật qua DELETE.
+   - Mỗi card hiển thị assignee (UUID rút gọn monospace, hover thấy đủ), "Chưa gán" nếu trống, + createdAt vi-VN.
+3. Nav → **Activity**: **stats cards** (Tổng task / Cần làm / Đang làm / Xong / Sự kiện 24h qua) + **feed timeline nhóm theo ngày** phản ánh mọi thao tác ở bước 2 qua Kafka (outbox → `task-events` → go consumer): badge "đã tạo / đã cập nhật / đã giao / đã xoá" từng màu, tên task, time vi-VN. Nút *Làm mới* load lại.
+4. **Remote-down fallback**: dừng 1 remote rồi reload shell — đường A: `docker stop boilerplate-remote-tasks-1`; đường B: Ctrl-C dev server `:4001`. Shell vẫn nguyên (nav + user chip), slot Tasks hiện fallback "Không tải được phần **tasks**…" + nút **Thử lại**; **Activity vẫn chạy bình thường**. Khôi phục: khởi động lại remote (`docker start` / chạy lại `pnpm dev`) rồi nút *Thử lại* tải lại remote; nếu nút chưa ăn (MF runtime giữ rejection cũ) thì **reload trang** — remote sống lại mount bình thường.
+
+### 4a. Auth thật — register / refresh / logout-all 2 tab (epic auth-real)
+
+1. **Register**: mở `http://localhost:8080/` → tab **Register** trên login screen → email mới + password (8–72 ký tự) + tên hiển thị → tạo xong là đăng nhập luôn (roles `["user"]`). Đăng xuất → đăng nhập lại bằng account vừa tạo ✓.
+2. **Refresh rotation (2 tab)**: đăng nhập cùng account ở 2 tab. Tab 1 đứng yên đến khi access token hết hạn (30m) — request kế tab 1 tự refresh (rotate) rồi retry, KHÔNG bị văng về login. (Nhạy hơn: `POST /api/auth/refresh` tay bằng refreshToken trong `localStorage['bp.rt']` — response trả cặp mới, token cũ không dùng lại được.)
+3. **Logout-all (chuẩn acceptance — 1 tab chết, 1 tab còn)**: tab 2 bấm **Đăng xuất** (chỉ revoke refresh của tab đó — tab 1 VẪN sống vì access token 30m còn hạn). Để chết HẾT tab: gọi logout-all (chưa có nút UI — dùng token của account). P2 security-audit SF-5: đừng dán token thẳng vào lệnh (rơi shell history) — dùng `read -rs`:
+   ```bash
+   read -rs TOKEN   # dán access token rồi Enter (không echo)
+   curl -X POST http://localhost:8080/api/auth/logout-all -H "Authorization: Bearer $TOKEN"
+   unset TOKEN
+   ```
+   Quay lại tab 1, bấm bất kỳ thao tác gọi API kế tiếp → 401 → auto-refresh fail (token bị revoke-all) → về màn login. Đó là hành vi ĐÚNG (không cross-tab realtime — kiểm ở request kế).
+4. **RBAC demo**: login `bob@demo.local` / `demo-password` (roles `["user"]`) → tạo task → nút **Xoá** → bị chặn (403 FORBIDDEN — hiện thông báo lỗi, task còn nguyên). Login `alice@demo.local` (roles `["admin"]`) → xoá cùng task → thành công. e2e assert cùng chuỗi (bước 11–12).
+
+### 4b. Saga demo (story FI-76 — cần đường A, có Kafka)
+
+1. Trong **Tasks**, tạo task (vd `saga-demo`) rồi gán cho user fixture fail: **`fail@demo.local`** — UI hiển thị assignee ở chế độ read-only (UUID rút gọn), việc gán đi qua API: `PATCH /api/tasks/{id}` với `assigneeId=55555555-5555-4555-8555-555555555555` (swagger `:8080/api/tasks/docs` hoặc curl với Bearer token).
+2. Go consumer cố tình fail ×3 (simulate hook — assignee trùng svc-fail) → publish compensating event `task.assignment_failed` vào topic chung → node compensation consumer cập nhật status.
+3. Quan sát trên **Tasks**: task chuyển badge **"Gán thất bại"** (pill đỏ chấm đỏ — nhận diện rõ; task ở trạng thái này không còn select status — system-owned). Event gốc (task.assigned) nằm ở `task-events.dlq`:
+   ```bash
+   docker compose -f platform/docker-compose.yml --env-file platform/.env.example exec -T kafka \
+     /opt/kafka/bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 \
+     --topic task-events.dlq --from-beginning --timeout-ms 15000
+   # mỗi dòng = 1 DLQ message: {"schemaVersion":1,"originalEvent":"{...task.assigned...}","error":{"reason":...,"retries":3,...}}
+   ```
+4. **Recovery**: re-assign cho user hợp lệ (bob, id `22222222-2222-4222-8222-222222222222`) → saga chạy lại từ đầu (bob ≠ svc-fail, go handler xử lý thường). LƯU Ý: `assignment_failed` là system-owned — re-assign KHÔNG tự reset status (repo `update()` chỉ set field trong patch); muốn đưa task về luồng hiển thị bình thường, PATCH tường minh `{"assigneeId":"<bob-id>","status":"todo"}` (status writable 3 giá trị — `assignment_failed` PATCH cấm). Trên UI task có lại badge "Cần làm" + select status.
+
+> ℹ️ BUG-1 standalone prod trắng trang (report VU-53, 2026-10-14) **ĐÃ FIX** (sf-5b): shared `eager:true` + entry `standalone` static + nginx alias `/remotes/<name>/` — standalone :4001/:4002 render đầy đủ ở build prod. Evidence: `docs/superpowers/evidence/sf-5b-ui-redesign-fix/` (browser walkthrough + phantom-grep trước/sau).
+
+> ℹ️ Job `convergence/e2e-smoke` (GitHub Actions) mô tả chuỗi saga assert status + DLQ bằng `kafka-console-consumer` (không cần browser) — **hiện workflow ĐANG DISABLE (billing, xem CLAUDE.md)**; gate khi push là `.husky/pre-push` (chỉ FE checks, không chạy e2e). Cần verify saga thì chạy tay: `bash scripts/smoke/e2e.sh` (mục "Verify chain bằng smoke script" trên).
+
+### 4c. Storybook — design system sống (Templates + 129 titles)
+
+UI của shell/remotes build từ `@wakii/ui-kit` — xem toàn bộ + thử template ghép sẵn:
+
+```bash
+pnpm --filter @wakii/ui-kit storybook   # → http://localhost:6006 (script tự stamp version)
+```
+
+Số liệu thật (index Storybook 2026-10-18): **129 titles · 623 story exports**, trong đó
+nhóm **Templates** — 6 template "trang thật" (controlled state sống, không phải mock render):
+
+| Template | Story path (`?path=/story/…`) | Ghép từ |
+|----------|-------------------------------|---------|
+| Dashboard admin | `templates-dashboard--dashboard` | `Layout` (Sider+Header) + Row/Col + Card/Statistic + Table + Timeline + Chart |
+| Kanban project | `templates-kanban-project--project-board` | `KanbanBoard` (4 cột + WIP limit) + Segmented/Input.Search/Select filter + `Timesheet` + `message` toast khi move |
+| CRUD table | `templates-crud-table--full-demo` | `Table` (sort 3-state/selection/expandable/fixed header/summary) + `Drawer` form (useForm+zod) + `Popconfirm` + `message` |
+| Auth | `templates-auth--sign-in` · `--sign-up` · `--split-layout` | `useForm` + zod + Field/Input/Button + `Layout` split |
+| Landing | `templates-landing--landing-alive` | `Parallax` + `Reveal` + `CountUp`/`Statistic` + `Grid` |
+| Settings | `templates-settings--settings` | `Tabs` + `Switch` + `Field` + live theme toggle |
+
+Mẹo: toolbar Storybook có **toggle dark** (`data-bp-theme` trên body preview — mọi component
+theo token nên cả index đổi theme 1 click). AI agents đọc [AGENTS.md](../AGENTS.md) +
+[docs/ai/recipes.md](ai/recipes.md) — bản đồ khi-dùng + 12 recipe copy-chạy. Chi tiết
+Templates: `app/ui-kit/README.md` § Templates.
+
+## 5. Copy/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
+# rồi lặp lại mục 2-4 trong project mới
+```
+
+Phát triển tiếp project mới theo story workflow (Wakii): xem [wakii-playbook.md](wakii-playbook.md) — decision tree story/single/fix + 4 archetype chia SF + gates.
+
+## 6. CI báo gì
+
+| Workflow | Chạy khi | Bằng chứng |
+|----------|---------|-----------|
+| `contracts` | contracts/**, platform/** đổi | spectral + gitleaks + compose config + boot-smoke auth-svc + schemathesis FULL (auth.yaml v2) |
+| `services-*` / `shell` / `remotes-*` | thư mục tương ứng đổi | build + test + docker build + boot-smoke (node/go có kafka boot-smoke) |
+| `convergence` (SF-5, story FI-76) | mọi push | e2e 2 chiều trên compose 10 services (happy qua Kafka + saga → `assignment_failed` + DLQ assert) + copy-dir standalone + scaffold output build được |
+
+## 7. Hành trình team — app-fit 4 apps + tài liệu nội bộ (2026-10-18)
+
+**App-fit**: 4 app FE đã migrate hết sang `@wakii/ui-kit` (tokens + components qua source):
+
+| App | Đã fit |
+|-----|--------|
+| `app/shell` (MF host :3000) | layout + nav + tokens từ phiên trước |
+| `app/remotes/tasks` (:4001) | `TaskForm`/`TaskItem` chuyển `useForm` + zod + `Field`/`Input`/`Textarea` (+`useFieldArray` sẵn trong kit), `TaskList` giữ contract (EmptyState ở page level) |
+| `app/remotes/activity` (:4002) | `ActivityPage` + `StatTile` → `Card`/`Statistic` ui-kit |
+| `app/admin` | dashboard layout `Grid`/`Card`/`Statistic` giữ stat-intent |
+
+**Templates**: 6 trang mẫu ghép sẵn trong Storybook (bảng §4) — copy điểm khởi đầu cho
+trang thật; recipes kèm tại [docs/ai/recipes.md](ai/recipes.md).
+
+**Hướng tới 0.3.0**: megagate 32 commits (241416f..HEAD) đã gate xanh — release notes
+draft soạn sẵn tại [`docs/superpowers/specs/2026-10-18-0.3.0-release-notes.md`](superpowers/specs/2026-10-18-0.3.0-release-notes.md) — merge PR là chốt release
+(ui-kit consumed qua source nên "release" = điểm merge, xem CHANGELOG head).
+
+**Tài liệu nội bộ team (local-only, gitignored — không vào PR)**: `docs/team/` chứa
+[RULES.md](team/RULES.md) (hiến phần vận hành: vai trò, vòng làm việc, thang tin cậy
+T1→T3, sở hữu file), `TEAM.md` (roster + standup + report log), `DECISIONS.md`
+(tiền-duyệt), `inbox/` (thư peer-to-peer), `CHANNEL.md`. Bản tóm tắt in-repo cho
+session mới: [CLAUDE.md](../CLAUDE.md) § "Team protocol".

package/stack-template/orca.yaml

@@ -0,0 +1,146 @@
+# orca.yaml — descriptor MÁY ĐỌC cho AI agent (Claude Code / Orca agents / Codex…).
+# ⚠️ Orca CLI KHÔNG consume file này — nó là bản đồ repo dạng structured cho agent
+# parse khi onboard. Văn bản cho người/xét nghiệm: CLAUDE.md + docs/walkthrough.md.
+# Quy ước: sửa file này CÙNG commit với mọi thay đổi nó mô tả (port, lệnh, path) —
+# drift giữa descriptor và thực tế = lỗi onboarding agent (tương tự quy tắc 4 chỗ
+# của port table — platform/conventions/05-ports.md).
+name: architecture-overview
+description: >
+  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, Docker Compose + CI. Scaffold project mới:
+  bash scripts/scaffold/scaffold.sh <tên-mới>
+
+stack:
+  node: ">=22"
+  pnpm: ">=9"            # corepack enable — root packageManager pin 9.15.9
+  jdk: "21"
+  go: "1.24"
+  postgres: "16"
+  workspaces: pnpm workspace (root) NHƯNG node-svc + auth-svc có standalone lockfile (cài riêng, xem services.auth-svc.install)
+
+# ── Contracts — SOURCE OF TRUTH. Sửa contract TRƯỚC, code theo sau. ──────────
+contracts:
+  openapi: [contracts/openapi/tasks.yaml, contracts/openapi/users.yaml, contracts/openapi/activity.yaml, contracts/openapi/auth.yaml]
+  ddl_canonical: contracts/db/tasks-schema.sql
+  events_contract: contracts/events/task-events.md
+  event_fixtures: contracts/events/fixtures/   # golden envelope — node/go test cùng nguồn
+  auth_users_fixture: contracts/auth/users.json  # id UUID CỐ ĐỊNH — không đổi id user cũ
+  lint: pnpm lint:contracts                    # spectral
+
+services:
+  gateway:
+    type: nginx
+    port: 8080
+    path: platform/gateway
+    note: CỔNG DUY NHẤT browser/FE chạm vào — routing /api/<svc>/* + presence-check JWT (401)
+  node-svc:
+    path: services/node-svc
+    port: 3001
+    tech: Fastify + TypeScript + Drizzle
+    install: cd services/node-svc && pnpm install --frozen-lockfile --ignore-workspace
+    dev: pnpm dev            # tsx watch
+    build: pnpm build        # tsc
+    test: pnpm test          # vitest run
+    healthz: [/healthz, /readyz]
+    owns: schema tasks — CRUD + outbox relay + compensation consumer (Kafka)
+  spring-svc:
+    path: services/spring-svc
+    port: 8081
+    tech: Spring Boot 3 + Flyway
+    run: ./mvnw spring-boot:run
+    test: ./mvnw test
+    owns: schema users + teams (@Transactional demo)
+  go-svc:
+    path: services/go-svc
+    port: 8082
+    tech: Go 1.24 + chi
+    run: go run ./cmd/server
+    test: go test ./...
+    healthz: [/healthz, /readyz]
+    owns: schema activity (tự migrate) — feed/stats + Kafka consumer (idempotent, retry ×3 → DLQ + saga)
+    note: đọc-ONLY schema tasks qua role go_readonly; snapshot openapi nhúng phải bit-identical contract (CI drift-guard)
+  auth-svc:
+    path: services/auth-svc
+    port: 8090
+    tech: Fastify + TypeScript + Drizzle (auth thật — epic auth-real VU-59)
+    install: cd services/auth-svc && pnpm install --frozen-lockfile --ignore-workspace
+    dev: pnpm dev            # tsx watch
+    build: pnpm build        # tsc
+    test: pnpm test          # vitest run
+    healthz: [/healthz, /readyz]
+    owns: schema auth (users + refresh_tokens — seed users.json GIỮ UUID) — register/login/refresh rotation CAS/reuse-detect/logout; claims roles = RBAC source
+    note: iss JWT PINNED "auth-mock" (token-contract.md — giá trị lịch sử, KHÔNG đổi theo tên service)
+
+app:
+  shared:
+    path: app/shared
+    scope: "@wakii/fe-shared"
+    role: LOGIC (api-client/token-storage/error-envelope/mf-bootstrap) — consumed QUA SOURCE, không build
+    read_locked:   # cấm sửa ngoài story/epic được duyệt — versions + contracts đã test thật
+      - src/api-client.ts
+      - src/token-storage.ts
+      - src/error-envelope.ts
+      - src/mf-bootstrap.ts
+      - package.json#mfToolkit
+  ui-kit:
+    path: app/ui-kit
+    scope: "@wakii/ui-kit"
+    role: DESIGN SYSTEM (tokens + base css + primitives + Storybook 9 dev-only) — consumed QUA SOURCE; KHÔNG read-locked (đổi qua story thường, evidence = build-storybook) — ADR-0009
+  shell:
+    path: app/shell
+    port: 3000
+    role: MF host (Rspack) — nav + login + RemoteSlot (error boundary + retry)
+    commands: {dev: pnpm dev, build: pnpm build, test: pnpm test, typecheck: pnpm typecheck}
+  remotes:
+    tasks: {path: app/remotes/tasks, port: 4001, gateway: /remotes/tasks/}
+    activity: {path: app/remotes/activity, port: 4002, gateway: /remotes/activity/}
+    note: standalone dev vẫn tự mang tokens (import tokens trong entry — quyết định epic VU-53 #5)
+  pins:              # catalog: (pnpm-workspace.yaml) + mfToolkit — NÂNG CẤP PHẢI RE-SPIKE (app/spike)
+    react: 19.3.0
+    react-dom: 19.3.0
+    rspack: 1.7.12
+    module-federation-enhanced: 0.21.6
+
+run:
+  compose:            # đường A — khuyến nghị, full saga + DLQ
+    prep: |
+      cd platform && cp -n .env.example .env   # điền JWT_SECRET + passwords
+      docker compose --env-file .env up -d postgres kafka
+      # đợi kafka healthy rồi tạo topic TRƯỚC khi boot services (race empty-assignment):
+      for topic in task-events task-events.dlq; do
+        docker compose --env-file .env 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
+      docker compose --env-file .env up -d --build        # 10 services, health-gated chain
+    verify: bash scripts/smoke/e2e.sh                      # 2 chiều — happy + saga + DLQ assert
+    url: http://localhost:8080
+  native: docs/walkthrough.md                              # đường B — từng service, SMOKE_SAGA=0 cho smoke
+  demo_login: {user: alice@demo.local, password: demo-password}
+  saga_fail_user: fail@demo.local                          # assign cho user này → go fail ×3 → assignment_failed → DLQ
+
+test_all:              # full suite local — PASS hết trước khi claim done
+  - pnpm --filter shell test && pnpm --filter shell typecheck
+  - pnpm --filter node-svc test
+  - pnpm --filter auth-svc test
+  - cd services/go-svc && go test ./...
+  - cd services/spring-svc && ./mvnw test
+
+docs:
+  start_here: docs/walkthrough.md          # fresh-clone → demo chạy được
+  conventions: platform/conventions/       # 01–09 — BẮT BUỘC, không đúng = review fail
+  adr: docs/adr/                           # 0001–0009 — quyết định kiến trúc đã chốt
+  toolchain: docs/toolchain.md
+  ci: .github/workflows/                   # 10 workflows (HIỆN DISABLE — xem gotchas) — bảng mô tả ở CLAUDE.md
+  evidence: docs/superpowers/evidence/     # test-run + screenshots theo story
+
+gotchas:
+  - "CI GitHub Actions ĐANG DISABLE (billing, 2026-10) — gate khi push là .husky/pre-push (branch rule + FE checks theo path); workflows trong .github/ chỉ còn giá trị tham khảo khi bật lại"
+  - "Vitest test ranh giới ngày: TZ pin qua test.env trong vitest.config — môi trường dev +07 che bug, đừng bỏ pin"
+  - "node-svc + auth-svc: standalone lockfile — pnpm install PHẢI --ignore-workspace, chạy TRONG thư mục service, không phải workspace root"
+  - "fe-shared standalone: khai catalog: → cần mini workspace (sed catalog block từ root pnpm-workspace.yaml) — mẫu ở .github/workflows/convergence.yml step copy-dir"
+  - "pgdata volume từ bản cũ thiếu user svc-fail/svc-activity (Flyway V2) + role auth_svc/schema auth (init script chỉ chạy volume mới — 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 từ .env.example"
+  - "assignment_failed là system-owned: re-assign KHÔNG tự reset status — PATCH tường minh {assigneeId, status:'todo'} (status writable: todo/in_progress/done)"
+  - "Inter-service call QUA TÊN COMPOSE (http://node-svc:3001), không localhost; .env không bao giờ commit"
+  - "Sửa port = 4 chỗ cùng commit: conventions/05-ports.md + .env.example + docker-compose.yml + README"

package/stack-template/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "__STACK_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Boilerplate microservice + micro-frontend — template nội bộ copy-able (epic FI-62)",
+  "packageManager": "pnpm@9.15.9",
+  "engines": {
+    "node": ">=22",
+    "pnpm": ">=9"
+  },
+  "scripts": {
+    "lint:contracts": "spectral lint contracts/openapi/*.yaml",
+    "prepare": "test -e .git && husky || true"
+  },
+  "devDependencies": {
+    "@stoplight/spectral-cli": "^6.17.0",
+    "husky": "^9.1.0"
+  }
+}

package/stack-template/platform/.env.example

@@ -0,0 +1,72 @@
+# ============================================================================
+# Env inventory ĐẦY ĐỦ — nguồn sự duy nhất về cấu hình compose + services.
+# Cách dùng: cp .env.example .env rồi điền giá trị thật. .env KHÔNG commit.
+# Quy tắc: thêm env var mới = thêm vào đây cùng commit (platform/conventions/06).
+# ============================================================================
+
+# --- Shared ---
+# Secret ký + verify JWT HS256 (contracts/auth/token-contract.md). BẮT BUỘC đổi khi dùng.
+# Sinh: openssl rand -base64 48
+JWT_SECRET=change-me-openssl-rand-base64-48
+
+# Log level mọi service: debug | info | warn | error
+LOG_LEVEL=info
+
+# --- Ports (platform/conventions/05-ports.md) ---
+# ⚠️ Các biến *_PORT chỉ đổi port side HOST (truy cập từ máy dev); port TRONG
+# mạng compose cố định theo bảng — container port hardcode trong compose.
+GATEWAY_PORT=8080
+SHELL_PORT=3000
+REMOTE_TASKS_PORT=4001
+REMOTE_ACTIVITY_PORT=4002
+NODE_SVC_PORT=3001
+SPRING_SVC_PORT=8081
+GO_SVC_PORT=8082
+AUTH_PORT=8090
+POSTGRES_PORT=5432
+
+# --- Postgres ---
+POSTGRES_USER=boilerplate
+POSTGRES_PASSWORD=change-me-postgres
+POSTGRES_DB=boilerplate
+
+# Password per-service DB role (tạo bởi platform/postgres/init/01-init.sh)
+NODE_SVC_DB_PASSWORD=change-me-node
+SPRING_SVC_DB_PASSWORD=change-me-spring
+GO_SVC_DB_PASSWORD=change-me-go
+GO_READONLY_DB_PASSWORD=change-me-goreadonly
+AUTH_SVC_DB_PASSWORD=change-me-auth
+
+# Password service user `svc-activity` (fixture users.json) — go-svc login
+# auth lấy service token cho resolver (conventions/09). BẮT BUỘC khớp
+# AUTH_DEV_PASSWORD (auth-svc so password hash của seeded users — token-contract.md §5).
+SVC_ACTIVITY_PASSWORD=demo-password
+
+# --- Kafka (conventions/09, ADR-0008) ---
+# Bootstrap servers. Trong mạng compose = tên service `kafka:9092` (9092 KHÔNG
+# expose ra host). Native dev ngoài compose override thành localhost:9092.
+KAFKA_BROKERS=kafka:9092
+
+# --- URLs inter-service (trong mạng compose dùng tên service) ---
+NODE_SVC_URL=http://node-svc:3001
+SPRING_SVC_URL=http://spring-svc:8081
+GO_SVC_URL=http://go-svc:8082
+# KEY giữ AUTH_MOCK_URL (go-svc đọc theo tên env này — gap-answer ④ epic VU-59);
+# VALUE trỏ auth-svc (đổi KEY = follow-up cụm iss-rename).
+AUTH_MOCK_URL=http://auth-svc:8090
+SHELL_URL=http://shell:3000
+REMOTE_TASKS_URL=http://remote-tasks:4001
+REMOTE_ACTIVITY_URL=http://remote-activity:4002
+
+# --- FE (dev, ngoài compose) ---
+# Origin được phép CORS khi chạy native dev (platform/conventions/07-cors.md)
+CORS_DEV_ORIGIN=http://localhost:3000,http://localhost:4001,http://localhost:4002
+
+# --- auth (rename AUTH_MOCK_* → AUTH_* hoàn tất SF-5 VU-64 — compose đã swap) ---
+# Dev password cho SEEDED fixture users (users.json — token-contract.md §5).
+# Default demo-password KHÔNG ĐỔI: e2e + svc-activity + seed cùng một nguồn.
+AUTH_DEV_PASSWORD=demo-password
+# TTL access token JWT (auth-svc — token-contract.md §1)
+ACCESS_TOKEN_TTL=30m
+# Đường dẫn users fixture trong container
+USERS_FIXTURE_PATH=/app/users.json

package/stack-template/platform/conventions/01-dockerfile-pattern.md

@@ -0,0 +1,78 @@
+# 01 — Dockerfile multi-stage pattern
+
+Mọi service dùng **2 stage**: `deps` (cài dependency, cache được) → `runtime` (copy artifact + prod deps, image mỏng). Không chạy build tool trong runtime image.
+
+## Node (Fastify/TS — node-svc, auth-svc)
+
+```dockerfile
+# deps stage
+FROM node:22-alpine AS deps
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile
+
+# runtime stage
+FROM node:22-alpine AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=deps /app/node_modules ./node_modules
+COPY dist ./dist
+USER node
+EXPOSE 3001
+CMD ["node", "dist/server.js"]
+```
+
+## Spring Boot (spring-svc)
+
+```dockerfile
+# deps stage — mvnw tải dependency vào layer cache riêng
+FROM eclipse-temurin:21-jdk-alpine AS deps
+WORKDIR /app
+COPY .mvn .mvn
+COPY mvnw pom.xml ./
+RUN ./mvnw -B dependency:go-offline
+
+# build stage
+FROM deps AS build
+COPY src src
+RUN ./mvnw -B package -DskipTests
+
+# runtime stage — JRE-only, jar fat
+FROM eclipse-temurin:21-jre-alpine AS runtime
+WORKDIR /app
+COPY --from=build /app/target/*.jar app.jar
+USER 1001
+EXPOSE 8081
+ENTRYPOINT ["java", "-jar", "app.jar"]
+```
+
+## Go (go-svc)
+
+```dockerfile
+# build stage
+FROM golang:1.24-alpine AS build
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /out/go-svc ./cmd/server
+
+# runtime stage — static binary trên distroless
+FROM gcr.io/distroless/static-debian12:nonroot AS runtime
+COPY --from=build /out/go-svc /go-svc
+EXPOSE 8082
+ENTRYPOINT ["/go-svc"]
+```
+
+## Quy tắc
+
+1. **Pin base image theo digest hoặc minor tag cụ thể** — không `:latest`. SF-7 rà lại lần cuối.
+2. Image chạy **non-root** (`USER node` / `USER 1001` / distroless nonroot).
+3. `EXPOSE` = port của service theo [05-ports.md](05-ports.md).
+4. Healthcheck KHÔNG khai trong Dockerfile — khai trong `platform/docker-compose.yml` (một nguồn duy nhất).
+5. Thứ tự `COPY` tối ưu cache: lockfile/manifest trước, source sau.
+6. CI boot-smoke build đúng Dockerfile này — nếu build local pass mà CI fail, check `.dockerignore` trước (node_modules/target/bin không được vào context).
+7. **Lockfile variant cho workspace member (SF-7 sync — học từ SF-2, improvements-log):** service là member của pnpm workspace nhưng compose build context = **thư mục con** → root `pnpm-lock.yaml` KHÔNG vào được context. Hai cách chuẩn:
+   - **Local standalone lockfile** (precedent node-svc, auth-svc): commit `pnpm-lock.yaml` trong thư mục service (sinh bằng `pnpm install --ignore-workspace`), Dockerfile `COPY package.json pnpm-lock.yaml` + `pnpm install --frozen-lockfile`.
+   - **Repo-root build context** (precedent shell/remotes): Dockerfile khai `context: ..` + `dockerfile: app/<app>/Dockerfile` để root workspace lockfile + `app/shared` vào được context.
+   Đừng trộn: COPY root lockfile trong context thư mục con = build fail lúc deps stage.

package/stack-template/platform/conventions/02-healthcheck.md

@@ -0,0 +1,26 @@
+# 02 — Healthcheck: `/healthz` + `/readyz`
+
+Mọi HTTP service expose 2 endpoint không-auth (gateway không chặn, service không verify JWT trên 2 path này):
+
+| Endpoint | Ý nghĩa | Trả về khi ổn | Trả về khi chưa ổn |
+|----------|---------|---------------|--------------------|
+| `/healthz` | **Liveness** — process sống | `200 {"status":"ok"}` | process chết → không response |
+| `/readyz` | **Readiness** — nhận traffic được (deps xong) | `200 {"status":"ok"}` | `503` error envelope |
+
+## Điều kiện ready per service
+
+| Service | `/readyz` = 200 khi |
+|---------|---------------------|
+| node-svc | DB migration chạy xong + spring-svc reachable (kiểm lúc boot, không ping liên tục) |
+| spring-svc | Flyway migration xong + DataSource healthy |
+| go-svc | Migration schema `activity` xong + SELECT thử được schema `tasks` (readonly role) |
+| auth-svc | migration schema auth + seed fixture xong (/readyz kiểm DB thật — rule 2) |
+
+## Quy tắc
+
+1. Body JSON: `{"status":"ok"}` — không thêm trường (CI boot-smoke grep đúng shape này).
+2. `/readyz` phải kiểm tra **thật** (query DB thật), không hardcode 200.
+3. Compose `healthcheck` khai ở `platform/docker-compose.yml` probe **`/readyz`** (health-gated — SF-7). Ngoại lệ có chủ đích: **go-svc KHÔNG có healthcheck trong compose** — runtime distroless không có shell/wget, Dockerfile read-only với convergence (SF-7); readiness của go-svc được chứng minh bằng `scripts/smoke/e2e.sh` poll `/api/activity/stats` (compose `depends_on` go-svc ở mức `service_started`). Gateway cũng KHÔNG có healthcheck (nginx proxy thuần, không route `/readyz` — probe sẽ 404).
+4. CI boot-smoke job: container up → curl `/healthz` → curl `/readyz` → cả hai 200 mới pass.
+5. Path mounting: service mount **prefix `/api/<svc>`** cho business routes; `/healthz` + `/readyz` nằm **ngoài prefix** (naked path, ví dụ node-svc serve `/healthz` chứ không phải `/api/tasks/healthz`). Xem [08-gateway-and-remotes.md](08-gateway-and-remotes.md).
+6. **Mirror rule (SF-7, học từ SF-4 — improvements-log finding schemathesis 404):** service expose `/healthz` + `/readyz` **cả hai dạng** — naked path (cho compose healthcheck + CI boot-smoke) VÀ mirror dưới prefix `/api/<svc>/healthz` + `/api/<svc>/readyz` (cho OpenAPI spec khai dưới `servers.url` + schemathesis contract test). Áp cho MỌI service mới; auth-svc là precedent mới nhất (auth-mock cũ đã decommission — epic auth-real SF-5). Service không expose mirror = contract test fail 404 khi chạy qua base-url có prefix.

package/stack-template/platform/conventions/03-logging.md

@@ -0,0 +1,41 @@
+# 03 — JSON log shape chung
+
+Mọi service log JSON một dòng mỗi entry ra **stdout** (12-factor; compose/CI collect). Không log ra file.
+
+## Shape
+
+```json
+{
+  "ts": "2026-10-12T05:00:00.123Z",
+  "level": "info",
+  "service": "node-svc",
+  "msg": "task created",
+  "requestId": "b1c2...",
+  "taskId": "9f0e...",
+  "durationMs": 12
+}
+```
+
+| Trường | Bắt buộc | Ghi chú |
+|--------|----------|---------|
+| `ts` | ✓ | ISO 8601 UTC, độ chính xác ms |
+| `level` | ✓ | `debug` \| `info` \| `warn` \| `error` |
+| `service` | ✓ | `node-svc` \| `spring-svc` \| `go-svc` \| `auth-svc` \| `gateway` |
+| `msg` | ✓ | Câu ngắn, tiếng Anh, không nhạy cảm |
+| `requestId` | khi xử lý request | Lấy từ header `X-Request-Id` (gateway sinh nếu thiếu) — trace xuyên gateway → service |
+| còn lại | tuỳ | Case camelCase; KHÔNG log JWT/email/password toàn phần (mask email: `a***@demo.local`) |
+
+## Stack mapping
+
+| Stack | Thư viện |
+|-------|----------|
+| node-svc | `pino` (mặc định JSON) |
+| spring-svc | Logback `LogstashEncoder` (`net.logstash.logback`) |
+| go-svc | `log/slog` JSON handler |
+| auth-svc | `pino` |
+
+## Quy tắc
+
+1. **Fire-and-forget event push** (node-svc → go-svc): fail = log `level:"warn"`, msg chứa `event push failed`, KHÔNG raise error cho caller, KHÔNG retry (ADR SF-7).
+2. Unhandled error: `level:"error"` + stack trong trường `err` (string).
+3. Không dùng `console.log` trong service Node — mọi log đi qua logger có shape trên.

package/stack-template/platform/conventions/04-error-envelope.md

@@ -0,0 +1,41 @@
+# 04 — Error envelope chung
+
+Mọi HTTP response 4xx/5xx của mọi service dùng **một** shape — mirror trong `components.schemas.Error` của cả 4 OpenAPI specs (spectral rule `error-envelope-shape` warn nếu lệch).
+
+## Shape
+
+```json
+{
+  "error": {
+    "code": "TASK_NOT_FOUND",
+    "message": "Task 9f0e... không tồn tại",
+    "requestId": "b1c2...",
+    "details": null
+  }
+}
+```
+
+| Trường | Bắt buộc | Ghi chú |
+|--------|----------|---------|
+| `error.code` | ✓ | `SCREAMING_SNAKE` — máy đọc được |
+| `error.message` | ✓ | Người đọc được; không chứa secret |
+| `error.requestId` | ✓ (nullable) | Echo `X-Request-Id` |
+| `error.details` | ✗ | Dữ liệu bổ sung có cấu trúc (vd validation field errors) |
+
+## Code catalog tối thiểu
+
+| Code | HTTP | Dùng khi |
+|------|------|----------|
+| `VALIDATION_ERROR` | 400 | Payload sai schema |
+| `UNAUTHORIZED` | 401 | Thiếu/sai/hết hạn JWT (service tự verify) |
+| `NOT_FOUND` | 404 | Resource không tồn tại |
+| `CONFLICT` | 409 | Email đã tồn tại… |
+| `UNPROCESSABLE` | 422 | Assignee không tồn tại (spring trả 404 khi node validate) |
+| `DEPENDENCY_DOWN` | 503 | spring-svc down khi node validate user (fail-closed); go không đọc được schema tasks |
+| `INTERNAL` | 500 | Unhandled — KHÔNG lộ stack trong message |
+
+## Quy tắc
+
+1. Fastify/spring/Go framework error mặc định (vd Fastify `FST_ERR_*`) phải được **map sang envelope** bằng error handler riêng.
+2. Gateway (nginx) 401 presence-check trả envelope tương tự (`{"error":{"code":"UNAUTHORIZED",...}}`) qua `default.conf` inline response.
+3. FE decode envelope bằng helper `decodeErrorEnvelope` trong `app/shared` — không tự parse message đáy.