@edupia-tutor/spec-driven-docs 0.14.0

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

@@ -0,0 +1,302 @@
+# 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

@@ -0,0 +1,15 @@
+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

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

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

@@ -0,0 +1,66 @@
+# 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=<official .feature path>"
+  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.

package/modules/react/architecture-snippets/hooks-query-patterns.md

@@ -0,0 +1,254 @@
+# React — Hooks, React Query & Zustand Patterns
+
+## React Query — Query Hook
+
+```typescript
+// features/order/queries/order.queries.ts
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { orderApi } from '@/api/order.api';
+import type { CreateOrderPayload, Order } from '../types';
+
+// Query key factory — single source of truth for cache invalidation
+export const orderKeys = {
+  all: ['ORDERS'] as const,
+  lists: () => [...orderKeys.all, 'list'] as const,
+  list: (customerId: number) => [...orderKeys.lists(), { customerId }] as const,
+  detail: (id: number) => [...orderKeys.all, 'detail', id] as const,
+};
+
+// @trace.implements=ORD-UC1-SC1
+// @trace.source=specs/order/order-management/bdd/ORD-UC1.feature
+export function useOrderList(customerId: number) {
+  return useQuery({
+    queryKey: orderKeys.list(customerId),
+    queryFn: () => orderApi.getByCustomer(customerId),
+    staleTime: 30_000,
+  });
+}
+
+// @trace.implements=ORD-UC2-SC1
+// @trace.source=specs/order/order-management/bdd/ORD-UC2.feature
+export function useCreateOrder() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (payload: CreateOrderPayload) => orderApi.create(payload),
+    onSuccess: (_, variables) => {
+      // Invalidate order list for this customer
+      queryClient.invalidateQueries({ queryKey: orderKeys.list(variables.customerId) });
+    },
+  });
+}
+```
+
+## API Client (Axios)
+
+```typescript
+// api/order.api.ts
+import { apiClient } from '@/api/client';
+import type { CreateOrderPayload, Order, PaginatedResponse } from '@/features/order/types';
+
+export const orderApi = {
+  getByCustomer: (customerId: number) =>
+    apiClient.get<PaginatedResponse<Order>>('/v1/orders', { params: { customerId } })
+      .then(res => res.data),
+
+  getById: (id: number) =>
+    apiClient.get<Order>(`/v1/orders/${id}`).then(res => res.data),
+
+  create: (payload: CreateOrderPayload) =>
+    apiClient.post<Order>('/v1/orders', payload).then(res => res.data),
+
+  cancel: (id: number) =>
+    apiClient.patch<void>(`/v1/orders/${id}/cancel`).then(res => res.data),
+};
+```
+
+```typescript
+// api/client.ts — Axios instance with auth interceptor
+import axios from 'axios';
+
+export const apiClient = axios.create({
+  baseURL: import.meta.env.VITE_API_URL,
+  headers: { 'Content-Type': 'application/json' },
+});
+
+apiClient.interceptors.request.use(config => {
+  const token = localStorage.getItem('access_token');
+  if (token) config.headers.Authorization = `Bearer ${token}`;
+  return config;
+});
+
+apiClient.interceptors.response.use(
+  res => res,
+  error => {
+    if (error.response?.status === 401) {
+      // redirect to login
+      window.location.href = '/login';
+    }
+    return Promise.reject(error);
+  }
+);
+```
+
+## Zustand Store (Client State)
+
+```typescript
+// features/cart/store/cart.store.ts
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+import type { CartItem } from '../types';
+
+interface CartStore {
+  items: CartItem[];
+  addItem: (item: CartItem) => void;
+  removeItem: (productId: number) => void;
+  clearCart: () => void;
+  total: () => number;
+}
+
+export const useCartStore = create<CartStore>()(
+  persist(
+    (set, get) => ({
+      items: [],
+
+      addItem: (item) =>
+        set(state => {
+          const existing = state.items.find(i => i.productId === item.productId);
+          if (existing) {
+            return {
+              items: state.items.map(i =>
+                i.productId === item.productId
+                  ? { ...i, quantity: i.quantity + item.quantity }
+                  : i
+              ),
+            };
+          }
+          return { items: [...state.items, item] };
+        }),
+
+      removeItem: (productId) =>
+        set(state => ({ items: state.items.filter(i => i.productId !== productId) })),
+
+      clearCart: () => set({ items: [] }),
+
+      total: () => get().items.reduce((sum, i) => sum + i.price * i.quantity, 0),
+    }),
+    { name: 'cart-storage' }
+  )
+);
+```
+
+## Feature Component (Container)
+
+```tsx
+// features/order/components/OrderListPage.tsx
+// @trace.implements=ORD-UC1-SC1
+// @trace.source=specs/order/order-management/bdd/ORD-UC1.feature
+import { useAuth } from '@/hooks/useAuth';
+import { useOrderList } from '../queries/order.queries';
+import { OrderCard } from './OrderCard';
+
+export function OrderListPage() {
+  const { user } = useAuth();
+  const { data: orders, isLoading, isError } = useOrderList(user.id);
+
+  if (isLoading) return <div>Loading...</div>;
+  if (isError)   return <div>Failed to load orders.</div>;
+
+  return (
+    <div className="order-list">
+      {orders?.map(order => (
+        <OrderCard key={order.id} order={order} />
+      ))}
+      {orders?.length === 0 && <p>No orders yet.</p>}
+    </div>
+  );
+}
+```
+
+## React Hook Form + Zod
+
+```tsx
+// features/order/components/CreateOrderForm.tsx
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { useCreateOrder } from '../queries/order.queries';
+
+const createOrderSchema = z.object({
+  customerId: z.number().positive(),
+  items: z.array(z.object({
+    productId: z.number().positive(),
+    quantity: z.number().int().min(1),
+  })).min(1, 'At least one item required'),
+});
+
+type CreateOrderForm = z.infer<typeof createOrderSchema>;
+
+export function CreateOrderForm({ customerId }: { customerId: number }) {
+  const { mutate: createOrder, isPending } = useCreateOrder();
+
+  const { register, handleSubmit, formState: { errors } } = useForm<CreateOrderForm>({
+    resolver: zodResolver(createOrderSchema),
+    defaultValues: { customerId, items: [] },
+  });
+
+  const onSubmit = (data: CreateOrderForm) => createOrder(data);
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      {/* form fields */}
+      {errors.items && <p className="error">{errors.items.message}</p>}
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Creating...' : 'Create Order'}
+      </button>
+    </form>
+  );
+}
+```
+
+## Test with React Testing Library + MSW
+
+```tsx
+// features/order/__tests__/OrderListPage.test.tsx
+// @trace.verifies=ORD-UC1
+// @trace.test_type=integration
+import { render, screen, waitFor } from '@testing-library/react';
+import { http, HttpResponse } from 'msw';
+import { server } from '@/test/server';
+import { renderWithProviders } from '@/test/utils';
+import { OrderListPage } from '../components/OrderListPage';
+
+describe('OrderListPage', () => {
+  it('displays orders after successful fetch', async () => {
+    server.use(
+      http.get('/v1/orders', () =>
+        HttpResponse.json([
+          { id: 1, status: 'pending', customerId: 42, items: [] },
+        ])
+      )
+    );
+
+    renderWithProviders(<OrderListPage />, { user: { id: 42 } });
+
+    expect(screen.getByText('Loading...')).toBeInTheDocument();
+
+    await waitFor(() =>
+      expect(screen.queryByText('Loading...')).not.toBeInTheDocument()
+    );
+
+    expect(screen.getByText('Order #1')).toBeInTheDocument();
+  });
+
+  it('shows empty state when no orders exist', async () => {
+    server.use(http.get('/v1/orders', () => HttpResponse.json([])));
+
+    renderWithProviders(<OrderListPage />, { user: { id: 42 } });
+
+    await waitFor(() =>
+      expect(screen.getByText('No orders yet.')).toBeInTheDocument()
+    );
+  });
+});
+```