@educa-corp/sdd-framework 0.5.0 → 0.7.0

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

@@ -1,90 +0,0 @@
-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/{platform}/{UC-ID}-{slug}.feature"
-  verifies: "// @trace.verifies={UC-ID}"
-  test_type: "// @trace.test_type=unit|integration"

package/modules/php-laravel/architecture-snippets/service-repository.md

@@ -1,302 +0,0 @@
-# PHP Laravel — Service-Repository Architecture Patterns
-
-## Form Request (Validation Layer)
-
-```php
-<?php
-// app/Http/Requests/Order/CreateOrderRequest.php
-
-namespace App\Http\Requests\Order;
-
-use Illuminate\Foundation\Http\FormRequest;
-
-class CreateOrderRequest extends FormRequest
-{
-    public function authorize(): bool
-    {
-        return true; // auth handled by middleware
-    }
-
-    public function rules(): array
-    {
-        return [
-            'customer_id'     => ['required', 'integer', 'exists:customers,id'],
-            'items'           => ['required', 'array', 'min:1'],
-            'items.*.product_id' => ['required', 'integer', 'exists:products,id'],
-            'items.*.quantity'   => ['required', 'integer', 'min:1'],
-        ];
-    }
-
-    public function messages(): array
-    {
-        return [
-            'items.required' => 'At least one order item is required.',
-        ];
-    }
-}
-```
-
-## Repository Interface + Eloquent Implementation
-
-```php
-<?php
-// app/Repositories/OrderRepositoryInterface.php
-
-namespace App\Repositories;
-
-use App\Models\Order;
-use Illuminate\Contracts\Pagination\LengthAwarePaginator;
-
-interface OrderRepositoryInterface
-{
-    public function findById(int $id): ?Order;
-    public function findByCustomer(int $customerId, int $perPage = 15): LengthAwarePaginator;
-    public function create(array $data): Order;
-    public function updateStatus(int $id, string $status): bool;
-}
-```
-
-```php
-<?php
-// app/Repositories/Eloquent/OrderRepository.php
-
-namespace App\Repositories\Eloquent;
-
-use App\Models\Order;
-use App\Repositories\OrderRepositoryInterface;
-use Illuminate\Contracts\Pagination\LengthAwarePaginator;
-
-class OrderRepository implements OrderRepositoryInterface
-{
-    public function findById(int $id): ?Order
-    {
-        return Order::with(['items.product', 'customer'])->find($id);
-    }
-
-    public function findByCustomer(int $customerId, int $perPage = 15): LengthAwarePaginator
-    {
-        return Order::where('customer_id', $customerId)
-            ->with('items')
-            ->latest()
-            ->paginate($perPage);
-    }
-
-    public function create(array $data): Order
-    {
-        return Order::create($data);
-    }
-
-    public function updateStatus(int $id, string $status): bool
-    {
-        return Order::where('id', $id)->update(['status' => $status]) > 0;
-    }
-}
-```
-
-## Service Layer
-
-```php
-<?php
-// app/Services/Order/OrderService.php
-
-namespace App\Services\Order;
-
-use App\Exceptions\BusinessException;
-use App\Models\Order;
-use App\Repositories\OrderRepositoryInterface;
-use Illuminate\Support\Facades\DB;
-
-class OrderService
-{
-    // @trace.implements=ORD-UC1-SC1
-    // @trace.source=specs/order/order-management/bdd/ORD-UC1.feature
-    public function __construct(
-        private readonly OrderRepositoryInterface $orderRepository
-    ) {}
-
-    public function createOrder(int $customerId, array $items): Order
-    {
-        return DB::transaction(function () use ($customerId, $items) {
-            $order = $this->orderRepository->create([
-                'customer_id' => $customerId,
-                'status'      => 'pending',
-            ]);
-
-            foreach ($items as $item) {
-                $order->items()->create([
-                    'product_id' => $item['product_id'],
-                    'quantity'   => $item['quantity'],
-                ]);
-            }
-
-            return $order->load('items.product');
-        });
-    }
-
-    public function cancelOrder(int $orderId): void
-    {
-        $order = $this->orderRepository->findById($orderId);
-
-        if (!$order) {
-            throw new BusinessException("Order #{$orderId} not found.", 404);
-        }
-
-        if ($order->status !== 'pending') {
-            throw new BusinessException("Only pending orders can be cancelled.", 422);
-        }
-
-        $this->orderRepository->updateStatus($orderId, 'cancelled');
-    }
-}
-```
-
-## Resource Controller
-
-```php
-<?php
-// app/Http/Controllers/Order/OrderController.php
-
-namespace App\Http\Controllers\Order;
-
-use App\Http\Controllers\Controller;
-use App\Http\Requests\Order\CreateOrderRequest;
-use App\Http\Resources\Order\OrderResource;
-use App\Services\Order\OrderService;
-use Illuminate\Http\JsonResponse;
-use Illuminate\Http\Request;
-
-class OrderController extends Controller
-{
-    public function __construct(
-        private readonly OrderService $orderService
-    ) {}
-
-    // @trace.implements=ORD-UC1-SC1
-    // @trace.source=specs/order/order-management/bdd/ORD-UC1.feature
-    public function store(CreateOrderRequest $request): JsonResponse
-    {
-        $order = $this->orderService->createOrder(
-            customerId: $request->validated('customer_id'),
-            items: $request->validated('items')
-        );
-
-        return response()->json([
-            'status'  => 'success',
-            'message' => 'Order created successfully.',
-            'data'    => new OrderResource($order),
-        ], 201);
-    }
-
-    // @trace.implements=ORD-UC2-SC1
-    // @trace.source=specs/order/order-management/bdd/ORD-UC2.feature
-    public function destroy(int $id): JsonResponse
-    {
-        $this->orderService->cancelOrder($id);
-
-        return response()->json([
-            'status'  => 'success',
-            'message' => 'Order cancelled.',
-        ]);
-    }
-}
-```
-
-## API Resource (Response Transformer)
-
-```php
-<?php
-// app/Http/Resources/Order/OrderResource.php
-
-namespace App\Http\Resources\Order;
-
-use Illuminate\Http\Request;
-use Illuminate\Http\Resources\Json\JsonResource;
-
-class OrderResource extends JsonResource
-{
-    public function toArray(Request $request): array
-    {
-        return [
-            'id'          => $this->id,
-            'status'      => $this->status,
-            'customer_id' => $this->customer_id,
-            'items'       => OrderItemResource::collection($this->whenLoaded('items')),
-            'created_at'  => $this->created_at->toISOString(),
-        ];
-    }
-}
-```
-
-## Feature Test (HTTP Layer)
-
-```php
-<?php
-// tests/Feature/Order/CreateOrderTest.php
-
-namespace Tests\Feature\Order;
-
-use App\Models\Customer;
-use App\Models\Product;
-use Illuminate\Foundation\Testing\RefreshDatabase;
-use Tests\TestCase;
-
-// @trace.verifies=ORD-UC1
-// @trace.test_type=feature
-class CreateOrderTest extends TestCase
-{
-    use RefreshDatabase;
-
-    /** @test */
-    public function it_creates_order_successfully(): void
-    {
-        $customer = Customer::factory()->create();
-        $product  = Product::factory()->create(['stock' => 10]);
-
-        $response = $this->actingAs($customer)
-            ->postJson('/api/v1/orders', [
-                'customer_id' => $customer->id,
-                'items' => [
-                    ['product_id' => $product->id, 'quantity' => 2],
-                ],
-            ]);
-
-        $response->assertStatus(201)
-            ->assertJsonStructure(['status', 'data' => ['id', 'status', 'items']]);
-
-        $this->assertDatabaseHas('orders', ['customer_id' => $customer->id, 'status' => 'pending']);
-    }
-
-    /** @test */
-    public function it_returns_422_when_items_are_empty(): void
-    {
-        $customer = Customer::factory()->create();
-
-        $response = $this->actingAs($customer)
-            ->postJson('/api/v1/orders', ['customer_id' => $customer->id, 'items' => []]);
-
-        $response->assertStatus(422)
-            ->assertJsonValidationErrors(['items']);
-    }
-}
-```
-
-## Service Provider Binding
-
-```php
-<?php
-// app/Providers/RepositoryServiceProvider.php
-
-namespace App\Providers;
-
-use App\Repositories\Eloquent\OrderRepository;
-use App\Repositories\OrderRepositoryInterface;
-use Illuminate\Support\ServiceProvider;
-
-class RepositoryServiceProvider extends ServiceProvider
-{
-    public function register(): void
-    {
-        $this->app->bind(OrderRepositoryInterface::class, OrderRepository::class);
-    }
-}
-```

