create-wakii-stack 0.0.0-stage → 0.1.1

package/stack-template/services/node-svc/src/db/schema-diff.test.ts

@@ -0,0 +1,252 @@
+// schema-diff.test.ts — EXIT CRITERION SF-2: migration sinh đúng canonical DDL
+// contracts/db/tasks-schema.sql (diff = 0). Không có postgres local → so sánh
+// cấu trúc sau chuẩn hoá (bỏ quote/comment/USING btree/NULLS LAST/tên constraint —
+// các khác biệt purely-cosmetic giữa 2 cách sinh SQL, không đổi semantics).
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const CANONICAL = resolve(here, '../../../../contracts/db/tasks-schema.sql');
+const MIGRATIONS = resolve(here, '../../drizzle');
+
+interface TableDef {
+  name: string;
+  columns: string[];
+  checks: string[];
+  // nội bộ parse — CHECK giữ tên constraint để ALTER ... DROP/ADD CONSTRAINT
+  // (migration sửa CHECK viết dạng drop + add cùng tên) tác động đúng entry.
+  checkDefs: Array<{ name: string; text: string }>;
+}
+
+function stripComments(sql: string): string {
+  return sql
+    .replace(/\r/g, '') // CRLF (Windows checkout) — phá mọi anchor $ phía dưới
+    .split('\n')
+    .filter((l) => !l.trimStart().startsWith('--'))
+    .join('\n')
+    .replace(/--> statement-breakpoint/g, '');
+}
+
+function splitTopLevel(stmt: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let cur = '';
+  for (const ch of stmt) {
+    if (ch === '(') depth++;
+    if (ch === ')') depth--;
+    if (ch === ',' && depth === 0) {
+      parts.push(cur);
+      cur = '';
+    } else {
+      cur += ch;
+    }
+  }
+  if (cur.trim()) parts.push(cur);
+  return parts.map((p) => p.trim()).filter(Boolean);
+}
+
+function unquote(s: string): string {
+  return s.replace(/"/g, '');
+}
+
+function normType(t: string): string {
+  return unquote(t.trim().toLowerCase()).replace(/\s+with\s+time\s+zone/g, ' timestamptz');
+}
+
+function normExpr(e: string): string {
+  return unquote(e.trim().toLowerCase())
+    .replace(/\s*,\s*/g, ',')
+    .replace(/\s+/g, ' ')
+    .replace(/\btasks\.tasks\./g, ''); // CHECK bên migration qualify đủ tên cột — canonical không
+}
+
+function normalizeDdl(sqlText: string): { schemas: string[]; tables: TableDef[]; indexes: string[] } {
+  const schemas: string[] = [];
+  const tables: TableDef[] = [];
+  const indexes: string[] = [];
+
+  for (const rawStmt of stripComments(sqlText).split(';')) {
+    const stmt = rawStmt.trim();
+    if (!stmt) continue;
+    const lower = stmt.toLowerCase();
+
+    if (lower.startsWith('create schema')) {
+      schemas.push(unquote(lower.replace(/create schema (if not exists )?/, 'create schema ').trim()));
+      continue;
+    }
+
+    const idxMatch = stmt.match(
+      /^create index (?:if not exists )?(\S+)\s+on\s+(\S+)\s*(?:using btree\s*)?\(([\s\S]+)\)$/i,
+    );
+    if (idxMatch) {
+      const cols = splitTopLevel(idxMatch[3])
+        .map((c) =>
+          normExpr(c)
+            .replace(/\s+desc\s+nulls\s+last/g, ' desc')
+            .replace(/\s+asc\s+nulls\s+last/g, '')
+            .trim(),
+        )
+        .sort();
+      indexes.push(`${unquote(idxMatch[1]).toLowerCase()} on ${unquote(idxMatch[2]).toLowerCase()} (${cols.join(',')})`);
+      continue;
+    }
+
+    const tblMatch = stmt.match(
+      /^create table (?:if not exists )?((?:"[^"]+"|[\w]+)(?:\.(?:"[^"]+"|[\w]+))?)\s*\(([\s\S]+)\)\s*$/i,
+    );
+    if (tblMatch) {
+      const name = unquote(tblMatch[1]).toLowerCase();
+      const def: TableDef = { name, columns: [], checks: [], checkDefs: [] };
+      for (const item of splitTopLevel(tblMatch[2])) {
+        if (/^constraint /i.test(item) || /^check\s*\(/i.test(item)) {
+          const checkBody = item.match(/check\s*\(([\s\S]+)\)/i);
+          const cname = item.match(/^constraint\s+(\S+)/i);
+          if (checkBody) {
+            def.checkDefs.push({
+              name: cname ? unquote(cname[1]).toLowerCase() : '',
+              text: normExpr(checkBody[1]),
+            });
+            def.checks = def.checkDefs.map((c) => `check (${c.text})`).sort();
+          }
+          continue;
+        }
+        // Column def: name type [primary key] [not null] [default expr] — bố trí lại
+        // deterministic (canonical order) để 2 phía so sánh được. Gộp trước
+        // "timestamp with time zone" → timestamptz; DEFAULT expr là token kế tiếp.
+        const collapsed = item.replace(/\btimestamp\s+with\s+time\s+zone\b/i, 'timestamptz');
+        const parts = collapsed.split(/\s+/);
+        const colName = unquote(parts[0]).toLowerCase();
+        const colType = normType(parts[1]);
+        let isPk = false;
+        let notNull = false;
+        let deflt = '';
+        for (let i = 2; i < parts.length; i++) {
+          const m = parts[i].trim().toLowerCase();
+          if (m === 'primary' && parts[i + 1]?.toLowerCase() === 'key') {
+            isPk = true;
+            i++;
+          } else if (m === 'not' && parts[i + 1]?.toLowerCase() === 'null') {
+            notNull = true;
+            i++;
+          } else if (m === 'default') {
+            deflt = `default ${normExpr(parts[i + 1] ?? '')}`;
+            i++;
+          } else if (m === 'check') {
+            // CHECK inline (canonical style) — gom phần còn lại làm check body
+            const body = parts.slice(i + 1).join(' ').replace(/^\(/, '').replace(/\)$/, '');
+            def.checkDefs.push({ name: '', text: normExpr(body) });
+            def.checks = def.checkDefs.map((c) => `check (${c.text})`).sort();
+            break;
+          }
+        }
+        if (isPk) notNull = false; // PK ngầm NOT NULL — canonical không ghi
+        def.columns.push(
+          [colName, colType, isPk ? 'primary key' : '', notNull ? 'not null' : '', deflt]
+            .filter(Boolean)
+            .join(' '),
+        );
+      }
+      def.columns.sort();
+      def.checks.sort();
+      tables.push(def);
+      continue;
+    }
+
+    // ALTER TABLE ... DROP CONSTRAINT x / ADD CONSTRAINT x CHECK (...) — kiểu
+    // statement drizzle-kit sinh khi sửa CHECK (SF-2 migration 0001). Net effect
+    // trên model: xoá/thêm entry checkDefs theo tên, checks derive lại sorted.
+    const alterMatch = stmt.match(
+      /^alter table (?:only )?\s*((?:"[^"]*"|[\w]+)(?:\.(?:"[^"]*"|[\w]+))?)\s+([\s\S]+)$/i,
+    );
+    if (alterMatch) {
+      const tableName = unquote(alterMatch[1]).toLowerCase();
+      const action = alterMatch[2].trim();
+      const table = tables.find((t) => t.name === tableName);
+      if (!table) throw new Error(`ALTER TABLE trên bảng chưa parse: ${tableName}`);
+
+      const dropMatch = action.match(/^drop constraint (?:if exists )?(\S+)$/i);
+      if (dropMatch) {
+        const cname = unquote(dropMatch[1]).toLowerCase();
+        table.checkDefs = table.checkDefs.filter((c) => c.name !== cname);
+        table.checks = table.checkDefs.map((c) => `check (${c.text})`).sort();
+        continue;
+      }
+      const addMatch = action.match(/^add constraint (\S+) check\s*\(([\s\S]+)\)$/i);
+      if (addMatch) {
+        table.checkDefs.push({ name: unquote(addMatch[1]).toLowerCase(), text: normExpr(addMatch[2]) });
+        table.checks = table.checkDefs.map((c) => `check (${c.text})`).sort();
+        continue;
+      }
+      throw new Error(`Unhandled ALTER TABLE action (mở rộng normalizer): ${action.slice(0, 120)}`);
+    }
+
+    throw new Error(`Unhandled DDL statement (mở rộng normalizer): ${stmt.slice(0, 120)}`);
+  }
+
+  schemas.sort();
+  tables.sort((a, b) => a.name.localeCompare(b.name));
+  indexes.sort();
+  return { schemas, tables, indexes };
+}
+
+describe('migration khớp canonical DDL (exit criterion SF-2: diff = 0)', () => {
+  const canonical = normalizeDdl(readFileSync(CANONICAL, 'utf8'));
+
+  function loadMigrated() {
+    const { readdirSync } = require('node:fs') as typeof import('node:fs');
+    const files = readdirSync(MIGRATIONS)
+      .filter((f) => f.endsWith('.sql'))
+      .sort();
+    expect(files.length).toBeGreaterThan(0);
+    const combined = files.map((f) => readFileSync(resolve(MIGRATIONS, f), 'utf8')).join('\n');
+    return normalizeDdl(combined);
+  }
+
+  it('mọi migration file cộng lại = canonical (outbox whitelist riêng — không đếm vào canonical)', () => {
+    const migrated = loadMigrated();
+    // Bảng outbox là node-internal infra (ADR-0008) — KHÔNG vào canonical DDL:
+    // tách khỏi so sánh canonical, assert expected-def riêng ở test dưới.
+    const OUTBOX = 'tasks.outbox';
+    const migratedContract = migrated.tables.filter((t) => t.name !== OUTBOX);
+
+    // bảng/schema/index sinh ra bởi migration phải phủ đúng canonical
+    expect(migrated.schemas).toEqual(canonical.schemas);
+    expect(migratedContract.map((t) => t.name)).toEqual(canonical.tables.map((t) => t.name));
+    for (const canonTable of canonical.tables) {
+      const migTable = migratedContract.find((t) => t.name === canonTable.name);
+      expect(migTable, `table ${canonTable.name} missing`).toBeDefined();
+      expect(migTable!.columns, `columns of ${canonTable.name}`).toEqual(canonTable.columns);
+      expect(migTable!.checks, `checks of ${canonTable.name}`).toEqual(canonTable.checks);
+    }
+    expect(migrated.indexes).toEqual(canonical.indexes);
+    expect(migrated.tables.map((t) => t.name)).toContain(OUTBOX);
+  });
+
+  it('outbox def đúng expected-def riêng (whitelist SF-2 — node-internal infra)', () => {
+    const { 'tasks.outbox': outboxTable } = Object.fromEntries(
+      loadMigrated()
+        .tables.map((t) => [t.name, t]),
+    );
+    expect(outboxTable).toBeDefined();
+    // Cột đúng spec (epic spec rev 3 / context pack sf-2.md mục 3): id UUID do
+    // node sinh, type, payload jsonb, created_at, published_at nullable.
+    expect(outboxTable!.columns.sort()).toEqual(
+      [
+        'created_at timestamptz not null default now()',
+        'id uuid primary key',
+        'payload jsonb not null',
+        'published_at timestamptz',
+        'type varchar(40) not null',
+      ].sort(),
+    );
+    expect(outboxTable!.checks).toEqual([]); // không CHECK — type do app kiểm soát
+  });
+
+  it('sanity: canonical có bảng tasks.tasks + 3 index + KHÔNG outbox', () => {
+    expect(canonical.tables.map((t) => t.name)).toContain('tasks.tasks');
+    expect(canonical.tables.map((t) => t.name)).not.toContain('tasks.outbox');
+    expect(canonical.indexes.length).toBe(3);
+  });
+});

