@educa-corp/sdd-framework 0.5.0 → 0.7.0

package/modules/java-spring/architecture-snippets/layered-arch.md

@@ -1,201 +0,0 @@
-# Java Spring Boot — Layered Architecture Code Patterns
-
-## Controller Pattern
-
-```java
-@RestController
-@RequestMapping("/v1/orders")
-@RequiredArgsConstructor
-// @trace.implements=ORDER-UC1-SC1
-// @trace.source=specs/order/order-management/bdd/ORDER-UC1-create-order.feature
-public class OrderController {
-
-    private final OrderFacade orderFacade;
-
-    @PostMapping
-    public ResponseEntity<ApiResponse<OrderResponse>> createOrder(
-            @Valid @RequestBody CreateOrderRequest request) {
-        OrderResponse result = orderFacade.createOrder(request);
-        return ResponseEntity.status(HttpStatus.CREATED)
-                .body(ApiResponse.success(result));
-    }
-
-    @GetMapping("/{id}")
-    // @trace.implements=ORDER-UC1-SC2
-    public ResponseEntity<ApiResponse<OrderResponse>> getOrder(@PathVariable Long id) {
-        OrderResponse result = orderFacade.getOrder(id);
-        return ResponseEntity.ok(ApiResponse.success(result));
-    }
-}
-```
-
-## Service Interface Pattern
-
-```java
-public interface OrderService {
-    OrderResponse createOrder(CreateOrderRequest request);
-    OrderResponse getOrderById(Long id);
-    void cancelOrder(Long id);
-}
-```
-
-## Service Implementation Pattern
-
-```java
-@Service
-@RequiredArgsConstructor
-@Transactional(readOnly = true)
-public class OrderServiceImpl implements OrderService {
-
-    private final OrderRepository orderRepository;
-    private final OrderMapper orderMapper;
-
-    @Override
-    @Transactional
-    public OrderResponse createOrder(CreateOrderRequest request) {
-        Order order = orderMapper.toEntity(request);
-        order.setStatus(OrderStatus.PENDING);
-        Order saved = orderRepository.save(order);
-        return orderMapper.toResponse(saved);
-    }
-
-    @Override
-    public OrderResponse getOrderById(Long id) {
-        Order order = orderRepository.findById(id)
-                .orElseThrow(() -> new ResourceNotFoundException("Order", id));
-        return orderMapper.toResponse(order);
-    }
-
-    @Override
-    @Transactional
-    public void cancelOrder(Long id) {
-        Order order = orderRepository.findById(id)
-                .orElseThrow(() -> new ResourceNotFoundException("Order", id));
-        order.setStatus(OrderStatus.CANCELLED);
-    }
-}
-```
-
-## Repository Interface Pattern
-
-```java
-@Repository
-public interface OrderRepository extends JpaRepository<Order, Long> {
-
-    List<Order> findByCustomerIdAndStatus(Long customerId, OrderStatus status);
-
-    @Query("SELECT o FROM Order o JOIN FETCH o.items WHERE o.id = :id")
-    Optional<Order> findByIdWithItems(@Param("id") Long id);
-
-    Page<Order> findByCreatedAtBetween(
-            LocalDateTime from, LocalDateTime to, Pageable pageable);
-}
-```
-
-## DTO Pattern
-
-```java
-// Request DTO
-@Data
-@NoArgsConstructor
-@AllArgsConstructor
-public class CreateOrderRequest {
-    @NotNull(message = "customerId is required")
-    private Long customerId;
-
-    @NotEmpty(message = "items must not be empty")
-    private List<OrderItemRequest> items;
-
-    @NotBlank(message = "shippingAddress is required")
-    private String shippingAddress;
-}
-
-// Response DTO
-@Data
-@Builder
-@NoArgsConstructor
-@AllArgsConstructor
-public class OrderResponse {
-    private Long id;
-    private Long customerId;
-    private OrderStatus status;
-    private List<OrderItemResponse> items;
-    private BigDecimal totalAmount;
-    private LocalDateTime createdAt;
-}
-```
-
-## MapStruct Mapper Pattern
-
-```java
-@Mapper(componentModel = "spring", unmappedTargetPolicy = ReportingPolicy.ERROR)
-public interface OrderMapper {
-
-    @Mapping(target = "id", ignore = true)
-    @Mapping(target = "status", ignore = true)
-    @Mapping(target = "createdAt", ignore = true)
-    Order toEntity(CreateOrderRequest request);
-
-    OrderResponse toResponse(Order order);
-
-    List<OrderResponse> toResponseList(List<Order> orders);
-}
-```
-
-## ApiResponse Wrapper Pattern
-
-```java
-@Data
-@Builder
-@NoArgsConstructor
-@AllArgsConstructor
-public class ApiResponse<T> {
-    private boolean success;
-    private T data;
-    private String message;
-    private String errorCode;
-    private LocalDateTime timestamp;
-
-    public static <T> ApiResponse<T> success(T data) {
-        return ApiResponse.<T>builder()
-                .success(true)
-                .data(data)
-                .timestamp(LocalDateTime.now())
-                .build();
-    }
-
-    public static <T> ApiResponse<T> error(String errorCode, String message) {
-        return ApiResponse.<T>builder()
-                .success(false)
-                .errorCode(errorCode)
-                .message(message)
-                .timestamp(LocalDateTime.now())
-                .build();
-    }
-}
-```
-
-## Facade Pattern (optional orchestration layer)
-
-```java
-@Service
-@RequiredArgsConstructor
-public class OrderFacade {
-
-    private final OrderService orderService;
-    private final InventoryService inventoryService;
-    private final NotificationService notificationService;
-
-    public OrderResponse createOrder(CreateOrderRequest request) {
-        // 1. Validate inventory
-        inventoryService.validateAvailability(request.getItems());
-        // 2. Create order
-        OrderResponse order = orderService.createOrder(request);
-        // 3. Reserve inventory
-        inventoryService.reserveItems(order.getId(), request.getItems());
-        // 4. Send confirmation
-        notificationService.sendOrderConfirmation(order);
-        return order;
-    }
-}
-```

