effekt-interface/resources/skills_rules_api_doc.md

测试 Skills 与业务规则接口文档

1. 基础说明

接口前缀：/it/api

统一响应：

{
  "code": 20000,
  "msg": "success",
  "data": {}
}

鉴权：需要登录态 token。

建议请求头：

Authorization: Bearer ${token}

也兼容：

accessToken: ${token}

---

2. 枚举

2.1 Skill 类型 skill_type

值	含义
1	通用测试策略
2	历史缺陷模式
3	边界场景
4	接口测试
5	UI 测试
6	性能测试
7	安全测试
8	数据一致性
9	并发/幂等
99	其他

2.2 风险等级 risk_level

值	含义
0	高风险
1	中高风险
2	中风险
3	低风险

2.3 业务规则优先级 priority

值	含义
0	高优先级
1	中高优先级
2	中优先级
3	低优先级

2.4 状态 status

值	含义
1	启用
2	停用
3	草稿

---

3. Skill 接口

3.1 创建 Skill

POST /it/api/skill/create

权限：skill:create

请求体：

{
  "projectId": 1,
  "moduleId": 10,
  "name": "支付金额边界校验",
  "description": "用于支付金额相关需求的边界测试生成",
  "skillType": 3,
  "riskLevel": 0,
  "tags": ["支付", "金额", "边界"],
  "status": 1
}

参数：

字段	类型	必填	说明
projectId	number	是	项目 ID
moduleId	number	否	模块 ID
name	string	是	Skill 名称
description	string	否	用户补充描述，会作为大模型生成 Skill 内容的输入
skillType	number	否	Skill 类型，未传时默认 1；大模型也可能根据内容修正
riskLevel	number	否	风险等级，未传时默认 2；大模型也可能根据内容修正
tags	string[]	否	初始标签数组，大模型可能补全
status	number	否	状态，默认 1

说明：

• code 不需要前端传，后端自动生成项目内唯一编码。
• triggerCondition 不需要前端传，后端默认使用当前 AI 生成用例的触发条件。
• outputSpec 不需要前端传，后端默认使用当前 AI 生成用例的输出规范。
• reasoningPath 不需要前端传，后端会调用大模型并根据 config/skills/skill-creator/SKILL.md 规则生成。
• ownerId 不需要前端传，后端默认取当前登录人 ID。
• 创建成功后，后端会在 config/skills/{产品名称}/{项目名称}/{模块名称}/{Skill名称}/SKILL.md 生成 Skill 文件。
• 数据库会保存生成文件路径到 skill_file_path。

成功响应：

{
  "code": 20000,
  "msg": "success",
  "data": {
    "id": 1
  }
}

常见失败：

{
  "code": 40009,
  "msg": "projectId、name 为必传参数"
}

{
  "code": 40009,
  "msg": "AI生成 Skill 内容失败: xxx"
}

---

3.2 更新 Skill

POST /it/api/skill/update

权限：skill:update

请求体：

{
  "skillId": 1,
  "name": "支付金额边界校验",
  "description": "更新后的描述",
  "triggerCondition": "更新后的触发条件",
  "reasoningPath": "更新后的推理路径",
  "outputSpec": "更新后的输出规范",
  "skillType": 3,
  "riskLevel": 0,
  "tags": ["支付", "金额", "边界", "参数校验"],
  "status": 1,
  "ownerId": 8
}

说明：

• 当前接口不支持更新 code。
• 更新成功后，后端会根据更新后的 Skill 内容重新创建 SKILL.md 文件。
• 新文件路径会同步更新到数据库 skill_file_path。
• 数据库更新成功后会删除原 Skill 文件夹。
• 如果数据库更新失败，后端会删除新创建的文件夹并保留旧数据库记录和旧文件，避免数据库与文件不一致。

成功响应：

{
  "code": 20000,
  "msg": "success",
  "data": {
    "id": 1
  }
}

---

3.3 删除 Skill

POST /it/api/skill/delete

权限：skill:delete

请求体：

{
  "skillId": 1
}

说明：软删除，设置 is_delete = 1，并删除该 Skill 对应的 config/skills/{产品名称}/{项目名称}/{模块名称}/{Skill名称} 文件夹。

成功响应：

{
  "code": 20000,
  "msg": "success",
  "data": {
    "id": 1
  }
}

---

3.4 Skill 详情

GET /it/api/skill/detail?skillId=1

权限：skill:detail

成功响应：

