ai-engineering-init 1.12.1 → 1.13.0

package/.claude/skills/lanhu-design/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: lanhu-design
+description: |
+  蓝湖设计稿与 Axure 原型分析。通过 lanhu MCP Server 直接读取蓝湖项目的原型页面、设计图、切图资源。
+
+  触发场景：
+  - 需要从蓝湖获取 Axure 原型页面进行需求分析
+  - 需要查看蓝湖 UI 设计图和设计参数
+  - 需要提取蓝湖设计稿中的切图资源
+  - 需要通过蓝湖团队留言板协作
+  - 收到蓝湖邀请链接需要解析
+
+  触发词：蓝湖、lanhu、设计稿、原型图、蓝湖链接、设计图、切图
+---
+
+# 蓝湖设计稿分析
+
+## 前置条件
+
+lanhu MCP Server 已注册在 `.claude/settings.json`。首次使用需配置蓝湖 Cookie：
+
+1. 浏览器登录蓝湖 → F12 开发者工具 → Network → 复制请求头中的 Cookie
+2. 填入 `.claude/settings.json` 的 `lanhu.env.LANHU_COOKIE`
+
+## MCP 工具清单
+
+| 工具 | 用途 | 输入 |
+|------|------|------|
+| `lanhu_resolve_invite_link` | 解析蓝湖邀请链接 | 邀请链接 URL |
+| `lanhu_get_pages` | 获取原型文档页面列表+截图 | 含 docId 的蓝湖 URL |
+| `lanhu_get_ai_analyze_page_result` | AI 分析原型页面（开发/测试/探索视角） | 含 docId 的 URL + 页面名 + 模式 |
+| `lanhu_get_designs` | 获取 UI 设计图列表 | 不含 docId 的蓝湖 URL |
+| `lanhu_get_ai_analyze_design_result` | AI 分析设计图（含尺寸/颜色/CSS） | 不含 docId 的 URL + 设计图名 |
+| `lanhu_get_design_slices` | 提取设计稿切图资源 | 不含 docId 的 URL + 设计图名 |
+| `lanhu_say` | 发送团队留言 | URL + 内容 |
+| `lanhu_say_list` | 查询留言列表 | URL 或 'all' |
+| `lanhu_say_detail` | 查看留言详情 | 消息 ID |
+| `lanhu_say_edit` | 编辑留言 | URL + 消息 ID + 新内容 |
+| `lanhu_say_delete` | 删除留言 | URL + 消息 ID |
+| `lanhu_get_members` | 获取项目成员 | URL |
+
+## URL 类型区分（重要）
+
+| URL 类型 | 特征 | 用于 |
+|---------|------|------|
+| **原型文档 URL** | 含 `docId` 参数 | `lanhu_get_pages`、`lanhu_get_ai_analyze_page_result` |
+| **设计项目 URL** | 不含 `docId` | `lanhu_get_designs`、`lanhu_get_design_slices` |
+| **邀请链接** | `lanhuapp.com/link/#/invite?sid=xxx` | 先用 `lanhu_resolve_invite_link` 解析 |
+
+## 典型工作流
+
+### 1. 需求分析（与 analyze-requirements 联动）
+
+```
+收到蓝湖链接
+  │
+  ├─ 邀请链接？ → lanhu_resolve_invite_link → 获取真实 URL
+  │
+  ├─ 含 docId？（原型文档）
+  │   ├─ lanhu_get_pages → 获取页面列表和截图
+  │   └─ lanhu_get_ai_analyze_page_result(mode="development") → 获取字段/逻辑/流程
+  │
+  └─ 不含 docId？（设计项目）
+      ├─ lanhu_get_designs → 获取设计图列表
+      └─ lanhu_get_ai_analyze_design_result → 获取尺寸/颜色/CSS
+```
+
+### 2. 前端开发（获取设计参数）
+
+```
+lanhu_get_designs → 查看设计图列表
+  → lanhu_get_ai_analyze_design_result → 获取精确设计参数（尺寸/间距/颜色/字体）+ HTML+CSS 代码
+  → lanhu_get_design_slices → 提取切图/图标资源
+```
+
+### 3. 分析模式选择
+
+`lanhu_get_ai_analyze_page_result` 支持 3 种模式：
+
+| 模式 | 关注点 | 适用场景 |
+|------|--------|---------|
+| `development` | 字段规则、业务逻辑、全局流程图 | 后端/前端开发 |
+| `testing` | 测试场景、用例、边界值、校验规则 | 测试编写 |
+| `exploration` | 核心功能概览、模块依赖、评审要点 | 需求评审 |
+
+## 与其他技能联动
+
+| 场景 | 先用 lanhu-design | 再用 |
+|------|-------------------|------|
+| 需求分析 | 获取原型截图和页面结构 | `analyze-requirements` 输出开发任务清单 |
+| 前端开发 | 获取设计参数和切图 | `ui-pc` 实现页面 |
+| 接口开发 | 从原型推导接口字段 | `api-development` / `crud-development` |
+
+## 注意
+
+- 蓝湖 Cookie 有效期有限，过期需重新获取
+- 原型文档和设计项目使用不同的 URL 格式，工具不能混用
+- 大型原型建议分页面分析，避免单次请求过大
+- 与 `analyze-requirements` 的区别：本技能负责**从蓝湖获取数据**，`analyze-requirements` 负责**分析数据输出任务**

