create-wakii-stack 0.0.0-stage → 0.1.1

package/stack-template/services/auth-svc/src/repo.test-support.ts

@@ -0,0 +1,168 @@
+// repo.test-support.ts — InMemoryAuthRepo: mirror ĐÚNG semantics của
+// DrizzleAuthRepo (rotation CAS 1 "tx": select row → CAS revoked_at IS NULL
+// AND expires_at > now → 0 rows = reuse → revoke-all user; token lạ → không
+// revoke). Chỉ dùng bởi *.test.ts — excluded khỏi build (tsconfig).
+// Atomicity THẬT trên postgres được chứng minh ở repo.drizzle.integration.test.ts.
+import { randomUUID } from 'node:crypto';
+import { hashPassword, sha256Hex } from './auth-crypto.js';
+import type {
+  AuthRepo,
+  AuthUser,
+  AuthUserWithHash,
+  FixtureUser,
+  NewRefreshTokenInput,
+  NewUserInput,
+  RotateResult,
+} from './repo.js';
+
+const DEMO_HASH = await hashPassword('demo-password');
+
+export interface UserRow extends AuthUserWithHash {
+  createdAt: Date;
+}
+
+export interface RefreshRow {
+  id: string;
+  userId: string;
+  tokenHash: string;
+  expiresAt: Date;
+  revokedAt: Date | null;
+  replacedBy: string | null;
+  createdAt: Date;
+}
+
+export function aliceRow(): UserRow {
+  return {
+    id: '11111111-1111-4111-8111-111111111111',
+    email: 'alice@demo.local',
+    displayName: 'Alice Demo',
+    roles: ['admin'],
+    passwordHash: DEMO_HASH,
+    createdAt: new Date('2026-01-01T00:00:00Z'),
+  };
+}
+
+export function bobRow(): UserRow {
+  return {
+    id: '22222222-2222-4222-8222-222222222222',
+    email: 'bob@demo.local',
+    displayName: 'Bob Demo',
+    roles: ['user'],
+    passwordHash: DEMO_HASH,
+    createdAt: new Date('2026-01-01T00:00:01Z'),
+  };
+}
+
+function duplicateEmailError(): Error & { code: string } {
+  const err = new Error('duplicate key value violates unique constraint "users_email_unique"') as Error & { code: string };
+  err.code = '23505';
+  return err;
+}
+
+export class InMemoryAuthRepo implements AuthRepo {
+  users = new Map<string, UserRow>();
+  refreshRows: RefreshRow[] = [];
+  failPing = false;
+
+  constructor(seed: UserRow[] = []) {
+    for (const row of seed) this.users.set(row.id, { ...row });
+  }
+
+  seedUserRow(row: UserRow): void {
+    this.users.set(row.id, { createdAt: new Date(0), ...row });
+  }
+
+  rowByToken(rawToken: string): RefreshRow | undefined {
+    const hash = sha256Hex(rawToken);
+    return this.refreshRows.find((r) => r.tokenHash === hash);
+  }
+
+  async ping(): Promise<void> {
+    if (this.failPing) throw new Error('db down');
+  }
+
+  async listUsers(): Promise<FixtureUser[]> {
+    return [...this.users.values()]
+      .sort((a, b) => (a.createdAt?.getTime() ?? 0) - (b.createdAt?.getTime() ?? 0) || a.id.localeCompare(b.id))
+      .map((u) => ({ id: u.id, email: u.email, roles: [...u.roles] }));
+  }
+
+  async getUserByEmail(email: string): Promise<AuthUserWithHash | null> {
+    const normalized = email.trim().toLowerCase();
+    for (const u of this.users.values()) {
+      if (u.email === normalized) return { id: u.id, email: u.email, displayName: u.displayName, roles: [...u.roles], passwordHash: u.passwordHash };
+    }
+    return null;
+  }
+
+  async getUserById(id: string): Promise<AuthUser | null> {
+    const u = this.users.get(id);
+    return u ? { id: u.id, email: u.email, displayName: u.displayName, roles: [...u.roles] } : null;
+  }
+
+  async createUser(input: NewUserInput): Promise<AuthUser> {
+    const normalized = input.email.trim().toLowerCase();
+    for (const u of this.users.values()) {
+      if (u.email === normalized) throw duplicateEmailError();
+    }
+    const row: UserRow = { ...input, email: normalized, roles: [...input.roles], createdAt: new Date() };
+    this.users.set(row.id, row);
+    return { id: row.id, email: row.email, displayName: row.displayName, roles: [...row.roles] };
+  }
+
+  async insertUserIfAbsent(input: NewUserInput): Promise<boolean> {
+    if (this.users.has(input.id)) return false; // ON CONFLICT (id) DO NOTHING
+    const normalized = input.email.trim().toLowerCase();
+    for (const u of this.users.values()) {
+      if (u.email === normalized) return false;
+    }
+    this.users.set(input.id, { ...input, email: normalized, roles: [...input.roles], createdAt: new Date() });
+    return true;
+  }
+
+  async insertRefreshToken(input: NewRefreshTokenInput): Promise<void> {
+    this.refreshRows.push({ ...input, revokedAt: null, replacedBy: null, createdAt: new Date() });
+  }
+
+  // CAS semantics của DrizzleAuthRepo — KHÔNG atomic thật (postgres chứng minh),
+  // nhưng cùng luật: revoked_at IS NULL AND expires_at > now().
+  async rotateRefreshToken(oldTokenHash: string, next: Omit<NewRefreshTokenInput, 'userId'>): Promise<RotateResult> {
+    const old = this.refreshRows.find((r) => r.tokenHash === oldTokenHash);
+    if (!old) return { status: 'unknown' };
+    const now = new Date();
+    const wins = old.revokedAt === null && old.expiresAt.getTime() > now.getTime();
+    if (!wins) {
+      // reuse-detect: revoke TẤT CẢ của user (token-contract §3)
+      for (const r of this.refreshRows) {
+        if (r.userId === old.userId && r.revokedAt === null) r.revokedAt = now;
+      }
+      return { status: 'reuse' };
+    }
+    old.revokedAt = now;
+    old.replacedBy = next.id;
+    this.refreshRows.push({ ...next, userId: old.userId, revokedAt: null, replacedBy: null, createdAt: now });
+    return { status: 'ok', userId: old.userId };
+  }
+
+  async revokeByTokenHash(tokenHash: string): Promise<void> {
+    const row = this.refreshRows.find((r) => r.tokenHash === tokenHash);
+    if (row && row.revokedAt === null) row.revokedAt = new Date();
+  }
+
+  async revokeAllForUser(userId: string): Promise<void> {
+    const now = new Date();
+    for (const r of this.refreshRows) {
+      if (r.userId === userId && r.revokedAt === null) r.revokedAt = now;
+    }
+  }
+}
+
+export function makeRefreshInput(userId: string, rawToken: string, ttlMs = 7 * 24 * 3600 * 1000): NewRefreshTokenInput & { token: string } {
+  return {
+    id: randomUUID(),
+    userId,
+    tokenHash: sha256Hex(rawToken),
+    expiresAt: new Date(Date.now() + ttlMs),
+    token: rawToken,
+  };
+}

