create-wakii-stack 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,155 @@
+# node-svc — task API (Fastify + TypeScript)
+
+Task CRUD service của boilerplate epic FI-62 (SF-2, Linear FI-70). Contract-first:
+API source of truth `contracts/openapi/tasks.yaml`, DB source of truth
+`contracts/db/tasks-schema.sql` (canonical DDL — migration của service này sinh
+đúng cấu trúc, có test `schema-diff.test.ts` chặn diff ≠ 0).
+
+Epic FI-76 (SF-2 FI-79) thêm **transactional outbox + Kafka producer/consumer**
+(ADR-0008, conventions/09): mutation task + outbox ghi CÙNG 1 tx, relay publish
+topic `task-events`, compensation consumer nhận `task.assignment_failed`.
+
+## Chạy native (dev — máy không Docker)
+
+```bash
+# từ repo root — pnpm workspace
+pnpm install --frozen-lockfile
+
+# cần postgres 16 chạy sẵn (local/remote) — role node_svc + schema tasks
+# (schema tạo bởi platform/postgres/init/01-init.sh khi chạy compose; native
+# tự tạo thì dùng: CREATE ROLE node_svc LOGIN PASSWORD '...'; CREATE SCHEMA tasks;)
+export DATABASE_URL="postgres://node_svc:<NODE_SVC_DB_PASSWORD>@localhost:5432/boilerplate"
+export JWT_SECRET="<cùng giá trị auth-mock dùng để ký>"
+export SPRING_SVC_URL="http://localhost:8081"   # default native
+export GO_SVC_URL="http://localhost:8082"
+export CORS_DEV_ORIGIN="http://localhost:3000,http://localhost:4001,http://localhost:4002"
+export LOG_LEVEL=info
+# export KAFKA_BROKERS="localhost:9092"  # optional — thiếu = relay + consumer không start
+
+pnpm --filter node-svc dev        # tsx watch, port 3001 (PORT để override)
+pnpm --filter node-svc test       # vitest — 48 tests, không cần postgres/kafka
+pnpm --filter node-svc build      # tsc → dist/
+```
+
+Boot sequence: env fail-fast (thiếu biến = thoát ngay) → drizzle migration →
+spring reachability check (1 lần) → relay + compensation consumer (chỉ khi có
+`KAFKA_BROKERS` — lazy, KHÔNG chặn boot/readyz) → listen `0.0.0.0:$PORT`.
+
+Swagger UI: `http://localhost:3001/api/tasks/docs` (mirror tối thiểu của
+tasks.yaml). Qua gateway `:8080/api/tasks/docs` cần Bearer token (gateway
+presence-check chặn browser không token).
+
+## Chạy docker
+
+```bash
+docker compose -f platform/docker-compose.yml --env-file platform/.env.example up -d --build node-svc
+# compose inject: PORT, DATABASE_URL, JWT_SECRET, SPRING_SVC_URL, GO_SVC_URL,
+#                CORS_DEV_ORIGIN, LOG_LEVEL
+```
+
+Image multi-stage (conventions/01): `node:22-alpine`, `pnpm install
+--frozen-lockfile`, chạy non-root `USER node`, EXPOSE 3001. Local lockfile
+`pnpm-lock.yaml` (thư mục này, sinh bằng `pnpm install --ignore-workspace`) vì
+compose build context = thư mục này — root workspace lockfile không vào được
+context. Healthcheck khai ở compose (conventions/01 rule 4).
+
+## Env vars
+
+| Biến | Bắt buộc | Ý nghĩa |
+|------|----------|---------|
+| `PORT` | ✓ (compose set 3001) | Listen port — conventions/05 |
+| `DATABASE_URL` | ✓ | Postgres URL, role `node_svc`, search_path `tasks` |
+| `JWT_SECRET` | ✓ | Secret HS256 — verify token auth-mock (token-contract.md) |
+| `SPRING_SVC_URL` | ✓ | spring-svc base URL — validate assignee |
+| `GO_SVC_URL` | ✓ | (hiện không dùng — event push đã thay bằng outbox; giữ cho compose inject không fail) |
+| `CORS_DEV_ORIGIN` | ✗ | Dev origins phân tách phẩy; rỗng = deny-by-default |
+| `LOG_LEVEL` | ✗ (default info) | debug\|info\|warn\|error |
+| `KAFKA_BROKERS` | ✗ | Phẩy-phân-tách broker list (vd `kafka:9092`). Thiếu = relay + compensation consumer KHÔNG start (warn 1 lần) — lazy-connect, KHÔNG vào readyz (conventions/09 rule 1) |
+
+## API summary (chi tiết: contracts/openapi/tasks.yaml)
+
+| Method | Path | Ghi chú |
+|--------|------|---------|
+| GET | `/api/tasks` | filter `status`,`assigneeId`; `limit` (1-100, default 20), `offset` |
+| GET | `/api/tasks/{taskId}` | 404 `TASK_NOT_FOUND`; non-uuid → 400 |
+| POST | `/api/tasks` | `{title, description?, assigneeId?}` → 201; validate assignee (xem failure semantics) |
+| PATCH | `/api/tasks/{taskId}` | minProperties 1; **KHÔNG null được assigneeId** (contract non-nullable); `status` chỉ nhận writable 3 giá trị — `assignment_failed` system-owned (compensation ghi, không client) |
+| DELETE | `/api/tasks/{taskId}` | 204 |
+| GET | `/healthz` (naked + `/api/tasks/healthz`) | liveness — không auth |
+| GET | `/readyz` (naked + `/api/tasks/readyz`) | readiness — không auth |
+
+Auth: mọi `/api/tasks/*` business route bắt buộc `Authorization: Bearer <JWT>`;
+service TỰ verify signature + exp + iss (không tin gateway) → sai/hết hạn →
+401 `{"error":{"code":"UNAUTHORIZED",...}}`.
+
+## Failure semantics (đọc trước khi đổi)
+
+- **User validation — fail-closed**: POST/PATCH có `assigneeId` → `GET
+  {SPRING_SVC_URL}/api/users/{id}` timeout 2s. spring 404 → **422
+  UNPROCESSABLE** (task không ghi); spring down/timeout → **503
+  DEPENDENCY_DOWN** (task không ghi — không có nửa chừng). Degrade method
+  (ADR): khi spring down, FE vẫn đọc/xoá task được; chỉ blocked thao tác có
+  assignee mới. Chọn fail-closed vì `assignee_id` không có FK chéo schema —
+  DB không tự chắn assignee ma (canonical DDL comment #1).
+- **Event push — transactional outbox (ADR-0008, thay fire-and-forget ADR-0006)**:
+  mutation + INSERT `tasks.outbox` trong CÙNG 1 tx (`repo.drizzle.ts` — seam-fail
+  test chứng minh task + outbox cùng biến mất). Relay poll 500ms publish topic
+  `task-events` (key = `payload.taskId`, envelope khớp golden fixtures
+  `contracts/events/fixtures/`) rồi mark `published_at`; publish fail = retry
+  tick sau (at-least-once, consumer dedupe bằng envelope `id`); purge row
+  published cũ > 7 ngày. Event matrix PRESENCE-BASED (ADR-0008): POST →
+  `task.created`; PATCH có `assigneeId` → `task.assigned` (+`task.updated` nếu
+  body còn field khác); PATCH không `assigneeId` → `task.updated`; DELETE →
+  `task.deleted`. Envelope `id` UUIDv4 do repo sinh từng event.
+- **Compensation consumer (saga)**: group `node-svc-compensation`, CHỈ xử lý
+  `task.assignment_failed` (filter-by-type — task-events.md): conditional UPDATE
+  `SET status='assignment_failed' WHERE id AND assignee_id=<event.assigneeId>
+  AND status <> 'assignment_failed'` — guard chống stale compensation
+  (assignee khác / event lặp = không đổi), idempotent. Manual offset commit
+  SAU khi DB op xong; lỗi DB retry ×3 in-memory → hết lượt vào
+  `task-events.dlq` rồi commit (KHÔNG block partition — conventions/09 rule 7).
+- **Readiness — deviation ghi nhận**: `/readyz` = DB migrated + SELECT 1 ok
+  (hard gate). Spring reachability chỉ kiểm 1 lần lúc boot + log warn, KHÔNG
+  gate ready — lệch wordings của conventions/02 và summary `/readyz` trong
+  tasks.yaml (cả hai nói "spring dependency pass"). Lý do: SF-3 (spring-svc)
+  deploy song song/lifecycle riêng — nếu readyz gate cứng vào spring thì
+  node-svc không bao giờ nhận traffic khi spring restart; validation đã
+  fail-closed ở request-time nên user-visible không đổi. SF-7 docs-sync:
+  cập nhật conventions/02 khi convergence, đừng "fix ngược" README này.
+- **Error envelope**: mọi 4xx/5xx theo `platform/conventions/04` — Fastify
+  error gốc (FST_ERR_*) được map sang envelope, validation → 400
+  `VALIDATION_ERROR`.
+
+## Tests
+
+```bash
+pnpm --filter node-svc test
+```
+
+- Unit/contract (48): auth (missing/bad signature/expired/wrong iss), CRUD
+  happy + validation + 404/422/503, **outbox event matrix** (payload so golden
+  fixtures — load chung với relay test + consumer test SF-3), seam-fail giữa
+  2 step → task + outbox cùng biến mất, PATCH `assignment_failed` → 400, GET
+  `assignment_failed` → 200, CORS (echo dev origin / deny-by-default), readyz
+  DB fail.
+- `schema-diff.test.ts`: migration vs canonical DDL — structural normalized
+  comparison (exit criterion SF-2 diff=0; bảng `tasks.outbox` whitelist riêng —
+  node-internal infra, KHÔNG vào canonical DDL).
+- `repo.drizzle.test.ts`: mutation + outbox trong CÙng 1 tx (mock-db — rollback
+  thật của postgres chứng minh ở CI boot-smoke + saga e2e).
+- `outbox-relay.test.ts` / `compensation-consumer.test.ts`: publish đúng golden
+  fixture format; filter-by-type + conditional guard + retry ×3 → DLQ.
+- CI (`services-node-svc.yml`): native build+test, docker build, **boot-smoke**
+  (compose postgres thật → CRUD smoke bằng JWT CI), **kafka-boot-smoke**
+  (postgres + kafka + node-svc → tạo task → assert outbox row
+  `published_at IS NOT NULL` — relay THẬT trên broker thật, P0 plan-critic).
+
+## Copy-dir standalone (cho SF-7)
+
+Thư mục này tự chứa đủ: package.json + local pnpm-lock.yaml (không phụ thuộc
+workspace root), Dockerfile, README. Copy-dir phải KÈM dependency ngoài mà test
+resolve tới repo-relative:
+- `contracts/db/tasks-schema.sql` — `schema-diff.test.ts` đọc (FLAG sẵn
+  convergence.yml:62, đã gặp ở SF-7);
+- `contracts/events/fixtures/*.json` — relay/consumer test load chung (2 đầu
+  cùng nguồn sự thật, task-events.md).

package/stack-template/services/node-svc/drizzle/0000_init.sql

@@ -0,0 +1,17 @@
+CREATE SCHEMA IF NOT EXISTS "tasks";
+--> statement-breakpoint
+CREATE TABLE "tasks"."tasks" (
+	"id" uuid PRIMARY KEY NOT NULL,
+	"title" varchar(200) NOT NULL,
+	"description" text,
+	"status" varchar(20) DEFAULT 'todo' NOT NULL,
+	"assignee_id" uuid,
+	"created_by" uuid NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "status_check" CHECK ("tasks"."tasks"."status" IN ('todo', 'in_progress', 'done'))
+);
+--> statement-breakpoint
+CREATE INDEX "idx_tasks_status" ON "tasks"."tasks" USING btree ("status");--> statement-breakpoint
+CREATE INDEX "idx_tasks_assignee_id" ON "tasks"."tasks" USING btree ("assignee_id");--> statement-breakpoint
+CREATE INDEX "idx_tasks_created_at" ON "tasks"."tasks" USING btree ("created_at" DESC NULLS LAST);

package/stack-template/services/node-svc/drizzle/0001_status-assignment-failed.sql

@@ -0,0 +1,2 @@
+ALTER TABLE "tasks"."tasks" DROP CONSTRAINT "status_check";--> statement-breakpoint
+ALTER TABLE "tasks"."tasks" ADD CONSTRAINT "status_check" CHECK ("tasks"."tasks"."status" IN ('todo', 'in_progress', 'done', 'assignment_failed'));

package/stack-template/services/node-svc/drizzle/0002_outbox-table.sql

@@ -0,0 +1,7 @@
+CREATE TABLE "tasks"."outbox" (
+	"id" uuid PRIMARY KEY NOT NULL,
+	"type" varchar(40) NOT NULL,
+	"payload" jsonb NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"published_at" timestamp with time zone
+);

package/stack-template/services/node-svc/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,136 @@
+{
+  "id": "48123e68-2063-4e8a-b20f-7a6a29e23c7e",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "tasks.tasks": {
+      "name": "tasks",
+      "schema": "tasks",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(200)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'todo'"
+        },
+        "assignee_id": {
+          "name": "assignee_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_by": {
+          "name": "created_by",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "idx_tasks_status": {
+          "name": "idx_tasks_status",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "idx_tasks_assignee_id": {
+          "name": "idx_tasks_assignee_id",
+          "columns": [
+            {
+              "expression": "assignee_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "idx_tasks_created_at": {
+          "name": "idx_tasks_created_at",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": false,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "status_check": {
+          "name": "status_check",
+          "value": "\"tasks\".\"tasks\".\"status\" IN ('todo', 'in_progress', 'done')"
+        }
+      },
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {
+    "tasks": "tasks"
+  },
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/stack-template/services/node-svc/drizzle/meta/0001_snapshot.json

@@ -0,0 +1,136 @@
+{
+  "id": "3d90368a-b2ee-4cef-a40a-9622e96d0270",
+  "prevId": "48123e68-2063-4e8a-b20f-7a6a29e23c7e",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "tasks.tasks": {
+      "name": "tasks",
+      "schema": "tasks",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(200)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'todo'"
+        },
+        "assignee_id": {
+          "name": "assignee_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_by": {
+          "name": "created_by",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "idx_tasks_status": {
+          "name": "idx_tasks_status",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "idx_tasks_assignee_id": {
+          "name": "idx_tasks_assignee_id",
+          "columns": [
+            {
+              "expression": "assignee_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "idx_tasks_created_at": {
+          "name": "idx_tasks_created_at",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": false,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "status_check": {
+          "name": "status_check",
+          "value": "\"tasks\".\"tasks\".\"status\" IN ('todo', 'in_progress', 'done', 'assignment_failed')"
+        }
+      },
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {
+    "tasks": "tasks"
+  },
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/stack-template/services/node-svc/drizzle/meta/0002_snapshot.json

@@ -0,0 +1,180 @@
+{
+  "id": "73f5385d-f98b-4a13-90dc-6b5d66a606ff",
+  "prevId": "3d90368a-b2ee-4cef-a40a-9622e96d0270",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "tasks.outbox": {
+      "name": "outbox",
+      "schema": "tasks",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "type": {
+          "name": "type",
+          "type": "varchar(40)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "payload": {
+          "name": "payload",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "published_at": {
+          "name": "published_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "tasks.tasks": {
+      "name": "tasks",
+      "schema": "tasks",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(200)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'todo'"
+        },
+        "assignee_id": {
+          "name": "assignee_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_by": {
+          "name": "created_by",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "idx_tasks_status": {
+          "name": "idx_tasks_status",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "idx_tasks_assignee_id": {
+          "name": "idx_tasks_assignee_id",
+          "columns": [
+            {
+              "expression": "assignee_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "idx_tasks_created_at": {
+          "name": "idx_tasks_created_at",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": false,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "status_check": {
+          "name": "status_check",
+          "value": "\"tasks\".\"tasks\".\"status\" IN ('todo', 'in_progress', 'done', 'assignment_failed')"
+        }
+      },
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {
+    "tasks": "tasks"
+  },
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/stack-template/services/node-svc/drizzle/meta/_journal.json

@@ -0,0 +1,27 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1791791902713,
+      "tag": "0000_init",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1791868128263,
+      "tag": "0001_status-assignment-failed",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1791869618318,
+      "tag": "0002_outbox-table",
+      "breakpoints": true
+    }
+  ]
+}

package/stack-template/services/node-svc/drizzle.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'drizzle-kit';
+
+// Migration source-of-truth là SQL file commit trong drizzle/ — generate lại
+// chỉ khi schema.ts đổi. CI không chạy generate (chỉ diff-check).
+export default defineConfig({
+  dialect: 'postgresql',
+  schema: './src/db/schema.ts',
+  out: './drizzle',
+  strict: true,
+});