package/modules/java-spring/module.yaml

@@ -1,15 +0,0 @@
-name: "Java Spring Boot"
-version: "1.0.0"
-description: "Spring Boot 3.x with layered architecture"
-language: "Java"
-framework: "Spring Boot"
-stack_type: "backend"
-default_layer_order:
-  - DTO
-  - Entity/Model
-  - Repository
-  - Service interface
-  - Service impl
-  - Facade (optional)
-  - Controller
-test_framework: "JUnit 5 + Mockito"

package/modules/java-spring/stack-profile.yaml

@@ -1,28 +0,0 @@
-build:
-  compile: "mvn clean install -DskipTests"
-  test: "mvn test"
-  run: "mvn spring-boot:run"
-
-architecture:
-  style: "Layered (Controller → Facade → Service → Repository)"
-  key_rules:
-    - "Controllers must not contain business logic"
-    - "Services own transaction boundaries (@Transactional)"
-    - "Repositories use Spring Data JPA"
-    - "Facades orchestrate multiple services (optional layer)"
-
-coding_standards:
-  naming:
-    classes: "PascalCase"
-    methods: "camelCase"
-    packages: "lowercase.snake_case"
-  patterns:
-    response_wrapper: "ApiResponse<T>"
-    mapping: "MapStruct"
-    exception_base: "ResourceNotFoundException"
-
-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/nextjs/architecture-snippets/app-router-patterns.md

