create-wakii-stack 0.0.0-stage → 0.1.0

package/stack-template/contracts/openapi/tasks.yaml

@@ -0,0 +1,316 @@
+openapi: 3.0.3
+info:
+  title: Tasks API (node-svc)
+  version: 0.1.0
+  description: |
+    Source of truth cho API task của node-svc (SF-2).
+    DB schema: `tasks` — canonical DDL tại `contracts/db/tasks-schema.sql` (khớp 1:1 với Task schema dưới đây).
+    Mọi path được gateway nginx route qua `/api/tasks` (pass-through, KHÔNG rewrite — service tự mount prefix này).
+    Auth: JWT Bearer bắt buộc (gateway chặn thiếu-token 401; node-svc TỰ verify signature + expiry).
+  contact:
+    name: boilerplate epic FI-62
+servers:
+  - url: /api/tasks
+tags:
+  - name: tasks
+paths:
+  /healthz:
+    get:
+      tags: [tasks]
+      summary: Liveness probe
+      operationId: getHealthz
+      responses:
+        "200":
+          description: Service sống
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HealthStatus"
+  /readyz:
+    get:
+      tags: [tasks]
+      summary: Readiness probe (DB migration xong + user-validation dependency reachable)
+      operationId: getReadyz
+      responses:
+        "200":
+          description: Sẵn sàng nhận traffic
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HealthStatus"
+        "503":
+          description: Chưa sẵn sàng
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /tasks:
+    get:
+      tags: [tasks]
+      summary: Liệt kê tasks (phân trang + lọc)
+      operationId: listTasks
+      parameters:
+        - name: status
+          in: query
+          required: false
+          schema:
+            $ref: "#/components/schemas/TaskStatus"
+        - name: assigneeId
+          in: query
+          required: false
+          schema:
+            type: string
+            format: uuid
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+        - name: offset
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+      responses:
+        "200":
+          description: Danh sách tasks
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TaskList"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+    post:
+      tags: [tasks]
+      summary: Tạo task mới (validate user qua spring-svc; push event fire-and-forget sang go-svc)
+      operationId: createTask
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateTaskRequest"
+      responses:
+        "201":
+          description: Task đã tạo
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Task"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "422":
+          description: Assignee không tồn tại (spring-svc trả 404 khi validate)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "503":
+          description: spring-svc down khi validate user — fail-closed
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /tasks/{taskId}:
+    parameters:
+      - name: taskId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+    get:
+      tags: [tasks]
+      summary: Lấy 1 task
+      operationId: getTask
+      responses:
+        "200":
+          description: Task
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Task"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+    patch:
+      tags: [tasks]
+      summary: Cập nhật một phần task
+      operationId: updateTask
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UpdateTaskRequest"
+      responses:
+        "200":
+          description: Task sau cập nhật
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Task"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+    delete:
+      tags: [tasks]
+      summary: Xoá task
+      operationId: deleteTask
+      responses:
+        "204":
+          description: Đã xoá
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+components:
+  responses:
+    BadRequest:
+      description: Payload không hợp lệ
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+    Unauthorized:
+      description: Thiếu hoặc sai JWT
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+    Forbidden:
+      description: Token hợp lệ nhưng không đủ quyền (DELETE chỉ admin — envelope code FORBIDDEN)
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+    NotFound:
+      description: Không tìm thấy
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+  schemas:
+    TaskStatus:
+      type: string
+      enum: [todo, in_progress, done]
+      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.
+    TaskStatusExtended:
+      type: string
+      enum: [todo, in_progress, done, assignment_failed]
+      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.
+    Task:
+      type: object
+      required: [id, title, status, createdBy, createdAt, updatedAt]
+      properties:
+        id:
+          type: string
+          format: uuid
+        title:
+          type: string
+          maxLength: 200
+        description:
+          type: string
+          nullable: true
+        status:
+          $ref: "#/components/schemas/TaskStatusExtended"
+        assigneeId:
+          type: string
+          format: uuid
+          nullable: true
+          description: UUID user của spring-svc — KHÔNG FK chéo schema (xem DDL comment)
+        createdBy:
+          type: string
+          format: uuid
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+    CreateTaskRequest:
+      type: object
+      required: [title]
+      properties:
+        title:
+          type: string
+          minLength: 1
+          maxLength: 200
+        description:
+          type: string
+        assigneeId:
+          type: string
+          format: uuid
+    UpdateTaskRequest:
+      type: object
+      minProperties: 1
+      properties:
+        title:
+          type: string
+          minLength: 1
+          maxLength: 200
+        description:
+          type: string
+        status:
+          $ref: "#/components/schemas/TaskStatus"
+        assigneeId:
+          type: string
+          format: uuid
+    TaskList:
+      type: object
+      required: [items, total]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/Task"
+        total:
+          type: integer
+    HealthStatus:
+      type: object
+      required: [status]
+      properties:
+        status:
+          type: string
+          enum: [ok]
+    Error:
+      type: object
+      description: Error envelope chung — shape chuẩn hoá trong platform/conventions/04-error-envelope.md
+      required: [error]
+      properties:
+        error:
+          type: object
+          required: [code, message]
+          properties:
+            code:
+              type: string
+              description: Mã máy đọc được, vd TASK_NOT_FOUND / VALIDATION_ERROR / UNAUTHORIZED
+            message:
+              type: string
+            requestId:
+              type: string
+              nullable: true
+            details:
+              description: Tuỳ service — dữ liệu bổ sung có cấu trúc
+              nullable: true

