create-wakii-stack 0.0.0-stage → 0.1.0

package/stack-template/platform/conventions/05-ports.md

@@ -0,0 +1,38 @@
+# 05 — PORT TABLE (nguồn sự thật duy nhất)
+
+Port cố định, giá trị dev = giá trị compose (override được qua `.env`, xem [06-configuration.md](06-configuration.md)). Không service nào tự chọn port khác.
+
+## Bảng
+
+| Thành phần | Port | Ghi chú |
+|------------|------|---------|
+| **nginx gateway** | **8080** | CỔNG DUY NHẤT browser/FE chạm vào |
+| shell (MF host) | 3000 | dev server; compose static qua gateway `/` |
+| remote `tasks` (FE) | 4001 | dev server; gateway `/remotes/tasks/` |
+| remote `activity` (FE) | 4002 | dev server; gateway `/remotes/activity/` |
+| node-svc | 3001 | Fastify + TS |
+| spring-svc | 8081 | Spring Boot 3 |
+| go-svc | 8082 | Go chi |
+| auth-svc | 8090 | Fastify + TS (auth thật — epic auth-real) |
+| postgres | 5432 | Postgres 16 |
+
+## Env var tương ứng (khai trong `platform/.env.example`)
+
+```
+GATEWAY_PORT=8080
+SHELL_PORT=3000
+REMOTE_TASKS_PORT=4001
+REMOTE_ACTIVITY_PORT=4002
+NODE_SVC_PORT=3001
+SPRING_SVC_PORT=8081
+GO_SVC_PORT=8082
+AUTH_PORT=8090
+POSTGRES_PORT=5432
+```
+
+## Quy tắc
+
+1. Service **listen** theo env `PORT`/`SERVER_PORT` riêng của nó, default = bảng trên.
+2. Inter-service call ĐI QUA TÊN COMPOSE (`http://node-svc:3001`), không qua gateway, không qua `localhost` — trong mạng docker `localhost` = container mình.
+3. Native mode (không docker, dev local): gọi thẳng `http://localhost:<port>` — CORS rule xem [07-cors.md](07-cors.md).
+4. Đổi port = sửa file này + `.env.example` + compose + README **trong cùng commit** (4 chỗ phải khớp).

package/stack-template/platform/conventions/06-configuration.md

@@ -0,0 +1,25 @@
+# 06 — Configuration: 100% qua env-var
+
+Không config file riêng cho service. Không hardcode secret. 12-factor.
+
+## Quy tắc
+
+1. **Mọi cấu hình theo môi trường đi qua env-var** — DB URL, JWT secret, port, URL service láng giềng, level log.
+2. `platform/.env.example` là **inventory ĐẦY ĐỦ** — thêm env var mới cho service nào phải thêm vào đó cùng commit, kèm comment 1 dòng giải thích. `.env` gitignored.
+3. Compose đọc `.env` tự động (file cùng thư mục `platform/`); CI dùng `--env-file platform/.env.example` cho job chỉ validate.
+4. Secret (`JWT_SECRET`, `POSTGRES_PASSWORD`, DB passwords): `.env.example` chứa **placeholder** rõ ràng (`change-me-...`), giá trị thật chỉ trong `.env` local / CI secret.
+5. Tên env var: `SCREAMING_SNAKE_CASE`, prefix theo service (`NODE_SVC_*`, `SPRING_SVC_*`, `GO_SVC_*`, `AUTH_MOCK_*`) trừ shared (`JWT_SECRET`, `POSTGRES_*`, `GATEWAY_PORT`).
+6. Service fail-fast khi thiếu env bắt buộc lúc boot (không fallback im lặng giá trị mặc định cho secret).
+
+## Nhóm env chính (chi tiết đầy đủ trong `.env.example`)
+
+| Nhóm | Biến |
+|------|------|
+| Shared secret | `JWT_SECRET` |
+| Postgres | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`, `POSTGRES_PORT` |
+| Per-service DB creds | `NODE_SVC_DB_PASSWORD`, `SPRING_SVC_DB_PASSWORD`, `GO_SVC_DB_PASSWORD`, `GO_READONLY_DB_PASSWORD` |
+| Ports | xem [05-ports.md](05-ports.md) |
+| URLs inter-service | `SPRING_SVC_URL`, `AUTH_MOCK_URL`, `SHELL_URL`, `REMOTE_TASKS_URL`, `REMOTE_ACTIVITY_URL` |
+| CORS | `CORS_DEV_ORIGIN` |
+| Log | `LOG_LEVEL` |
+| Mock auth | `AUTH_MOCK_DEV_PASSWORD`, `USERS_FIXTURE_PATH` |

package/stack-template/platform/conventions/07-cors.md

@@ -0,0 +1,23 @@
+# 07 — CORS dev-profile rule
+
+## Quy tắc cốt lõi
+
+**Prod (qua gateway): KHÔNG cần CORS** — browser chỉ nói chuyện với một origin (gateway :8080); FE không bao giờ gọi service port trực tiếp.
+
+**Dev native (không docker): CÓ CORS** — FE dev server :3000/:4001/:4002 gọi thẳng `localhost:3001/8081/8082/8090` → mở CORS cho đúng các origin dev, không mở đại `*` kèm credentials.
+
+## Cụ thể
+
+| Service | Mechanism | Scope |
+|---------|-----------|-------|
+| node-svc | `@fastify/cors` | origin = `CORS_DEV_ORIGIN` (env, ví dụ `http://localhost:3000,http://localhost:4001,http://localhost:4002`); methods GET/POST/PATCH/DELETE; headers `Authorization, Content-Type, X-Request-Id` |
+| spring-svc | `WebMvcConfigurer#addCorsMappings`, bean chỉ active với profile `dev` (`@Profile("dev")`) | cùng scope ở trên, đọc `cors.dev-origins` từ env |
+| go-svc | middleware `github.com/rs/cors` | cùng scope, đọc `CORS_DEV_ORIGIN` |
+| auth-svc | `@fastify/cors` | mở cho dev origin (FE dev gọi trực tiếp :8090) |
+
+## Quy tắc
+
+1. Origin KHÔNG hardcode — đọc `CORS_DEV_ORIGIN` (danh sách phân tách phẩy).
+2. Không bao giờ `origin: *` kết hợp `credentials: true`.
+3. Prod profile (compose): CORS middleware vẫn mount nhưng origin list rỗng → không header ACAO nào được emit (deny-by-default).
+4. Native FE dev mà thiếu CORS → lỗi network ngay trong console — check env trước khi debug service.

