create-wakii-stack 0.0.0-stage → 0.1.0

package/stack-template/services/node-svc/src/types/api.d.ts

@@ -0,0 +1,391 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+
+export interface paths {
+    "/healthz": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Liveness probe */
+        get: operations["getHealthz"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/readyz": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Readiness probe (DB migration xong + user-validation dependency reachable) */
+        get: operations["getReadyz"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/tasks": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Liệt kê tasks (phân trang + lọc) */
+        get: operations["listTasks"];
+        put?: never;
+        /** Tạo task mới (validate user qua spring-svc; push event fire-and-forget sang go-svc) */
+        post: operations["createTask"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/tasks/{taskId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                taskId: string;
+            };
+            cookie?: never;
+        };
+        /** Lấy 1 task */
+        get: operations["getTask"];
+        put?: never;
+        post?: never;
+        /** Xoá task */
+        delete: operations["deleteTask"];
+        options?: never;
+        head?: never;
+        /** Cập nhật một phần task */
+        patch: operations["updateTask"];
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        /**
+         * @description WRITABLE status — query param + PATCH body CHỈ nhận 3 giá trị này
+         *     (khớp CHECK constraint writable trong contracts/db/tasks-schema.sql).
+         *     go-svc stats group theo đúng 3 giá trị này.
+         *     `assignment_failed` KHÔNG ở đây — system-owned (compensation ghi,
+         *     không client) — xem TaskStatusExtended.
+         * @enum {string}
+         */
+        TaskStatus: "todo" | "in_progress" | "done";
+        /**
+         * @description READ-ONLY — chỉ `Task.status` response. `assignment_failed` là trạng
+         *     thái hệ thống (saga compensation — ADR-0008): consumer node-svc-compensation
+         *     ghi qua conditional UPDATE; PATCH KHÔNG nhận giá trị này.
+         * @enum {string}
+         */
+        TaskStatusExtended: "todo" | "in_progress" | "done" | "assignment_failed";
+        Task: {
+            /** Format: uuid */
+            id: string;
+            title: string;
+            description?: string | null;
+            status: components["schemas"]["TaskStatusExtended"];
+            /**
+             * Format: uuid
+             * @description UUID user của spring-svc — KHÔNG FK chéo schema (xem DDL comment)
+             */
+            assigneeId?: string | null;
+            /** Format: uuid */
+            createdBy: string;
+            /** Format: date-time */
+            createdAt: string;
+            /** Format: date-time */
+            updatedAt: string;
+        };
+        CreateTaskRequest: {
+            title: string;
+            description?: string;
+            /** Format: uuid */
+            assigneeId?: string;
+        };
+        UpdateTaskRequest: {
+            title?: string;
+            description?: string;
+            status?: components["schemas"]["TaskStatus"];
+            /** Format: uuid */
+            assigneeId?: string;
+        };
+        TaskList: {
+            items: components["schemas"]["Task"][];
+            total: number;
+        };
+        HealthStatus: {
+            /** @enum {string} */
+            status: "ok";
+        };
+        /** @description Error envelope chung — shape chuẩn hoá trong platform/conventions/04-error-envelope.md */
+        Error: {
+            error: {
+                /** @description Mã máy đọc được, vd TASK_NOT_FOUND / VALIDATION_ERROR / UNAUTHORIZED */
+                code: string;
+                message: string;
+                requestId?: string | null;
+                /** @description Tuỳ service — dữ liệu bổ sung có cấu trúc */
+                details?: unknown;
+            };
+        };
+    };
+    responses: {
+        /** @description Payload không hợp lệ */
+        BadRequest: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+        /** @description Thiếu hoặc sai JWT */
+        Unauthorized: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+        /** @description Token hợp lệ nhưng không đủ quyền (DELETE chỉ admin — envelope code FORBIDDEN) */
+        Forbidden: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+        /** @description Không tìm thấy */
+        NotFound: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+    };
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export interface operations {
+    getHealthz: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Service sống */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HealthStatus"];
+                };
+            };
+        };
+    };
+    getReadyz: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Sẵn sàng nhận traffic */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HealthStatus"];
+                };
+            };
+            /** @description Chưa sẵn sàng */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    listTasks: {
+        parameters: {
+            query?: {
+                status?: components["schemas"]["TaskStatus"];
+                assigneeId?: string;
+                limit?: number;
+                offset?: number;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Danh sách tasks */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TaskList"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+        };
+    };
+    createTask: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CreateTaskRequest"];
+            };
+        };
+        responses: {
+            /** @description Task đã tạo */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Task"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            /** @description Assignee không tồn tại (spring-svc trả 404 khi validate) */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description spring-svc down khi validate user — fail-closed */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    getTask: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                taskId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Task */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Task"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    deleteTask: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                taskId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Đã xoá */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    updateTask: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                taskId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["UpdateTaskRequest"];
+            };
+        };
+        responses: {
+            /** @description Task sau cập nhật */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Task"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+}

package/stack-template/services/node-svc/src/types/log.ts

@@ -0,0 +1,3 @@
+// log.ts — kiểu hàm log chung (tránh phụ thuộc pino type ở client/infra layer).
+export type LogLevelName = 'debug' | 'info' | 'warn' | 'error';
+export type LogFn = (level: LogLevelName, msg: string, fields?: Record<string, unknown>) => void;

package/stack-template/services/node-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"]
+}

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