package/stack-template/contracts/openapi/users.yaml

@@ -0,0 +1,345 @@
+openapi: 3.0.3
+info:
+  title: Users API (spring-svc)
+  version: 0.1.0
+  description: |
+    Source of truth cho API users + teams của spring-svc (SF-3, Spring Boot 3 Web MVC).
+    DB schema: `users` (Flyway migration, seed đọc `contracts/auth/users.json` — id phải khớp 100%).
+    node-svc validate assignee bằng GET /users/{userId} (timeout 2s, fail-closed 503 khi spring down).
+    Mọi path được gateway route qua `/api/users` (pass-through — service mount prefix này).
+    Auth: JWT Bearer bắt buộc; spring-svc TỰ verify signature + expiry.
+servers:
+  - url: /api/users
+tags:
+  - name: users
+  - name: teams
+paths:
+  /healthz:
+    get:
+      tags: [users]
+      summary: Liveness probe (Spring actuator bridge)
+      operationId: getHealthz
+      responses:
+        "200":
+          description: Service sống
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HealthStatus"
+  /readyz:
+    get:
+      tags: [users]
+      summary: Readiness probe (Flyway migration xong + DB reachable)
+      operationId: getReadyz
+      responses:
+        "200":
+          description: Sẵn sàng
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HealthStatus"
+        "503":
+          description: Chưa sẵn sàng (migration chưa chạy xong)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /users:
+    get:
+      tags: [users]
+      summary: Liệt kê users
+      operationId: listUsers
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 50
+        - name: offset
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+      responses:
+        "200":
+          description: Danh sách users
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/UserList"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+    post:
+      tags: [users]
+      summary: Tạo user
+      operationId: createUser
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateUserRequest"
+      responses:
+        "201":
+          description: User đã tạo
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/User"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "409":
+          description: Email đã tồn tại
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /users/{userId}:
+    parameters:
+      - name: userId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+    get:
+      tags: [users]
+      summary: Lấy 1 user (endpoint node-svc dùng để validate assignee)
+      operationId: getUser
+      responses:
+        "200":
+          description: User
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/User"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+    patch:
+      tags: [users]
+      summary: Cập nhật user
+      operationId: updateUser
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UpdateUserRequest"
+      responses:
+        "200":
+          description: User sau cập nhật
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/User"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /teams:
+    get:
+      tags: [teams]
+      summary: Liệt kê teams
+      operationId: listTeams
+      responses:
+        "200":
+          description: Danh sách teams
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TeamList"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+    post:
+      tags: [teams]
+      summary: Tạo team
+      operationId: createTeam
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateTeamRequest"
+      responses:
+        "201":
+          description: Team đã tạo
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Team"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+  /teams/{teamId}:
+    parameters:
+      - name: teamId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+    get:
+      tags: [teams]
+      summary: Lấy 1 team (kèm member ids)
+      operationId: getTeam
+      responses:
+        "200":
+          description: Team
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Team"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+components:
+  responses:
+    BadRequest:
+      description: Payload không hợp lệ
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+    Unauthorized:
+      description: Thiếu hoặc sai JWT
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+    NotFound:
+      description: Không tìm thấy
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+  schemas:
+    Role:
+      type: string
+      enum: [admin, user]
+      description: Phải khớp roles trong contracts/auth/users.json
+    User:
+      type: object
+      required: [id, email, displayName, roles]
+      properties:
+        id:
+          type: string
+          format: uuid
+        email:
+          type: string
+          format: email
+        displayName:
+          type: string
+        roles:
+          type: array
+          items:
+            $ref: "#/components/schemas/Role"
+    CreateUserRequest:
+      type: object
+      required: [email, displayName]
+      properties:
+        email:
+          type: string
+          format: email
+        displayName:
+          type: string
+          minLength: 1
+        roles:
+          type: array
+          items:
+            $ref: "#/components/schemas/Role"
+          default: [user]
+    UpdateUserRequest:
+      type: object
+      minProperties: 1
+      properties:
+        displayName:
+          type: string
+          minLength: 1
+        roles:
+          type: array
+          items:
+            $ref: "#/components/schemas/Role"
+    UserList:
+      type: object
+      required: [items, total]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/User"
+        total:
+          type: integer
+    Team:
+      type: object
+      required: [id, name]
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        memberIds:
+          type: array
+          items:
+            type: string
+            format: uuid
+    CreateTeamRequest:
+      type: object
+      required: [name]
+      properties:
+        name:
+          type: string
+          minLength: 1
+        memberIds:
+          type: array
+          items:
+            type: string
+            format: uuid
+    TeamList:
+      type: object
+      required: [items, total]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/Team"
+        total:
+          type: integer
+    HealthStatus:
+      type: object
+      required: [status]
+      properties:
+        status:
+          type: string
+          enum: [ok]
+    Error:
+      type: object
+      description: Error envelope chung — shape chuẩn hoá trong platform/conventions/04-error-envelope.md
+      required: [error]
+      properties:
+        error:
+          type: object
+          required: [code, message]
+          properties:
+            code:
+              type: string
+            message:
+              type: string
+            requestId:
+              type: string
+              nullable: true
+            details:
+              nullable: true