{
  "code": 20000,
  "msg": "success",
  "data": {
    "id": 1,
    "project_id": 1,
    "module_id": 10,
    "name": "支付金额边界校验",
    "code": "PAY_AMOUNT_BOUNDARY",
    "description": "用于支付金额相关需求的边界测试生成",
    "trigger_condition": "需求中出现支付、金额、扣款、退款、余额等关键词时触发",
    "reasoning_path": "识别金额字段，构造最小值、最大值、0、负数、小数精度、超限金额等场景",
    "output_spec": "必须覆盖正常金额、0元、负数、超大金额、小数精度、余额不足",
    "skill_file_path": "D:\\zhyy\\effekt-interface\\config\\skills\\产品A\\项目A\\支付模块\\支付金额边界校验\\SKILL.md",
    "skill_type": 3,
    "risk_level": 0,
    "tags": ["支付", "金额", "边界"],
    "status": 1,
    "owner_id": 8,
    "created_by": 6,
    "usage_count": 0,
    "is_delete": 0,
    "created_time": "2025-09-20 12:00:00",
    "updated_time": "2025-09-20 12:00:00"
  }
}

---

3.5 Skill 列表

GET /it/api/skill/list

权限：skill:list

Query 参数：

参数	类型	必填	说明
pageNo	number	否	页码，默认 1
pageSize	number	否	每页数量，默认 20
projectId	number	否	项目 ID
moduleId	number	否	模块 ID
status	number	否	状态
skillType	number	否	Skill 类型
riskLevel	number	否	风险等级
keyword	string	否	搜索 name/code/description/trigger_condition
tag	string	否	单个标签过滤

请求示例：

GET /it/api/skill/list?pageNo=1&pageSize=20&projectId=1&moduleId=10&keyword=支付&status=1

成功响应：

{
  "code": 20000,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "project_id": 1,
        "module_id": 10,
        "name": "支付金额边界校验",
        "code": "PAY_AMOUNT_BOUNDARY",
        "description": "用于支付金额相关需求的边界测试生成",
        "trigger_condition": "需求中出现支付、金额、扣款、退款、余额等关键词时触发",
        "reasoning_path": "识别金额字段...",
        "output_spec": "必须覆盖正常金额...",
        "skill_file_path": "D:\\zhyy\\effekt-interface\\config\\skills\\产品A\\项目A\\支付模块\\支付金额边界校验\\SKILL.md",
        "skill_type": 3,
        "risk_level": 0,
        "tags": ["支付", "金额", "边界"],
        "status": 1,
        "owner_id": 8,
        "usage_count": 0,
        "created_time": "2025-09-20 12:00:00",
        "updated_time": "2025-09-20 12:00:00"
      }
    ],
    "total": 1
  }
}

---

4. Business Rule 接口

4.1 创建业务规则

POST /it/api/business-rule/create

权限：business-rule:create

请求体：

{
  "projectId": 1,
  "moduleId": 10,
  "name": "支付金额必须大于 0",
  "description": "用于支付、充值、扣款、退款等金额输入场景的参数校验规则",
  "priority": 0,
  "tags": ["支付", "金额", "参数校验"],
  "status": 1
}

参数：

字段	类型	必填	说明
projectId	number	是	项目 ID
moduleId	number	否	模块 ID
name	string	是	规则名称
description	string	否	用户补充描述，会作为大模型生成规则内容的输入
priority	number	否	优先级，默认 2；大模型也可能根据内容修正
tags	string[]	否	初始标签数组，大模型可能补全
status	number	否	状态，默认 1

说明：

• ruleCode 不需要前端传，后端自动生成项目内唯一编码。
• ruleContent、applicableScene、example 不需要前端传，后端会调用大模型生成。
• ownerId 不需要前端传，后端默认取当前登录人 ID。
• 创建成功后，后端会在 config/rules/{产品名称}/{项目名称}/{模块名称}/{规则名称}/RULE.md 生成业务规则文件。
• 数据库会保存生成文件路径到 rule_file_path。

成功响应：

{
  "code": 20000,
  "msg": "success",
  "data": {
    "id": 1
  }
}

---

4.2 更新业务规则

POST /it/api/business-rule/update

权限：business-rule:update

请求体：

{
  "ruleId": 1,
  "name": "支付金额必须大于 0",
  "ruleContent": "支付金额必须大于 0，等于 0 或小于 0 时接口应返回参数错误",
  "applicableScene": "支付、充值、扣款、退款金额输入",
  "example": "amount=0，预期返回金额必须大于0",
  "priority": 0,
  "tags": ["支付", "金额", "参数校验"],
  "status": 1,
  "ownerId": 8
}

说明：