package/stack-template/services/auth-svc/src/repo.ts

@@ -0,0 +1,60 @@
+// repo.ts — bề mặt dữ liệu auth (interface). DrizzleAuthRepo = postgres thật;
+// InMemoryAuthRepo (repo.test-support.ts) mirror semantics cho unit test.
+// Điểm nóng nhất là rotateRefreshToken — CAS atomic 1 tx (token-contract.md §3).
+export interface AuthUser {
+  id: string;
+  email: string;
+  displayName: string;
+  roles: string[];
+}
+
+export interface AuthUserWithHash extends AuthUser {
+  passwordHash: string;
+}
+
+export interface FixtureUser {
+  id: string;
+  email: string;
+  roles: string[];
+}
+
+export interface NewUserInput {
+  id: string;
+  email: string; // đã normalize lowercase ở tầng route
+  displayName: string;
+  roles: string[];
+  passwordHash: string;
+}
+
+export interface NewRefreshTokenInput {
+  id: string;
+  userId: string;
+  tokenHash: string; // sha256 hex — DB không lưu raw
+  expiresAt: Date;
+}
+
+export type RotateResult =
+  | { status: 'ok'; userId: string } // CAS thắng — cặp mới đã INSERT trong cùng tx
+  | { status: 'reuse' } // 0 rows (đã dùng/revoked/hết hạn) → đã revoke-all user
+  | { status: 'unknown' }; // token lạ không có row — không biết user, không revoke gì
+
+export interface AuthRepo {
+  ping(): Promise<void>;
+  listUsers(): Promise<FixtureUser[]>;
+  getUserByEmail(email: string): Promise<AuthUserWithHash | null>;
+  getUserById(id: string): Promise<AuthUser | null>;
+  /** Email trùng → throw error có .code = '23505' (route map → 409 CONFLICT). */
+  createUser(input: NewUserInput): Promise<AuthUser>;
+  /** Seed idempotent — ON CONFLICT (id) DO NOTHING; true = insert mới. */
+  insertUserIfAbsent(input: NewUserInput): Promise<boolean>;
+  insertRefreshToken(input: NewRefreshTokenInput): Promise<void>;
+  /**
+   * Rotation CAS trong 1 tx (token-contract §3). `next` KHÔNG có userId —
+   * repo tự fill từ row cũ (route chưa biết user khi nhận token opaque).
+   * 'ok' trả userId để route sign access token mới.
+   */
+  rotateRefreshToken(oldTokenHash: string, next: Omit<NewRefreshTokenInput, 'userId'>): Promise<RotateResult>;
+  /** Idempotent — token lạ/đã revoke = no-op (logout 204 không leak tồn tại). */
+  revokeByTokenHash(tokenHash: string): Promise<void>;
+  revokeAllForUser(userId: string): Promise<void>;
+}