package/modules/php-laravel/module.yaml

@@ -1,15 +0,0 @@
-name: "PHP Laravel"
-version: "1.0.0"
-description: "Laravel 11 backend with service-repository pattern"
-language: "PHP"
-framework: "Laravel"
-stack_type: "backend"
-default_layer_order:
-  - Form Request (validation)
-  - Model / Eloquent
-  - Repository interface
-  - Repository impl
-  - Service
-  - Controller (Resource Controller)
-  - Resource (API response transformer)
-test_framework: "PHPUnit + Pest"

package/modules/php-laravel/stack-profile.yaml

@@ -1,56 +0,0 @@
-build:
-  compile: "composer install"
-  test: "php artisan test"
-  run: "php artisan serve"
-  migrate: "php artisan migrate"
-  seed: "php artisan db:seed"
-
-architecture:
-  style: "Service-Repository (Controller → Service → Repository → Model)"
-  key_rules:
-    - "Controllers must not contain business logic — delegate to Services"
-    - "Services own business logic and transaction boundaries"
-    - "Repositories abstract all Eloquent/DB queries"
-    - "Form Requests handle all input validation (never validate in controller)"
-    - "API Resources transform Model output (never return raw Model/array)"
-    - "Use dependency injection via constructor, not Facades in classes"
-
-coding_standards:
-  naming:
-    controllers: "PascalCase + Controller suffix — Resource style (e.g., OrderController)"
-    services: "PascalCase + Service suffix (e.g., OrderService)"
-    repositories:
-      interface: "PascalCase + RepositoryInterface (e.g., OrderRepositoryInterface)"
-      impl: "PascalCase + Repository (e.g., EloquentOrderRepository)"
-    models: "PascalCase singular (e.g., Order)"
-    form_requests: "PascalCase + Request suffix (e.g., CreateOrderRequest)"
-    resources: "PascalCase + Resource suffix (e.g., OrderResource)"
-    files:
-      controller: "app/Http/Controllers/{Domain}/{Name}Controller.php"
-      service: "app/Services/{Domain}/{Name}Service.php"
-      repository_interface: "app/Repositories/{Name}RepositoryInterface.php"
-      repository_impl: "app/Repositories/Eloquent/{Name}Repository.php"
-      model: "app/Models/{Name}.php"
-      form_request: "app/Http/Requests/{Domain}/{Action}{Name}Request.php"
-      resource: "app/Http/Resources/{Domain}/{Name}Resource.php"
-  patterns:
-    response_wrapper: "JsonResponse with status/data/message structure"
-    pagination: "Laravel paginate() — returns LengthAwarePaginator"
-    exception_base: "App\\Exceptions\\BusinessException"
-    transactions: "DB::transaction(fn () => ...) in Service layer"
-    events: "Laravel Events + Listeners for domain events"
-
-testing:
-  unit: "PHPUnit or Pest"
-  feature: "Laravel Feature Tests (HTTP layer with database)"
-  patterns:
-    - "Use RefreshDatabase or DatabaseTransactions trait"
-    - "Fake external services with Http::fake() or mock()"
-    - "Use actingAs(\$user) for auth context"
-    - "Assert JSON structure with assertJson() / assertJsonStructure()"
-
-trace_tags:
-  implements: "// @trace.implements={UC-ID}-SC{N}"
-  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
-  verifies: "// @trace.verifies={UC-ID}"
-  test_type: "// @trace.test_type=unit|feature"

