create-wakii-stack 0.0.0-stage → 0.1.0

package/stack-template/app/ui-kit/src/utils/format.test.ts

@@ -0,0 +1,63 @@
+// Tests format — 4 formatter: giá trị + edge (0, âm, biên unit, tương lai/quá khứ).
+import { describe, expect, it } from 'vitest';
+import { formatBytes, formatCurrency, formatNumber, formatRelativeTime } from './format.js';
+
+describe('formatCurrency', () => {
+  it('mặc định vi-VN/VND, 0 thập phân', () => {
+    // Intl vi-VN: nhóm bằng dấu chấm, ký hiệu ₫
+    expect(formatCurrency(1234567)).toContain('1.234.567');
+    expect(formatCurrency(1234567)).toContain('₫');
+  });
+
+  it('locale/currency/decimals tuỳ chỉnh', () => {
+    expect(formatCurrency(9.5, { locale: 'en-US', currency: 'USD', decimals: 2 })).toBe('$9.50');
+  });
+});
+
+describe('formatBytes', () => {
+  it('B giữ nguyên; 1024-base sang KB/MB/GB', () => {
+    expect(formatBytes(512)).toBe('512 B');
+    expect(formatBytes(1536)).toBe('1.5 KB');
+    expect(formatBytes(1024 * 1024)).toBe('1.0 MB');
+    expect(formatBytes(3 * 1024 ** 3)).toBe('3.0 GB');
+    expect(formatBytes(2 * 1024 ** 4)).toBe('2.0 TB');
+  });
+
+  it('edge: 0 · âm/không hợp lệ → "0 B"; decimals tuỳ chỉnh', () => {
+    expect(formatBytes(0)).toBe('0 B');
+    expect(formatBytes(-5)).toBe('0 B');
+    expect(formatBytes(NaN)).toBe('0 B');
+    expect(formatBytes(1536, 2)).toBe('1.50 KB');
+  });
+});
+
+describe('formatRelativeTime', () => {
+  const now = new Date('2026-10-24T12:00:00Z');
+
+  it('quá khứ → "x phút trước" (vi-VN, numeric auto)', () => {
+    const then = new Date(now.getTime() - 5 * 60_000);
+    expect(formatRelativeTime(then, { now })).toBe('5 phút trước');
+  });
+
+  it('tương lai → "sau x phút" (vi RTF thêm "sau"); giây → "vài giây trước" (auto)', () => {
+    const future = new Date(now.getTime() + 3 * 60_000);
+    expect(formatRelativeTime(future, { now })).toBe('sau 3 phút nữa');
+    const justNow = new Date(now.getTime() - 2_000);
+    expect(formatRelativeTime(justNow, { now })).toContain('giây');
+  });
+
+  it('đơn vị lớn: giờ/ngày/tuần đúng ngưỡng', () => {
+    expect(formatRelativeTime(new Date(now.getTime() - 2 * 3600_000), { now })).toBe('2 giờ trước');
+    expect(formatRelativeTime(new Date(now.getTime() - 3 * 86400_000), { now })).toBe('3 ngày trước');
+    expect(formatRelativeTime(new Date(now.getTime() - 2 * 604800_000), { now })).toBe('2 tuần trước');
+  });
+});
+
+describe('formatNumber', () => {
+  it('mặc định vi-VN nhóm chuẩn; decimals; compact ("1,2 Tr" — ICU vi)', () => {
+    expect(formatNumber(1234567)).toBe('1.234.567');
+    expect(formatNumber(3.14159, { decimals: 2 })).toBe('3,14');
+    expect(formatNumber(1234567, { compact: true })).toBe('1 Tr'); // ICU vi dùng NBSP trước đơn vị
+    expect(formatNumber(1234567, { compact: true, decimals: 1 })).toBe('1,2 Tr');
+  });
+});

package/stack-template/app/ui-kit/src/utils/format.ts

