@educa-corp/sdd-framework 0.2.6 → 0.2.8

package/core/modules/phaser-game/stack-profile.yaml

@@ -0,0 +1,90 @@
+build:
+  compile: "tsc --noEmit && vite build"        # type-check, then bundle to dist/ (base './')
+  test: "vitest run"
+  run: "vite"                                    # dev server with HMR
+  lint: "eslint . --ext .ts"
+
+architecture:
+  style: "Phaser 3 scene state machine + framework-free domain logic + direct backend API (token injected by host) + thin native window bridge"
+  key_rules:
+    - "Keep GAME LOGIC that can be pure (scoring, spawn tables, weight/physics math) in framework-free TS modules under src/domain/ — no Phaser imports there, so it unit-tests in Node"
+    - "Scenes orchestrate; they call domain functions and drive Phaser objects — they do NOT hold complex business math inline"
+    - "One responsibility per scene: BootScene (read host config), PreloadScene (load assets + game data), MenuScene, GameScene, GameOverScene, UIScene (HUD overlay run in parallel)"
+    - "Game objects (Miner, Hook, Gold) are Phaser.GameObjects subclasses (prefabs) — reusable, self-contained"
+    - "APPROACH A: the game calls the backend DIRECTLY (fetch). Host (Flutter) injects a HostConfig (apiBase, token, userId, sessionId) into the WebView BEFORE load — the game never hard-codes URLs or tokens"
+    - "All backend I/O goes through ONE API client (src/api/) that reads the token from HostConfig and sets the Authorization header — never scatter raw fetch() across scenes"
+    - "The native bridge (GameContract) is thin: window CONTROL only (onReady, onClose/back). Data does NOT go through native in Approach A — it goes over HTTP"
+    - "Tuning numbers live in src/config/constants.ts, never hard-coded in scenes"
+    - "Vite base MUST be './' so the built bundle works from file:// inside a WebView"
+    - "Use Phaser Arcade Physics for collision/overlap; avoid hand-rolled loops unless the mechanic needs it"
+    - "Cross-scene / game↔UI communication uses an event emitter (this.game.events or a shared EventBus), not direct scene references"
+    - "Debug console (eruda) is loaded ONLY when the URL has ?debug=1 — never bundled into the default runtime path"
+    - "Never trust HostConfig blindly — validate it at boot (BootScene) and fail loudly (call onClose) if apiBase/token is missing"
+  folder_structure: |
+    .
+    ├── index.html                 ← <div id="game"> + <script type="module" src="/src/main.ts">
+    ├── vite.config.ts             ← base: './', @vitejs/plugin-legacy for old WebView
+    ├── tsconfig.json
+    ├── public/assets/             ← images, audio, atlases, tilemaps (copied as-is)
+    ├── src/
+    │   ├── main.ts                ← Phaser.Game config + scene list, mount debug bridge
+    │   ├── contracts/
+    │   │   ├── game-contract.ts   ← GameContract (window control) + HostConfig shape
+    │   │   └── api.dto.ts         ← backend request/response DTOs (GameDataDto, ResultDto)
+    │   ├── config/
+    │   │   ├── constants.ts       ← GRAVITY, HOOK_SPEED, SPAWN_TABLE...
+    │   │   ├── host-config.ts     ← read + validate window.GAME_CONFIG injected by Flutter
+    │   │   └── game-config.ts     ← Phaser.Types.Core.GameConfig
+    │   ├── api/                   ← client.ts (fetch + auth header), game.api.ts (loadData, submitResult)
+    │   ├── domain/                ← PURE TS, no Phaser: scoring.ts, spawn.ts, hook-physics.ts
+    │   ├── scenes/                ← BootScene.ts, PreloadScene.ts, MenuScene.ts, GameScene.ts, GameOverScene.ts, UIScene.ts
+    │   ├── objects/               ← Miner.ts, Hook.ts, Gold.ts (Phaser.GameObjects prefabs)
+    │   ├── bridge/                ← native-bridge.ts (onReady/onClose), event-bus.ts
+    │   └── debug/                 ← eruda.ts (lazy-loaded when ?debug=1)
+    └── tests/                     ← *.test.ts (Vitest → domain/) + e2e/*.spec.ts (Playwright)
+
+coding_standards:
+  naming:
+    scenes: "PascalCase + 'Scene' suffix (BootScene, GameScene, UIScene)"
+    game_objects: "PascalCase prefab class (Miner, Hook, Gold)"
+    domain_functions: "camelCase pure functions (calcScore, rollSpawn, retractSpeed)"
+    contracts: "PascalCase interface, 'Contract'/'Dto' suffix (GameContract, ScoreDto)"
+    constants: "SCREAMING_SNAKE_CASE (GRAVITY, HOOK_SPEED, SPAWN_TABLE)"
+    scene_keys: "kebab or PascalCase string key matching class (scene.start('GameScene'))"
+    files:
+      scene: "{Name}Scene.ts"
+      object: "{Object}.ts"
+      domain: "{topic}.ts"
+      contract: "game-contract.ts / {topic}.dto.ts"
+      test: "{unit}.test.ts"
+  patterns:
+    scenes: "Phaser scene lifecycle: init(data) → preload() → create() → update(t, dt); transition via this.scene.start('Key', data)"
+    hud: "UIScene launched in parallel (this.scene.launch('UIScene')) and rendered above GameScene"
+    physics: "Arcade Physics — this.physics.add.overlap(hook, goldGroup, onGrab)"
+    assets: "Load everything in PreloadScene with a progress bar; reference by key afterwards"
+    animation: "Tweens (this.tweens.add) for hook swing/retract easing; sprite sheet anims for characters"
+    state_transfer: "Pass data between scenes via scene.start('Key', payload); load game data once in PreloadScene via the API client, then hand it to GameScene"
+    host_config: "Flutter injects window.GAME_CONFIG = { apiBase, token, userId, sessionId } via initialUserScripts/evaluateJavascript BEFORE the page loads; read + validate it once in host-config.ts"
+    api_client: "APPROACH A — game calls backend directly. One fetch wrapper sets Authorization: Bearer <token> from HostConfig; game.api.ts exposes loadData()/submitResult() returning typed DTOs; handle 401/timeout and surface to the player"
+    native_bridge: "Thin GameContract = window control only. onReady() when boot ok; onClose() on back/X button → Flutter pops the WebView. NO data over the bridge in Approach A"
+    events: "EventBus (Phaser.Events.EventEmitter) for game→HUD updates (score changed, time left)"
+    webview: "Vite base './' + @vitejs/plugin-legacy + core-js for ES5 WebViews; toggle legacy per Android min-SDK"
+    debug: "eruda (or vConsole) lazy-imported only when new URLSearchParams(location.search).get('debug') === '1'"
+
+testing:
+  unit: "Vitest — target src/domain/ pure functions (scoring, spawn rolls, retract speed by weight). No Phaser, no DOM, no canvas mock needed"
+  e2e: "Playwright — run vite preview, load the page, drive canvas via keyboard/pointer, assert on the HUD DOM overlay or exposed window.__gameState"
+  patterns:
+    - "Split logic so the testable part imports zero Phaser — Phaser scenes stay thin wrappers"
+    - "Inject a seeded RNG into spawn functions so tests are deterministic"
+    - "Expose a minimal window.__gameState (score, scene) in dev/e2e builds for Playwright assertions"
+    - "Mock the native bridge with a fake GameContract in tests; assert onReady/onClose are called"
+    - "Mock fetch (or the API client) in unit tests; assert loadData()/submitResult() send the right URL, auth header, and payload"
+    - "In e2e, stub window.GAME_CONFIG and intercept backend routes with Playwright page.route() so tests need no real server"
+    - "Do not pixel-diff the canvas — assert on state and HUD text instead"
+
+trace_tags:
+  implements: "// @trace.implements={UC-ID}-SC{N}"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  verifies: "// @trace.verifies={UC-ID}"
+  test_type: "// @trace.test_type=unit|integration"

package/core/steps/context-loader.md

@@ -42,6 +42,7 @@ Thực hiện các bước theo đúng thứ tự. Lưu mọi thứ vào bộ nh
 - `paths.business_dictionary` → path tới business-dictionary.md
 - `paths.core_entities` → path tới core-entities.md
 - `paths.tech_docs_dir` → gốc tài liệu kỹ thuật (gộp với specs_dir trong bố cục feature-package — tech-docs nằm dưới `{specs_dir}/{domain}/{prd-slug}/tech-docs/`)
+- `paths.src_dir` → gốc mã nguồn (nơi generate-code đặt & quét code; nguồn chính cho FE + phạm vi reuse-scan của DS5)
 - `paths.trace_dir` → thư mục trạng thái trace; cấu trúc: `.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` (mỗi UC × platform một sổ)
 
 Nếu không có section `paths`, dùng các giá trị mặc định:
@@ -54,6 +55,7 @@ Nếu không có section `paths`, dùng các giá trị mặc định:
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
 - `core_entities` = `specs/domain-knowledge/core-entities.md`
 - `tech_docs_dir` = `specs`
+- `src_dir` = `src`
 - `trace_dir` = `.trace`
 
 Lưu ý: Trong bố cục feature-package, `specs_dir` là gốc thống nhất. Mọi loại spec artifact (PRD, BDD, tech-docs, design-spec) đều nằm dưới `{specs_dir}/{domain}/{prd-slug}/`. `prd-slug` là tên folder feature-package, không phải một biến config riêng.

package/core/steps/gate.md

@@ -49,7 +49,8 @@ Hiển thị và chờ phản hồi:
 
 ## Bước 1 — Xác định Target File
 
-1. Nếu `$ARGUMENTS` được cung cấp và trỏ tới một file tồn tại → dùng trực tiếp làm target.
+0. **Tách cờ trước khi resolve target.** `$ARGUMENTS` có thể lẫn các `--flag` (vd `--phase=integration`, `--comment`, `--fix`). **Loại bỏ mọi token bắt đầu bằng `--`** ra khỏi phần dùng để tìm target — chỉ giữ phần path/UC-ID/ticket. (Các flag đó do phần logic riêng của lệnh parse ở bước sau, KHÔNG phải tên file.)
+1. Nếu `$ARGUMENTS` (đã tách cờ) được cung cấp và trỏ tới một file tồn tại → dùng trực tiếp làm target.
 2. Nếu `$ARGUMENTS` là một **UC-ID / ticket ID / tên rút gọn** (không có path) → phân giải thành file bằng cách glob theo bố cục feature-package. `{prd-slug}` lúc này **chưa biết**, nên dùng wildcard `*` cho segment đó, và `**` đệ quy dưới `bdd/` để phủ hết các thư mục con theo platform (`bdd/web/`, `bdd/app/`, `bdd/system/`):
    - **Lệnh BDD** (target là `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — hoặc `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` nếu domain cũng chưa biết. Nếu lệnh ngụ ý một platform/scope cụ thể (vd: system tech-doc cần BDD `system/`), ưu tiên kết quả trong thư mục con platform đó.
    - **Lệnh PRD** (target là file PRD `{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder, cạnh `bdd/`): `{specs_dir}/{domain}/*/{TICKET-ID}*.md` nếu biết TICKET-ID; nếu không, `{specs_dir}/{domain}/*/*.md` (khớp feature folder có id tương ứng), hoặc `{specs_dir}/*/*/*.md` nếu domain cũng chưa biết. *(Glob `*/*.md` ở cấp gốc folder chỉ khớp PRD — tech-docs/design-spec `.md` nằm sâu hơn trong thư mục con.)*

package/core/templates/project-context.yaml

@@ -35,6 +35,12 @@ paths:
   # prd-slug is derived from the PRD folder path — not a separate config variable.
   specs_dir: "specs"
   templates_dir: "specs/templates"
+
+  # Source code root — gốc mã nguồn của service/app này (nơi generate-code đặt & quét code).
+  # BE thường suy vị trí từ CLAUDE.md §2 (code_base_package + layer); src_dir là gốc chung,
+  # và là NGUỒN CHÍNH cho FE (component/hook/service/adapter) + phạm vi quét reuse (DS5).
+  # Ví dụ: "src" (mono FE), "app/src", "src/main/java" (BE). Chỉnh theo layout thật của repo.
+  src_dir: "src"
   feature_template: ".agent/templates/feature.template"   # SoT skeleton .feature (dùng bởi /generate-bdd qua {{include}})
   bdd_writing_guide: "specs/templates/bdd-writing-guide.md"
   trace_report: "specs/.trace/trace-report.md"

package/docs/02-concepts/pipeline-steps/06-code.md

@@ -70,12 +70,15 @@ Code là **hệ quả của spec, không phải nguồn**. Bước này biến s
 5. **Build verify** — chạy `{conventions.build_command}`, ≤3 retry.
 6. **Ghi trace row** vào `.tsv` (trong spec repo nếu umbrella — thao tác ghi liên-repo).
 
-**Phase cho Frontend:**
-| Phase | Ý nghĩa |
+**Mode theo phase × platform:**
+| Mode | Ý nghĩa |
 |-------|---------|
 | `--phase=ui` | FE Phase 1 — sinh UI + layer **mock API** từ System BDD contract |
-| `--phase=integration` | FE nối vào **BE contract thật** (đọc tech-design từ spec repo) |
-| *(default)* | Backend — sinh từ tech-design §4 |
+| `--phase=integration` | FE Phase 2 — **thay** mock bằng **BE contract thật** (đọc tech-design từ spec repo); UI đã có |
+| *(default, `web`/`app`)* | **`fe_full`** — sinh UI **+** wire API thật một lần, bỏ lớp mock |
+| *(default, `system`)* | Backend — sinh từ tech-design §4 |
+
+> Nhánh wire API thật (`integration` / `fe_full`) đi qua **DS4** (kiểm §4.5.4 đủ, vét nguồn rồi gộp-hỏi) và **DS5** (phát hiện component/service FE đang chạy → hỏi reuse/new, không dựng song song). Bảng hành vi đầy đủ từng bước → [Explain · generate-code](../../explain/09-generate-code.md#hành-vi-theo-mode-phase--platform).
 
 **`/review-code`** — read-only, chỉ báo findings (không tự sửa: "AI tự fix tự review" = lặp lỗi).
 **`/fix-bug`** — sửa lỗi có root-cause + regression test; xem [Feedback Loop](10-feedback-loop.md).

package/docs/03-guides/developer.md

@@ -42,12 +42,15 @@ flowchart LR
 
 ---
 
-## Frontend: hai phase
+## Frontend: hai phase, hoặc một lần (full)
 
-| Phase | Khi nào | Việc |
+| Mode | Khi nào | Việc |
 |-------|---------|------|
 | `--phase=ui` | BE contract chưa sẵn | Sinh UI + layer **mock API** từ System BDD |
-| `--phase=integration` | BE contract `approved` | Nối vào contract thật (đọc tech-design từ spec repo) |
+| `--phase=integration` | BE contract `approved`, UI đã có | Nối vào contract thật (đọc tech-design từ spec repo) |
+| **không flag** (`fe_full`) | contract sẵn, muốn làm dứt điểm | Sinh UI **+** wire API thật một lần, bỏ lớp mock |
+
+> Cả `integration` lẫn `fe_full` đều qua **DS4** (kiểm §4.5.4 đủ trước khi wire; vét nguồn rồi gộp-hỏi thay vì hỏi live) và **DS5** (thấy component/service FE đang chạy thì **hỏi reuse/new**, không im lặng dựng mới). Bảng hành vi đầy đủ theo từng mode → [Explain · generate-code](../explain/09-generate-code.md#hành-vi-theo-mode-phase--platform).
 
 ---
 

package/docs/explain/09-generate-code.md

@@ -15,7 +15,7 @@ Code là **hệ quả của spec**. Command biến scenario thành code sao cho:
 ## Vị trí & tiền đề
 
 - **Vị trí:** Phase Implementation, sau BDD + tech-docs.
-- **Gate vào:** cảnh báo mềm DS1 (BDD chưa approved), DS2 (design-spec), DS3 (tech-doc contract).
+- **Gate vào:** cảnh báo mềm DS1 (BDD chưa approved), DS2 (design-spec), DS3 (tech-doc contract BE), **DS4** (client contract §4.5.4) + **DS5** (FE reuse gate) — DS4/DS5 chỉ khi wire API thật (`integration`/`fe_full`). Xem [Hành vi theo mode](#hành-vi-theo-mode-phase--platform).
 
 ---
 
@@ -30,7 +30,7 @@ Code là **hệ quả của spec**. Command biến scenario thành code sao cho:
 ## Các bước xử lý (chi tiết)
 
 1. **Guard BDD & Design Spec** — DS1/DS2/DS3 cảnh báo mềm nếu nguồn chưa chốt.
-2. **Phase Detection** — `--phase=ui` (FE Phase 1: UI + mock API; **mock source hybrid** = ưu tiên tech-doc §4 contract, fallback System BDD) · `--phase=integration` (thay mock bằng API thật) · default (BE/full-stack). `system` → bỏ flag.
+2. **Phase Detection** — `--phase=ui` (FE Phase 1: UI + mock API; **mock source hybrid** = ưu tiên tech-doc §4 contract, fallback System BDD) · `--phase=integration` (thay mock bằng API thật) · **`fe_full`** (default trên `web`/`app`: UI + real API một lần, bỏ mock) · default BE (`system`, full backend). Chi tiết: [Hành vi theo mode](#hành-vi-theo-mode-phase--platform).
 3. **Figma Dev Mode MCP Check** (sinh UI) — đọc frame Figma độ trung thực cao cho codegen.
 4. **Read Trace State** — so `bdd_version`/spec với `.tsv` → phân loại **new / drifted / synced-skip**.
 5. **Package Placement** — đặt code đúng `code_base_package` + strategy (by-layer/by-feature), chống phân mảnh.
@@ -42,11 +42,47 @@ Code là **hệ quả của spec**. Command biến scenario thành code sao cho:
 8. **CHECKPOINT — Code Generation Plan** — 🛑 trình: scenarios (X new, Y drifted, Z synced-skip) · CREATE (mới) · **EXTEND (ADD-ONLY, cấm full Write)** · **FILL** (lấp stub tại chỗ, không đẻ method song song) · SKIP + danh sách member GIỮ NGUYÊN (UC khác). **Scope Lock**: chỉ đọc/implement UC target.
 9. **Branch** `feature/{TICKET}-{slug}`.
 10. **Generate** theo **thứ tự layer từ CLAUDE.md §2**; tag `@trace.implements/source` ở boundary.
-11. **Mock/Integration** — layer mock (`--phase=ui`) hoặc thay adapter thật (`--phase=integration`).
+11. **Mock/Integration** — layer mock (`--phase=ui`) · thay adapter thật (`--phase=integration`) · wire real thẳng (`fe_full`). Nhánh wire API thật đi qua **DS4** (kiểm §4.5.4 đủ + **SRC-CHAIN** vét nguồn, gộp-hỏi thay vì hỏi live).
 12. **Self-Review (3 vòng)** → **Build Verify** (`{build_command}`, ≤3 retry) → **Write Trace State** → **Refresh Panel Mirror** (Living Docs umbrella) → **Commit** (sau khi duyệt).
 
 ---
 
+## Hành vi theo mode (Phase × Platform)
+
+`generate-code` rẽ nhánh theo `--phase` và platform của `.feature`. Bốn mode:
+
+- **`--phase=ui`** — FE Phase 1: chỉ UI + mock, không chạm API thật (prototype nhanh).
+- **`--phase=integration`** — FE Phase 2: **không** sinh lại UI, chỉ **thay** mock bằng real adapter.
+- **`fe_full`** — default (không flag) trên feature `web`/`app`: UI **+** wire API thật trong một lần, bỏ lớp mock trung gian.
+- **default BE** — không flag trên `system`: full backend.
+
+| Bước / Gate | `--phase=ui` | `--phase=integration` | `fe_full` (default web/app) | default BE (`system`) |
+|---|:--:|:--:|:--:|:--:|
+| **DS1** — BDD `approved` guard | ✅ | ✅ | ✅ | ✅ |
+| **DS2** — design-spec guard (FE) | ✅ | ✅ | ✅ | — |
+| **DS3** — BE contract gate (§4) | — | — | — | ✅ |
+| **DS4** — client contract gate (§4.5.4) | ⏭️ cố ý | ✅ | ✅ | — |
+| **DS5** — FE component/service reuse gate | ⏭️ | ✅ | ✅ | — |
+| **Sinh UI** (Figma MCP, component, state) | ✅ | ⏭️ giữ UI cũ | ✅ | — |
+| **Test Selectors** (emit test-id) | ✅ | ⏭️ | ✅ | — |
+| **Mock API Layer** | ✅ | ⏭️ | ⏭️ | — |
+| **Integration Phase** (real API adapter) | ⏭️ | ✅ | ✅ | — |
+| **Wire-up API** | dùng **mock** | **lật** mock→real | wire **thẳng** real | — (BE là API) |
+| **SRC-CHAIN** (vét nguồn trước khi hỏi) | ✅¹ | ✅ | ✅ | ✅ |
+| **Nguồn shape/contract** | §4 nếu có, else System BDD | §4.5.4 → §4.1–4.3 | §4.5.4 → §4.1–4.3 (+ design-spec) | §4 (DS3, nguyên văn) |
+| **Output adapter** | `{UC}MockApiAdapter` | `{UC}ApiAdapter` (giữ mock) | `{UC}ApiAdapter` (không mock) | — |
+| **Trace `fe_phase`** | `ui` | `integrated` | `integrated` | `—` |
+
+<sub>✅ chạy · ⏭️ bỏ qua (có chủ đích) · — không áp dụng. ¹SRC-CHAIN là quy tắc chung, active mọi mode; chỉ được **gom-hỏi qua DS4** ở integration/fe_full.</sub>
+
+**Bất đối xứng đáng nhớ:**
+- **DS4** có ở mọi nhánh wire API thật (integration + fe_full), **trừ** `ui` (cố ý) và BE (BE dùng DS3).
+- **Mock API Layer** là thứ **duy nhất** riêng `--phase=ui`.
+- **Sinh UI** có ở `ui` và `fe_full`, **không** ở `integration` (giả định UI đã có từ pha ui).
+- **`fe_full` = `ui` + `integration`** gộp một lần (bỏ mock), nhưng **vẫn giữ safety gate DS4** — không phải đường tắt kém an toàn.
+
+---
+
 ## Checkpoint & Gate
 
 - 🛑 **Comprehension checkpoint** (Code Generation Plan) — điểm dừng chính; Dev xác nhận drift + scope đúng.
@@ -59,6 +95,8 @@ Code là **hệ quả của spec**. Command biến scenario thành code sao cho:
 - **Seam & Stub Ledger** — cơ chế tinh vi nhất: giải quyết vấn đề "sinh code từng BDD rời tạo hàm mồ côi". `READY` là cờ 🔴 để lần sau nối hàng thật vào.
 - **Scope Lock + ADD-ONLY + FILL** — bảo toàn code UC khác trong file dùng chung; EXTEND chỉ Edit thêm, FILL lấp stub tại chỗ.
 - **Mock source hybrid** — mock shape ưu tiên contract thật để đỡ rework lúc integration.
+- **SRC-CHAIN + DS4** — "vét cạn nguồn trước khi hỏi": khi §4.5.4 thiếu, quét lần lượt PRD/BDD/design-spec/core-entities/mock adapter (skip-if-answered) rồi **gộp mọi gap vào một checkpoint** thay vì hỏi live từng câu. DS4 là cổng đối xứng với DS3 của BE cho nhánh FE wire API thật (integration/fe_full).
+- **DS5 — FE reuse gate** ("discover & reuse trước khi dựng mới"): ở nhánh wire API thật, nếu **không có mock adapter** (chạy `--phase=integration` một mình trên app brownfield) nhưng **quét thấy component/service FE đang chạy** → **hỏi reuse/new** thay vì im lặng dựng adapter song song, mồ côi. Chọn *reuse* → EXTEND/wire vào code có sẵn.
 - **3 vòng self-review + build ≤3 retry** — hai lớp tự kiểm trước khi giao.
 
 ---