package/stack-template/services/auth-svc/src/routes/auth.ts

@@ -0,0 +1,193 @@
+// auth.ts — 5 endpoints + GET /users (contracts/openapi/auth.yaml v2 +
+// contracts/auth/token-contract.md v2 — ĐỌC CÙNG, 2 file là một hiệp ước):
+//   POST /register  201 AuthSession {user, accessToken, refreshToken} | 409
+//   POST /login     200 AuthSession | 401 (message chung, không lộ user tồn tại)
+//   POST /refresh   200 TokenPair (rotation CAS §3) | 401 reuse/hết hạn/lạ
+//   POST /logout    204 idempotent
+//   POST /logout-all 204 (Bearer bắt buộc) — revoke tất cả của sub
+//   GET  /users     200 {users:[{id,email,roles}]} — serve từ schema auth (giữ v1)
+// KHÔNG log password/refreshToken (logger redact + không đưa vào log call).
+import { randomUUID } from 'node:crypto';
+import type { FastifyInstance } from 'fastify';
+import jwt from 'jsonwebtoken';
+import { REFRESH_TTL_MS, hashPassword, newRefreshToken, sha256Hex, verifyPassword } from '../auth-crypto.js';
+import { JWT_ISSUER, requireBearer } from '../plugins/auth.js';
+import type { AuthRepo, AuthUser, NewUserInput } from '../repo.js';
+
+// HttpError — envelope handler của app đọc statusCode + code (mirror node-svc).
+export class HttpError extends Error {
+  // statusCode (không phải status) — tên fastify error handler đọc
+  constructor(
+    public readonly statusCode: number,
+    public readonly code: string,
+    message: string,
+    public readonly details?: unknown,
+  ) {
+    super(message);
+  }
+}
+
+// Dummy hash cho timing equalization khi email lạ — verify THẬT vào 1 hash
+// argon2id huyền thoại để thời gian phản hồi 401 không phân biệt email tồn tại.
+const DUMMY_HASH: string = await hashPassword(`dummy-${randomUUID()}`);
+
+const emailSchema = { type: 'string', format: 'email' } as const;
+
+const registerBodySchema = {
+  type: 'object',
+  required: ['email', 'password', 'displayName'],
+  properties: {
+    email: emailSchema,
+    password: { type: 'string', minLength: 8, maxLength: 72 }, // argon2 input limit — auth.yaml
+    displayName: { type: 'string', minLength: 1 },
+  },
+} as const;
+
+const loginBodySchema = {
+  type: 'object',
+  required: ['email', 'password'],
+  properties: { email: emailSchema, password: { type: 'string', minLength: 1 } },
+} as const;
+
+const refreshBodySchema = {
+  type: 'object',
+  required: ['refreshToken'],
+  properties: { refreshToken: { type: 'string', minLength: 1 } },
+} as const;
+
+interface Deps {
+  repo: AuthRepo;
+  jwtSecret: string;
+  accessTokenTtl: string;
+}
+
+function normalizeEmail(email: string): string {
+  return email.trim().toLowerCase();
+}
+
+function signAccessToken(user: AuthUser, jwtSecret: string, ttl: string): string {
+  // claims giữ nguyên shape v1 — iss LITERAL "auth-mock" PINNED (token-contract §1)
+  return jwt.sign(
+    { sub: user.id, email: user.email, roles: user.roles, iss: JWT_ISSUER },
+    jwtSecret,
+    { algorithm: 'HS256', expiresIn: ttl as jwt.SignOptions['expiresIn'] }, // '30m' — env đã validate format
+  );
+}
+
+function toPublicUser(user: AuthUser): { id: string; email: string; displayName: string; roles: string[] } {
+  return { id: user.id, email: user.email, displayName: user.displayName, roles: user.roles };
+}
+
+export function registerAuthRoutes(app: FastifyInstance, deps: Deps): void {
+  const { repo, jwtSecret, accessTokenTtl } = deps;
+
+  // Cấp session: sign access + INSERT refresh token (sha256-at-rest, TTL 7d)
+  const issueSession = async (user: AuthUser) => {
+    const refreshToken = newRefreshToken();
+    await repo.insertRefreshToken({
+      id: randomUUID(),
+      userId: user.id,
+      tokenHash: sha256Hex(refreshToken),
+      expiresAt: new Date(Date.now() + REFRESH_TTL_MS),
+    });
+    return { user: toPublicUser(user), accessToken: signAccessToken(user, jwtSecret, accessTokenTtl), refreshToken };
+  };
+
+  // ---- register (auth.yaml v2 — 201, đăng nhập luôn sau khi tạo) ----
+  app.post(
+    '/register',
+    { schema: { body: registerBodySchema } },
+    async (request, reply) => {
+      const body = request.body as { email: string; password: string; displayName: string };
+      const input: NewUserInput = {
+        id: randomUUID(),
+        email: normalizeEmail(body.email), // lưu lowercase-normalized — auth.yaml description
+        displayName: body.displayName,
+        roles: ['user'], // register luôn gán ["user"] — spec §Register
+        passwordHash: await hashPassword(body.password),
+      };
+      let created: AuthUser;
+      try {
+        created = await repo.createUser(input);
+      } catch (err) {
+        if ((err as { code?: string }).code === '23505') {
+          // race-safe: UNIQUE violation → 409 (không leak nhiều hơn cần)
+          throw new HttpError(409, 'CONFLICT', 'Email đã tồn tại');
+        }
+        throw err;
+      }
+      const session = await issueSession(created);
+      reply.status(201);
+      return session;
+    },
+  );
+
+  // ---- login ----
+  app.post(
+    '/login',
+    { schema: { body: loginBodySchema } },
+    async (request) => {
+      const body = request.body as { email: string; password: string };
+      const user = await repo.getUserByEmail(normalizeEmail(body.email));
+      // Verify THẬT kể cả khi user lạ (dummy hash) — 401 không phân biệt nguyên
+      // nhân, không rò sự tồn tại email qua timing (message chung auth-mock v1).
+      const passwordOk = await verifyPassword(user?.passwordHash ?? DUMMY_HASH, body.password);
+      if (!user || !passwordOk) {
+        throw new HttpError(401, 'UNAUTHORIZED', 'Invalid credentials');
+      }
+      return issueSession(user);
+    },
+  );
+
+  // ---- refresh (rotation CAS + reuse-detect — token-contract §3) ----
+  app.post(
+    '/refresh',
+    { schema: { body: refreshBodySchema } },
+    async (request) => {
+      const { refreshToken } = request.body as { refreshToken: string };
+      // Sinh raw token mới TRƯỚC — route giữ raw để trả client, repo chỉ thấy
+      // hash (DB không bao giờ chứa raw — token-contract §2).
+      const nextRaw = newRefreshToken();
+      const result = await repo.rotateRefreshToken(sha256Hex(refreshToken), {
+        id: randomUUID(),
+        tokenHash: sha256Hex(nextRaw),
+        expiresAt: new Date(Date.now() + REFRESH_TTL_MS),
+      });
+      if (result.status === 'unknown') {
+        // Token lạ (không row) — chỉ 401, không revoke gì, không biết user
+        throw new HttpError(401, 'UNAUTHORIZED', 'Invalid or expired refresh token');
+      }
+      if (result.status === 'reuse') {
+        // Strict — mọi session của user vừa bị revoke, client phải login lại
+        throw new HttpError(401, 'UNAUTHORIZED', 'Refresh token reuse detected — all sessions revoked');
+      }
+      const user = await repo.getUserById(result.userId);
+      if (!user) throw new HttpError(401, 'UNAUTHORIZED', 'Invalid or expired refresh token');
+      return { accessToken: signAccessToken(user, jwtSecret, accessTokenTtl), refreshToken: nextRaw };
+    },
+  );
+
+  // ---- logout (204 idempotent — token lạ/đã revoke vẫn 204, không leak) ----
+  app.post('/logout', { schema: { body: refreshBodySchema } }, async (request, reply) => {
+    const { refreshToken } = request.body as { refreshToken: string };
+    await repo.revokeByTokenHash(sha256Hex(refreshToken));
+    reply.status(204);
+    return null;
+  });
+
+  // ---- logout-all (Bearer bắt buộc — verify iss literal PINNED) ----
+  app.post(
+    '/logout-all',
+    { preHandler: requireBearer(jwtSecret) },
+    async (request, reply) => {
+      await repo.revokeAllForUser(request.user!.sub);
+      reply.status(204);
+      return null;
+    },
+  );
+
+  // ---- users (giữ v1 — danh sách demo cho FE picker, serve từ schema auth) ----
+  app.get('/users', async () => {
+    return { users: await repo.listUsers() };
+  });
+}