@@ -0,0 +1,5 @@
+target/
+.git/
+.idea/
+*.iml
+.mvn/wrapper/maven-wrapper.jar

package/stack-template/services/spring-svc/.mvn/wrapper/maven-wrapper.properties

@@ -0,0 +1,20 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+wrapperVersion=3.3.2
+distributionType=only-script
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.9/apache-maven-3.9.9-bin.zip
+wrapperUrl=https://repo.maven.apache.org/maven2/org/apache/maven/wrapper/maven-wrapper/3.3.2/maven-wrapper-3.3.2.jar

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

@@ -0,0 +1,22 @@
+# spring-svc — multi-stage theo platform/conventions/01
+# deps → build → runtime (JRE-only, non-root 1001)
+
+# deps stage — mvnw tải dependency vào layer cache riêng
+FROM eclipse-temurin:21-jdk-alpine AS deps
+WORKDIR /app
+COPY .mvn .mvn
+COPY mvnw pom.xml ./
+RUN ./mvnw -B dependency:go-offline
+
+# build stage — codegen models chạy trong generate-sources (snapshot users.yaml)
+FROM deps AS build
+COPY src src
+RUN ./mvnw -B package -DskipTests
+
+# runtime stage — JRE-only, jar fat
+FROM eclipse-temurin:21-jre-alpine AS runtime
+WORKDIR /app
+COPY --from=build /app/target/*.jar app.jar
+USER 1001
+EXPOSE 8081
+ENTRYPOINT ["java", "-jar", "app.jar"]

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

@@ -0,0 +1,121 @@
+# spring-svc — user API (Spring Boot 3)
+
+Source-of-truth **users + teams** của boilerplate (SF-3, Linear FI-71). Spring Boot 3.5 Web MVC (không
+reactive), Java 21, Flyway (schema `users`), JWT HS256 **service-side verify**, port **8081** (conventions/05).
+
+## Contracts (source of truth — KHÔNG sửa trong thư mục này)
+
+| Contract | Dùng để |
+|---|---|
+| `contracts/openapi/users.yaml` | API surface + codegen models (maven plugin) |
+| `contracts/auth/users.json` | Seed migration (V2) đọc qua env `USERS_FIXTURE_PATH` |
+| `contracts/auth/token-contract.md` | JWT verify (HS256, TTL 8h, iss `auth-mock`) |
+| `platform/conventions/*` | port, healthcheck, log JSON, error envelope, CORS, Dockerfile pattern |
+
+## API — FINAL paths (contract-resolved: `servers.url /api/users` + path)
+
+| Method | Path | Ghi chú |
+|---|---|---|
+| GET | `/api/users/users?limit&offset` | list, limit ∈ [1,100] default 50 |
+| POST | `/api/users/users` | 201; thiếu `roles` → default `["user"]`; email trùng → 409 |
+| GET | `/api/users/users/{userId}` | endpoint node-svc dùng validate assignee |
+| PATCH | `/api/users/users/{userId}` | displayName/roles; body rỗng → 400 |
+| GET | `/api/users/teams` · POST | POST dedupe `memberIds` |
+| GET | `/api/users/teams/{teamId}` | kèm memberIds |
+| GET | `/healthz` · `/readyz` | naked, không-auth; ready = Flyway xong + DB pass; 503 → envelope `DEPENDENCY_DOWN` |
+| GET | `/actuator/health/liveness` | actuator probes |
+
+⚠️ `/api/teams` **không tồn tại** — gateway chỉ route `/api/users/*`; mọi consumer dùng bảng trên.
+Swagger UI (host port 8081, KHÔNG qua gateway): `http://localhost:8081/swagger-ui/index.html`.
+
+## Chạy (dev machine không Docker/JDK → toolchain-in-Docker trong CI là đường chính)
+
+**CI (GitHub Actions)** — `.github/workflows/services-spring-svc.yml`: build-test (`mvnw verify` trên
+Postgres service container thật, init script SF-1 mount đầy đủ), docker-build, boot-smoke (compose up →
+login auth-mock → GET fixture user → 401-from-service checks), drift-guard snapshot.
+
+**Native (máy có JDK 21):**
+```bash
+cd services/spring-svc
+JWT_SECRET=$(openssl rand -base64 48) \
+USERS_FIXTURE_PATH=../../contracts/auth/users.json \
+SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/boilerplate \
+SPRING_DATASOURCE_USERNAME=spring_svc SPRING_DATASOURCE_PASSWORD=... \
+./mvnw spring-boot:run
+```
+CORS dev-native: thêm `-Dspring.profiles.active=dev` + env `CORS_DEV_ORIGIN=http://localhost:3000,...`.
+
+**Docker (máy có Docker):** `docker compose -f platform/docker-compose.yml up --build spring-svc` —
+entry đã pre-seed bởi SF-1 (SF-3 KHÔNG sửa compose).
+
+## Env vars (fail-fast khi thiếu bắt buộc)
+
+| Env | Bắt buộc | Ý nghĩa |
+|---|---|---|
+| `JWT_SECRET` | ✓ | HS256 secret (UTF-8 bytes) — khớp auth-mock; thiếu = fail boot |
+| `USERS_FIXTURE_PATH` | ✓ | Đường dẫn `contracts/auth/users.json` (compose mount `/app/contracts/auth/users.json`) |
+| `SPRING_DATASOURCE_URL/USERNAME/PASSWORD` | ✓ | Role `spring_svc` (search_path=users do init script SF-1 set) |
+| `SERVER_PORT` | — | default 8081 |
+| `CORS_DEV_ORIGIN` | — | comma list; chỉ có tác dụng với profile `dev` |
+| `LOG_LEVEL` | — | default `info` |
+
+## ADR (ghi ngắn tại chỗ — tổng hợp đầy đủ ở SF-7)
+
+1. **JWT: jjwt + servlet filter tự viết** thay spring-security-oauth2-resource-server — mock 1 secret
+   HS256, kiểm soát 401 envelope conventions/04; điểm cắm OIDC: đổi filter sang JWKS/RS256, claims giữ nguyên.
+2. **Snapshot `src/main/resources/openapi/users.yaml` là BIT-IDENTICAL của `contracts/openapi/users.yaml`**
+   — KHÔNG sửa file này; Docker build context = `services/spring-svc` không thấy `contracts/`. Sync = copy
+   lại từ contracts; CI drift-guard (`diff`) chặn lệch. Provenance: commit đầu T1 (FI-71).
+3. **Seed = Flyway Java migration (V2) đọc file fixture thật** — không hardcode SQL id → khớp fixture theo
+   cấu trúc. **Fixture evolution**: thêm user mới sau khi V2 đã applied = viết **V3 migration** đọc fixture
+   và insert phần tăng (V2 chỉ chạy 1 lần — Flyway versioning).
+4. **healthz/readyz mirror dưới `/api/users/*`** (generated interface) là pattern conventions/02 như
+   auth-mock — probe thật dùng naked `/healthz` `/readyz`.
+5. **Email uniqueness case-sensitive** (DB UNIQUE) — auth-mock login lowercase là đủ demo; dự án thật
+   cắm OIDC sẽ bỏ match-by-email.
+6. **Codegen `interfaceOnly`** — supersét của "types only" trong context pack: models + API interface,
+   controllers implement interface → compile-error nếu lệch contract (contract-sync compile-time).
+
+## @Transactional demo — Situation A (SF-4, FI-78)
+
+`service/TeamService.createTeam` tạo team + members qua **N lệnh ghi riêng biệt** trong MỘT
+transaction (`@Transactional`):
+
+```
+step 1  teams.saveAndFlush(team)            — INSERT teams row
+step 2  teams.insertMember(teamId, bob)     — INSERT team_members từng dòng qua repository
+step 3  teams.insertMember(teamId, memberX) ← fail giữa chừng?
+        → ROLLBACK TOÀN BỘ: team + members đã insert trước đó cùng biến mất
+```
+
+**Rollback trigger deterministic** (fixture CÓ SẴN, không cần user mới): member có email
+`alice@demo.local` (`TeamService.ROLLBACK_TRIGGER_EMAIL`) → service throw `ApiException.conflict`
+→ client nhận error envelope **409 CONFLICT** (conventions/04) → DB không còn dấu vết gì.
+Test chứng minh bằng **repository assert** (`TeamServiceRollbackTest`): `existsByName=false` +
+`countMembersByTeamName=0` sau request fail — không chỉ nhìn response code.
+
+### Situation A vs Situation B
+
+| | Situation A (file này) | Situation B (cross-service) |
+|---|---|---|
+| Phạm vi | Nhiều step **CÙNG 1 DB** | Nhiều **service**, nhiều DB |
+| Giải pháp | **1 transaction là đủ** (`@Transactional`) | 1 tx KHÔNG phủ được service khác → **Saga + Transactional Outbox** |
+| Fail giữa chừng | Rollback tự động toàn bộ | Compensating action (event-driven) |
+| Tham chiếu | `service/TeamService` | node-svc outbox relay + go-svc saga —
+`docs/superpowers/specs/2026-10-13-kafka-outbox-saga.md` |
+
+Quy tắc chọn: nếu mọi lệnh ghi đều qua cùng một datasource → bọc trong `@Transactional`
+(Situation A); chỉ khi ghi vượt ra ngoài DB (Kafka, HTTP, email…) mới cần pattern Situation B.
+
+Lưu ý API: contract teams **không đổi** (path/shape giữ nguyên) — member UUID không tồn tại
+trong `users` vẫn được chấp nhận như trước (không FK); trigger chỉ kích hoạt khi user tồn tại
+và email trùng.
+
+## Tests
+
+`mvnw verify` — @SpringBootTest trên **Postgres thật** (CI service container, KHÔNG H2):
+seed-id-match 100% (đọc cùng `contracts/auth/users.json`), JWT filter 6 case, users/teams API,
+health shape, log shape conventions/03, CORS dev/default. CRUD tests `@Transactional` (rollback) —
+seed test độc lập. @Transactional demo tests (`TeamServiceRollbackTest`) **KHÔNG** `@Transactional`
+ở test — request chạy trong transaction của server để commit/rollback thật, assert DB qua
+repository (happy + rollback + trigger-ở-vị-trí-đầu).