420b9e37fa
1. 新增文档源管理模块（documentSource） - 控制器：documentSourceController.py - DAO层：documentSourceDao.py - 模型：documentSourceModel.py - 服务层：documentSourceService.py 2. 新增技能管理模块（skill） - 控制器：skillController.py - DAO层：skillDao.py - 模型：skillModel.py - 服务层：skillService.py 3. 新增AI服务（aiService.py） 4. 新增配置文件 - AI配置：config/ai_config.py - 技能配置：config/skills/test-case-generator/ 5. 新增SQL脚本 - 文档权限：add_document_permissions.sql - 模块状态字段：add_module_status_field.sql - 文档源表：create_document_source_table.sql - 技能规则：skills_rules_pgsql.sql
609 lines
15 KiB
Markdown
609 lines
15 KiB
Markdown
# 测试 Skills 与业务规则接口文档
|
||
|
||
## 1. 基础说明
|
||
|
||
接口前缀：`/it/api`
|
||
|
||
统一响应：
|
||
|
||
```json
|
||
{
|
||
"code": 20000,
|
||
"msg": "success",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
鉴权：需要登录态 token。
|
||
|
||
建议请求头：
|
||
|
||
```http
|
||
Authorization: Bearer ${token}
|
||
```
|
||
|
||
也兼容：
|
||
|
||
```http
|
||
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
|
||
|
||
```http
|
||
POST /it/api/skill/create
|
||
```
|
||
|
||
权限：`skill:create`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"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`。
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"code": 20000,
|
||
"msg": "success",
|
||
"data": {
|
||
"id": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
常见失败：
|
||
|
||
```json
|
||
{
|
||
"code": 40009,
|
||
"msg": "projectId、name 为必传参数"
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 40009,
|
||
"msg": "AI生成 Skill 内容失败: xxx"
|
||
}
|
||
```
|
||
|
||
***
|
||
|
||
### 3.2 更新 Skill
|
||
|
||
```http
|
||
POST /it/api/skill/update
|
||
```
|
||
|
||
权限：`skill:update`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"skillId": 1,
|
||
"name": "支付金额边界校验",
|
||
"description": "更新后的描述",
|
||
"triggerCondition": "更新后的触发条件",
|
||
"reasoningPath": "更新后的推理路径",
|
||
"outputSpec": "更新后的输出规范",
|
||
"skillType": 3,
|
||
"riskLevel": 0,
|
||
"tags": ["支付", "金额", "边界", "参数校验"],
|
||
"status": 1,
|
||
"ownerId": 8
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- 当前接口不支持更新 `code`。
|
||
- 更新成功后，后端会根据更新后的 Skill 内容重新创建 `SKILL.md` 文件。
|
||
- 新文件路径会同步更新到数据库 `skill_file_path`。
|
||
- 数据库更新成功后会删除原 Skill 文件夹。
|
||
- 如果数据库更新失败，后端会删除新创建的文件夹并保留旧数据库记录和旧文件，避免数据库与文件不一致。
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"code": 20000,
|
||
"msg": "success",
|
||
"data": {
|
||
"id": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
***
|
||
|
||
### 3.3 删除 Skill
|
||
|
||
```http
|
||
POST /it/api/skill/delete
|
||
```
|
||
|
||
权限：`skill:delete`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"skillId": 1
|
||
}
|
||
```
|
||
|
||
说明：软删除，设置 `is_delete = 1`，并删除该 Skill 对应的 `config/skills/{产品名称}/{项目名称}/{模块名称}/{Skill名称}` 文件夹。
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"code": 20000,
|
||
"msg": "success",
|
||
"data": {
|
||
"id": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
***
|
||
|
||
### 3.4 Skill 详情
|
||
|
||
```http
|
||
GET /it/api/skill/detail?skillId=1
|
||
```
|
||
|
||
权限：`skill:detail`
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"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 列表
|
||
|
||
```http
|
||
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 | 否 | 单个标签过滤 |
|
||
|
||
请求示例：
|
||
|
||
```http
|
||
GET /it/api/skill/list?pageNo=1&pageSize=20&projectId=1&moduleId=10&keyword=支付&status=1
|
||
```
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"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 创建业务规则
|
||
|
||
```http
|
||
POST /it/api/business-rule/create
|
||
```
|
||
|
||
权限：`business-rule:create`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"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`。
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"code": 20000,
|
||
"msg": "success",
|
||
"data": {
|
||
"id": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
***
|
||
|
||
### 4.2 更新业务规则
|
||
|
||
```http
|
||
POST /it/api/business-rule/update
|
||
```
|
||
|
||
权限：`business-rule:update`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"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`。
|
||
- 数据库更新成功后会删除原业务规则文件夹。
|
||
- 如果数据库更新失败，后端会删除新创建的文件夹并保留旧数据库记录和旧文件，避免数据库与文件不一致。
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"code": 20000,
|
||
"msg": "success",
|
||
"data": {
|
||
"id": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
***
|
||
|
||
### 4.3 删除业务规则
|
||
|
||
```http
|
||
POST /it/api/business-rule/delete
|
||
```
|
||
|
||
权限：`business-rule:delete`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"ruleId": 1
|
||
}
|
||
```
|
||
|
||
说明：软删除，设置 `is_delete = 1`，并删除该业务规则对应的 `config/rules/{产品名称}/{项目名称}/{模块名称}/{规则名称}` 文件夹。
|
||
|
||
***
|
||
|
||
### 4.4 业务规则详情
|
||
|
||
```http
|
||
GET /it/api/business-rule/detail?ruleId=1
|
||
```
|
||
|
||
权限：`business-rule:detail`
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"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 业务规则列表
|
||
|
||
```http
|
||
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 | 否 | 单个标签过滤 |
|
||
|
||
请求示例：
|
||
|
||
```http
|
||
GET /it/api/business-rule/list?pageNo=1&pageSize=20&projectId=1&moduleId=10&keyword=金额&status=1
|
||
```
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```bash
|
||
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 创建业务规则
|
||
|
||
```bash
|
||
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 生成用例链路。
|
||
|