• 当前接口不支持更新 ruleCode。
• 更新成功后，后端会根据更新后的业务规则内容重新创建 RULE.md 文件。
• 新文件路径会同步更新到数据库 rule_file_path。
• 数据库更新成功后会删除原业务规则文件夹。
• 如果数据库更新失败，后端会删除新创建的文件夹并保留旧数据库记录和旧文件，避免数据库与文件不一致。

成功响应：

{
  "code": 20000,
  "msg": "success",
  "data": {
    "id": 1
  }
}

---

4.3 删除业务规则

POST /it/api/business-rule/delete

权限：business-rule:delete

请求体：

{
  "ruleId": 1
}

说明：软删除，设置 is_delete = 1，并删除该业务规则对应的 config/rules/{产品名称}/{项目名称}/{模块名称}/{规则名称} 文件夹。

---

4.4 业务规则详情

GET /it/api/business-rule/detail?ruleId=1

权限：business-rule:detail

成功响应：

{
  "code": 20000,
  "msg": "success",
  "data": {
    "id": 1,
    "project_id": 1,
    "module_id": 10,
    "name": "支付金额必须大于 0",
    "rule_code": "PAY_AMOUNT_GT_ZERO",
    "rule_content": "支付金额必须大于 0，等于 0 或小于 0 时接口应返回参数错误",
    "applicable_scene": "支付、充值、扣款、退款金额输入",
    "example": "amount=0，预期返回金额必须大于0",
    "rule_file_path": "D:\\zhyy\\effekt-interface\\config\\rules\\产品A\\项目A\\支付模块\\支付金额必须大于 0\\RULE.md",
    "priority": 0,
    "tags": ["支付", "金额", "参数校验"],
    "status": 1,
    "owner_id": 8,
    "created_by": 6,
    "usage_count": 0,
    "is_delete": 0,
    "created_time": "2025-09-20 12:00:00",
    "updated_time": "2025-09-20 12:00:00"
  }
}

---

4.5 业务规则列表

GET /it/api/business-rule/list

权限：business-rule:list

Query 参数：

参数	类型	必填	说明
pageNo	number	否	页码，默认 1
pageSize	number	否	每页数量，默认 20
projectId	number	否	项目 ID
moduleId	number	否	模块 ID
status	number	否	状态
priority	number	否	优先级
keyword	string	否	搜索 name/rule_code/rule_content/applicable_scene
tag	string	否	单个标签过滤

请求示例：

GET /it/api/business-rule/list?pageNo=1&pageSize=20&projectId=1&moduleId=10&keyword=金额&status=1

成功响应：

{
  "code": 20000,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "project_id": 1,
        "module_id": 10,
        "name": "支付金额必须大于 0",
        "rule_code": "PAY_AMOUNT_GT_ZERO",
        "rule_content": "支付金额必须大于 0，等于 0 或小于 0 时接口应返回参数错误",
        "applicable_scene": "支付、充值、扣款、退款金额输入",
        "example": "amount=0，预期返回金额必须大于0",
        "priority": 0,
        "tags": ["支付", "金额", "参数校验"],
        "status": 1,
        "owner_id": 8,
        "usage_count": 0,
        "created_time": "2025-09-20 12:00:00",
        "updated_time": "2025-09-20 12:00:00"
      }
    ],
    "total": 1
  }
}

---

5. 调用示例

5.1 curl 创建 Skill

curl -X POST 'http://localhost:5010/it/api/skill/create' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-token' \
  -d '{
    "projectId": 1,
    "name": "支付金额边界校验",
    "code": "PAY_AMOUNT_BOUNDARY",
    "triggerCondition": "需求中出现支付、金额、扣款、退款、余额等关键词时触发",
    "skillType": 3,
    "riskLevel": 0,
    "tags": ["支付", "金额", "边界"]
  }'

5.2 curl 创建业务规则

curl -X POST 'http://localhost:5010/it/api/business-rule/create' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-token' \
  -d '{
    "projectId": 1,
    "name": "支付金额必须大于 0",
    "ruleCode": "PAY_AMOUNT_GT_ZERO",
    "ruleContent": "支付金额必须大于 0，等于 0 或小于 0 时接口应返回参数错误",
    "priority": 0,
    "tags": ["支付", "金额", "参数校验"]
  }'

---

6. 注意事项

1. 返回字段是后端数据库下划线风格，例如 project_id、created_time。
2. tags 是数组，创建和更新时必须传数组。
3. 删除是软删除。
4. Skill 的 code 和业务规则的 ruleCode 当前不支持更新。
5. 本次接口只做 Skills / Rules 管理，暂未接入 PRD AI 生成用例链路。