package/stack-template/platform/conventions/08-gateway-and-remotes.md

@@ -0,0 +1,33 @@
+# 08 — Gateway routing table + MF remote registry
+
+## Routing table (nginx — `platform/gateway/nginx/nginx.conf`)
+
+| Path | Upstream | Auth presence check | Ghi chú |
+|------|----------|--------------------|---------|
+| `/api/tasks/*` | `node-svc:3001` | ✓ thiếu `Authorization` → 401 | pass-through, KHÔNG rewrite — service mount `/api/tasks` prefix |
+| `/api/users/*` | `spring-svc:8081` | ✓ 401 | |
+| `/api/activity/*` | `go-svc:8082` | ✓ 401 | |
+| `/api/auth/*` | `auth-svc:8090` | ✗ mở | entry login + register + refresh (auth.yaml v2) |
+| `/` | `shell:3000` | ✗ | MF host (SF-5) — 502 đến khi shell tồn tại |
+| `/remotes/<name>/*` | remote `<name>` | ✗ | remote static (SF-6) — 502 đến khi tồn tại |
+
+Quy tắc kỹ thuật:
+1. **Pass-through**: `proxy_pass` không có URI part → original path giữ nguyên. OpenAPI `servers.url` = `/api/<svc>` khớp chính xác.
+2. **Lazy DNS**: mọi upstream set qua biến + `resolver 127.0.0.11` (Docker DNS) — gateway KHÔNG crash-loop khi một upstream chưa tồn tại (stage đầu chỉ có postgres + auth-svc + gateway chạy được; shell/services vào sau).
+3. Gateway sinh `X-Request-Id` nếu client thiếu (mirror vào response) — trace xuyên service, xem [03-logging.md](03-logging.md).
+4. Gateway chỉ làm **presence check** JWT — KHÔNG verify signature (không giữ secret). Verify thật ở từng service, xem `contracts/auth/token-contract.md` §4.
+
+## MF remote registry
+
+Nguồn sự thật cho FE shell (SF-5) biết load remote nào ở đâu. Env-configurable — dev trỏ dev server, prod trỏ static qua gateway.
+
+| Remote name | Module expose | Dev URL (env `REMOTE_TASKS_URL` / `REMOTE_ACTIVITY_URL`) | Prod URL |
+|-------------|---------------|------------------|----------|
+| `tasks` | `./TasksPage` | `http://localhost:4001/remoteEntry.js` | `/remotes/tasks/remoteEntry.js` (relative qua gateway) |
+| `activity` | `./ActivityPage` | `http://localhost:4002/remoteEntry.js` | `/remotes/activity/remoteEntry.js` |
+
+Quy tắc:
+1. Shell đọc registry từ env (`REMOTE_TASKS_URL`, `REMOTE_ACTIVITY_URL`) lúc build/bootstrap — KHÔNG hardcode URL.
+2. Remote name (`tasks`, `activity`) là khoá module federation — đổi tên = breaking, phải đồng bộ shell + remote + file này.
+3. Shared singletons (react, react-dom): quản qua pnpm catalog — chi tiết trong `app/shared/package.json` (trường `mfToolkit.pinned`, kết quả spike SF-1).
+4. **Singleton remote khai `requiredVersion: false` tường minh (SF-7 sync — học từ SF-6):** giá trị `catalog:` là literal pnpm-workspace, bundler MF không hiểu — `@module-federation/enhanced` infer thành `requiredVersion: "catalog:"` sai và match fail lúc runtime. Remote dùng shared singleton từ host phải khai `requiredVersion: false` trong share config (precedent: `app/remotes/{tasks,activity}/rspack.config.js`).