package/stack-template/services/auth-svc/src/routes/health.ts

@@ -0,0 +1,40 @@
+// health.ts — /healthz (liveness) + /readyz (readiness = SELECT 1 thật —
+// conventions/02 rule 2, KHÔNG hardcode 200). Đăng ký 2 lần: naked path
+// (compose healthcheck + CI boot-smoke) và mirror /api/auth/* (auth.yaml
+// servers.url + schemathesis — conventions/02 rule 6). CẢ HAI không-auth.
+import type { FastifyInstance } from 'fastify';
+import type { AuthRepo } from '../repo.js';
+
+function healthBody(): { status: 'ok' } {
+  return { status: 'ok' };
+}
+
+function notReady(): {
+  error: { code: string; message: string; requestId: string | null; details: null };
+} {
+  return {
+    error: {
+      code: 'DEPENDENCY_DOWN',
+      message: 'database not ready',
+      requestId: null,
+      details: null,
+    },
+  };
+}
+
+export function registerHealthRoutes(app: FastifyInstance, repo: AuthRepo): void {
+  app.get('/healthz', async () => healthBody());
+
+  app.get(
+    '/readyz',
+    async (_request, reply) => {
+      try {
+        await repo.ping();
+        return healthBody();
+      } catch {
+        reply.status(503);
+        return notReady();
+      }
+    },
+  );
+}