@@ -0,0 +1,81 @@
+// format — formatter dùng chung (vi-VN mặc định, Intl): tiền tệ · byte ·
+// thời gian tương đối · số. NHẤT QUÁN với formatSize trong ui/upload (1024-base,
+// 1 thập phân cho KB/MB) — bản này mở rộng đủ GB/TB + tùy chọn decimals.
+// 0 deps; SSR an toàn (Intl có trong Node 18+).
+
+export interface FormatCurrencyOptions {
+  /** BCP 47 locale — mặc định 'vi-VN'. */
+  locale?: string;
+  /** Mã tiền ISO 4217 — mặc định 'VND'. */
+  currency?: string;
+  /** Số chữ số thập phân — mặc định 0 (VND không dùng xu). */
+  decimals?: number;
+}
+
+/** Định dạng tiền: formatCurrency(1234567) → "1.234.567 ₫" (vi-VN/VND). */
+export function formatCurrency(value: number, options: FormatCurrencyOptions = {}): string {
+  const { locale = 'vi-VN', currency = 'VND', decimals = 0 } = options;
+  return new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency,
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+  }).format(value);
+}
+
+const BYTE_UNITS = ['B', 'KB', 'MB', 'GB', 'TB'] as const;
+
+/** Định dạng byte (1024-base, 1 thập phân từ KB — khớp formatSize upload):
+ * formatBytes(1536) → "1.5 KB". */
+export function formatBytes(bytes: number, decimals = 1): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return `0 ${BYTE_UNITS[0]}`;
+  if (bytes < 1024) return `${Math.round(bytes)} ${BYTE_UNITS[0]}`;
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < BYTE_UNITS.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${value.toFixed(decimals)} ${BYTE_UNITS[unit]}`;
+}
+
+const RELATIVE_UNITS: Array<{ limit: number; div: number; unit: Intl.RelativeTimeFormatUnit }> = [
+  { limit: 60, div: 1, unit: 'second' },
+  { limit: 3600, div: 60, unit: 'minute' },
+  { limit: 86400, div: 3600, unit: 'hour' },
+  { limit: 604800, div: 86400, unit: 'day' },
+  { limit: 2629800, div: 604800, unit: 'week' },
+  { limit: 31557600, div: 2629800, unit: 'month' },
+  { limit: Infinity, div: 31557600, unit: 'year' },
+];
+
+/** Thời gian tương đối (Intl.RelativeTimeFormat): formatRelativeTime(Date.now() -
+ * 5 * 60_000) → "5 phút trước"; tương lai → "in 5 minutes" (en) / "5 phút nữa" (vi). */
+export function formatRelativeTime(date: Date | number | string, options: { locale?: string; now?: Date | number } = {}): string {
+  const { locale = 'vi-VN', now = Date.now() } = options;
+  const then = date instanceof Date ? date.getTime() : new Date(date).getTime();
+  const diffSeconds = Math.round((new Date(now).getTime() - then) / 1000);
+  const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+  const abs = Math.abs(diffSeconds);
+  const found = RELATIVE_UNITS.find((u) => abs < u.limit) ?? RELATIVE_UNITS[RELATIVE_UNITS.length - 1]!;
+  return rtf.format(-Math.round(diffSeconds / found.div), found.unit);
+}
+
+export interface FormatNumberOptions {
+  /** BCP 47 locale — mặc định 'vi-VN'. */
+  locale?: string;
+  /** Số chữ số thập phân — mặc định 0. */
+  decimals?: number;
+  /** Nén nhóm (1.2K · 3.4M) — dùng notation 'compact'. */
+  compact?: boolean;
+}
+
+/** Định dạng số: formatNumber(1234567) → "1.234.567"; compact → "1,2 tr" (vi). */
+export function formatNumber(value: number, options: FormatNumberOptions = {}): string {
+  const { locale = 'vi-VN', decimals = 0, compact = false } = options;
+  return new Intl.NumberFormat(locale, {
+    notation: compact ? 'compact' : 'standard',
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+  }).format(value);
+}

package/stack-template/app/ui-kit/tests/setup.ts

@@ -0,0 +1,15 @@
+import '@testing-library/jest-dom/vitest';
+
+// jsdom thiếu matchMedia — thêm no-op nếu test cần (thêm thuộc tính thiếu của MediaQueryList)
+if (!window.matchMedia) {
+  window.matchMedia = ((query: string) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: () => {},
+    removeListener: () => {},
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    dispatchEvent: () => false,
+  })) as unknown as typeof window.matchMedia;
+}

package/stack-template/app/ui-kit/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "types": ["vitest/globals", "@testing-library/jest-dom"]
+  },
+  "include": ["src", "tests", "vitest.config.ts", ".storybook"]
+}

package/stack-template/app/ui-kit/tsup.config.ts

@@ -0,0 +1,37 @@
+// tsup — build dist cho npm publish (batch ⑭ worker B). Workspace VẪN phân phối source
+// trực tiếp (exports → ./src/index.ts, consumed qua source); dist CHỈ dùng khi publish
+// (publishConfig.exports → dist). dts on; external toàn peer/heavy deps — consumer tự mang:
+// react(+jsx-runtime)/react-dom, swiper (+ 'swiper/css' giữ nguyên specifier trong dist),
+// zod, chart.js, @fullcalendar/* (schedule là peer-lazy), @tiptap/* (editor).
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: {
+    index: 'src/index.ts',
+    carousel: 'src/entries/carousel.ts',
+    chart: 'src/entries/chart.ts',
+    schedule: 'src/entries/schedule.ts',
+    editor: 'src/entries/editor.ts',
+    // Entry riêng cho thân Editor — wrapper lazy qua BIẾN specifier (esbuild
+    // inline dynamic import khi splitting:false); dist/editorInner.js.
+    editorInner: 'src/ui/editor/EditorInner.tsx',
+    experience3d: 'src/entries/experience3d.ts',
+  },
+  format: ['esm', 'cjs'],
+  // splitting FALSE: mỗi entry self-contained — chunk dùng chung (vd EditorInner)
+  // kéo static import peer (@tiptap/starter-kit) vào graph index dù consumer
+  // không dùng entry đó → vite build consumer fail resolve (gate starter
+  // 2026-10-24). Đổi lại: entry lớn hơn chút nhưng phân lập đúng peer-dep.
+  splitting: false,
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  external: [
+    /^react(-dom)?($|\/)/, // react, react/jsx-runtime, react-dom/client
+    /^swiper($|\/)/, // swiper + 'swiper/css' (+/pagination)
+    /^zod($|\/)/,
+    /^chart\.js($|\/)/,
+    /^@fullcalendar\//,
+    /^@tiptap\//,
+  ],
+});

package/stack-template/app/ui-kit/vercel.json

@@ -0,0 +1,6 @@
+{
+  "framework": null,
+  "outputDirectory": "storybook-static",
+  "installCommand": "pnpm install",
+  "buildCommand": "pnpm --filter ui-kit build-storybook"
+}

package/stack-template/app/ui-kit/vitest.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from 'vitest/config';
+
+// ui-kit test đứng riêng — react/@types có trong devDependencies (chỉ phục vụ test,
+// runtime vẫn "consumer cung cấp" qua source-consumption) nên không cần alias như shell.
+export default defineConfig({
+  esbuild: {
+    // JSX primitives compile automatic runtime — không thì esbuild rơi về
+    // classic "React.createElement" → "React is not defined" lúc render
+    jsx: 'automatic',
+  },
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: ['./tests/setup.ts'],
+    coverage: {
+      provider: 'v8',
+      include: ['src/**'],
+      exclude: ['src/**/*.stories.tsx', 'src/**/*.test.tsx'], // test colocated không pha loãng coverage // stories không chạy trong vitest — pha loãng số liệu
+      thresholds: { lines: 85, statements: 85, functions: 90, branches: 90 },
+    },
+  },
+});

package/stack-template/contracts/auth/token-contract.md

@@ -0,0 +1,119 @@
+# Token Contract — auth-svc (HS256 + refresh rotation) — v2
+
+> SF-1 (VU-60) sở hữu. Hiệp ước của epic auth-real (VU-59): mọi SF sau (SF-2 auth-svc,
+> SF-3 RBAC, SF-4 FE refresh-client, SF-5 convergence) code THEO file này + `contracts/openapi/auth.yaml` v2.
+> Chuyển tiếp: auth-mock chạy song song đến SF-5 decommission với hành vi v1 của nó —
+> từ SF-2 mọi implementation/test bám target dưới đây.
+
+## 1. Access token — JWT HS256, TTL 30m
+
+- **Algorithm**: HS256 (HMAC-SHA256) — symmetric, một secret chung (`JWT_SECRET`, §5).
+- **Header**:
+
+```json
+{ "alg": "HS256", "typ": "JWT" }
+```
+
+- **Payload (claims)** — shape giữ nguyên so với v1:
+
+| Claim  | Kiểu      | Bắt buộc | Ý nghĩa |
+|--------|-----------|----------|---------|
+| `sub`  | string    | ✓        | **User id (UUID)** — primary key `auth.users` của auth-svc; seeded users giữ nguyên UUID fixture `contracts/auth/users.json`. node-svc lấy đây làm `created_by`/`assignee_id`. |
+| `email`| string    | ✓        | Email (lowercase-normalized) |
+| `roles`| string[]  | ✓        | Vd `["admin"]`, `["user"]` — mirror `auth.users.roles`; source-of-truth cho RBAC (SF-3) |
+| `iss`  | string    | ✓        | **PINNED `"auth-mock"`** — ⚠️ giá trị lịch sử CỐ Ý giữ nguyên: node-svc + spring-svc + go-svc verify và 2 CI workflow hardcode chuỗi này; đổi chuỗi = follow-up nhỏ RIÊNG (ngoài epic này), KHÔNG đổi trong auth-svc |
+| `iat`  | int (epoch giây) | ✓ | Thời điểm cấp |
+| `exp`  | int (epoch giây) | ✓ | `iat + 1800` |
+
+- **TTL: 30 phút = 1800 giây** — cấu hình env `ACCESS_TOKEN_TTL=30m` (auth-svc đọc; token hết hạn → FE auto-refresh, §4).
+
+## 2. Refresh token — opaque 256-bit, TTL 7d
+
+- **Opaque, không phải JWT**: `crypto.randomBytes(32)` (256-bit entropy) → base64url. Client nhận raw, không parse được gì.
+- **Server chỉ lưu hash `sha256(refresh_token)`** — DB không bao giờ chứa raw; leak DB không dựng lại token được. So khớp bằng hash lookup.
+- **TTL: 7 ngày** — `expires_at = created_at + 7d`; hết hạn → 401 ở `/refresh`.
+- **FE storage: `localStorage['bp.rt']`** (key mới, tách khỏi `token-storage.ts` READ-LOCKED).
+  **Rationale — accepted-for-demo**: localStorage đọc được qua XSS = rủi ro đã cân nhắc và CHẤP NHẬN cho scope demo của boilerplate (security pass epic ghi nhận ở acceptance #7). httpOnly-cookie + CSRF protection = **upgrade path** ghi ở §8; không mở lại tranh luận trong epic này.
+
+## 3. Rotation CAS atomic + reuse-detect (strict)
+
+Mỗi `POST /api/auth/refresh`: sinh refresh token mới TRƯỚC, rồi CAS (compare-and-set) atomic trên row cũ.
+**INSERT row refresh token mới nằm trong CÙNG transaction với CAS UPDATE** — bước nào trượt
+(CAS thua / INSERT fail) → rollback cả hai, không bao giờ tồn tại trạng thái "đã revoke cũ
+nhưng chưa có cặp mới".
+
+```sql
+UPDATE auth.refresh_tokens
+SET revoked_at = now(), replaced_by = $new_id
+WHERE id = $old_id AND revoked_at IS NULL AND expires_at > now()
+RETURNING id;
+```
+
+(`expires_at > now()` enforce TTL 7d của §2 — token hết hạn KHÔNG thắng CAS; rơi vào
+nhánh 0-rows strict bên dưới, không có refresh-chain vô hạn.)
+
+- **RETURNING ≥ 1 row** → thắng CAS: trả cặp mới (accessToken 30m + refreshToken mới 7d). Token cũ đã revoked, `replaced_by` trỏ token mới.
+- **RETURNING 0 rows** → **reuse-detect** (token đã dùng / đã revoke / đã hết hạn / không tồn tại):
+  - Token **có row** (đã dùng / revoked / hết hạn): xác định được `user_id` → revoke **TẤT CẢ**
+    refresh token của user + trả **401** envelope `UNAUTHORIZED`:
+
+    ```sql
+    UPDATE auth.refresh_tokens
+    SET revoked_at = now()
+    WHERE user_id = $sub AND revoked_at IS NULL;
+    ```
+
+  - Token **lạ / không tồn tại** (không có row): không biết `user_id` → chỉ **401** đơn thuần,
+    không revoke gì (không có user để revoke).
+  **Strict by design** — token bị replay = kẻ tấn công chiếm được → mất toàn bộ session của user đó an toàn hơn cho phép token cũ còn dùng (chain-only revoke). User chỉ cần login lại.
+- **2 tab refresh đồng thời**: request thua CAS bị coi reuse → 401. Chấp nhận strict; FE dùng **single-flight promise lock** (SF-4) giảm xác suất — documented, không claim cross-tab realtime.
+
+## 4. Flows + endpoints (shape v2)
+
+| Endpoint | Request | Response |
+|---|---|---|
+| `POST /api/auth/register` | `{email, password(8–72), displayName}` | **201** `AuthSession {user, accessToken, refreshToken}`; 409 `CONFLICT` email trùng |
+| `POST /api/auth/login` | `{email, password}` | **200** `AuthSession` như trên; 401 `UNAUTHORIZED` |
+| `POST /api/auth/refresh` | `{refreshToken}` | **200** `TokenPair {accessToken, refreshToken}` (rotation CAS §3); 401 khi reuse/hết hạn |
+| `POST /api/auth/logout` | `{refreshToken}` | **204** — **idempotent**: token lạ/đã revoke vẫn 204 (không leak tồn tại) |
+| `POST /api/auth/logout-all` | Bearer (không body) | **204** — revoke tất cả refresh của `sub`; access còn hạn tự chết ở lần refresh kế |
+| `GET /api/auth/users` | — | **200** danh sách user demo — auth-svc serve từ schema `auth` (giữ endpoint v1) |
+
+- **Register**: roles gán `["user"]`; email normalize lowercase trước lưu/lookup; password 8–72 ký tự (argon2 input limit), hash **argon2id**.
+- **FE flow (SF-4)**: login/register → lưu cặp (access → `tokenStorage`, refresh → `localStorage['bp.rt']`); 401 từ API → refresh **đúng một lần** (single-flight) → retry; logout → gọi endpoint + clear cả 2 key.
+- **Lỗi**: envelope conventions/04 — `VALIDATION_ERROR` 400 · `UNAUTHORIZED` 401 · `CONFLICT` 409.
+
+## 5. Secrets + env phân phối
+
+- `JWT_SECRET` — auth-svc **ký**, node-svc/spring-svc/go-svc **verify**. Compose inject cùng một giá trị; không commit (`.env` gitignored).
+- `AUTH_DEV_PASSWORD` *(rename từ `AUTH_MOCK_DEV_PASSWORD` — compose tham chiếu swap ở SF-5, gap-answer ⑦)* — dev password của **seeded fixture users**: seed tạo `password_hash = argon2id(AUTH_DEV_PASSWORD)`. Default **`demo-password` KHÔNG ĐỔI** — e2e + go-svc (`svc-activity` login) + seed cùng một nguồn. `users.json` KHÔNG thêm password — chỉ `$comment` mapping.
+- `ACCESS_TOKEN_TTL=30m` — auth-svc đọc (§1).
+- Seed idempotent `ON CONFLICT (id) DO NOTHING` — UUID fixture giữ nguyên.
+
+## 6. Enforcement 2 lớp (bất biến — giữ nguyên v1)
+
+| Lớp | Ai | Kiểm tra gì | Fail |
+|-----|----|-------------|------|
+| 1 — Presence | nginx gateway | Header `Authorization: Bearer ...` có tồn tại trên `/api/tasks`, `/api/users`, `/api/activity` | `401` ngay tại gateway. `/api/auth`, `/`, `/remotes/*` KHÔNG bị chặn |
+| 2 — Verify | Từng service (node/spring/go) | Tự verify **signature (HS256 với JWT_SECRET) + expiry (`exp`) + `iss`** (giá trị pinned §1). KHÔNG tin kết luận của gateway | `401` error envelope `{code: "UNAUTHORIZED"}` |
+
+Nguyên tắc: gateway là tiện ích giảm noise, **không phải biên bảo mật**. RBAC (roles) là việc của service — SF-3 demo qua node-svc `DELETE` admin-only; gateway chỉ presence-check.
+
+## 7. Ví dụ payload
+
+```json
+{
+  "sub": "11111111-1111-4111-8111-111111111111",
+  "email": "alice@demo.local",
+  "roles": ["admin"],
+  "iss": "auth-mock",
+  "iat": 1728700000,
+  "exp": 1728701800
+}
+```
+
+## 8. Upgrade paths (ngoài scope epic này)
+
+- **RS256/JWKS + OIDC thật**: chuyển sign/verify sang asymmetric + expose `/.well-known/openid-configuration` thật (v2 DROP discovery stub v1 — không ai consume). Claims `sub/email/roles` giữ nguyên để FE/services không đổi.
+- **httpOnly-cookie** cho refresh token (thay `localStorage['bp.rt']`) + CSRF protection.
+- **Đổi chuỗi `iss`** thành `"auth-svc"` — follow-up nhỏ riêng: 3 constants service + 2 CI workflows, làm khi có SF chạm cả 3 vùng.

package/stack-template/contracts/auth/users.json

@@ -0,0 +1,35 @@
+{
+  "$comment": "Fixture users chung — auth-mock (SF-1) đọc runtime; spring-svc seed migration (SF-3) đọc cùng file, id phải khớp 100%. UUID cố định có chủ đích (dễ debug demo). Thêm user mới = thêm entry, KHÔNG đổi id của user cũ (SF-2/3/4 đã seed theo). displayName là nguồn sự thật cho seed SF-3 (khớp User schema trong contracts/openapi/users.yaml). SF-1 FI-77 thêm 2 service user: svc-activity (go-svc login lấy service token — password = SVC_ACTIVITY_PASSWORD env, khớp AUTH_MOCK_DEV_PASSWORD) + svc-fail (simulate fail hook saga — assign task cho user này → go consumer fail ×3 → assignment_failed).",
+  "users": [
+    {
+      "id": "11111111-1111-4111-8111-111111111111",
+      "email": "alice@demo.local",
+      "displayName": "Alice Demo",
+      "roles": ["admin"]
+    },
+    {
+      "id": "22222222-2222-4222-8222-222222222222",
+      "email": "bob@demo.local",
+      "displayName": "Bob Demo",
+      "roles": ["user"]
+    },
+    {
+      "id": "33333333-3333-4333-8333-333333333333",
+      "email": "carol@demo.local",
+      "displayName": "Carol Demo",
+      "roles": ["user"]
+    },
+    {
+      "id": "44444444-4444-4444-8444-444444444444",
+      "email": "svc-activity@demo.local",
+      "displayName": "Svc Activity (service user)",
+      "roles": ["user"]
+    },
+    {
+      "id": "55555555-5555-4555-8555-555555555555",
+      "email": "fail@demo.local",
+      "displayName": "Fail Demo (saga fail hook)",
+      "roles": ["user"]
+    }
+  ]
+}

package/stack-template/contracts/db/tasks-schema.sql

@@ -0,0 +1,62 @@
+-- ============================================================================
+-- CANONICAL DDL — bảng `tasks` (schema `tasks`)
+-- Epic FI-62 · SF-1 (FI-64) sở hữu. SF-2 (node-svc) và SF-4 (go-svc) ĐỌC file này:
+--   - node-svc: migration PHẢI sinh ra cấu trúc KHỚP 1:1 với DDL này
+--     (exit criterion SF-2: diff schema thực tế vs file này = 0)
+--   - go-svc: stats query (`GROUP BY status`, COUNT) dựa trên đúng các cột ở đây
+-- Thay đổi file này = phải đồng bộ contracts/openapi/tasks.yaml (Task schema).
+-- ============================================================================
+
+CREATE SCHEMA IF NOT EXISTS tasks;
+
+CREATE TABLE IF NOT EXISTS tasks.tasks (
+    id            uuid PRIMARY KEY,
+    title         varchar(200) NOT NULL,
+    description   text,
+    status        varchar(20)  NOT NULL DEFAULT 'todo'
+                  CHECK (status IN ('todo', 'in_progress', 'done', 'assignment_failed')),
+    assignee_id   uuid,
+    created_by    uuid NOT NULL,
+    created_at    timestamptz  NOT NULL DEFAULT now(),
+    updated_at    timestamptz  NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_tasks_status      ON tasks.tasks (status);
+CREATE INDEX IF NOT EXISTS idx_tasks_assignee_id ON tasks.tasks (assignee_id);
+CREATE INDEX IF NOT EXISTS idx_tasks_created_at  ON tasks.tasks (created_at DESC);
+
+-- ----------------------------------------------------------------------------
+-- Quyết định thiết kế (đừng "sửa giúp"):
+--
+-- 1. assignee_id / created_by KHÔNG có FK sang schema `users`:
+--    users thuộc schema `users` do spring-svc (SF-3) sở hữu và migrate. FK chéo
+--    schema tạo coupling migration giữa 2 service độc lập. Tính toàn vẹn
+--    được đảm bảo ở mức ứng dụng: node-svc validate assignee qua REST
+--    GET /api/users/{userId} (timeout 2s, fail-closed 503) trước khi ghi.
+--
+-- 2. status là varchar + CHECK constraint (không PG enum type): migration
+--    đa công cụ (drizzle cho SF-2) sinh được 1:1, và CHECK là nguồn sự thật
+--    mirror của enum TaskStatus trong contracts/openapi/tasks.yaml.
+--
+-- 3. id do ứng dụng sinh (uuid v4) — không dùng DEFAULT gen_random_uuid()
+--    để migration của node-svc khớp DDL không cần extension pgcrypto.
+--
+-- 4. `assignment_failed` là TRẠNG THÁI HỆ THỐNG (saga compensation — ADR-0008):
+--    chỉ node-svc compensation consumer ghi qua conditional UPDATE; API PATCH
+--    KHÔNG nhận (TaskStatus writable 3 giá trị, TaskStatusExtended response 4).
+--
+-- 5. Grants: role `go_readonly` được SELECT qua ALTER DEFAULT PRIVILEGES
+--    (platform/postgres/init/01-init.sh) — hiệu lực cho bảng do migration
+--    node-svc tạo SAU script init này.
+--
+-- 6. APPLY CONTEXT (SF-7 note — học từ SF-4, improvements-log finding
+--    "CREATE SCHEMA IF NOT EXISTS permission-denied"): dòng `CREATE SCHEMA`
+--    ở đầu file cần **CREATE privilege trên DATABASE**, khác với phần table
+--    DDL bên dưới chỉ cần CREATE **trên schema `tasks`**. Khi apply-as-role
+--    (per-service DB role chỉ có grant schema-level):
+--      - Chạy phần CREATE SCHEMA bằng owner/bootstrap role (hoặc bỏ qua nếu
+--        schema đã tồn tại — CREATE SCHEMA IF NOT EXISTS vẫn denied với role
+--        thiếu database-level CREATE, dù schema có sẵn);
+--      - Chỉ chạy phần table + index bằng service role.
+--    Compose path không bị ảnh hưởng (init script chạy bằng superuser).
+-- ----------------------------------------------------------------------------

package/stack-template/contracts/events/fixtures/task.assigned.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "id": "2b3c4d5e-6f70-4b80-8c91-0d1e2f3a4b5c",
+  "type": "task.assigned",
+  "occurredAt": "2026-10-13T09:10:00Z",
+  "payload": {
+    "taskId": "c7c7c7c7-7777-4777-8777-777777777777",
+    "userId": "11111111-1111-4111-8111-111111111111",
+    "assigneeId": "22222222-2222-4222-8222-222222222222"
+  }
+}

package/stack-template/contracts/events/fixtures/task.assignment_failed.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "id": "4d5e6f70-8192-4da0-8eb1-2f3a4b5c6d7e",
+  "type": "task.assignment_failed",
+  "occurredAt": "2026-10-13T09:20:00Z",
+  "payload": {
+    "taskId": "c7c7c7c7-7777-4777-8777-777777777777",
+    "assigneeId": "55555555-5555-4555-8555-555555555555",
+    "reason": "simulate notify fail (fixture user svc-fail) — retry x3 het"
+  }
+}

package/stack-template/contracts/events/fixtures/task.created.json

@@ -0,0 +1,12 @@
+{
+  "schemaVersion": 1,
+  "id": "6f1a2b3c-4d5e-4f60-8a71-9b0c1d2e3f40",
+  "type": "task.created",
+  "occurredAt": "2026-10-13T09:00:00Z",
+  "payload": {
+    "taskId": "c7c7c7c7-7777-4777-8777-777777777777",
+    "userId": "11111111-1111-4111-8111-111111111111",
+    "title": "Ship Kafka foundation",
+    "status": "todo"
+  }
+}

package/stack-template/contracts/events/fixtures/task.deleted.json

@@ -0,0 +1,10 @@
+{
+  "schemaVersion": 1,
+  "id": "3c4d5e6f-7081-4c90-8da1-1e2f3a4b5c6d",
+  "type": "task.deleted",
+  "occurredAt": "2026-10-13T09:15:00Z",
+  "payload": {
+    "taskId": "c7c7c7c7-7777-4777-8777-777777777777",
+    "userId": "11111111-1111-4111-8111-111111111111"
+  }
+}

package/stack-template/contracts/events/fixtures/task.updated.json

@@ -0,0 +1,12 @@
+{
+  "schemaVersion": 1,
+  "id": "1a2b3c4d-5e6f-4a70-8b81-9c0d1e2f3a4b",
+  "type": "task.updated",
+  "occurredAt": "2026-10-13T09:05:00Z",
+  "payload": {
+    "taskId": "c7c7c7c7-7777-4777-8777-777777777777",
+    "userId": "11111111-1111-4111-8111-111111111111",
+    "title": "Ship Kafka foundation (đổi tên)",
+    "status": "in_progress"
+  }
+}

package/stack-template/contracts/events/task-events.md

@@ -0,0 +1,80 @@
+# Task events — hợp đồng async (Kafka) giữa node-svc ↔ go-svc
+
+Nguồn sự duy nhất về envelope + payload + consumer convention cho topic `task-events`.
+Mọi producer/consumer (node-svc outbox relay SF-2, go-svc consumer SF-3) PHẢI theo
+file này. Golden fixtures machine-checkable: [`fixtures/`](fixtures/) — relay test +
+consumer test + CI console-producer ĐỀU load chung các file này. Quy tắc vận hành:
+[platform/conventions/09-async-messaging.md](../../platform/conventions/09-async-messaging.md).
+Quyết định kiến trúc: [docs/adr/0008-kafka-outbox-saga.md](../../docs/adr/0008-kafka-outbox-saga.md).
+
+## Envelope (bắt buộc, mọi event)
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "UUIDv4 — producer sinh, KHÓA IDEMPOTENCY của consumer",
+  "type": "task.created | task.updated | task.assigned | task.deleted | task.assignment_failed",
+  "occurredAt": "RFC3339 UTC (vd 2026-10-13T09:00:00Z)",
+  "payload": { "...": "shape theo type — bảng dưới" }
+}
+```
+
+| Field | Kiểu | Quy tắc |
+|---|---|---|
+| `schemaVersion` | integer | Cố định `1`. Thêm field payload không breaking (consumer bỏ qua field lạ); đổi shape breaking = tăng version |
+| `id` | UUIDv4 | Producer sinh MỖI event (trong cùng DB tx với mutation — outbox). Consumer dùng làm khóa idempotency — KHÔNG dùng taskId |
+| `type` | string enum | 5 giá trị ở trên. KHÔNG bịa type mới ngoài enum |
+| `occurredAt` | RFC3339 UTC | Thời điểm mutation (không phải lúc publish) |
+| `payload` | object | Theo type — bảng dưới. Không chứa secret |
+
+## Payload shape theo event type
+
+| Type | Payload fields (camelCase) | Sinh bởi |
+|---|---|---|
+| `task.created` | `taskId` uuid · `userId` uuid (owner) · `title` string · `status` string (`todo\|in_progress\|done`) · `assigneeId` uuid **?** | node-svc (POST) |
+| `task.updated` | `taskId` uuid · `userId` uuid · chỉ các field ĐỔI trong: `title?` · `status?` · `assigneeId?` | node-svc (PATCH không có assigneeId) |
+| `task.assigned` | `taskId` uuid · `userId` uuid (người assign) · `assigneeId` uuid | node-svc (PATCH có `assigneeId` trong body — **presence-based**: same-value re-PATCH vẫn bắn event mới, id mới) |
+| `task.deleted` | `taskId` uuid · `userId` uuid | node-svc (DELETE) |
+| `task.assignment_failed` | `taskId` uuid · `assigneeId` uuid · `reason` string | go-svc consumer (retry ×3 hết — compensating event) |
+
+Quy ước `status` trong payload: chỉ giá trị writable 3 giá trị. `task.assignment_failed`
+là TRẠNG THÁI hệ thống — KHÔNG bao giờ xuất hiện trong `payload.status` của event,
+chỉ tồn tại ở `tasks.status` (DB) qua compensation.
+
+## Topics
+
+| Topic | Partition | Dùng |
+|---|---|---|
+| `task-events` | 1 | Mọi event ở bảng trên. Message **key = `payload.taskId`** — thứ tự per-task guaranteed trong partition |
+| `task-events.dlq` | 1 | Message GỐC + metadata lỗi, sau retry ×3 hết. KHÔNG requeue tự động |
+
+Demo dùng auto-create topic (config mặc định image). Copy production: tạo topic
+tường minh (`kafka-topics.sh --create`), partition theo load, KHÔNG dựa auto-create.
+
+## Consumer groups — filter-by-type convention
+
+Hai group cùng đọc `task-events`, tự lọc theo `type`:
+
+| Group | Nhận | Bỏ qua |
+|---|---|---|
+| `go-svc-activity` (go-svc consumer) | MỌI type **TRỪ** `task.assignment_failed` | `task.assignment_failed` |
+| `node-svc-compensation` (node-svc consumer) | **CHỈ** `task.assignment_failed` | 4 type còn lại |
+
+Thêm group mới = thêm dòng ở đây cùng commit.
+
+## Delivery semantics
+
+- **At-least-once** → consumer PHẢI idempotent: dedupe bằng envelope `id`
+  (vd Postgres `INSERT ... ON CONFLICT (id) DO NOTHING`).
+- **Manual offset commit SAU khi DB tx commit thành công** — commit trước tx =
+  crash giữa chừng mất event; commit sau tx = at-least-once (dedupe lo phần còn lại).
+- **Retry ×3 in-memory** (backoff) cho lỗi xử lý → hết lượt: ghi message gốc vào
+  `task-events.dlq` + metadata lỗi, KHÔNG block partition. Riêng `task.assignment_failed`
+  là compensating event — được PUBLISH lại vào `task-events` (không vào DLQ).
+- `auto.offset.reset: earliest` — consumer mới đọc lại từ đầu (fixture demo, idempotency lo duplicates).
+
+## Không làm
+
+- Không đưa secret/token vào payload (envelope đi qua broker PLAINTEXT — compose-internal).
+- Không đổi envelope/topic/group khi chưa sửa file này + golden fixtures CÙNG commit.
+- Không thêm Avro/Schema Registry — JSON thuần với `schemaVersion` (ADR-0008).