package/modules/qc-playwright/stack-profile.yaml

@@ -1,66 +0,0 @@
-# QC automation module — Python + pytest-playwright + Page Object
-# Used by the /qc-* commands (the official QC automation pipeline ported from the QC team).
-# This is the QC test-authoring/execution stack, independent of the dev implementation
-# module (java-spring, react, flutter, …). Selected via tech_stack.qc_module or per /qc-* run.
-
-build:
-  test: "python3 -m pytest"
-  e2e: "python3 -m pytest -m e2e"
-  report: "python3 -m pytest --html=reports/<feature>/report.html --self-contained-html"
-  show_trace: "python3 -m playwright show-trace <test-results/<nodeid>/trace.zip>"
-
-architecture:
-  style: "Page Object Model over pytest-playwright — Markdown test-case first, Python second"
-  key_rules:
-    - "Markdown-first: never generate Python until a reviewed .Test.md exists for the feature"
-    - "No Allure, no hand-written dashboard, no record_video — use Playwright Trace + pytest-html"
-    - "No hard-coded URL/credential/timeout — read from Env.* and CONFIG[...]"
-    - "No time.sleep() — use Playwright auto-wait / expect()"
-    - "Each test independent via pytest-playwright fixtures (page / logged_in_page / …)"
-    - "Page Object extends slim BasePage; split 3 layers: locators _x(), actions verb_noun(), assertions assert_x() using expect()"
-    - "Locator priority: data-testid → role → label/text → CSS → avoid XPath"
-    - "test-id values come from the FE tech-design §2b Test Selectors contract ({UC-ID}-tech-design-{platform}.md) — prefer them (no runtime scan); fall back to role/text only when an actionable element has no test-id there, and note the gap"
-    - "Group tests by (role, account) so login/logout never interleaves across roles"
-    - "Cover 100% of TCs in the .Test.md — every TC ends Pass/Fail/Skip, none left Draft"
-  folder_structure: |
-    {paths.qc_dir}/{UC-ID}/test-cases/   ← test-case Markdown (.Test.md) — source of truth (mặc định docs/, lộ ra ngoài)
-    pages/                         ← Page Object Model
-    │   ├── base_page.py           ← slim BasePage (click/fill/wait/screenshot)
-    │   └── <feature>_page.py
-    tests/                         ← pytest scripts, 1-1 with test-cases/
-    │   ├── conftest.py            ← fixtures: browser, page, logged_in_page, tracing
-    │   └── <project>/test_<feature>.py
-    utils/                         ← config_loader, logger, steps, test_ordering, report helpers
-    test_data/                     ← JSON datasets
-    config/config.yaml             ← browser, timeout, video/screenshot/trace toggles
-    reports/  test-results/        ← generated (gitignored): html report, trace.zip, screenshots
-
-coding_standards:
-  naming:
-    test_case_id: "TC_<FEATURE>_<NNN>"
-    test_class: "TestFeatureHappyCase"
-    test_function: "test_TC<NNN>_<snake_case>"
-    page_object: "<feature>_page.py with <Feature>Page class extending BasePage"
-    files:
-      test_case_md: "{paths.qc_dir}/{UC-ID}/test-cases/TC_<FEATURE>.Test.md"
-      page_object: "pages/<feature>_page.py"
-      test_script: "tests/<project>/test_<feature>.py"
-  patterns:
-    steps: "wrap steps with `with step(\"…\")` (from utils.steps import step)"
-    assertions: "Playwright expect() — never bare assert on dynamic UI"
-    fixtures: "auth fixtures register via register_auth_fixtures([...]) in project conftest"
-    fail_triage: "classify each FAIL as script-bug (fix selector/logic) vs product-gap (keep FAIL + evidence, never fake-pass)"
-
-testing:
-  layers: "functional (gui-screen / gui-feature / api), integration (api/db/gui/kafka), e2e (journey), non-functional, exploratory"
-  runner: "pytest-playwright; trace via context.tracing.start in conftest"
-  report: "pytest-html (--html ... --self-contained-html) + Playwright Trace viewer"
-
-trace_tags:
-  # QC tests map back to the framework's scenarios — drives qc_status in the trace TSV.
-  verifies: "# @trace.verifies={UC-ID}-SC{N}"
-  source: "# @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
-  test_type: "# @trace.test_type=functional|integration|e2e|non-functional"
-
-# qc_status: /qc-run-test writes pass|fail|skip|not_run + qc_run_at into {trace_dir}/{UC-ID}.tsv
-# (parallel to dev_selftest), surfaced in Living Docs as the OFFICIAL QC automation result.