package/stack-template/services/auth-svc/src/server.ts

@@ -0,0 +1,54 @@
+// server.ts — boot entry (mirror node-svc): env fail-fast → DB + migration →
+// seed users fixture (idempotent — USERS_FIXTURE_PATH optional, thiếu = warn +
+// bỏ seed, register vẫn chạy) → listen PORT. Migration chạy lúc boot → CI
+// boot-smoke thấy "migration chạy xong" qua readyz 200 (SELECT 1 thật).
+import { buildApp, migrationsFolder } from './app.js';
+import { closeDb, createDb } from './db/client.js';
+import { runMigrations } from './db/migrate.js';
+import { seedUsersFromFixture } from './db/seed.js';
+import { loadEnv } from './env.js';
+import { authSvcLogger } from './logger.js';
+import { DrizzleAuthRepo } from './repo.drizzle.js';
+
+async function main(): Promise<void> {
+  const env = loadEnv();
+  const logger = authSvcLogger(env.logLevel);
+
+  const { pool, db } = createDb(env.databaseUrl);
+  const repo = new DrizzleAuthRepo(db);
+
+  // Migration — custom runner (xem db/migrate.ts: role auth_svc không có CREATE
+  // trên database, chỉ trên schema auth — SF-5 init script).
+  const ran = await runMigrations(db, migrationsFolder());
+  logger.info({ migrations: ran }, 'migrations applied');
+
+  // Seed fixture — idempotent ON CONFLICT (id) DO NOTHING. USERS_FIXTURE_PATH:
+  // set mà file thiếu/sai = fail-fast (config lỗi); không set = warn + skip
+  // (service vẫn boot — register/login user tự tạo vẫn chạy; compose + CI luôn set).
+  if (env.usersFixturePath) {
+    await seedUsersFromFixture(repo, env.usersFixturePath, env.authDevPassword, logger);
+  } else {
+    logger.warn('USERS_FIXTURE_PATH not set — skip seeding fixture users (register vẫn hoạt động)');
+  }
+
+  const app = buildApp({ env, repo });
+
+  const shutdown = async (signal: string): Promise<void> => {
+    logger.info({ signal }, 'shutting down');
+    await app.close();
+    await closeDb({ pool, db });
+    process.exit(0);
+  };
+  process.on('SIGINT', () => void shutdown('SIGINT'));
+  process.on('SIGTERM', () => void shutdown('SIGTERM'));
+
+  await app.listen({ port: env.port, host: '0.0.0.0' });
+  logger.info({ port: env.port }, 'auth-svc listening');
+}
+
+main().catch((err) => {
+  // fail-fast boot (conventions/06 rule 6) — không fallback im lặng
+  // eslint-disable-next-line no-console
+  console.error(JSON.stringify({ level: 'error', service: 'auth-svc', msg: 'boot failed', err: err instanceof Error ? err.stack : String(err) }));
+  process.exit(1);
+});

