@tinkcarlos/skillora 0.2.0

package/.claude/skills/api-scaffolding/SKILL.md

@@ -0,0 +1,431 @@
+---
+name: api-scaffolding
+description: |
+  API scaffolding with contract-first design and multi-framework support.
+
+  Use when:
+  - Creating new API endpoints (REST/GraphQL/gRPC)
+  - Designing API architecture and service boundaries
+  - Setting up backend project structure
+  - Implementing authentication/authorization
+
+  Key Features:
+  - Contract-first: OpenAPI/GraphQL schema before code
+  - Multi-framework: FastAPI, Django, Express, NestJS
+  - Security-first: Auth patterns built-in
+  - Integration with fullstack-developer workflow
+allowed-tools: [read, write, execute, grep, glob, mcp__serena__find_symbol, mcp__serena__get_symbols_overview]
+---
+
+# API Scaffolding
+
+Contract-first, security-built-in, production-ready.
+
+## The Iron Law
+
+```
+NO CODE WITHOUT CONTRACT. NO ENDPOINT WITHOUT AUTH CHECK. NO RESPONSE WITHOUT VALIDATION.
+```
+
+---
+
+## Quick Start Decision Tree
+
+```
+API 需求
+    │
+    ▼
+┌─────────────────────────────────────────────────────────────┐
+│ Step 1: 选择 API 类型                                        │
+│ ─────────────────────────────────────────────────────────── │
+│ REST API → OpenAPI 3.1 contract                             │
+│ GraphQL → Schema-first design                               │
+│ gRPC → Protocol Buffers definition                          │
+│ WebSocket → Event schema definition                         │
+└─────────────────────────────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────────────────────────────────────┐
+│ Step 2: 选择框架                                             │
+│ ─────────────────────────────────────────────────────────── │
+│ Python: FastAPI (推荐) / Django REST                        │
+│ Node.js: NestJS (推荐) / Express                            │
+│ Go: Gin / Echo                                              │
+│ Java: Spring Boot                                           │
+└─────────────────────────────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────────────────────────────────────┐
+│ Step 3: 执行脚手架流程                                       │
+│ ─────────────────────────────────────────────────────────── │
+│ 1. 定义 Contract (OpenAPI/GraphQL Schema)                   │
+│ 2. 生成项目结构                                              │
+│ 3. 实现端点 + 验证                                           │
+│ 4. 添加认证/授权                                             │
+│ 5. 集成测试                                                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🔴 Contract-First Protocol (MANDATORY)
+
+### Step 1: 定义 API Contract
+
+**在写任何代码之前，必须先定义 contract:**
+
+```yaml
+# openapi.yaml
+openapi: 3.1.0
+info:
+  title: [API Name]
+  version: 1.0.0
+paths:
+  /api/v1/[resource]:
+    get:
+      summary: List [resources]
+      parameters:
+        - name: page
+          in: query
+          schema:
+            type: integer
+            default: 1
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/[Resource]List'
+```
+
+### Step 2: Contract 验证清单
+
+| 检查项 | 通过标准 |
+|--------|----------|
+| 资源命名 | 复数名词，kebab-case |
+| HTTP 方法 | GET/POST/PUT/PATCH/DELETE 语义正确 |
+| 状态码 | 200/201/204/400/401/403/404/500 覆盖 |
+| 分页 | 列表接口必须支持分页 |
+| 版本 | URL 或 Header 版本控制 |
+| 错误格式 | 统一错误响应结构 |
+
+---
+
+## 🔴 Project Structure Templates
+
+### FastAPI (Python)
+
+```
+project/
+├── app/
+│   ├── __init__.py
+│   ├── main.py              # FastAPI app entry
+│   ├── config.py            # Settings with Pydantic
+│   ├── api/
+│   │   ├── __init__.py
+│   │   ├── deps.py          # Dependencies (auth, db)
+│   │   └── v1/
+│   │       ├── __init__.py
+│   │       ├── router.py    # API router
+│   │       └── endpoints/
+│   │           └── [resource].py
+│   ├── models/              # SQLAlchemy models
+│   ├── schemas/             # Pydantic schemas
+│   ├── services/            # Business logic
+│   └── core/
+│       ├── security.py      # Auth utilities
+│       └── exceptions.py    # Custom exceptions
+├── tests/
+├── alembic/                 # Migrations
+├── requirements.txt
+└── docker-compose.yml
+```
+
+### NestJS (Node.js)
+
+```
+project/
+├── src/
+│   ├── main.ts
+│   ├── app.module.ts
+│   ├── common/
+│   │   ├── decorators/
+│   │   ├── filters/
+│   │   ├── guards/
+│   │   └── interceptors/
+│   └── modules/
+│       └── [resource]/
+│           ├── [resource].module.ts
+│           ├── [resource].controller.ts
+│           ├── [resource].service.ts
+│           ├── dto/
+│           └── entities/
+├── test/
+├── package.json
+└── docker-compose.yml
+```
+
+---
+
+## 🔴 Security Patterns (MANDATORY)
+
+### Authentication Flow
+
+| 场景 | 推荐方案 |
+|------|----------|
+| SPA + API | JWT + Refresh Token |
+| Server-rendered | Session + CSRF Token |
+| Mobile App | OAuth2 + PKCE |
+| Service-to-Service | mTLS / API Key |
+| Third-party | OAuth2 Authorization Code |
+
+### Authorization Checklist
+
+```python
+# 每个端点必须检查:
+# 1. 认证 (Authentication)
+@router.get("/users/{user_id}")
+async def get_user(
+    user_id: int,
+    current_user: User = Depends(get_current_user)  # ✅ 认证
+):
+    # 2. 授权 (Authorization)
+    if current_user.id != user_id and not current_user.is_admin:  # ✅ 授权
+        raise HTTPException(status_code=403, detail="Not authorized")
+
+    # 3. 输入验证 (已通过 Pydantic schema)
+    return await user_service.get(user_id)
+```
+
+### Security Headers
+
+```python
+# middleware/security.py
+SECURITY_HEADERS = {
+    "X-Content-Type-Options": "nosniff",
+    "X-Frame-Options": "DENY",
+    "X-XSS-Protection": "1; mode=block",
+    "Strict-Transport-Security": "max-age=31536000; includeSubDomains",
+    "Content-Security-Policy": "default-src 'self'"
+}
+```
+
+---
+
+## 🔴 Input Validation Protocol
+
+### Pydantic Schema 规范
+
+```python
+from pydantic import BaseModel, Field, validator
+
+class UserCreate(BaseModel):
+    username: str = Field(..., min_length=3, max_length=50, pattern=r'^[a-zA-Z0-9_]+$')
+    email: EmailStr
+    password: str = Field(..., min_length=8)
+
+    @validator('password')
+    def password_strength(cls, v):
+        if not any(c.isupper() for c in v):
+            raise ValueError('Password must contain uppercase')
+        if not any(c.isdigit() for c in v):
+            raise ValueError('Password must contain digit')
+        return v
+```
+
+### 验证清单
+
+| 检查项 | 实现方式 |
+|--------|----------|
+| 类型验证 | Pydantic/Zod schema |
+| 长度限制 | min_length/max_length |
+| 格式验证 | regex pattern |
+| 业务规则 | custom validator |
+| SQL 注入 | ORM 参数化查询 |
+| XSS | 输出编码 |
+
+---
+
+## 🔴 Error Handling Standard
+
+### 统一错误响应格式
+
+```python
+class ErrorResponse(BaseModel):
+    error: str           # 错误类型
+    message: str         # 用户友好消息
+    details: list = []   # 详细错误信息
+    request_id: str      # 请求追踪 ID
+
+# 示例响应
+{
+    "error": "validation_error",
+    "message": "Invalid input data",
+    "details": [
+        {"field": "email", "message": "Invalid email format"}
+    ],
+    "request_id": "req_abc123"
+}
+```
+
+### HTTP 状态码映射
+
+| 状态码 | 使用场景 |
+|--------|----------|
+| 200 | 成功 (GET/PUT/PATCH) |
+| 201 | 创建成功 (POST) |
+| 204 | 删除成功 (DELETE) |
+| 400 | 请求格式错误 |
+| 401 | 未认证 |
+| 403 | 无权限 |
+| 404 | 资源不存在 |
+| 409 | 资源冲突 |
+| 422 | 验证失败 |
+| 429 | 请求过多 |
+| 500 | 服务器错误 |
+
+---
+
+## 🔴 Database Integration
+
+### Repository Pattern
+
+```python
+# repositories/user_repository.py
+class UserRepository:
+    def __init__(self, db: AsyncSession):
+        self.db = db
+
+    async def get_by_id(self, user_id: int) -> User | None:
+        result = await self.db.execute(
+            select(User).where(User.id == user_id)
+        )
+        return result.scalar_one_or_none()
+
+    async def create(self, user_data: UserCreate) -> User:
+        user = User(**user_data.model_dump())
+        self.db.add(user)
+        await self.db.commit()
+        await self.db.refresh(user)
+        return user
+```
+
+### Transaction Management
+
+```python
+# 事务边界在 Service 层
+async def transfer_funds(from_id: int, to_id: int, amount: Decimal):
+    async with db.begin():  # 事务开始
+        from_account = await account_repo.get(from_id)
+        to_account = await account_repo.get(to_id)
+
+        if from_account.balance < amount:
+            raise InsufficientFundsError()
+
+        from_account.balance -= amount
+        to_account.balance += amount
+        # 事务自动提交或回滚
+```
+
+---
+
+## 🔴 API Documentation
+
+### OpenAPI 自动生成
+
+```python
+# FastAPI 自动生成 OpenAPI
+app = FastAPI(
+    title="My API",
+    description="API description",
+    version="1.0.0",
+    docs_url="/docs",      # Swagger UI
+    redoc_url="/redoc",    # ReDoc
+    openapi_url="/openapi.json"
+)
+
+# 端点文档
+@router.post(
+    "/users",
+    response_model=UserResponse,
+    status_code=201,
+    summary="Create a new user",
+    description="Create a new user with the provided data",
+    responses={
+        201: {"description": "User created successfully"},
+        400: {"description": "Invalid input"},
+        409: {"description": "User already exists"}
+    }
+)
+async def create_user(user: UserCreate):
+    ...
+```
+
+---
+
+## Agent 路由
+
+| 任务类型 | 调用 Agent |
+|----------|------------|
+| 后端架构设计 | `agents/backend-architect.md` |
+| FastAPI 开发 | `agents/fastapi-pro.md` |
+| Django 开发 | `agents/django-pro.md` |
+| GraphQL 设计 | `agents/graphql-architect.md` |
+
+---
+
+## 与 fullstack-developer 集成
+
+### 调用时机
+
+```
+fullstack-developer Phase 4
+    │
+    ├── 需要 API 开发?
+    │       ↓
+    │   api-scaffolding
+    │       │
+    │       ├── 定义 Contract
+    │       ├── 生成项目结构
+    │       ├── 实现端点
+    │       └── 返回: API 代码 + 文档
+    │
+    └── 继续下一任务
+```
+
+### 输出要求
+
+```markdown
+## API Scaffolding 完成报告
+
+### Contract
+- OpenAPI: `docs/openapi.yaml`
+- 端点数量: X
+
+### 实现
+| 端点 | 方法 | 文件 |
+|------|------|------|
+| /api/v1/users | GET/POST | api/v1/endpoints/users.py |
+
+### 安全
+- [ ] 认证: JWT
+- [ ] 授权: RBAC
+- [ ] 输入验证: Pydantic
+
+### 测试
+- [ ] 单元测试覆盖
+- [ ] 集成测试覆盖
+```
+
+---
+
+## Reference Navigation
+
+| Situation | Read This |
+|-----------|-----------|
+| FastAPI 模板 | `skills/fastapi-templates/SKILL.md` |
+| 后端架构 | `agents/backend-architect.md` |
+| GraphQL 设计 | `agents/graphql-architect.md` |
+| API 测试 | `../api-testing-observability/SKILL.md` |
+| 数据库设计 | `../database-migrations/SKILL.md` |