@@ -1,269 +0,0 @@
-# Next.js App Router — Server Components, Server Actions & DAL Patterns
-
-## Data Access Layer (server-only)
-
-```typescript
-// lib/dal/orders.dal.ts
-// @trace.source=specs/order/order-management/bdd/ORD-UC1.feature
-import 'server-only'; // prevents accidental import on client
-import { db } from '@/lib/db';
-import type { Order } from '@/types/order';
-
-export async function getOrderById(id: number): Promise<Order | null> {
-  return db.order.findUnique({
-    where: { id },
-    include: { items: { include: { product: true } }, customer: true },
-  });
-}
-
-export async function listOrdersByCustomer(customerId: number): Promise<Order[]> {
-  return db.order.findMany({
-    where: { customerId },
-    include: { items: true },
-    orderBy: { createdAt: 'desc' },
-  });
-}
-```
-
-## Server Component (Data Fetching + Layout)
-
-```tsx
-// app/(dashboard)/orders/page.tsx
-// @trace.implements=ORD-UC1-SC1
-// @trace.source=specs/order/order-management/bdd/ORD-UC1.feature
-import { listOrdersByCustomer } from '@/lib/dal/orders.dal';
-import { getCurrentUser } from '@/lib/auth';
-import { OrderCard } from './_components/OrderCard';
-import { EmptyState } from '@/components/ui/EmptyState';
-
-export default async function OrdersPage() {
-  const user = await getCurrentUser();
-  const orders = await listOrdersByCustomer(user.id);
-
-  return (
-    <section>
-      <h1>My Orders</h1>
-      {orders.length === 0 ? (
-        <EmptyState message="No orders yet." />
-      ) : (
-        <ul>
-          {orders.map(order => (
-            <OrderCard key={order.id} order={order} />
-          ))}
-        </ul>
-      )}
-    </section>
-  );
-}
-```
-
-## Zod Schema (shared server + client)
-
-```typescript
-// lib/validations/order.schema.ts
-import { z } from 'zod';
-
-export const createOrderSchema = z.object({
-  customerId: z.number().positive(),
-  items: z.array(z.object({
-    productId: z.number().positive(),
-    quantity: z.number().int().min(1, 'Quantity must be at least 1'),
-  })).min(1, 'At least one item is required'),
-});
-
-export type CreateOrderInput = z.infer<typeof createOrderSchema>;
-```
-
-## Server Action (Mutation)
-
-```typescript
-// lib/actions/order.actions.ts
-'use server';
-// @trace.implements=ORD-UC2-SC1
-// @trace.source=specs/order/order-management/bdd/ORD-UC2.feature
-
-import { revalidatePath } from 'next/cache';
-import { redirect } from 'next/navigation';
-import { createOrderSchema } from '@/lib/validations/order.schema';
-import { db } from '@/lib/db';
-import { getCurrentUser } from '@/lib/auth';
-
-// Returns { error } on failure, redirects on success
-export async function createOrder(formData: FormData) {
-  const user = await getCurrentUser();
-
-  const parsed = createOrderSchema.safeParse({
-    customerId: user.id,
-    items: JSON.parse(formData.get('items') as string),
-  });
-
-  if (!parsed.success) {
-    return { error: parsed.error.flatten().fieldErrors };
-  }
-
-  try {
-    await db.order.create({
-      data: {
-        customerId: parsed.data.customerId,
-        status: 'pending',
-        items: {
-          create: parsed.data.items.map(item => ({
-            productId: item.productId,
-            quantity: item.quantity,
-          })),
-        },
-      },
-    });
-  } catch {
-    return { error: { _form: ['Failed to create order. Please try again.'] } };
-  }
-
-  revalidatePath('/orders');
-  redirect('/orders');
-}
-
-export async function cancelOrder(orderId: number) {
-  const user = await getCurrentUser();
-
-  const order = await db.order.findFirst({
-    where: { id: orderId, customerId: user.id },
-  });
-
-  if (!order) return { error: 'Order not found.' };
-  if (order.status !== 'pending') return { error: 'Only pending orders can be cancelled.' };
-
-  await db.order.update({ where: { id: orderId }, data: { status: 'cancelled' } });
-
-  revalidatePath('/orders');
-  return { success: true };
-}
-```
-
-## Client Component (Interactive UI)
-
-```tsx
-// app/(dashboard)/orders/_components/CancelOrderButton.tsx
-'use client';
-// @trace.implements=ORD-UC3-SC1
-// @trace.source=specs/order/order-management/bdd/ORD-UC3.feature
-import { useTransition } from 'react';
-import { cancelOrder } from '@/lib/actions/order.actions';
-
-interface Props {
-  orderId: number;
-  disabled?: boolean;
-}
-
-export function CancelOrderButton({ orderId, disabled }: Props) {
-  const [isPending, startTransition] = useTransition();
-
-  const handleCancel = () => {
-    startTransition(async () => {
-      const result = await cancelOrder(orderId);
-      if (result?.error) {
-        alert(result.error); // replace with toast in real app
-      }
-    });
-  };
-
-  return (
-    <button
-      onClick={handleCancel}
-      disabled={disabled || isPending}
-      className="btn-danger"
-    >
-      {isPending ? 'Cancelling...' : 'Cancel Order'}
-    </button>
-  );
-}
-```
-
-## API Route (for webhooks / external consumers)
-
-```typescript
-// app/api/orders/webhook/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import { verifyWebhookSignature } from '@/lib/webhook';
-import { db } from '@/lib/db';
-
-export async function POST(request: NextRequest) {
-  const body = await request.json();
-
-  if (!verifyWebhookSignature(request, body)) {
-    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
-  }
-
-  if (body.event === 'payment.completed') {
-    await db.order.update({
-      where: { id: body.orderId },
-      data: { status: 'paid', paidAt: new Date() },
-    });
-  }
-
-  return NextResponse.json({ received: true });
-}
-```
-
-## Loading + Error Boundaries
-
-```tsx
-// app/(dashboard)/orders/loading.tsx
-export default function OrdersLoading() {
-  return (
-    <div className="order-skeleton">
-      {Array.from({ length: 3 }).map((_, i) => (
-        <div key={i} className="skeleton-card animate-pulse" />
-      ))}
-    </div>
-  );
-}
-```
-
-```tsx
-// app/(dashboard)/orders/error.tsx
-'use client';
-export default function OrdersError({ error, reset }: {
-  error: Error & { digest?: string };
-  reset: () => void;
-}) {
-  return (
-    <div className="error-state">
-      <p>Failed to load orders: {error.message}</p>
-      <button onClick={reset}>Try again</button>
-    </div>
-  );
-}
-```
-
-## Playwright E2E Test
-
-```typescript
-// e2e/orders/create-order.spec.ts
-// @trace.verifies=ORD-UC2
-// @trace.test_type=e2e
-import { test, expect } from '@playwright/test';
-import { loginAs } from '../fixtures/auth';
-
-test.describe('Create Order', () => {
-  test.use({ storageState: 'e2e/.auth/customer.json' }); // reuse auth state
-
-  test('customer creates an order successfully', async ({ page }) => {
-    await page.goto('/orders/new');
-
-    await page.getByLabel('Product').selectOption({ label: 'Wireless Headphones' });
-    await page.getByLabel('Quantity').fill('2');
-    await page.getByRole('button', { name: 'Add to Cart' }).click();
-    await page.getByRole('button', { name: 'Place Order' }).click();
-
-    await expect(page).toHaveURL(/\/orders\/\d+/);
-    await expect(page.getByText('Order placed successfully')).toBeVisible();
-  });
-
-  test('shows validation error when cart is empty', async ({ page }) => {
-    await page.goto('/orders/new');
-    await page.getByRole('button', { name: 'Place Order' }).click();
-
-    await expect(page.getByText('At least one item is required')).toBeVisible();
-  });
-});
-```