package/.codex/skills/auto-test/SKILL.md

@@ -0,0 +1,453 @@
+---
+name: auto-test
+description: |
+  API 自动化测试技能。基于 Apifox MCP 读取接口文档，使用 Hurl 生成并执行真实 HTTP 测试，
+  支持单接口测试、单业务组合（CRUD 生命周期）、跨业务串联（多模块流程），生成 HTML/JSON 测试报告。
+  测试失败时自动调用 fix-bug 技能走标准修复流程。
+
+  触发场景：
+  - 需要对 API 接口进行自动化测试
+  - 需要验证接口是否符合文档定义
+  - 需要组合多个接口形成业务流程测试
+  - 需要生成接口测试报告
+  - 开发完成后需要回归测试验证
+
+  触发词：自动测试、auto-test、接口测试、API测试、Hurl、测试报告、回归测试
+---
+
+# API 自动化测试（Hurl + Apifox MCP）
+
+## 概述
+
+通过 Apifox MCP 读取接口文档 → AI 生成 Hurl 测试文件 → 执行真实 HTTP 请求 → 生成测试报告 → 失败项**自动调用 `/fix-bug` 走标准修复流程**。
+
+**前置依赖**：
+- Hurl CLI（`brew install hurl` / `winget install hurl` / `apt install hurl`）
+- Apifox MCP Server（已配置项目 ID 和 Access Token）
+- 后端服务运行中
+
+## 测试粒度
+
+| 粒度 | 说明 | 文件命名 | 示例 |
+|------|------|---------|------|
+| **单接口** | 一个 API 端点的正常+异常场景 | `{接口名}.hurl` | `create-order.hurl` |
+| **单业务组合** | 一个模块的 CRUD 生命周期 | `{模块}-lifecycle.hurl` | `order-lifecycle.hurl` |
+| **跨业务串联** | 多模块联动的完整业务流程 | `{流程名}-flow.hurl` | `menu-order-payment-flow.hurl` |
+
+## 文件结构
+
+```
+tests/hurl/
+├── env/
+│   ├── dev.env              # 开发环境变量
+│   ├── test.env             # 测试环境
+│   └── prod.env             # 生产环境（只读接口）
+├── {模块名}/                 # 按业务模块组织
+│   ├── {接口名}.hurl         # 单接口测试
+│   └── {模块}-lifecycle.hurl # 单业务组合
+├── flows/                   # 跨业务串联
+│   └── {流程名}-flow.hurl
+└── reports/                 # 测试报告（gitignore）
+    ├── index.html
+    └── report.json
+```
+
+## 系统接口请求响应规范
+
+> 详细参考：`references/api-conventions.md`（首次生成测试时必须读取）
+
+### 核心契约速查
+
+| 项目 | 规范 |
+|------|------|
+| 请求封装 | `{"content": { ... }}` （LeRequest） |
+| 成功码 | `code == 10000` |
+| 认证头 | `X-Token` + `merchant-id` + `Merchant-Id` |
+| 未授权 | 不带 X-Token → HTTP 401 |
+
+### 返回类型 → data 结构映射
+
+| Controller 返回类型 | data 结构 | 断言关键路径 |
+|---------------------|----------|-------------|
+| `Long`（save） | 雪花 ID | `$.data` isInteger |
+| `void`（delete/submit/export） | null | 仅验证 `$.code == 10000` |
+| `XxxVO`（detail） | 对象 | `$.data.id` exists |
+| `PageVO<T>`（设置类 page） | `$.data.records[]` | `$.data.records` isCollection |
+| `ReportBaseTotalVO<T>`（报表 page） | `$.data.resultPage.records[]` + `$.data.totalLine` | 分页 + 合计行 |
+
+### content 传值类型（最易出错）
+
+| 场景 | content 类型 | 示例 |
+|------|-------------|------|
+| 分页查询 | 对象 | `{"page":{"current":1,"size":10},"keyword":"xxx"}` |
+| 新增/编辑 | 对象 | `{"name":"xxx","entries":[...]}` |
+| 详情/删除/提交 | **裸 Long** | `{{id}}`（不是 `{"id":{{id}}}`） |
+
+> **关键区别**：detail/delete/submit 的 content 是**直接传 ID 值**，不需要包装成对象。
+
+## Hurl 语法速查
+
+### 请求头规范（必须遵守）
+
+每个需要认证的请求必须携带以下 Header：
+
+| Header | 来源 | 用途 |
+|--------|------|------|
+| `X-Token` | 环境变量 `{{x_token}}`（配置文件提供） | 认证令牌 |
+| `merchant-id` | 环境变量 `{{merchant_id}}` | 商户路由（数据源切换） |
+| `Merchant-Id` | 环境变量 `{{merchant_id_auth}}` | 商户权限校验 |
+
+### 基础请求 + 断言
+
+```hurl
+# 请求
+POST {{base_url}}/api/v2/web/order/add
+Content-Type: application/json
+X-Token: {{x_token}}
+merchant-id: {{merchant_id}}
+Merchant-Id: {{merchant_id_auth}}
+{
+  "content": {
+    "menuId": 1001,
+    "quantity": 2
+  }
+}
+
+# 响应断言
+HTTP 200
+[Asserts]
+jsonpath "$.code" == 10000
+jsonpath "$.msg" == "操作成功"
+jsonpath "$.data" isInteger
+```
+
+### 变量捕获（请求间传递数据）
+
+```hurl
+# 如果需要动态获取 Token，可以通过登录接口捕获
+POST {{base_url}}/api/v2/web/auth/login
+Content-Type: application/json
+{
+  "username": "{{username}}",
+  "password": "{{password}}"
+}
+
+HTTP 200
+[Captures]
+x_token: jsonpath "$.data.token"
+```
+
+> 注意：X-Token 优先使用 env 文件中预配置的值，避免每次都调登录接口。
+> 仅在测试登录流程本身或 Token 过期场景时，才通过登录接口动态获取。
+
+### 常用断言
+
+```hurl
+[Asserts]
+# 状态码
+status == 200
+
+# JSON 路径
+jsonpath "$.code" == 10000
+jsonpath "$.data" exists
+jsonpath "$.data" isCollection
+jsonpath "$.data.id" isInteger
+jsonpath "$.data.name" isString
+jsonpath "$.data.list" count > 0
+
+# 类型检查
+jsonpath "$.data.price" isFloat
+
+# 包含
+jsonpath "$.msg" contains "成功"
+
+# 正则
+jsonpath "$.data.phone" matches "^1[3-9]\\d{9}$"
+```
+
+### 环境变量文件格式
+
+```properties
+# env/dev.env
+base_url=http://192.168.97.235:58300
+
+# 认证 Token（X-Token 请求头，配置后所有请求自动携带）
+x_token=你的Token值
+
+# 商户路由（merchant-id 请求头，用于数据源切换）
+merchant_id=你的商户ID
+
+# 商户权限（Merchant-Id 请求头，用于权限校验）
+merchant_id_auth=你的商户ID
+```
+
+## 执行命令
+
+```bash
+# 运行单个测试
+hurl --test --variables-file tests/hurl/env/dev.env tests/hurl/order/create-order.hurl
+
+# 运行模块所有测试
+hurl --test --variables-file tests/hurl/env/dev.env tests/hurl/order/*.hurl
+
+# 运行全部测试 + 生成报告
+hurl --test \
+  --variables-file tests/hurl/env/dev.env \
+  --report-html tests/hurl/reports \
+  --report-json tests/hurl/reports/report.json \
+  tests/hurl/**/*.hurl
+
+# 传递动态变量（如时间戳避免唯一键冲突）
+TS=$(date +%s) && hurl --test \
+  --variables-file tests/hurl/env/dev.env \
+  --variable "voucher_type_ts=$TS" \
+  --variable "voucher_word_ts=$TS" \
+  tests/hurl/finance/*.hurl
+
+# 指定超时（毫秒）
+hurl --test --connect-timeout 5000 --max-time 30000 ...
+
+# 失败时继续执行（不中断）
+hurl --test --continue-on-error ...
+```
+
+## 生成测试的流程
+
+### 第一步：读取接口文档
+
+通过 Apifox MCP 读取指定模块的接口列表：
+- 接口路径、HTTP 方法
+- 请求参数（Header、Body、Query）
+- 响应结构（字段名、类型、示例值）
+
+### 第二步：读取 Param/VO 源码（关键！）
+
+**必须读取后端源码**以确保测试完整性：
+
+1. **Param 类**：提取所有查询条件字段，确保每个字段都有对应测试用例
+2. **VO 类**：提取所有响应字段，在断言中验证字段存在性和类型
+3. **Mapper XML**：理解 SQL 逻辑、JOIN 关系、动态条件
+
+```
+示例：SubjectDetailParam 有 startDate、endDate、areaId、canteenId、keyword
+→ 测试用例必须覆盖：
+  - 基础分页查询（startDate + endDate）
+  - keyword 搜索（科目编码/名称）
+  - 区域+食堂筛选（areaId + canteenId）
+  - 单日查询（startDate == endDate）
+  - 空结果区间（验证空数组返回）
+  - 分页第二页
+  - 导出接口
+  - 未授权测试
+```
+
+### 第三步：准备测试数据（先查后用，禁止硬编码）
+
+**核心原则：测试数据必须从真实环境动态获取，不能硬编码不存在的 ID 或编码。**
+
+```hurl
+# ✅ 正确：先查询获取真实数据，再用于后续请求
+# 0a. 获取真实食堂 ID
+POST {{base_url}}/api/v2/alloc/canteen/page-canteen
+...
+[Captures]
+canteen_id: jsonpath "$.data.records[0].canteenId"
+area_id: jsonpath "$.data.records[0].areaId"
+
+# 0b. 获取关联表的真实记录
+POST {{base_url}}/report/finance/setting/voucher-type/page
+...
+[Captures]
+voucher_type_id: jsonpath "$.data.records[0].id"
+```
+
+```hurl
+# ❌ 错误：硬编码不存在的引用数据
+{
+  "content": {
+    "costNo": "9999",        # 可能不存在
+    "voucherTypeId": 1       # 可能不存在
+  }
+}
+```
+
+**测试数据准备检查清单**：
+- [ ] 外键引用的 ID 通过查询接口动态获取
+- [ ] 业务编码（如 costNo）使用数据库中已存在的真实记录
+- [ ] 唯一键字段使用时间戳变量避免冲突（`{{xxx_ts}}`）
+- [ ] 创建的测试数据标记 summary 含 `auto-test` 便于识别清理
+- [ ] 测试结束后有清理步骤（删除测试数据）
+
+### 第四步：生成 .hurl 文件
+
+**查询条件完整覆盖**（每个 Param 字段都要有测试用例）：
+
+```
+单接口测试场景清单：
+1. 基础分页查询 — 必填参数，预期 code=10000，验证分页结构+VO 所有字段
+2. 合计行验证 — 如有 totalLine，验证所有合计字段存在
+3. 逐个查询条件 — 每个 Param 字段单独或组合测试
+4. 空结果验证 — 故意使用不匹配的条件，验证 records count == 0
+5. 分页翻页 — current=2 验证翻页正确
+6. 导出接口 — 验证 code=10000（异步导出返回 void）
+7. 未授权测试 — 不带 X-Token，预期 HTTP 401
+8. 数据清理 — 删除测试创建的数据
+```
+
+**数据正确性验证**（不只是结构存在，还要验证值合理）：
+
+```hurl
+# ✅ 结构验证 + 数据正确性
+[Asserts]
+jsonpath "$.code" == 10000
+jsonpath "$.data.resultPage.records" isCollection
+jsonpath "$.data.resultPage.records" count > 0
+# VO 字段存在性
+jsonpath "$.data.resultPage.records[0].costNo" isString
+jsonpath "$.data.resultPage.records[0].costTypeName" isString    # 关联字段不能为 null
+jsonpath "$.data.resultPage.records[0].debitAmount" exists
+# 合计行数据合理性
+jsonpath "$.data.totalLine.debitAmount" exists
+jsonpath "$.data.totalLine.creditAmount" exists
+```
+
+### 第五步：执行并生成报告
+
+```bash
+hurl --test \
+  --variables-file tests/hurl/env/dev.env \
+  --report-html tests/hurl/reports \
+  --report-json tests/hurl/reports/report.json \
+  --continue-on-error \
+  tests/hurl/{模块}/*.hurl
+```
+
+### 第六步：解析报告
+
+读取 `report.json`，输出摘要：
+
+```markdown
+## 测试报告摘要
+
+| 状态 | 数量 | 占比 |
+|------|------|------|
+| PASS | 15   | 75%  |
+| FAIL | 3    | 15%  |
+| ERROR| 2    | 10%  |
+
+### 失败详情
+
+| 文件 | 接口 | 失败原因 |
+|------|------|---------|
+| order/create-order.hurl | POST /api/v2/web/order/add | 预期 code=10000，实际 code=40001 |
+| menu/query-menu.hurl | GET /api/v2/web/menu/get/1 | 预期 HTTP 200，实际 HTTP 500 |
+```
+
+### 第七步：失败项自动触发 fix-bug 流程
+
+**当测试存在失败项时，必须自动调用 `/fix-bug` 走标准修复流程：**
+
+```
+测试失败 → 分析失败原因 → 分类处理：
+
+1. 测试数据问题（非代码 Bug）：
+   - 引用数据不存在 → 修正测试用例中的数据
+   - 唯一键冲突 → 添加时间戳变量
+   - 权限/状态限制 → 调整测试前置条件
+
+2. 后端代码 Bug：
+   → 自动调用 Skill(fix-bug) 走标准修复流程
+   → 包含：排查报告 → 用户确认 → 修复代码 → 重跑测试验证
+
+3. 接口文档与实现不一致：
+   → 输出差异报告，等待用户确认以哪个为准
+```
+
+**fix-bug 自动触发条件**：
+- HTTP 状态码非预期（如 500）
+- 业务码非预期（如 code != 10000）
+- 响应字段缺失或类型不匹配
+- 关联字段为 null（如 costTypeName 为 null 说明 JOIN 失败）
+- 导出数据异常（原始字段暴露、金额未转换等）
+
+**Bug 报告格式**（传递给 fix-bug）：
+
+```
+Bug 信息：
+- 接口：{METHOD} {URL}
+- 请求参数：{request body}
+- 预期响应：{expected}
+- 实际响应：{actual}
+- Hurl 文件：{file path}
+- 失败断言：{assertion detail}
+- 关联源码：{Controller/Service/Mapper 文件路径}
+```
+
+## LeRequest 适配
+
+leniu 项目的 POST 请求体使用 `LeRequest<T>` 封装：
+
+```hurl
+# ✅ 正确：使用 content 包装 + 三个必要 Header
+POST {{base_url}}/api/v2/web/order/add
+Content-Type: application/json
+X-Token: {{x_token}}
+merchant-id: {{merchant_id}}
+Merchant-Id: {{merchant_id_auth}}
+{
+  "content": {
+    "menuId": 1001,
+    "quantity": 2
+  }
+}
+
+# ❌ 错误：直接传业务字段 / 缺少 Header
+POST {{base_url}}/api/v2/web/order/add
+{
+  "menuId": 1001,
+  "quantity": 2
+}
+```
+
+## 已知陷阱（Lessons Learned）
+
+### 1. del_flag 约定不统一
+leniu 主表用 `2=正常, 1=删除`，但某些设置表（如 `finance_voucher_type`, `finance_voucher_word`）使用 `@TableLogic` 默认值 `0=正常, 1=删除`。**不要盲目统一，要检查每张表的实际约定。**
+
+### 2. 测试数据必须使用真实存在的引用数据
+关联查询（JOIN）依赖引用数据存在且状态正确。例如：
+- `cost_type` 表的 `state = 1` 才是有效记录
+- `costNo` 必须在 `cost_type` 中存在且 `state = 1`
+- 否则 LEFT JOIN 后关联字段（如 `costTypeName`）为 null
+
+### 3. 导出验证要点
+导出接口是异步的（返回 void → code=10000），需要额外关注：
+- VO 的 `@ExcelIgnore` 是否正确标记了内部字段
+- `@ExcelProperty(order=N)` 的顺序是否符合产品要求
+- 金额字段是否配置了 `converter = CustomNumberConverter.class`（分→元）
+- 枚举字段是否有对应的描述字段（如 submitStatus → submitStatusDesc）
+
+### 4. 唯一键冲突
+CRUD 生命周期测试中，新增记录的唯一键字段（如 typeCode）需要加时间戳变量：
+```hurl
+"typeCode": "AT_HURL_{{voucher_type_ts}}"
+```
+执行时通过 `--variable "voucher_type_ts=$(date +%s)"` 传入。
+
+### 5. 后端未重启
+修改后端代码后必须重启服务才能生效。如果测试结果不符合预期，先确认后端是否已重启。
+
+## .gitignore 配置
+
+```gitignore
+# Hurl 测试报告
+tests/hurl/reports/
+```
+
+## 注意
+
+- 测试文件（`.hurl`）需要 Git 管理，报告目录不需要
+- `env/*.env` 中的密码/Token 建议用环境变量替代，不要提交敏感信息
+- 如果是 leniu 项目的 POST 接口，请求体必须用 `{"content": {...}}` 包装
+- 生成测试前确保 Hurl CLI 已安装（`hurl --version`）
+- 与 `test-development` 技能的区别：本技能是真实 HTTP 请求的集成测试，`test-development` 是 JUnit5 单元测试/MockMvc 测试