package/stack-template/platform/conventions/09-async-messaging.md

@@ -0,0 +1,42 @@
+# 09 — Async messaging qua Kafka (outbox + consumer + DLQ)
+
+Hợp đồng envelope/payload/topics là nguồn sự thật riêng:
+[`contracts/events/task-events.md`](../../contracts/events/task-events.md) — file này
+chỉ quy tắc VẬN HÀNH. Quyết định kiến trúc: [ADR-0008](../../docs/adr/0008-kafka-outbox-saga.md).
+
+## Quy tắc
+
+1. **Lazy-connect**: Kafka KHÔNG vào `/readyz` và KHÔNG có service nào
+   `depends_on: kafka` — health-gated chain 9 service không bị kafka chặn. Service
+   boot được cả khi broker chưa lên: producer/consumer connect retry backoff lúc
+   boot, connect fail = log warn, KHÔNG crash, KHÔNG fallback im lặng sang chế độ
+   bỏ-event.
+2. **Producer qua transactional outbox**: mutation DB và INSERT outbox (envelope
+   `id` = UUIDv4 sinh trong repo) trong CÙNG 1 tx. Relay worker poll (~500ms)
+   publish rồi mark `published_at`. KHÔNG publish broker trực tiếp trong request
+   path — publish fail giữa chừng = mất event (đúng điều ADR-0006 đã loại).
+3. **Envelope bắt buộc**: mọi message JSON đúng envelope `{schemaVersion, id, type,
+   occurredAt, payload}` (task-events.md). `schemaVersion` integer cố định `1`;
+   payload chỉ thêm field không breaking — consumer BỎ QUA field lạ, không chết.
+4. **Consumer idempotent**: at-least-once là mặc định — dedupe bằng envelope `id`
+   (`ON CONFLICT DO NOTHING`), KHÔNG dùng taskId (re-assign = nhiều event hợp lệ
+   cùng taskId).
+5. **Manual commit sau DB tx**: offset commit CHỈ sau khi DB tx commit thành công.
+   Commit trước tx = crash mất event; at-least-once + idempotency lo phần còn lại.
+6. **Filter-by-type theo group**: mọi consumer khai group của mình ở
+   task-events.md và lọc theo `type` — group mới phải thêm vào bảng group trước.
+7. **Retry ×3 in-memory rồi DLQ**: lỗi xử lý retry backoff ×3 in-memory; hết lượt
+   → message gốc + metadata lỗi vào `task-events.dlq`, KHÔNG requeue vô hạn,
+   KHÔNG block partition. Copy production: thêm alert + replay tool cho DLQ.
+8. **Kafka compose-internal**: PLAINTEXT, 9092 không expose host, single-node
+   KRaft heap 512m. Copy production: SASL/SSL + multi-broker (viền thay đổi nằm
+   ở entry kafka compose + client config).
+9. **Không secret trong payload** — envelope đi qua broker PLAINTEXT; payload là
+   dữ liệu demo (users fixture, task title).
+
+## Env liên quan (chi tiết trong `.env.example`)
+
+| Biến | Dùng bởi |
+|------|----------|
+| `KAFKA_BROKERS` | node-svc (relay + compensation consumer), go-svc (consumer) |
+| `SVC_ACTIVITY_PASSWORD` | go-svc — login fixture user `svc-activity` lấy service token (khớp `AUTH_MOCK_DEV_PASSWORD`) |

package/stack-template/platform/conventions/README.md

@@ -0,0 +1,15 @@
+# Platform Conventions — index
+
+SF-1 (FI-64) sở hữu. **Mọi service/repo-con trong boilerplate PHẢI theo các conventions này** — SF-2..7 đọc trước khi code. Không đúng convention = review fail.
+
+| File | Nội dung |
+|------|----------|
+| [01-dockerfile-pattern.md](01-dockerfile-pattern.md) | Dockerfile multi-stage pattern chuẩn cho cả 3 stack |
+| [02-healthcheck.md](02-healthcheck.md) | `/healthz` (liveness) + `/readyz` (readiness) — contract cho compose + CI boot-smoke |
+| [03-logging.md](03-logging.md) | JSON log shape chung |
+| [04-error-envelope.md](04-error-envelope.md) | Error envelope chung (mirror trong 4 OpenAPI specs) |
+| [05-ports.md](05-ports.md) | PORT TABLE — nguồn sự thật duy nhất về port |
+| [06-configuration.md](06-configuration.md) | Config qua env-var — quy tắc + .env workflow |
+| [07-cors.md](07-cors.md) | CORS dev-profile rule |
+| [08-gateway-and-remotes.md](08-gateway-and-remotes.md) | Gateway routing table + MF remote registry |
+| [09-async-messaging.md](09-async-messaging.md) | Kafka lazy-connect + outbox + consumer idempotent + retry/DLQ (hợp đồng envelope: contracts/events/task-events.md) |