package/modules/nextjs/module.yaml

@@ -1,14 +0,0 @@
-name: "Next.js"
-version: "1.0.0"
-description: "Next.js 14+ App Router with Server Components, Server Actions, and React Query"
-language: "TypeScript"
-framework: "Next.js"
-stack_type: "fullstack"
-default_layer_order:
-  - Types / interfaces
-  - Server Actions (mutations)
-  - Data access layer (DAL) — server-side DB/API calls
-  - Server Components (data fetching + layout)
-  - Client Components (interactive UI)
-  - API Routes (for external consumers / webhooks)
-test_framework: "Vitest + React Testing Library + Playwright (E2E)"

package/modules/nextjs/stack-profile.yaml

@@ -1,74 +0,0 @@
-build:
-  compile: "npm run build"
-  test: "npm test"
-  run: "npm run dev"
-  lint: "npm run lint"
-  e2e: "npx playwright test"
-
-architecture:
-  style: "App Router — Server Components + Server Actions + Client Components"
-  key_rules:
-    - "Default to Server Components — only add 'use client' when interactivity is needed"
-    - "Data fetching happens in Server Components or Server Actions — never in useEffect"
-    - "Server Actions handle all mutations (form submits, data writes)"
-    - "Data Access Layer (DAL) abstracts all DB/external API calls — used only on server"
-    - "Client Components are 'leaf nodes' — keep them small and focused on interactivity"
-    - "API Routes (/api) used only for external consumers or webhooks, not for own UI"
-    - "Use Next.js cache() and unstable_cache for data memoization"
-  folder_structure: |
-    app/
-    ├── (auth)/               ← route group: auth pages
-    ├── (dashboard)/          ← route group: authenticated pages
-    │   └── orders/
-    │       ├── page.tsx      ← Server Component (list page)
-    │       ├── [id]/
-    │       │   └── page.tsx  ← Server Component (detail page)
-    │       └── _components/  ← feature-scoped Client Components
-    ├── api/                  ← API Routes (webhooks, external consumers)
-    └── layout.tsx
-    lib/
-    ├── dal/                  ← Data Access Layer (server-only DB/API calls)
-    │   └── orders.dal.ts
-    ├── actions/              ← Server Actions
-    │   └── order.actions.ts
-    └── validations/          ← Zod schemas (shared server+client)
-        └── order.schema.ts
-    components/
-    └── ui/                   ← shared primitive Client Components
-
-coding_standards:
-  naming:
-    server_components: "PascalCase, no suffix — co-locate in app/ route folder"
-    client_components: "PascalCase + 'use client' at top — in _components/ folders"
-    server_actions: "camelCase verb + noun (e.g., createOrder, cancelOrder) in lib/actions/"
-    dal_functions: "camelCase (e.g., getOrderById, listOrdersByCustomer) in lib/dal/"
-    files:
-      page: "app/{route}/page.tsx"
-      layout: "app/{route}/layout.tsx"
-      server_action: "lib/actions/{domain}.actions.ts"
-      dal: "lib/dal/{domain}.dal.ts"
-      schema: "lib/validations/{domain}.schema.ts"
-  patterns:
-    mutations: "Server Actions with useFormState / useTransition"
-    data_fetching: "Server Component async/await + fetch with revalidate options"
-    client_state: "Zustand or Context API (avoid for server-derived data)"
-    forms: "React Hook Form (client) OR native <form> with Server Actions"
-    error_handling: "error.tsx (route-level) + try/catch in Server Actions returning {error}"
-    loading: "loading.tsx (Suspense boundary) per route segment"
-    auth: "next-auth v5 (Auth.js) or middleware-based session check"
-
-testing:
-  unit: "Vitest + React Testing Library for Client Components"
-  integration: "Vitest + MSW for Server Actions"
-  e2e: "Playwright — full browser tests"
-  patterns:
-    - "Test Server Components by rendering with async render utilities"
-    - "Mock fetch/DB calls for Server Action tests"
-    - "Playwright tests cover full user flows (auth → action → result)"
-    - "Use @playwright/test fixtures for auth state reuse"
-
-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|e2e"