package/stack-template/services/auth-svc/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": false,
+    "sourceMap": false,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "src/**/*.test.ts", "src/**/*.test-support.ts"]
+}

package/stack-template/services/go-svc/.dockerignore

@@ -0,0 +1,5 @@
+.git
+.github
+docs
+test
+*.md

package/stack-template/services/go-svc/Dockerfile

@@ -0,0 +1,19 @@
+# go-svc — multi-stage distroless (platform/conventions/01).
+# Lệch nhỏ có chủ đích (dev machine không có Go — SF-4 README có ghi chú):
+# conventions/01 template COPY go.mod go.sum — go.sum không sinh được trên dev
+# machine (không toolchain), nên `go mod tidy` sinh go.sum in-image trước build.
+
+# build stage
+FROM golang:1.24-alpine AS build
+WORKDIR /src
+COPY go.mod ./
+RUN go mod download
+COPY . .
+# go.sum không commit (dev machine không có Go) — tidy sinh trước build
+RUN go mod tidy && 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"]

package/stack-template/services/go-svc/README.md

@@ -0,0 +1,93 @@
+# go-svc — activity API + Kafka consumer (Go 1.24 + chi)
+
+Service Go của boilerplate microservice: consume activity event qua **Kafka** topic `task-events` (idempotent, retry ×3 → DLQ + saga compensation), serve feed + stats cho FE. Sở hữu schema `activity` (tự migrate); đọc-ONLY schema `tasks` qua postgres role `go_readonly`.
+
+> Part of story Kafka + Outbox + Saga (Linear FI-76) — SF-3 / [FI-80](https://linear.app/hoivu/issue/FI-80). Supersedes luồng REST fire-and-forget của SF-4 (ADR-0008 supersede ADR-0006).
+
+## API surface
+
+Contract nguồn sự thật: [`contracts/openapi/activity.yaml`](../../contracts/openapi/activity.yaml) — service KHÔNG codegen từ spec. Snapshot nhúng `internal/api/openapi/activity.yaml` phải **bit-identical** với contract (CI job `drift-guard` chặn lệch).
+
+| Method | Path | Auth | Mô tả |
+|--------|------|------|-------|
+| GET | `/healthz` | không | Liveness — `{"status":"ok"}` (naked path, compose/CI probe) |
+| GET | `/readyz` | không | Readiness — migration `activity` xong + SELECT thử được schema `tasks` (readonly); fail → `503` envelope |
+| GET | `/api/activity/healthz`, `/api/activity/readyz` | không | Mirror dưới prefix (auth-mock precedent) |
+| GET | `/api/activity/feed` | JWT | Feed mới nhất trước + `total`; item bắt buộc có `userName` + `taskTitle` |
+| GET | `/api/activity/stats` | JWT | `totalTasks` + `tasksByStatus` (todo/in_progress/done/assignment_failed) + `recentEvents` (24h) |
+| GET | `/api/activity/docs` | không | Swagger UI (static, vendored — offline) |
+| GET | `/api/activity/openapi.yaml` | không | Spec copy cho swagger-ui (sync-check test + drift-guard chống drift với contracts) |
+| ~~POST~~ | ~~`/api/activity/events`~~ | — | **ĐÃ THANH LÝ** (SF-3) → `404` — event đi qua Kafka consumer (ADR-0008) |
+
+Qua nginx gateway (`:8080/api/activity/*`): gateway presence-check JWT (401 nếu thiếu). **Swagger UI qua gateway sẽ ăn 401** vì presence-check áp cho cả `/docs` — demo browser dùng direct port `http://localhost:8082/api/activity/docs`.
+
+## Kafka consumer (SF-3)
+
+Hợp đồng: [`contracts/events/task-events.md`](../../contracts/events/task-events.md) + [`platform/conventions/09-async-messaging.md`](../../platform/conventions/09-async-messaging.md). Thư viện `segmentio/kafka-go` (ADR-0008: franz-go là path production).
+
+- **Group** `go-svc-activity`, `auto.offset.reset: earliest`, 1 partition; filter-by-type — nhận mọi type TRỪ `task.assignment_failed` (compensating là của node-svc).
+- **Idempotency**: envelope `id` do producer (node outbox) sinh — `INSERT ... ON CONFLICT (id) DO NOTHING`; at-least-once redelivery không nhân đôi feed.
+- **Manual commit SAU khi xử lý xong** (DB insert đã commit hoặc message đã vào DLQ) — conventions/09 rule 5.
+- **Retry ×3 in-memory** (backoff 500ms) → hết lượt: publish compensating `task.assignment_failed` (envelope id MỚI do go sinh — chỉ khi nguồn là `task.assigned`, saga semantics) vào `task-events` + đẩy message gốc + metadata lỗi vào `task-events.dlq`. KHÔNG block partition, KHÔNG requeue.
+- **Lazy-connect**: broker chưa lên lúc boot chỉ log warn + retry vòng kế — KHÔNG crash, KHÔNG vào readyz, không service nào depends_on kafka.
+- **Saga fail hook**: `task.assigned` có `assigneeId = 55555555-...` (fixture `svc-fail`) → Handler cố tình fail — deterministic cho e2e saga (SF-5): retry ×3 → compensating → node mark task `assignment_failed`.
+
+## Service-token (resolver)
+
+go consumer không có HTTP caller để passthrough `Authorization` — tự login fixture service user **`svc-activity`** (`AUTH_MOCK_URL` + `SVC_ACTIVITY_PASSWORD`, giá trị khớp `AUTH_MOCK_DEV_PASSWORD`): warmup retry backoff lúc boot (KHÔNG crash khi auth-mock chưa lên), cache JWT 30 phút, **lazy re-login** khi spring trả 401. Resolver dùng token này enrich `userName` lúc consume (feed đọc lại sẽ backfill nếu `""`).
+
+## Chạy native (dev machine không Docker)
+
+Cần Postgres 16 với schemas + roles tạo sẵn (`platform/postgres/init/01-init.sh`) + Kafka (`apache/kafka` hoặc `redpanda`, bootstrap `localhost:9092`):
+
+```bash
+cd services/go-svc
+export PORT=8082
+export DATABASE_URL='postgres://go_svc:<GO_SVC_DB_PASSWORD>@localhost:5432/boilerplate'
+export DATABASE_READONLY_URL='postgres://go_readonly:<GO_READONLY_DB_PASSWORD>@localhost:5432/boilerplate'
+export JWT_SECRET='<openssl rand -base64 48>'
+export KAFKA_BROKERS='localhost:9092'
+export SVC_ACTIVITY_PASSWORD='demo-password'
+export AUTH_MOCK_URL='http://localhost:8090'
+export SPRING_SVC_URL='http://localhost:8081'          # resolve userName (tuỳ chọn dev)
+export CORS_DEV_ORIGIN='http://localhost:3000,http://localhost:4001,http://localhost:4002'
+export LOG_LEVEL=info
+go run ./cmd/server
+```
+
+Env bắt buộc: `DATABASE_URL`, `DATABASE_READONLY_URL`, `JWT_SECRET`, `KAFKA_BROKERS`, `SVC_ACTIVITY_PASSWORD` — thiếu → fail-fast lúc boot. Inventory đầy đủ trong [`platform/.env.example`](../../platform/.env.example).
+
+Compose: entry `go-svc` đã pre-seed env Kafka/service-token trong `platform/docker-compose.yml` — `docker compose up go-svc` (trên máy có Docker; CI verify).
+
+## Permission model (exit criterion)
+
+- go-svc kết nối DB bằng **2 pool**: owner `go_svc` (schema `activity` — ghi events) và `go_readonly` (chỉ SELECT schema `tasks` — stats).
+- Grants không cấp tay: `ALTER DEFAULT PRIVILEGES FOR ROLE node_svc IN SCHEMA tasks GRANT SELECT TO go_readonly` — hiệu lực cho bảng do migration node-svc (SF-2) tạo sau.
+- Không có grant (REVOKE) → `/stats` trả `503 {"error":{"code":"DEPENDENCY_DOWN",...}}` — permission boundary thể hiện đúng contract. Integration test + CI boot-smoke chứng minh cả 2 chiều: seed bằng role `node_svc` → stats đúng; REVOKE → 503 → GRANT lại → 200.
+
+## Display fields (userName / taskTitle)
+
+Contract yêu cầu feed item chứa user-display fields để FE render trực tiếp:
+
+- `taskTitle` — lookup readonly `tasks.tasks` (best-effort lúc consume + backfill lúc đọc).
+- `userName` — resolve qua **spring-svc REST** `GET /api/users/{id}` (`displayName`) bằng **service-token** (consumer path) hoặc passthrough `Authorization` (feed-read path), timeout 2s, cache in-memory 5 phút. (go_readonly KHÔNG có grant schema `users`.)
+- **ADR — degraded semantics**: spring/tasks down lúc consume → display fields lưu `""`, feed vẫn trả item; lúc đọc service thử resolve lại. Giá trị `""` là trạng thái THẬT (đối tác chưa sẵn sàng), không bịa placeholder.
+
+## Tests
+
+```bash
+go test ./...                              # unit (không DB/kafka — golden fixtures + fake producer)
+go test -tags integration ./test/integration/...   # integration (cần Postgres + roles, chạy trong CI)
+```
+
+CI: [`.github/workflows/services-go-svc.yml`](../../.github/workflows/services-go-svc.yml) — 4 jobs:
+1. **build-test** — setup-go 1.24 + postgres service container (init script thật chạy qua psql TCP) + `go vet` + unit (consumer golden fixtures, retry/DLQ fake) + integration (readonly-exit + idempotency duplicate envelope id = 1 row).
+2. **docker-build** — image multi-stage distroless.
+3. **boot-smoke** — compose up (postgres + auth-mock + **kafka**) → readyz **503 trước khi có tasks table** → DDL role `node_svc` + seed → readyz 200 → **tạo topic tường minh** (`kafka-topics.sh --create` task-events + dlq) → **console producer publish golden fixture** (exec trong container) → poll feed có row (proof event→feed) → **publish duplicate → feed không nhân đôi** (idempotency e2e) → stats 4 keys → POST /events **404** → gateway 401 → schemathesis.
+4. **drift-guard** — `diff` snapshot activity.yaml vs contracts (sửa 1 bỏ 1 = fail).
+
+## Ghi chú triển khai (lệch có chủ đích khỏi conventions/01)
+
+- **go.sum không commit**: dev machine không có Go toolchain → `go mod tidy` chạy in-image (Dockerfile build stage) và trong CI trước build. Khi copy standalone: chạy `go mod tidy` một lần.
+- **Vendored swagger-ui** (`internal/swagger/assets/`, v5.17.14, Apache-2.0 — LICENSE + NOTICE kèm theo): offline hoàn toàn, không CDN. Đặt tên `assets` thay vì `dist` để tránh root `.gitignore` (`dist/` dành cho FE builds).
+- Copy-dir standalone: service chạy độc lập cần `contracts/openapi/activity.yaml` NẰM CẠNH (sync-check test skip khi thiếu) — chứng minh copy-dir là việc của SF-7.