package/stack-template/platform/docker-compose.yml

@@ -0,0 +1,255 @@
+# ============================================================================
+# Boilerplate Microservice + Micro-frontend — compose
+#
+# ⚠️ Shared file — sửa QUA cơ chế gap-answer soạn trước + coordinator APPROVED
+#    (pattern story auth-real VU-59), KHÔNG tự sửa giữa story.
+#
+# Lịch sử sở hữu (người sửa cuối = auth-real SF-5 VU-64):
+#   FI-64 SF-1: khung 9 services health-gated + postgres init + auth-mock
+#     + 2 entry remotes (FE điền impl vào khung).
+#   FI-75 SF-7: health-gated depends_on (healthcheck /readyz node-svc +
+#     spring-svc; gateway gate auth/node/spring service_healthy + go-svc
+#     service_started — distroless không có shell/wget, conventions/02 rule 3;
+#     gateway KHÔNG có healthcheck).
+#   FI-77 SF-1: + entry kafka (apache/kafka KRaft single-node, KHÔNG zookeeper;
+#     heap 512m cho CI 7GB; healthcheck full-path /opt/kafka/bin/... — image
+#     không có script trên PATH; KHÔNG expose 9092 ra host; KHÔNG service nào
+#     depends_on kafka — lazy-connect, conventions/09).
+#   VU-59 SF-5: decommission auth-mock → entry auth-svc (services/auth-svc,
+#     auth thật — register/refresh/RBAC; healthcheck /readyz kiểm DB thật;
+#     mount users.json; role auth_svc + schema auth; go-svc AUTH_MOCK_URL
+#     đổi VALUE giữ KEY — gap-answer epic VU-59 mục ①②④⑤⑥⑦, coordinator
+#     APPROVED).
+#   2026-10-23: go-svc env roles đã đúng ở entry (đã fix từ trước) — xoá services/go-svc/ci.compose.override.yml (redundant) — coordinator duyệt.
+# ============================================================================
+
+name: __STACK_NAME__
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:?set in .env}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set in .env}
+      POSTGRES_DB: ${POSTGRES_DB:?set in .env}
+      # password cho per-service roles — init script (01-init.sh) dùng
+      NODE_SVC_DB_PASSWORD: ${NODE_SVC_DB_PASSWORD:?set in .env}
+      SPRING_SVC_DB_PASSWORD: ${SPRING_SVC_DB_PASSWORD:?set in .env}
+      GO_SVC_DB_PASSWORD: ${GO_SVC_DB_PASSWORD:?set in .env}
+      GO_READONLY_DB_PASSWORD: ${GO_READONLY_DB_PASSWORD:?set in .env}
+      AUTH_SVC_DB_PASSWORD: ${AUTH_SVC_DB_PASSWORD:?set in .env}
+    volumes:
+      - ./postgres/init:/docker-entrypoint-initdb.d:ro
+      - pgdata:/var/lib/postgresql/data
+    ports:
+      - "${POSTGRES_PORT:-5432}:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
+      interval: 5s
+      timeout: 3s
+      retries: 12
+
+  kafka:
+    # Apache Kafka KRaft single-node (KHÔNG zookeeper) — ADR-0008.
+    # Compose-internal ONLY: không có `ports` = KHÔNG expose 9092 ra host.
+    # KHÔNG service nào depends_on kafka — connect lazy + retry lúc boot
+    # (conventions/09); healthcheck chỉ để `docker compose ps` quan sát.
+    image: apache/kafka:3.9.0
+    environment:
+      KAFKA_NODE_ID: 1
+      KAFKA_PROCESS_ROLES: broker,controller
+      KAFKA_LISTENERS: PLAINTEXT://:9092,CONTROLLER://:9093
+      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092 # hostname service trong mạng compose
+      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT
+      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
+      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:9093
+      KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT
+      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1 # single-node
+      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
+      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
+      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0 # demo — consumer nhận event ngay
+      KAFKA_HEAP_OPTS: -Xmx512m -Xms256m # CI runner 7GB — heap nhỏ có chủ đích
+    healthcheck:
+      # full path BẮT BUỘC — image apache/kafka không đặt script kafka-* trên PATH
+      test: ["CMD-SHELL", "/opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server localhost:9092"]
+      interval: 10s
+      timeout: 10s
+      retries: 12
+      start_period: 20s
+
+  auth-svc:
+    build: ../services/auth-svc # auth thật (VU-59) thay auth-mock — cùng surface :8090 /api/auth/*
+    environment:
+      PORT: 8090 # container port CỐ ĐỊNH (conventions/05) — ${AUTH_PORT} chỉ đổi side host
+      DATABASE_URL: postgres://auth_svc:${AUTH_SVC_DB_PASSWORD:?set in .env}@postgres:5432/${POSTGRES_DB:?set in .env}
+      JWT_SECRET: ${JWT_SECRET:?set in .env}
+      ACCESS_TOKEN_TTL: ${ACCESS_TOKEN_TTL:-30m} # token-contract.md §1 (30m — cũ 8h của mock)
+      # decision #10: default demo-password KHÔNG đổi — e2e + svc-activity + seed cùng một nguồn
+      AUTH_DEV_PASSWORD: ${AUTH_DEV_PASSWORD:-demo-password}
+      # fixture mount trực tiếp từ contracts/ — sửa fixture không cần rebuild image
+      # (seed idempotent ON CONFLICT (id) DO NOTHING — token-contract.md §5)
+      USERS_FIXTURE_PATH: /app/users.json
+      CORS_DEV_ORIGIN: ${CORS_DEV_ORIGIN:-}
+      LOG_LEVEL: ${LOG_LEVEL:-info}
+    volumes:
+      - ../contracts/auth/users.json:/app/users.json:ro
+    ports:
+      - "${AUTH_PORT:-8090}:8090" # host-side port — truy cập từ máy dev
+    depends_on:
+      postgres:
+        condition: service_healthy
+    healthcheck:
+      # probe TRONG container — hardcode 8090 (conventions/05); ${AUTH_PORT} chỉ host-side.
+      # /readyz (KHÔNG /healthz như auth-mock cũ) — kiểm DB thật: healthy = đã
+      # migrate schema auth + seed fixture xong → gateway chỉ nhận traffic khi service thật sự sẵn sàng.
+      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8090/readyz"]
+      interval: 5s
+      timeout: 3s
+      retries: 12
+      start_period: 20s # chờ migration + seed fixture lúc boot
+
+  gateway:
+    image: nginx:1.27-alpine
+    volumes:
+      - ./gateway/nginx/nginx.conf:/etc/nginx/nginx.conf:ro
+    ports:
+      - "${GATEWAY_PORT:-8080}:8080"
+    depends_on:
+      auth-svc:
+        condition: service_healthy
+      node-svc:
+        condition: service_healthy
+      spring-svc:
+        condition: service_healthy
+      # go-svc: service_started — distroless không có shell/wget cho healthcheck
+      # (conventions/02 rule 3); readiness chứng minh bằng scripts/smoke/e2e.sh
+      # poll /api/activity/stats (SF-7, FI-75).
+      go-svc:
+        condition: service_started
+    # KHÔNG healthcheck cho gateway — nginx proxy thuần, không route /readyz
+    # (probe sẽ 404); wait do scripts/smoke/e2e.sh poll /api/auth/readyz đảm nhiệm.
+
+  # --- KHUNG services (SF-2/3/4 điền impl — KHÔNG sửa entry) ---
+
+  node-svc:
+    build: ../services/node-svc
+    environment:
+      PORT: 3001 # container port CỐ ĐỊNH (conventions/05)
+      DATABASE_URL: postgres://node_svc:${NODE_SVC_DB_PASSWORD:?set in .env}@postgres:5432/${POSTGRES_DB:?set in .env}
+      JWT_SECRET: ${JWT_SECRET:?set in .env}
+      SPRING_SVC_URL: http://spring-svc:8081
+      GO_SVC_URL: http://go-svc:8082
+      CORS_DEV_ORIGIN: ${CORS_DEV_ORIGIN:-}
+      LOG_LEVEL: ${LOG_LEVEL:-info}
+      # PRE-ADD (SF-1 FI-77) — outbox relay + compensation consumer (SF-2) đọc.
+      # Node KHÔNG phụ thuộc kafka lúc boot — lazy-connect (conventions/09).
+      KAFKA_BROKERS: ${KAFKA_BROKERS:-kafka:9092}
+    ports:
+      - "${NODE_SVC_PORT:-3001}:3001" # host-side
+    depends_on:
+      postgres:
+        condition: service_healthy
+      spring-svc:
+        condition: service_healthy # readyz node kiểm spring reachable lúc boot — gate ở đây (SF-7)
+    healthcheck: # SF-7: health-gated /readyz (conventions/02) — node:22-alpine có busybox wget
+      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:3001/readyz"]
+      interval: 5s
+      timeout: 3s
+      retries: 12
+      start_period: 20s # chờ migration + spring reachability check lúc boot
+
+  spring-svc:
+    build: ../services/spring-svc
+    environment:
+      SERVER_PORT: 8081 # container port CỐ ĐỊNH (conventions/05)
+      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/${POSTGRES_DB:?set in .env}
+      SPRING_DATASOURCE_USERNAME: spring_svc
+      SPRING_DATASOURCE_PASSWORD: ${SPRING_SVC_DB_PASSWORD:?set in .env}
+      JWT_SECRET: ${JWT_SECRET:?set in .env}
+      USERS_FIXTURE_PATH: /app/contracts/auth/users.json
+      CORS_DEV_ORIGIN: ${CORS_DEV_ORIGIN:-}
+      LOG_LEVEL: ${LOG_LEVEL:-info}
+    volumes:
+      - ../contracts/auth/users.json:/app/contracts/auth/users.json:ro
+    ports:
+      - "${SPRING_SVC_PORT:-8081}:8081" # host-side
+    depends_on:
+      postgres:
+        condition: service_healthy
+    healthcheck: # SF-7: health-gated /readyz (conventions/02) — temurin alpine có busybox wget
+      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8081/readyz"]
+      interval: 5s
+      timeout: 3s
+      retries: 12
+      start_period: 30s # chờ Flyway migration + JVM boot
+
+  go-svc:
+    build: ../services/go-svc
+    environment:
+      PORT: 8082 # container port CỐ ĐỊNH (conventions/05)
+      DATABASE_URL: postgres://go_svc:${GO_SVC_DB_PASSWORD:?set in .env}@postgres:5432/${POSTGRES_DB:?set in .env}
+      DATABASE_READONLY_URL: postgres://go_readonly:${GO_READONLY_DB_PASSWORD:?set in .env}@postgres:5432/${POSTGRES_DB:?set in .env}
+      JWT_SECRET: ${JWT_SECRET:?set in .env}
+      SPRING_SVC_URL: http://spring-svc:8081
+      CORS_DEV_ORIGIN: ${CORS_DEV_ORIGIN:-}
+      LOG_LEVEL: ${LOG_LEVEL:-info}
+      # PRE-ADD (SF-1 FI-77) — task consumer + saga (SF-3) đọc:
+      KAFKA_BROKERS: ${KAFKA_BROKERS:-kafka:9092}
+      # service-token login fixture user svc-activity (resolver enrich userName;
+      # login backoff + lazy re-login — conventions/09). Giá trị .env phải khớp
+      # AUTH_DEV_PASSWORD (auth-svc so password hash của seeded users).
+      # KEY giữ AUTH_MOCK_URL (go-svc đọc theo tên env này — gap-answer ④);
+      # VALUE trỏ auth-svc sau decommission (đổi KEY = follow-up cụm iss-rename).
+      AUTH_MOCK_URL: http://auth-svc:8090
+      SVC_ACTIVITY_PASSWORD: ${SVC_ACTIVITY_PASSWORD:?set in .env}
+    ports:
+      - "${GO_SVC_PORT:-8082}:8082" # host-side
+    depends_on:
+      postgres:
+        condition: service_healthy
+
+  # --- FE entries: shell (SF-5 thêm — GAP-ANSWER coordinator trên epic FI-62 2026-10-12:
+  #     "BẠN tự thêm theo port table, coordinator duyệt ở review"). remote-tasks /
+  #     remote-activity do SF-6 thêm. ---
+  shell:
+    build:
+      context: .. # repo root — Dockerfile cần app/shared + workspace lockfile
+      dockerfile: app/shell/Dockerfile
+    ports:
+      - "${SHELL_PORT:-3000}:3000" # container port cố định 3000 (conventions/05)
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:3000/"]
+      interval: 5s
+      timeout: 3s
+      retries: 12
+
+  # --- remote-tasks / remote-activity: SF-6 (FI-74) điền impl vào khung pre-seed ---
+  # (gap-answer được BRIEF SF-6 ủy quyền 2026-10-12: "BẠN tự thêm 2 entry remotes — build
+  # ../app/remotes/*, port theo port table, healthcheck static; coordinator duyệt ở review".
+  # SF-6 KHÔNG sửa phần khác của file này.)
+  remote-tasks:
+    build:
+      context: .. # repo root — Dockerfile cần app/shared + workspace lockfile
+      dockerfile: app/remotes/tasks/Dockerfile
+    ports:
+      - "${REMOTE_TASKS_PORT:-4001}:4001" # container port cố định 4001 (conventions/05)
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:4001/remoteEntry.js"]
+      interval: 5s
+      timeout: 3s
+      retries: 12
+
+  remote-activity:
+    build:
+      context: .. # repo root — Dockerfile cần app/shared + workspace lockfile
+      dockerfile: app/remotes/activity/Dockerfile
+    ports:
+      - "${REMOTE_ACTIVITY_PORT:-4002}:4002" # container port cố định 4002 (conventions/05)
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:4002/remoteEntry.js"]
+      interval: 5s
+      timeout: 3s
+      retries: 12
+
+volumes:
+  pgdata:

package/stack-template/platform/gateway/nginx/nginx.conf

@@ -0,0 +1,137 @@
+# ============================================================================
+# nginx gateway — routing theo platform/conventions/08-gateway-and-remotes.md
+# SF-1 sở hữu (FI-64). Services chỉ đọc, KHÔNG sửa.
+#
+# Design decisions:
+# - Pass-through: proxy_pass KHÔNG có URI part → path giữ nguyên; service mount
+#   đúng prefix /api/<svc> (khớp servers.url trong contracts/openapi/*.yaml).
+#   Ngoại lệ /remotes/<name>/*: strip prefix trước khi forward (static remote
+#   serve ở root — xem conventions/08).
+# - Lazy DNS: upstream đặt qua biến + resolver 127.0.0.11 (Docker DNS) —
+#   gateway KHÔNG crash-loop khi upstream chưa tồn tại (stage đầu chỉ có
+#   postgres/auth/gateway sống; shell + 3 services vào sau).
+# - JWT presence check CHỈ trên /api/tasks|users|activity — signature verify
+#   là việc của service (contracts/auth/token-contract.md §4).
+# ============================================================================
+
+worker_processes auto;
+error_log /dev/stderr warn;
+pid /tmp/nginx.pid;
+
+events {
+    worker_connections 1024;
+}
+
+http {
+    include /etc/nginx/mime.types;
+    default_type application/octet-stream;
+    sendfile on;
+    client_max_body_size 2m;
+
+    # Docker embedded DNS — resolve upstream lúc request (không lúc config load)
+    resolver 127.0.0.11 valid=10s ipv6=off;
+
+    # Request id: echo của client hoặc sinh mới ($request_id builtin) — conventions/03
+    map $http_x_request_id $req_id {
+        ""      $request_id;
+        default $http_x_request_id;
+    }
+
+    # Remote registry (prod mode): path /remotes/<name>/* → container remote.
+    # default rơi về shell — remote name lạ sẽ nhận 404 từ shell thay vì 500 gateway.
+    map $uri $remote_up {
+        ~^/remotes/tasks/    "http://remote-tasks:4001";
+        ~^/remotes/activity/ "http://remote-activity:4002";
+        default              "http://shell:3000";
+    }
+
+    server {
+        listen 8080;
+        server_name _;
+
+        # ---------- API: tasks → node-svc (presence check 401) ----------
+        location = /api/tasks {
+            if ($http_authorization = "") { return 401; }
+            set $up http://node-svc:3001;
+            proxy_pass $up;
+            proxy_set_header Host $host;
+            proxy_set_header X-Request-Id $req_id;
+        }
+        location /api/tasks/ {
+            if ($http_authorization = "") { return 401; }
+            set $up http://node-svc:3001;
+            proxy_pass $up;
+            proxy_set_header Host $host;
+            proxy_set_header X-Request-Id $req_id;
+        }
+
+        # ---------- API: users → spring-svc ----------
+        location = /api/users {
+            if ($http_authorization = "") { return 401; }
+            set $up http://spring-svc:8081;
+            proxy_pass $up;
+            proxy_set_header Host $host;
+            proxy_set_header X-Request-Id $req_id;
+        }
+        location /api/users/ {
+            if ($http_authorization = "") { return 401; }
+            set $up http://spring-svc:8081;
+            proxy_pass $up;
+            proxy_set_header Host $host;
+            proxy_set_header X-Request-Id $req_id;
+        }
+
+        # ---------- API: activity → go-svc ----------
+        location = /api/activity {
+            if ($http_authorization = "") { return 401; }
+            set $up http://go-svc:8082;
+            proxy_pass $up;
+            proxy_set_header Host $host;
+            proxy_set_header X-Request-Id $req_id;
+        }
+        location /api/activity/ {
+            if ($http_authorization = "") { return 401; }
+            set $up http://go-svc:8082;
+            proxy_pass $up;
+            proxy_set_header Host $host;
+            proxy_set_header X-Request-Id $req_id;
+        }
+
+        # ---------- API: auth → auth-svc (MỞ — entry login + register + refresh) ----------
+        location /api/auth {
+            set $up http://auth-svc:8090;
+            proxy_pass $up;
+            proxy_set_header Host $host;
+            proxy_set_header X-Request-Id $req_id;
+        }
+
+        # ---------- 401 body theo error envelope chung (conventions/04) ----------
+        error_page 401 = @unauthorized;
+        location @unauthorized {
+            default_type application/json;
+            add_header X-Request-Id $req_id always;
+            return 401 '{"error":{"code":"UNAUTHORIZED","message":"Missing Authorization header","requestId":null,"details":null}}';
+        }
+
+        # ---------- FE: remote static (SF-6) — strip prefix, forward root ----------
+        location /remotes/ {
+            # map $uri là LAZY-evaluated: phải nạp $remote_up vào $up TRƯỚC khi
+            # rewrite strip prefix. Tính map sau rewrite thì $uri đã thành
+            # "/remoteEntry.js" → mọi remote rơi default shell → nhận index.html
+            # của shell thay vì JS (MF load fail — bug gặp fresh-clone 2026-10-13).
+            set $up $remote_up;
+            rewrite ^/remotes/[a-z-]+(/.*)?$ $1 break;
+            proxy_pass $up;
+            proxy_set_header Host $host;
+            proxy_set_header X-Request-Id $req_id;
+        }
+
+        # ---------- FE: shell MF host (SF-5) — 502 đến khi shell tồn tại ----------
+        location / {
+            set $up http://shell:3000;
+            proxy_pass $up;
+            proxy_set_header Host $host;
+            proxy_set_header X-Request-Id $req_id;
+        }
+    }
+}