package/modules/nuxt/module.yaml

@@ -1,14 +0,0 @@
-name: "Nuxt"
-version: "1.0.0"
-description: "Nuxt 3 with SSR/SSG, Composition API, Pinia, and useFetch"
-language: "TypeScript"
-framework: "Nuxt 3"
-stack_type: "frontend"
-default_layer_order:
-  - Types / interfaces
-  - Server API routes (server/api/)
-  - Composables (useFetch / useAsyncData)
-  - State store (Pinia)
-  - UI components (presentational)
-  - Page components (pages/)
-test_framework: "Vitest + Vue Test Utils + @nuxt/test-utils"

package/modules/nuxt/stack-profile.yaml

@@ -1,58 +0,0 @@
-build:
-  compile: "npm run build"
-  test: "npm run test"
-  run: "npm run dev"
-  lint: "npm run lint"
-
-architecture:
-  style: "Pages + Composables + Server routes (SSR/SSG)"
-  key_rules:
-    - "Pages in pages/ are route-level containers — no business logic"
-    - "Business logic in composables/ using useAsyncData or useFetch"
-    - "Server-side logic in server/api/ routes (nitro)"
-    - "Client-only state in Pinia stores; server state via useAsyncData"
-    - "Shared UI primitives in components/ui/, auto-imported by Nuxt"
-    - "Use useRoute/useRouter instead of $route/$router in Composition API"
-    - "'use client' equivalent: wrap client-only code in onMounted or <ClientOnly>"
-  folder_structure: |
-    ├── components/
-    │   └── ui/           ← auto-imported UI primitives (BaseButton, BaseInput...)
-    ├── composables/      ← auto-imported composables (useOrderList...)
-    ├── pages/            ← file-based routing
-    ├── server/
-    │   └── api/          ← nitro server routes (GET /api/orders.ts)
-    ├── stores/           ← Pinia stores (auto-imported)
-    ├── plugins/          ← Nuxt plugins
-    └── utils/            ← auto-imported utilities
-
-coding_standards:
-  naming:
-    components: "PascalCase (auto-imported, e.g., OrderList, BaseButton)"
-    composables: "camelCase with 'use' prefix (auto-imported, e.g., useOrderList)"
-    stores: "camelCase + Store suffix via defineStore()"
-    server_routes: "method.path.ts (e.g., get.orders.ts or [id].get.ts)"
-    files:
-      component: "{Feature}.vue"
-      composable: "use{Feature}.ts"
-      store: "{feature}.store.ts"
-      server_route: "{resource}.get.ts / {resource}.post.ts"
-  patterns:
-    data_fetching: "useAsyncData() for SSR data, useFetch() for client fetches"
-    global_state: "Pinia stores"
-    forms: "VeeValidate + Zod"
-    api_client: "$fetch (ofetch) — built-in to Nuxt, SSR-compatible"
-    ssr_hydration: "useState() for shared SSR/client state to avoid hydration mismatch"
-
-testing:
-  unit: "Vitest + @nuxt/test-utils"
-  e2e: "Playwright via @nuxt/test-utils/e2e"
-  patterns:
-    - "Use mountSuspended() for components that need Nuxt context"
-    - "Use registerEndpoint() to mock server routes in tests"
-    - "Test pages with renderSuspended() from @nuxt/test-utils"
-
-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"