Initial commit

2025-11-30 08:53:00 +08:00
commit c961db41d7
20 changed files with 2110 additions and 0 deletions
--- a/commands/api-contract-define.md
+++ b/commands/api-contract-define.md
@@ -0,0 +1,129 @@
+# Define API Contract Between Backend and Frontend
+
+Feature: $ARGUMENTS
+
+## Task: Create detailed API contract specification for backend/frontend coordination
+
+1. **Define RESTful endpoints**:
+
+   ```yaml
+   Base URL: /api/v1/{feature}
+
+   Endpoints:
+   - GET /api/v1/{features}
+     Query params: page, size, sort, filter
+     Response: Page<{Feature}Response>
+
+   - GET /api/v1/{features}/{id}
+     Path param: id (Long)
+     Response: {Feature}Response
+
+   - POST /api/v1/{features}
+     Body: {Feature}Request
+     Response: {Feature}Response (201 Created)
+
+   - PUT /api/v1/{features}/{id}
+     Path param: id (Long)
+     Body: {Feature}Request
+     Response: {Feature}Response
+
+   - DELETE /api/v1/{features}/{id}
+     Path param: id (Long)
+     Response: 204 No Content
+   ```
+
+2. **Define request/response DTOs**:
+
+   ```typescript
+   // Request DTO (for POST/PUT)
+   interface {Feature}Request {
+     name: string;        // min: 2, max: 100
+     description?: string; // max: 1000
+     // Add domain-specific fields
+   }
+
+   // Response DTO (for GET)
+   interface {Feature}Response {
+     id: number;
+     name: string;
+     description?: string;
+     createdAt: string;   // ISO 8601
+     updatedAt: string;   // ISO 8601
+     // Add computed fields
+   }
+
+   // Page response wrapper
+   interface Page<T> {
+     content: T[];
+     totalElements: number;
+     totalPages: number;
+     size: number;
+     number: number;
+   }
+   ```
+
+3. **Define error responses**:
+
+   ```json
+   {
+     "timestamp": "2024-01-20T10:30:00Z",
+     "status": 400,
+     "error": "Bad Request",
+     "message": "Validation failed",
+     "path": "/api/v1/{features}",
+     "errors": [
+       {
+         "field": "name",
+         "message": "Name is required"
+       }
+     ]
+   }
+   ```
+
+4. **Define validation rules**:
+   - Backend: Bean Validation annotations
+   - Frontend: Matching Zod schemas
+
+   ```
+   name: required, 2-100 chars
+   description: optional, max 1000 chars
+   email: valid email format
+   date: ISO 8601 format
+   ```
+
+5. **Define status codes**:
+   - 200: OK (GET, PUT)
+   - 201: Created (POST)
+   - 204: No Content (DELETE)
+   - 400: Bad Request (validation)
+   - 404: Not Found
+   - 409: Conflict (duplicate)
+   - 500: Internal Server Error
+
+6. **Integration requirements**:
+   - CORS: Allow frontend origin
+   - Content-Type: application/json
+   - Authentication: Bearer token (if needed)
+   - Pagination: Spring Pageable format
+   - Sorting: field,direction (e.g., "name,asc")
+
+7. **Backend implementation notes**:
+
+   ```java
+   // Entity fields match response DTO
+   // Use MapStruct for DTO mapping
+   // Repository method naming conventions
+   // Service layer validation
+   ```
+
+8. **Frontend implementation notes**:
+   ```typescript
+   // Zod schemas match validation rules
+   // API client with base configuration
+   // TanStack Query hooks
+   // Error handling utilities
+   ```
+
+Save this contract as: `PRPs/working-memory/{feature-name}/contracts/{feature}-api-contract.md`
+
+Share this file between backend and frontend teams for alignment.