package/stack-template/platform/postgres/init/01-init.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# ============================================================================
+# Postgres init — chạy MỘT LẦN trên volume mới (docker-entrypoint-initdb.d).
+# Tạo: 4 schemas (tasks/users/activity/auth) + 1 LOGIN role per service + 1
+# readonly role cho go-svc đọc schema `tasks`.
+#
+# ĐIỂM MÚT: ALTER DEFAULT PRIVILEGES FOR ROLE node_svc — grant SELECT hiệu lực
+# cho BẢNG SINH SAU bởi migration của node-svc (SF-2). Không có default
+# privileges thì go_readonly không thấy bảng mới → stats 503.
+# ============================================================================
+set -euo pipefail
+
+psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" <<EOSQL
+-- Schemas — mỗi service 1 schema (multi-repo convention trong 1 DB)
+CREATE SCHEMA IF NOT EXISTS tasks;
+CREATE SCHEMA IF NOT EXISTS users;
+CREATE SCHEMA IF NOT EXISTS activity;
+CREATE SCHEMA IF NOT EXISTS auth;
+
+-- LOGIN role per service — mỗi service chỉ đụng schema của mình
+-- Ràng buộc (P2 security-audit SF-5): password KHÔNG chứa dấu nháy đơn (')
+-- — bash interpolate rồi bọc single-quote trong SQL; giá trị sai cú pháp làm
+-- init fail-closed (ON_ERROR_STOP) chứ không bypass. Upgrade path: psql -v
+-- binding (:'var') cho cả 5 role — follow-up, không phải instance mới alone.
+CREATE ROLE node_svc   LOGIN PASSWORD '${NODE_SVC_DB_PASSWORD}';
+CREATE ROLE spring_svc LOGIN PASSWORD '${SPRING_SVC_DB_PASSWORD}';
+CREATE ROLE go_svc     LOGIN PASSWORD '${GO_SVC_DB_PASSWORD}';
+CREATE ROLE auth_svc   LOGIN PASSWORD '${AUTH_SVC_DB_PASSWORD}';
+
+-- readonly role — go-svc đọc stats từ schema tasks (canonical DDL của SF-1)
+CREATE ROLE go_readonly LOGIN PASSWORD '${GO_READONLY_DB_PASSWORD}';
+
+-- Owners + quyền schema
+GRANT USAGE, CREATE ON SCHEMA tasks    TO node_svc;
+GRANT USAGE, CREATE ON SCHEMA users    TO spring_svc;
+GRANT USAGE, CREATE ON SCHEMA activity TO go_svc;
+GRANT USAGE, CREATE ON SCHEMA auth     TO auth_svc;
+ALTER ROLE node_svc   SET search_path = tasks;
+ALTER ROLE spring_svc SET search_path = users;
+ALTER ROLE go_svc     SET search_path = activity;
+ALTER ROLE auth_svc   SET search_path = auth;
+
+-- Readonly read path
+GRANT USAGE ON SCHEMA tasks TO go_readonly;
+
+-- ⚠️ Default privileges: grant áp dụng cho bảng tạo SAU này bởi owner role.
+-- (FOR ROLE node_svc = bảng do migration node-svc tạo ra.)
+ALTER DEFAULT PRIVILEGES FOR ROLE node_svc IN SCHEMA tasks
+  GRANT SELECT ON TABLES TO go_readonly;
+
+-- go-svc đọc display fields từ users schema? KHÔNG — userName resolve qua
+-- spring-svc (contract activity.yaml), go_readonly CHỈ được schema tasks.
+EOSQL
+
+echo "[init] schemas + roles + default privileges created OK"