package/stack-template/docs/adr/0001-mixed-stack.md

@@ -0,0 +1,14 @@
+# ADR 0001 — Mixed-stack backend (Node + Spring + Go)
+
+Ngày: 2026-10-12 · Status: Accepted · SF-7 tổng hợp từ epic FI-62
+
+## Context
+Boilerplate nội bộ phải phục vụ team có nhiều stack; mỗi service 1 stack đại diện để team copy đúng phần mình cần.
+
+## Decision
+3 service, mỗi stack một: node-svc (Fastify + TypeScript, Node 22 + pnpm), spring-svc (Spring Boot 3 Web MVC, JDK 21, không reactive), go-svc (Go 1.24 + chi). Không dùng 1 stack cho tất cả — mục đích là template, không phải microservice tối ưu.
+
+## Consequences
+- (+) Mỗi team copy đúng stack; sample đầy đủ 3 hệ sinh thái tooling (pnpm / mvnw / go mod).
+- (−) CI phải build 3 pipeline riêng (path-filtered per stack); toolchain local nặng hơn (xem [toolchain](../toolchain.md)).
+- (−) Convention phải được giữ bằng kỷ luật (conventions/ — JSON log, error envelope, healthcheck) vì framework nào cũng có cách riêng.

package/stack-template/docs/adr/0002-mf-rspack.md

@@ -0,0 +1,14 @@
+# ADR 0002 — Module Federation 2.0 trên Rspack (không Vite, không webpack)
+
+Ngày: 2026-10-12 · Status: Accepted
+
+## Context
+Micro-frontend cần runtime remote loading (shell load remote độc lập deploy). Webpack MF ổn định nhưng build chậm; Vite MF chưa production-grade; Rspack + @module-federation/enhanced là chọn chính thống của MF 2.0.
+
+## Decision
+Rspack + @module-federation/enhanced, React 19. Versions PIN qua spike thực tế (`app/shared/package.json` trường `mfToolkit.pinned` — host :3000 load được remote :4001 đã test). Singletons (react, react-dom) qua pnpm catalog; remote khai `requiredVersion: false` tường minh (conventions/08 rule 4).
+
+## Consequences
+- (+) Build nhanh, MF runtime API đầy đủ (loadRemote), ecosystem MF 2.0.
+- (−) Nâng cấp version = phải re-spike (không nâng vội); bundler KHÔNG trộn (tất cả FE cùng Rspack).
+- (−) Gotcha đã học: `catalog:` literal rò vào requiredVersion (→ rule 4); native `import()` biến không được rewrite (→ fe-shared `loadRemoteModule`).

package/stack-template/docs/adr/0003-contract-first.md

@@ -0,0 +1,14 @@
+# ADR 0003 — Contract-first (OpenAPI + canonical DDL + users fixture)
+
+Ngày: 2026-10-12 · Status: Accepted
+
+## Context
+3 service polyglot + FE shell/remotes phát triển song song — không có hợp lệ chung thì interface lệch nhau muộn (integration hell).
+
+## Decision
+`contracts/` là source of truth duy nhất: OpenAPI specs (tasks/users/activity/auth) cho API surface; `contracts/db/tasks-schema.sql` là canonical DDL bảng tasks (node-svc migration phải sinh khớp 1:1 — có test chặn diff; go-svc query theo đúng cột); `contracts/auth/users.json` là users fixture chung (auth-svc seed + spring seed đọc cùng file, id khớp 100% — tên dịch vụ `auth-mock` trong ghi chép cũ là tiền thân đã decommission, epic auth-real). Mỗi service codegen models từ OpenAPI (không gen full client). CI spectral lint + schemathesis contract test.
+
+## Consequences
+- (+) SF/teams phát triển song song được; breaking change thấy được ở lint/contract test trước runtime.
+- (−) Đổi API = sửa contract TRƯỚC, 2 bước (contract rồi code); codegen adds build step (spring generate-sources).
+- (−) Gotcha: codegen `interfaceOnly` giữ FULL path từ yaml (không strip servers.url) — implementor gắn class base-path phải hiểu điều này, nếu không route double-prefix (bug thật gặp ở SF-7 e2e — đã report epic FI-62).