package/stack-template/services/node-svc/src/db/schema.ts

@@ -0,0 +1,64 @@
+// schema.ts — drizzle definition của bảng `tasks`.
+// NGUỒN SỰ THẬT cấu trúc: contracts/db/tasks-schema.sql (canonical DDL, SF-1).
+// Bất kỳ lệch nào giữa schema này và DDL → schema-diff.test.ts FAIL.
+// Đúng các design decisions trong DDL comment: id app-generated (không
+// gen_random_uuid), status varchar + CHECK (không PG enum), không FK chéo schema.
+import { sql } from 'drizzle-orm';
+import {
+  check,
+  index,
+  jsonb,
+  pgSchema,
+  timestamp,
+  uuid,
+  varchar,
+  text,
+} from 'drizzle-orm/pg-core';
+
+export const tasksSchema = pgSchema('tasks');
+
+export const tasks = tasksSchema.table(
+  'tasks',
+  {
+    id: uuid('id').primaryKey(),
+    title: varchar('title', { length: 200 }).notNull(),
+    description: text('description'),
+    status: varchar('status', { length: 20 }).notNull().default('todo'),
+    assigneeId: uuid('assignee_id'),
+    createdBy: uuid('created_by').notNull(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [
+    // 'assignment_failed' chỉ compensation consumer ghi — API PATCH không nhận
+    // (TaskStatus writable 3 giá trị, TaskStatusExtended response 4 — tasks.yaml).
+    check(
+      'status_check',
+      sql`${t.status} IN ('todo', 'in_progress', 'done', 'assignment_failed')`,
+    ),
+    index('idx_tasks_status').on(t.status),
+    index('idx_tasks_assignee_id').on(t.assigneeId),
+    index('idx_tasks_created_at').on(t.createdAt.desc()),
+  ],
+);
+
+export type TaskRow = typeof tasks.$inferSelect;
+export type NewTaskRow = typeof tasks.$inferInsert;
+
+// outbox — transactional outbox (ADR-0008, conventions/09 rule 2): mutation task
+// + INSERT outbox trong CÙNG 1 tx; relay poll publish rồi mark published_at.
+// KHÔNG vào canonical DDL contracts/db/tasks-schema.sql — node-internal infra
+// (schema-diff.test whitelist riêng, không so với canonical).
+// id = envelope UUIDv4 do node sinh (khóa idempotency của consumer — task-events.md).
+// published_at NULL = chưa publish; relay publish TRƯỚC mark (crash giữa chừng
+// = duplicate → at-least-once, consumer dedupe). Purge: published cũ > 7 ngày.
+export const outbox = tasksSchema.table('outbox', {
+  id: uuid('id').primaryKey(),
+  type: varchar('type', { length: 40 }).notNull(),
+  payload: jsonb('payload').notNull(),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  publishedAt: timestamp('published_at', { withTimezone: true }),
+});
+
+export type OutboxRow = typeof outbox.$inferSelect;
+export type NewOutboxRow = typeof outbox.$inferInsert;

package/stack-template/services/node-svc/src/env.ts

@@ -0,0 +1,52 @@
+// env.ts — parse + fail-fast env config (conventions/06: 100% env-var, không
+// fallback im lặng cho secret). Compose entry pre-seed (SF-1) inject đủ biến.
+export interface Env {
+  port: number;
+  databaseUrl: string;
+  jwtSecret: string;
+  springSvcUrl: string;
+  goSvcUrl: string;
+  corsDevOrigin: string; // rỗng = deny-by-default (conventions/07)
+  logLevel: 'debug' | 'info' | 'warn' | 'error';
+  // OPTIONAL (conventions/09 rule 1 — lazy-connect): thiếu = relay + consumer
+  // KHÔNG start (warn 1 lần), service vẫn boot — Kafka KHÔNG vào readyz.
+  kafkaBrokers: string | null;
+}
+
+export function loadEnv(source: NodeJS.ProcessEnv = process.env): Env {
+  const missing: string[] = [];
+  const need = (name: string): string => {
+    const v = source[name];
+    if (!v || v.trim() === '') missing.push(name);
+    return v ?? '';
+  };
+
+  const port = Number(need('PORT') || '3001');
+  const databaseUrl = need('DATABASE_URL');
+  const jwtSecret = need('JWT_SECRET');
+  const springSvcUrl = need('SPRING_SVC_URL');
+  const goSvcUrl = need('GO_SVC_URL');
+  const corsDevOrigin = source.CORS_DEV_ORIGIN ?? '';
+  const logLevelRaw = source.LOG_LEVEL ?? 'info';
+
+  if (Number.isNaN(port) || port <= 0) {
+    throw new Error(`PORT invalid: "${source.PORT}" (conventions/05: node-svc = 3001)`);
+  }
+  if (!['debug', 'info', 'warn', 'error'].includes(logLevelRaw)) {
+    throw new Error(`LOG_LEVEL invalid: "${logLevelRaw}" (debug|info|warn|error)`);
+  }
+  if (missing.length > 0) {
+    throw new Error(`Missing required env vars: ${missing.join(', ')} (platform/.env.example)`);
+  }
+
+  return {
+    port,
+    databaseUrl,
+    jwtSecret,
+    springSvcUrl: springSvcUrl.replace(/\/+$/, ''),
+    goSvcUrl: goSvcUrl.replace(/\/+$/, ''),
+    corsDevOrigin,
+    logLevel: logLevelRaw as Env['logLevel'],
+    kafkaBrokers: source.KAFKA_BROKERS?.trim() || null,
+  };
+}

package/stack-template/services/node-svc/src/logger.ts

@@ -0,0 +1,18 @@
+// logger.ts — pino JSON shape chung (conventions/03): ts ISO-8601 UTC ms,
+// level, service, msg, requestId. Không console.log — mọi log qua đây.
+import pino from 'pino';
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export function nodeSvcLogger(level: LogLevel = 'info'): pino.Logger {
+  return pino({
+    level,
+    base: { service: 'node-svc' },
+    timestamp: () => `,"ts":"${new Date().toISOString()}"`,
+    // conventions/03: không log JWT/password toàn phần
+    redact: {
+      paths: ['authorization', 'req.headers.authorization', 'password', '*.password', 'token', '*.token'],
+      censor: '[REDACTED]',
+    },
+  });
+}

package/stack-template/services/node-svc/src/outbox-relay.test.ts

@@ -0,0 +1,141 @@
+// outbox-relay.test.ts — relay publish ĐÚNG golden fixture format (SF-2 FI-79).
+// Test load CHUNG contracts/events/fixtures/*.json với consumer test SF-3 +
+// CI console-producer (task-events.md) — không tự bịa format. Fake producer +
+// fake store → không cần broker (CI boot-smoke chạy relay THẬT trên kafka).
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import type { OutboxRow } from './db/schema.js';
+import {
+  OutboxRelay,
+  TASK_EVENTS_TOPIC,
+  toEnvelope,
+  type EventPublisher,
+  type OutboxMessage,
+  type OutboxStore,
+} from './outbox-relay.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const FIXTURES = resolve(here, '../../../contracts/events/fixtures');
+
+const FIXTURE_TYPES = [
+  'task.created',
+  'task.updated',
+  'task.assigned',
+  'task.deleted',
+] as const;
+
+function loadFixture(name: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(resolve(FIXTURES, `${name}.json`), 'utf8')) as Record<string, unknown>;
+}
+
+function fakeStore(
+  rows: OutboxRow[],
+  purged = 0,
+): OutboxStore & { marked: string[][]; purgeCalls: Date[] } {
+  return {
+    marked: [],
+    purgeCalls: [],
+    async findUnpublished() {
+      return rows;
+    },
+    async markPublished(ids: string[]) {
+      this.marked.push(ids);
+    },
+    async purgePublished(olderThan: Date) {
+      this.purgeCalls.push(olderThan);
+      return purged;
+    },
+  };
+}
+
+function fakePublisher(): EventPublisher & { sent: Array<{ topic: string; messages: OutboxMessage[] }> } {
+  return { sent: [], async send(topic, messages) { this.sent.push({ topic, messages }); } };
+}
+
+/** OutboxRow từ golden fixture — payload/type lấy TRỰC TIẾP từ fixture (2 đầu
+ *  load chung file), id/createdAt mô phỏng repo sinh. */
+function rowFromFixture(type: string): OutboxRow {
+  const fixture = loadFixture(type);
+  return {
+    id: fixture.id as string,
+    type,
+    payload: fixture.payload as Record<string, unknown>,
+    createdAt: new Date('2026-10-13T09:00:00.000Z'),
+    publishedAt: null,
+  };
+}
+
+describe('OutboxRelay — publish đúng golden fixture format', () => {
+  it('mỗi fixture type: message value khớp fixture (schemaVersion/type/payload 1:1)', async () => {
+    for (const type of FIXTURE_TYPES) {
+      const fixture = loadFixture(type);
+      const rows = [rowFromFixture(type)];
+      const store = fakeStore(rows);
+      const publisher = fakePublisher();
+      const relay = new OutboxRelay(store, publisher, () => {}, 500);
+
+      await relay.tick();
+
+      expect(publisher.sent).toHaveLength(1);
+      expect(publisher.sent[0].topic).toBe(TASK_EVENTS_TOPIC);
+      const message = publisher.sent[0].messages[0];
+      // key = payload.taskId (task-events.md — thứ tự per-task trong partition)
+      expect(message.key).toBe((fixture.payload as { taskId: string }).taskId);
+
+      const envelope = JSON.parse(message.value) as Record<string, unknown>;
+      // Envelope khớp golden fixture 1:1 (id + occurredAt là dữ liệu repo sinh)
+      expect(Object.keys(envelope).sort()).toEqual(Object.keys(fixture).sort());
+      expect(envelope.schemaVersion).toBe(1);
+      expect(envelope.type).toBe(fixture.type);
+      expect(envelope.payload).toEqual(fixture.payload);
+      expect(typeof envelope.id).toBe('string');
+      expect(envelope.occurredAt).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
+      // publish xong mới mark published_at
+      expect(store.marked).toEqual([[fixture.id]]);
+    }
+  });
+
+  it('toEnvelope: occurredAt = createdAt (thời điểm mutation, không phải lúc publish)', () => {
+    const row = rowFromFixture('task.created');
+    const envelope = toEnvelope(row);
+    expect(envelope.occurredAt).toBe('2026-10-13T09:00:00.000Z');
+    expect(envelope.id).toBe(row.id);
+    expect(envelope.schemaVersion).toBe(1);
+  });
+
+  it('tick fail (broker down) → warn, row giữ nguyên unpublished → tick sau retry', async () => {
+    const rows = [rowFromFixture('task.created')];
+    const store = fakeStore(rows);
+    const publisher: EventPublisher = {
+      async send() {
+        throw new Error('broker down');
+      },
+    };
+    const logs: Array<[string, string]> = [];
+    const relay = new OutboxRelay(store, publisher, (level, msg) => logs.push([level, msg]), 500);
+
+    await relay.tick();
+
+    expect(logs[0][0]).toBe('warn'); // KHÔNG crash — conventions/09 rule 1
+    expect(store.marked).toHaveLength(0); // KHÔNG mark khi publish fail
+  });
+
+  it('purge published cũ > N ngày chạy định kỳ theo tick', async () => {
+    const store = fakeStore([], 3);
+    const publisher = fakePublisher();
+    const relay = new OutboxRelay(store, publisher, () => {}, 500, {
+      purgeEveryTicks: 2,
+      purgeAfterMs: 1000,
+    });
+
+    await relay.tick();
+    expect(store.purgeCalls).toHaveLength(0); // tick 1 — chưa tới chu kỳ
+
+    await relay.tick();
+    expect(store.purgeCalls).toHaveLength(1);
+    // cutoff = now - 1000 (tính TRONG tick, sau khi 2 tick chạy) — đúng chiều
+    expect(store.purgeCalls[0].getTime()).toBeLessThanOrEqual(Date.now() - 1000);
+  });
+});