@pzy560117/codex-harness 0.1.0 → 0.1.1

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/api-contract-template/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: api-contract-template
+description: API 契约模板
+---
+
+# API 契约模板
+
+前端代码完成后，提取 API 契约供后端实现。
+
+## API 契约：[接口名称]
+
+### 基本信息
+| 属性 | 值 |
+|------|-----|
+| 接口名称 | |
+| 请求路径 | /api/v1/xxx |
+| 请求方法 | GET/POST/PUT/DELETE |
+| 关联页面 | |
+| 关联需求 | Req-XXX |
+
+### 请求参数
+
+#### Query 参数（GET请求）
+| 参数名 | 类型 | 必填 | 说明 | 示例 |
+|--------|------|------|------|------|
+| page | number | ❌ | 页码，默认1 | 1 |
+| pageSize | number | ❌ | 每页条数，默认10 | 10 |
+| status | string | ❌ | 状态筛选 | pending |
+| keyword | string | ❌ | 关键词搜索 | 订单 |
+
+#### Body 参数（POST/PUT请求）
+```json
+{
+  "name": "string, 必填, 名称, 2-50字符",
+  "description": "string, 选填, 描述, 最多500字符",
+  "status": "string, 必填, 枚举: draft/pending/approved"
+}
+```
+
+### 响应结构
+
+#### 成功响应
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "list": [
+      {
+        "id": "string",
+        "name": "string",
+        "status": "string",
+        "createTime": "YYYY-MM-DD HH:mm:ss",
+        "updateTime": "YYYY-MM-DD HH:mm:ss"
+      }
+    ],
+    "total": 100,
+    "page": 1,
+    "pageSize": 10
+  }
+}
+```
+
+#### 错误响应
+```json
+{
+  "code": 400001,
+  "message": "参数校验失败",
+  "data": null
+}
+```
+
+### 错误码定义
+| 错误码 | 含义 | 前端处理 |
+|--------|------|----------|
+| 400001 | 参数校验失败 | 显示具体字段错误 |
+| 401001 | 未登录 | 跳转登录页 |
+| 403001 | 无权限 | 显示无权限提示 |
+| 404001 | 资源不存在 | 显示404页面 |
+| 500001 | 服务器错误 | 显示通用错误提示 |
+
+### 幂等性（写操作必填）
+| 属性 | 值 |
+|------|-----|
+| 是否幂等 | 是/否 |
+| 幂等键 | X-Idempotency-Key header |
+| 有效期 | 24小时 |
+

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/api-design/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: api-design
+description: API Design Skill
+---
+
+# API Design Skill
+
+RESTful 和 GraphQL API 设计最佳实践。
+
+## RESTful API 规范
+
+### URL 设计原则
+- 使用名词复数表示资源：`/users`、`/orders`
+- 层级关系用嵌套：`/users/{id}/orders`
+- 使用连字符分隔：`/user-profiles`
+- 全小写，避免下划线
+
+### HTTP 方法语义
+| 方法 | 用途 | 幂等性 |
+|------|------|--------|
+| GET | 获取资源 | ✅ |
+| POST | 创建资源 | ❌ |
+| PUT | 全量更新 | ✅ |
+| PATCH | 部分更新 | ✅ |
+| DELETE | 删除资源 | ✅ |
+
+### 状态码规范
+```
+2xx 成功
+  200 OK - 通用成功
+  201 Created - 创建成功
+  204 No Content - 删除成功
+
+4xx 客户端错误
+  400 Bad Request - 请求格式错误
+  401 Unauthorized - 未认证
+  403 Forbidden - 无权限
+  404 Not Found - 资源不存在
+  409 Conflict - 资源冲突
+  422 Unprocessable Entity - 验证失败
+
+5xx 服务端错误
+  500 Internal Server Error
+  502 Bad Gateway
+  503 Service Unavailable
+```
+
+### 响应格式
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": 1,
+    "name": "example"
+  },
+  "meta": {
+    "page": 1,
+    "pageSize": 20,
+    "total": 100
+  }
+}
+```
+
+### 错误响应
+```json
+{
+  "code": 40001,
+  "message": "Validation failed",
+  "errors": [
+    {
+      "field": "email",
+      "message": "Invalid email format"
+    }
+  ]
+}
+```
+
+## 分页设计
+
+### 偏移分页（小数据量）
+```
+GET /users?page=1&pageSize=20
+```
+
+### 游标分页（大数据量）
+```
+GET /users?cursor=eyJpZCI6MTAwfQ&limit=20
+```
+
+## 版本控制
+
+### URL 路径版本（推荐）
+```
+/api/v1/users
+/api/v2/users
+```
+
+### Header 版本
+```
+Accept: application/vnd.api+json; version=1
+```
+
+## GraphQL 规范
+
+### Schema 设计
+```graphql
+type User {
+  id: ID!
+  email: String!
+  profile: Profile
+  orders(first: Int, after: String): OrderConnection!
+}
+
+type Query {
+  user(id: ID!): User
+  users(filter: UserFilter, pagination: Pagination): UserConnection!
+}
+
+type Mutation {
+  createUser(input: CreateUserInput!): CreateUserPayload!
+  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
+}
+```
+
+### 命名约定
+- Query: 名词，如 `user`、`users`
+- Mutation: 动词+名词，如 `createUser`、`deleteOrder`
+- Input: `XxxInput`
+- Payload: `XxxPayload`
+
+## 安全要点
+
+- 始终使用 HTTPS
+- 实现速率限制（Rate Limiting）
+- 验证所有输入参数
+- 不在 URL 中传递敏感信息
+- 使用 JWT 或 OAuth2.0 认证
+

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/api-integration/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: api-integration
+description: 前后端联调与 Mock
+---
+
+# 前后端联调工作流
+
+本项目前后端技术栈与联调架构说明。
+
+## 架构总览
+
+```
+┌─────────────┐  /api/v1/*   ┌───────────────┐  lb://service  ┌─────────────────┐
+│  Vue 3 前端  │ ──────────→ │ Spring Cloud  │ ────────────→ │  微服务集群       │
+│  Vite :5173  │   proxy     │ Gateway :8080 │    Nacos       │  auth / script   │
+│  Arco Design │             │ JWT Filter    │    路由发现     │  session/booking │
+│  Pinia       │             │ StripPrefix=2 │               │  stats/recommend │
+└─────────────┘             └───────────────┘               └─────────────────┘
+```
+
+### 技术栈一览
+
+| 层级 | 技术 | 备注 |
+|------|------|------|
+| 前端框架 | Vue 3 + TypeScript | `script-kill-frontend/` |
+| UI 组件 | Arco Design Web Vue 2.57+ | `@arco-design/web-vue` |
+| 状态管理 | Pinia 3.x | |
+| HTTP 客户端 | Axios 1.13+ | 封装在 `src/utils/http.ts` |
+| 构建工具 | Vite (rolldown-vite) | 代理 `/api/v1` → `:8080` |
+| 后端网关 | Spring Cloud Gateway | `:8080`，Nacos 服务发现 |
+| 认证 | JWT (Bearer Token) | Gateway 统一鉴权 |
+| API 文档 | Knife4j Gateway 聚合 | `http://localhost:8080/doc.html` |
+| 测试 | Vitest (前端) / Pytest (E2E) | |
+
+---
+
+## 1. Vite 代理配置
+
+```typescript
+// script-kill-frontend/vite.config.ts
+export default defineConfig({
+  server: {
+    proxy: {
+      '/api/v1': {
+        target: 'http://localhost:8080',  // Gateway 端口
+        changeOrigin: true
+        // 注意: 不要 rewrite 路径，Gateway 通过 StripPrefix=2 处理
+      }
+    }
+  }
+})
+```
+
+> [!IMPORTANT]
+> Gateway 的 `StripPrefix=2` 会移除前两段路径（`/api/v1`），实际到达微服务的路径为 `/auth/**`、`/scripts/**` 等。前端统一使用 `/api/v1/xxx` 即可。
+
+---
+
+## 2. Gateway 路由映射
+
+| 前端请求路径 | Gateway 路由 | 目标服务 | 服务内路径 |
+|-------------|-------------|---------|-----------|
+| `/api/v1/auth/**` | `auth-service` | `lb://auth-service` | `/auth/**` |
+| `/api/v1/scripts/**` | `script-service` | `lb://script-service` | `/scripts/**` |
+| `/api/v1/dms/**` | `script-service` | `lb://script-service` | `/dms/**` |
+| `/api/v1/sessions/**` | `session-service` | `lb://session-service` | `/sessions/**` |
+| `/api/v1/bookings/**` | `booking-service` | `lb://booking-service` | `/bookings/**` |
+| `/api/v1/orders/**` | `booking-service` | `lb://booking-service` | `/orders/**` |
+| `/api/v1/stats/**` | `stats-service` | `lb://stats-service` | `/stats/**` |
+| `/api/v1/recommendations/**` | `recommend-service` | `lb://recommend-service` | `/recommendations/**` |
+
+---
+
+## 3. HTTP 请求封装
+
+项目已在 `src/utils/http.ts` 中封装了统一的 HTTP 客户端：
+
+### 统一响应格式
+
+```typescript
+// 后端 Result<T> 结构
+interface ApiResult<T> { code: number; message: string; data: T }
+
+// 前端标准响应
+interface ApiResponse<T> { success: boolean; data: T; message: string; code: number }
+```
+
+**约定**: `code === 0` 表示业务成功，其他值为业务错误码。
+
+### 编写 API 模块
+
+```typescript
+// src/api/script.ts
+import http from '@/utils/http'
+import type { ApiResponse } from '@/utils/http'
+
+/** 剧本列表 */
+export interface ScriptVO {
+  id: number
+  name: string
+  type: string
+  minPlayers: number
+  maxPlayers: number
+}
+
+/** 获取剧本列表 */
+export function fetchScripts(params?: { type?: string; page?: number; size?: number }) {
+  return http.get<ApiResponse<ScriptVO[]>>('/scripts', { params })
+}
+
+/** 获取单个剧本 */
+export function fetchScriptById(id: number) {
+  return http.get<ApiResponse<ScriptVO>>(`/scripts/${id}`)
+}
+```
+
+### 在 Vue 组件中调用
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+import { fetchScripts, type ScriptVO } from '@/api/script'
+import { Message } from '@arco-design/web-vue'
+
+const scripts = ref<ScriptVO[]>([])
+const loading = ref(false)
+
+onMounted(async () => {
+  loading.value = true
+  const res = await fetchScripts()
+  if (res.data.success) {
+    scripts.value = res.data.data
+  } else {
+    Message.error(res.data.message)
+  }
+  loading.value = false
+})
+</script>
+```
+
+---
+
+## 4. 联调启动流程
+
+### 前置条件
+
+```bash
+# 1. 启动基础设施
+#    - MySQL 8.x (端口 3306)
+#    - Redis (端口 6379)
+#    - Nacos (端口 8848)
+
+# 2. 启动后端微服务（按依赖顺序）
+#    Gateway → Auth → Script → Session → Booking → Stats → Recommend
+
+# 3. 验证服务注册
+#    访问 Nacos 控制台: http://localhost:8848/nacos
+#    确认所有服务已注册
+
+# 4. 验证 API 文档
+#    访问 Knife4j: http://localhost:8080/doc.html
+#    查看各服务 API 接口
+
+# 5. 启动前端
+cd script-kill-frontend
+npm run dev
+# → http://localhost:5173
+```
+
+### 环境变量
+
+```bash
+# .env.development（默认，走 Vite 代理）
+VITE_API_BASE_URL=/api/v1
+
+# .env.production（生产，直连网关或 Nginx）
+VITE_API_BASE_URL=https://api.example.com/api/v1
+```
+
+---
+
+## 5. 常见联调问题排查
+
+### 快速诊断表
+
+| 症状 | 可能原因 | 排查步骤 |
+|------|---------|---------|
+| 前端 404 | 路径不匹配 | 对照 Gateway 路由表，检查 `StripPrefix` |
+| 前端 502 | 服务未启动 | 检查 Nacos 服务列表 |
+| 前端 401 | Token 缺失/过期 | F12 → Network → 检查 Authorization 头 |
+| 前端 403 | JWT Filter 拦截 | 检查 Gateway 白名单（如 `/auth/login`） |
+| CORS 报错 | Gateway 未配置 CORS | 在 Gateway 添加 `CorsWebFilter` |
+| 数据为空 | 数据库无数据 | 检查 Flyway 迁移是否成功 |
+| 响应格式错误 | 后端未用 `Result<T>` | 检查 Controller 返回值 |
+
+### Gateway CORS 配置
+
+```java
+// script-kill-gateway/.../config/CorsConfig.java
+@Configuration
+public class CorsConfig {
+    @Bean
+    public CorsWebFilter corsFilter() {
+        CorsConfiguration config = new CorsConfiguration();
+        config.addAllowedOrigin("http://localhost:5173");
+        config.addAllowedMethod("*");
+        config.addAllowedHeader("*");
+        config.setAllowCredentials(true);
+
+        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
+        source.registerCorsConfiguration("/**", config);
+        return new CorsWebFilter(source);
+    }
+}
+```
+
+> [!TIP]
+> 开发环境推荐使用 Vite 代理而非 CORS，避免跨域问题。生产环境由 Nginx 代理，同样无 CORS 问题。
+
+### 路径映射调试
+
+```bash
+# 验证 Gateway 路由是否生效
+curl -v http://localhost:8080/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"123456"}'
+
+# 直连微服务验证（绕过 Gateway）
+curl http://localhost:8081/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"123456"}'
+```
+
+---
+
+## 6. 联调 & E2E 验证清单
+
+### 接口层联调
+
+- [ ] 接口路径与 Gateway 路由一致
+- [ ] 请求方法正确（GET / POST / PUT / DELETE）
+- [ ] Query 参数 vs Body 参数格式正确
+- [ ] 响应结构遵循 `{ code, message, data }` 约定
+- [ ] 错误码定义前后端一致（参照 Knife4j 文档）
+- [ ] JWT Token 正确传递和校验
+- [ ] 分页参数约定一致（`page` / `size`）
+- [ ] 时间格式统一（ISO 8601 / 时间戳）
+
+### 业务流联调
+
+- [ ] 用户注册 → 登录 → 获取 Token 完整流程
+- [ ] 剧本 CRUD 操作
+- [ ] 场次创建和查询
+- [ ] 预约/取消预约流程
+- [ ] 并发预约不超卖
+
+### E2E 验证
+
+```bash
+# 运行 pytest E2E 测试
+cd script-kill-backend/e2e-tests
+pip install -r requirements.txt
+pytest -v --tb=short
+```
+
+---
+
+## 7. 调试技巧
+
+### 前端请求日志
+
+```typescript
+// 在 src/utils/http.ts 中已可扩展
+if (import.meta.env.DEV) {
+  http.interceptors.request.use((config) => {
+    console.log(`[API] ${config.method?.toUpperCase()} ${config.url}`, config.data || config.params)
+    return config
+  })
+  http.interceptors.response.use((response) => {
+    console.log(`[API] ← ${response.config.url}`, response.data)
+    return response
+  })
+}
+```
+
+### 后端日志定位
+
+```bash
+# 查看 Gateway 日志（路由匹配）
+# 在 application.yml 中临时开启:
+# logging.level.org.springframework.cloud.gateway: DEBUG
+
+# 查看具体微服务日志
+# 各微服务的 logs/ 目录或控制台输出
+```
+
+### 使用 Knife4j 测试
+
+1. 打开 `http://localhost:8080/doc.html`
+2. 选择目标服务（如 `auth-service`）
+3. 找到目标接口，填入参数
+4. 发送请求，对比前端期望的响应格式