345 lines
18 KiB
Markdown
345 lines
18 KiB
Markdown
# AI 交互接口文档 —— 禅道 AI SOP 改造（二期）
|
||
|
||
> **版本**：v1.0 ｜ **日期**：2026-08-06 ｜ **关联改动**：CHG-039 ~ CHG-070（鉴权落地 CHG-061）
|
||
> **验证状态**：✅ 已验证（全部字段/分支/错误文案均取自运行代码实证，非推测）
|
||
> **证据位置**：见文末「证据映射表」；单测 24 绿、8086 三×三鉴权矩阵实测通过（dev_log CHG-061）
|
||
> **适用范围**：AI 框架通道（demand-assessor / pmassist / tgassist 等技能脚本）与 zentao 后端的全部交互接口
|
||
|
||
---
|
||
|
||
## 1. 通用约定
|
||
|
||
### 1.1 Base URL
|
||
|
||
| 环境 | Base URL | 说明 |
|
||
|---|---|---|
|
||
| 本地测试 | `http://127.0.0.1:8085/zentao` | 框架脚本（submit_assessment.py / upload_md.py）默认地址（CHG-061 拍板"别用正线的 url"） |
|
||
| 测试库直连验证 | `192.168.1.161:3306/zentao_dev` | DB 回读校验用，非接口地址 |
|
||
| 生产 | `http://192.168.1.105:8015/zentao` | ⚠️ [ASSUMPTION] 端口 8015 见 dev_log CHG-070"发布 8015 即可生效"；主机地址以部署实为准 |
|
||
|
||
- 所有路径均含上下文根 `/zentao`（部署于域名根路径）。
|
||
- 字符集 UTF-8；JSON 接口 `produces = application/json; charset=UTF-8`。
|
||
|
||
### 1.2 鉴权（CHG-061 落地）
|
||
|
||
- 请求头：**`Authorization: {token}`**（JWT，由 `JwtAuthenticationFilter` 解析，写入 `RiskUserThreadLocal`）。
|
||
- token 获取（人工/调试用）：
|
||
```
|
||
POST /zentao/zt-user/login
|
||
Content-Type: application/json
|
||
{"account":"admin","password":"<md5(密码)>"}
|
||
→ 响应 data 即 token
|
||
```
|
||
- **AI 通道使用 ai 账户永久 token**（生成于 `.claude/ai_token.txt`，框架两脚本自动携带，无需手工管理）。
|
||
- token 缺失或无效：过滤器直接返回 `{"code":-1,"message":"请登录"}`，不进入业务层。
|
||
|
||
**接口级权限矩阵**：
|
||
|
||
| 接口 | 权限要求 | 越权响应 |
|
||
|---|---|---|
|
||
| `/zt-story-expand/saveOrUpdate` | **仅 ai 账户 token** | `code:-1` "该接口仅AI框架通道可用（需ai账户token）" |
|
||
| `/zt-task/aiBatchAdd` | **仅 ai 账户 token** | `code:-1` "aiBatchAdd仅AI框架通道可用（需ai账户token）" |
|
||
| `/common/uploadBind` | **任意登录态**（AI 带 ai token；UI 带用户 token） | `code:-1` "请登录（上传需携带有效token）" |
|
||
|
||
### 1.3 统一响应结构
|
||
|
||
```json
|
||
{ "code": 0, "message": "成功", "data": { } }
|
||
```
|
||
|
||
| code | 含义 | 触发 |
|
||
|---|---|---|
|
||
| `0` | 成功 | 正常返回（data 可为 null） |
|
||
| `-1` | 失败 | 业务校验失败（BusinessException，message 为具体原因）；文件为空；未登录 |
|
||
| `-2` | 重复添加 | 框架保留码，本三接口未使用 |
|
||
| `401` | 请登录 | 框架保留码；实际未登录返回 `-1` + "请登录"（过滤器写死） |
|
||
|
||
### 1.4 AI 框架典型调用时序
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Skill as AI 技能脚本<br/>(demand-assessor/tgassist)
|
||
participant ZT as zentao 后端
|
||
participant DB as MySQL (zt_*)
|
||
|
||
Note over Skill: .claude/ai_token.txt<br/>自动读 ai 永久 token
|
||
Skill->>ZT: ① POST /zt-story-expand/saveOrUpdate<br/>(W 指标 + 验收标准 MD)
|
||
ZT->>DB: upsert zt_story_expand（按 story_id）
|
||
Skill->>ZT: ② POST /zt-task/aiBatchAdd<br/>(拆分 devel/test 任务)
|
||
ZT->>DB: insert zt_task × N（跳过重复）<br/>+ zt_action 留痕（任务级+需求级）
|
||
Skill->>ZT: ③ POST /common/uploadBind<br/>(PRD/审查报告/日志等 MD 文件)
|
||
ZT->>DB: 刷新主表 url 字段 → 插 zt_file<br/>+ zt_action 动态
|
||
ZT-->>Skill: {"code":0,"data":zt_file 记录}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 接口一览
|
||
|
||
| # | 接口 | 方法 | 路径 | Content-Type | 鉴权 | 用途 | 关联 FR |
|
||
|---|---|---|---|---|---|---|---|
|
||
| 1 | AI 评估指标与验收标准提交 | POST | `/zentao/zt-story-expand/saveOrUpdate` | application/json | 仅 ai token | 七步评估结果（S/B/F(T)/G(A)/W）+ 验收标准 MD 落库 | FR-004 |
|
||
| 2 | AI 批量拆分任务 | POST | `/zentao/zt-task/aiBatchAdd` | application/json | 仅 ai token | 按任务清单批量建 devel/test 任务，防重跳过 | FR-006 |
|
||
| 3 | 文件上传并绑定业务对象 | POST | `/zentao/common/uploadBind` | multipart/form-data | 任意登录态 | 上传 MD 等文件，同步刷新主表 url 字段 | FR-002/005/008/010/011 |
|
||
|
||
---
|
||
|
||
## 3. 接口 1：AI 评估指标与验收标准提交
|
||
|
||
```
|
||
POST /zentao/zt-story-expand/saveOrUpdate
|
||
Content-Type: application/json
|
||
Authorization: {ai token}
|
||
```
|
||
|
||
**用途**：demand-assessor 七步评估完成后，将工作量指标与 AI 框架验收标准写入 `zt_story_expand`（按 `story_id` upsert）。生产侧由 `submit_assessment.py` 调用。
|
||
|
||
### 3.1 请求体字段（ZtStoryExpand）
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `storyId` | Integer | ✅ | 需求 ID（zt_story.id）。**为空时服务端静默返回成功、不处理**（见 3.2 分支②） |
|
||
| `numberUnits` | Integer | 评估时✅ | 单元数量 S |
|
||
| `unitBusinessComplexity` | String | 评估时✅ | 单元业务复杂度 B（如 `"2.2"`） |
|
||
| `technicalComplexityCoefficient` | String | 评估时✅ | 技术复杂度系数 F(T)（如 `"1.4"`） |
|
||
| `aiEfficiencyCoefficient` | String | 评估时✅ | AI 效率系数 G(A)（如 `"0.55"`） |
|
||
| `evaluationTime` | BigDecimal | 评估时✅ | 评估工时 W（人日，如 `5.1`） |
|
||
| `workloadIndex` | String | 否 | 工作量指数（finished 结算时优先取库内已有值） |
|
||
| `aiParticipationRate` | String | 否 | AI 参与率（只存不算，口径待定） |
|
||
| `requirementStatus` | String | 否 | `inProgress`（默认）/ `finished`；**finished 触发月度工作量结算** |
|
||
| `requirementCompletionDegree` | String | 否 | 需求完成度 `"0"~"100"`；finished 时被强制置 `"100"` |
|
||
| `acceptanceCriteria` | String | 否 | AI 框架验收指标（Given/When/Then，MD 文本）。与老验收标准 `zt_storyspec.verify` 互不干扰（CHG-022） |
|
||
| `productPerson` / `developPerson` / `testPerson` | String | 否 | 产品/开发/测试人员（中文名） |
|
||
| `id` / `createTime` / `updateTime` / `createUser` / `updateUser` | — | 无需传 | 服务端维护（id 自增，时间戳自动写） |
|
||
| `storyTitle` / `createUserNickname` / `month` / `monthEvaluationTime` | — | 无需传 | 非数据库字段（查询展示/内部结算用） |
|
||
|
||
### 3.2 业务规则与分支
|
||
|
||
| # | 分支 | 行为 |
|
||
|---|---|---|
|
||
| ① | token 非 ai 账户 | 拒绝：`-1` "该接口仅AI框架通道可用（需ai账户token）" |
|
||
| ② | `storyId` 为空 | **静默返回 `code:0`**，不建不改（注意：不等于参数报错） |
|
||
| ③ | 该 storyId 无记录 | insert；`requirementStatus` 未传时默认 `inProgress`；create/updateTime=now |
|
||
| ④ | 已有记录且其状态为 `finished` | **拒绝**："该需求已完成，不可再修改"（守卫：定稿后不可覆写） |
|
||
| ⑤ | 已有记录（非 finished） | update by id，updateTime=now |
|
||
| ⑥ | 本次提交 `requirementStatus=finished` | 强制完成度 `"100"`；写当月 `zt_story_month_workload`：增量 = 100 − 历史最高完成度；折算工时 = 工作量指数 × 增量 ÷ 100（2 位小数 HALF_UP）；增量 ≤ 0 记 0 |
|
||
| ⑦ | 幂等性 | 同 storyId 重复提交 = 覆盖更新，不产生重复行 |
|
||
|
||
### 3.3 报文示例
|
||
|
||
```json
|
||
{
|
||
"storyId": 9130,
|
||
"numberUnits": 3,
|
||
"unitBusinessComplexity": "2.2",
|
||
"technicalComplexityCoefficient": "1.4",
|
||
"aiEfficiencyCoefficient": "0.55",
|
||
"evaluationTime": 5.1,
|
||
"workloadIndex": "5.1",
|
||
"developPerson": "魏冬霞",
|
||
"testPerson": "罗勇",
|
||
"acceptanceCriteria": "## AC-001\n- Given ...\n- When ...\n- Then ..."
|
||
}
|
||
```
|
||
|
||
### 3.4 响应
|
||
|
||
```json
|
||
{ "code": 0, "message": "成功", "data": null }
|
||
```
|
||
|
||
失败：`{ "code": -1, "message": "该接口仅AI框架通道可用（需ai账户token）" }` / `{ "code": -1, "message": "该需求已完成，不可再修改" }`
|
||
|
||
---
|
||
|
||
## 4. 接口 2：AI 批量拆分任务
|
||
|
||
```
|
||
POST /zentao/zt-task/aiBatchAdd
|
||
Content-Type: application/json
|
||
Authorization: {ai token}
|
||
```
|
||
|
||
**用途**：按任务清单为指定需求批量创建研发/测试任务；同需求下重名同类型任务自动跳过。生产侧由任务拆分流程（tasks.md → zentao）调用。
|
||
|
||
### 4.1 请求体字段（ZtTaskAiBatchDTO）
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `storyId` | Integer | ✅ | 需求 ID；不存在则整批拒绝 |
|
||
| `tasks` | Array | ✅ 非空 | 任务项列表 |
|
||
| `tasks[].name` | String | ✅ | 任务名称（空则整批拒绝） |
|
||
| `tasks[].type` | String | ✅ | 仅 `devel`（开发）/ `test`（测试）；其他值**整批拒绝** |
|
||
| `tasks[].assignedTo` | String | 否 | 指派人账号（zt_user.account）；留痕时转中文昵称显示 |
|
||
| `tasks[].aiEvaluationTime` | Float | 否 | AI 评估工时 → 同时写入 `estimate` 与 `left`，`consumed=0` |
|
||
| `tasks[].planStartDate` | String | 否 | 预计开始 `yyyy-MM-dd` → `estStarted` |
|
||
| `tasks[].deadline` | String | 否 | 预计完成 `yyyy-MM-dd` → `deadline`，并写 `deadlineTime`（秒级时间戳） |
|
||
|
||
### 4.2 业务规则与分支
|
||
|
||
| # | 分支 | 行为 |
|
||
|---|---|---|
|
||
| ① | token 非 ai 账户 | 拒绝：`-1` "aiBatchAdd仅AI框架通道可用（需ai账户token）" |
|
||
| ② | `storyId` 空 / 需求不存在 / `tasks` 空 / 任一 name 空 / 任一 type 非 devel\|test / 日期格式错 | **整批拒绝**（BusinessException，事务回滚，一个都不建） |
|
||
| ③ | 防重 | 同需求下已存在 `name#type`（未删除）→ 跳过并记入 `skipped`；**批内重复同样防重**（建过的 key 即时入集合） |
|
||
| ④ | 创建字段 | `status=wait`、`openedby=ai`（token 身份）、`openeddate=now`、`estimate=left=aiEvaluationTime` |
|
||
| ⑤ | 留痕（CHG-059/060/062） | 任务级：`zt_action`（RW+XJ）每任务一条，与手工建任务同形状；需求级：**一批合并一条**（XQ+BJ），文案含个数、序号、各任务名称/类型/工时/指派中文名、跳过数 |
|
||
| ⑥ | 日期格式 | 非法日期整批拒绝："日期格式错误，应为yyyy-MM-dd:{任务名}" |
|
||
|
||
### 4.3 报文示例
|
||
|
||
```json
|
||
{
|
||
"storyId": 9130,
|
||
"tasks": [
|
||
{"name": "二期 DDL×3 + 自测", "type": "devel", "assignedTo": "guoqibing",
|
||
"aiEvaluationTime": 8, "planStartDate": "2026-08-10", "deadline": "2026-08-11"},
|
||
{"name": "后端接口测试：uploadBind/aiBatchAdd", "type": "test", "assignedTo": "zhangfubin",
|
||
"aiEvaluationTime": 8, "planStartDate": "2026-08-12", "deadline": "2026-08-12"}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 4.4 响应
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "成功",
|
||
"data": {
|
||
"created": 2,
|
||
"taskIds": [18565, 18566],
|
||
"skipped": ["二期 DDL×3 + 自测"]
|
||
}
|
||
}
|
||
```
|
||
|
||
- `created`：本次实际新建数；`taskIds`：新建任务 ID 列表；`skipped`：因重名同类型跳过的任务名列表。
|
||
- 全部重复时：`created:0`、`taskIds:[]`、`skipped` 全量 —— 仍返回 `code:0`（跳过不算失败）。
|
||
|
||
---
|
||
|
||
## 5. 接口 3：文件上传并绑定业务对象
|
||
|
||
```
|
||
POST /zentao/common/uploadBind
|
||
Content-Type: multipart/form-data
|
||
Authorization: {任意登录态 token}
|
||
```
|
||
|
||
**用途**：上传文件（AI 框架场景为 MD 文档）并一步绑定到业务对象：写磁盘 + 插 `zt_file` + **按 objectType 刷新主表访问链接字段** + 写动态留痕。生产侧由 `upload_md.py` 调用（默认本地 8085、自动带 ai token）。
|
||
|
||
### 5.1 表单字段（UploadDTO）
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `file` | File | ✅ | 上传文件（空文件拒绝）；服务端仅保留原扩展名，文件名为 `yyyyMMddHHmmss + UUID` |
|
||
| `objectType` | String | ✅ | 业务对象类型，**白名单 9 类**（见 5.2）；不在白名单整体拒绝 |
|
||
| `objectId` | Integer | ✅ | 主表记录 ID（需求/会议）；记录不存在则拒绝 |
|
||
| `title` | String | 否 | 文件标题；缺省取原始文件名（中文标题落库正确，CHG-061 已验证） |
|
||
| `reviewResult` | String | 否 | **仅 `objectType=aiCodeReview` 有效**：`pass` / `reject`，非空时同步写 `zt_story.code_review_status` |
|
||
|
||
### 5.2 objectType → 主表字段刷新映射（白名单）
|
||
|
||
| objectType | 含义 | 刷新主表字段 | 动态留痕 |
|
||
|---|---|---|---|
|
||
| `story` | PRD/需求文档 | `zt_story.prd_url` | XQ+BJ |
|
||
| `aiCodeReview` | 代码审查报告 | `zt_story.code_review_url`（+`code_review_status`，若传 reviewResult） | XQ+BJ |
|
||
| `aiWorkLog` | 工作日志 | `zt_story.work_log_url` | XQ+BJ |
|
||
| `aiDocUpdate` | AI 项目文档更新记录 | `zt_story.ai_doc_update_url` | XQ+BJ |
|
||
| `testCase` | 测试用例 | `zt_story.test_case_url` | XQ+BJ |
|
||
| `testReport` | 测试报告模版 | `zt_story.test_report_download_url` | XQ+BJ |
|
||
| `testReportSubmit` | 测试报告提交 | `zt_story.test_report_submit_url` | XQ+BJ |
|
||
| `testOther` | 其他测试文档 | `zt_story.test_other_url` | XQ+BJ |
|
||
| `meeting` | 会议纪要 | `zt_meeting.url` | MEET+BJ |
|
||
|
||
> FileTypes 枚举另有 task/bug/userStory 等 6 个 code，但 **uploadBind 不支持**——传入会拒绝："uploadBind不支持的objectType:{type}"。
|
||
|
||
### 5.3 业务规则与分支
|
||
|
||
| # | 分支 | 行为 |
|
||
|---|---|---|
|
||
| ① | 无登录态 | `-1` "请登录（上传需携带有效token）" |
|
||
| ② | file 为空 | `-1` "失败" |
|
||
| ③ | objectType/objectId 为空 | `-1` "objectType/objectId不能为空" |
|
||
| ④ | objectType 非枚举值 | "不支持的objectType:{type}"；是枚举但非白名单 → "uploadBind不支持的objectType:{type}" |
|
||
| ⑤ | objectId 记录不存在 | "需求不存在:{id}" / "会议不存在:{id}" |
|
||
| ⑥ | 执行顺序（事务） | **先校验并刷新主表 → 失败整体回滚不落盘**；再写磁盘 → 插 `zt_file` → 写 `zt_action`（文案含完整可访问 URL） |
|
||
| ⑦ | 落库字段 | `zt_file.addedby` = token 身份；`pathname`/`url` = 相对路径 `/zentao/img/{文件名}`（经前端源/代理可达，规避跨域）；`size` 字节数；`extension` 原扩展名 |
|
||
| ⑧ | 多文件 | 同一 (objectType, objectId) 可多次上传，形成多份列表；主表 url 字段记录**最新一份**，前端列表取 `zt_file` 全集 |
|
||
|
||
### 5.4 调用示例
|
||
|
||
```bash
|
||
curl -X POST "http://127.0.0.1:8085/zentao/common/uploadBind" \
|
||
-H "Authorization: {ai token}" \
|
||
-F "file=@代码审查报告.md" \
|
||
-F "objectType=aiCodeReview" \
|
||
-F "objectId=9130" \
|
||
-F "title=代码审查报告-v1" \
|
||
-F "reviewResult=pass"
|
||
```
|
||
|
||
### 5.5 响应
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "成功",
|
||
"data": {
|
||
"id": 1234,
|
||
"title": "代码审查报告-v1",
|
||
"extension": ".md",
|
||
"size": 5321,
|
||
"pathname": "/zentao/img/20260806170215a1b2c3....md",
|
||
"url": "/zentao/img/20260806170215a1b2c3....md",
|
||
"objecttype": "aiCodeReview",
|
||
"objectid": 9130,
|
||
"addedby": "ai",
|
||
"addeddate": "2026-08-06 17:02:15",
|
||
"deleted": "0"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 失败分支汇总（排障速查）
|
||
|
||
| 现象 | code | message | 排查 |
|
||
|---|---|---|---|
|
||
| 未带 token / token 失效 | -1 | 请登录 | 检查 `Authorization` 头；ai token 见 `.claude/ai_token.txt` |
|
||
| 用人工 token 调 saveOrUpdate / aiBatchAdd | -1 | 仅AI框架通道可用（需ai账户token） | 换 ai token；这是设计守卫，非缺陷 |
|
||
| 需求已 finished 再提交指标 | -1 | 该需求已完成，不可再修改 | 生产 itsm 已有 finished 记录被此守卫拒绝（summary 2026-08-06），属按设计拦截 |
|
||
| saveOrUpdate 返回 0 但库里没数据 | 0 | 成功 | 检查是否漏传 `storyId`（分支 3.2② 静默成功） |
|
||
| aiBatchAdd 一个任务都没建 | -1 | （任一校验消息） | 整批拒绝机制：任一任务非法全部回滚；先修非法项 |
|
||
| aiBatchAdd 成功但 created=0 | 0 | 成功 | 全部命中防重，看 `skipped` |
|
||
| uploadBind 报类型不支持 | -1 | (uploadBind)不支持的objectType | 对照 5.2 白名单（9 类） |
|
||
| uploadBind 成功但页面看不到 | 0 | 成功 | 前端列表读 `zt_file`；检查 objectType/objectId 是否传对、前端是否按类型渲染 |
|
||
|
||
---
|
||
|
||
## 7. 证据映射表
|
||
|
||
| 章节 | 关键结论 | 证据来源 |
|
||
|---|---|---|
|
||
| 1.2 鉴权 | Authorization 头 JWT 解析、越权文案 | [CODE:codes/zentao/src/main/java/com/sa/zentao/conf/JwtAuthenticationFilter.java:41-66] [CODE:ZtStoryExpandServiceImpl.java:41-45] [CODE:ZtTaskServiceImpl.java:1360-1364] [CODE:CommonsController.java:129-132] |
|
||
| 1.3 响应结构 | Result/Code 枚举值 | [CODE:codes/zentao/src/main/java/com/sa/zentao/dao/Result.java] [CODE:codes/zentao/src/main/java/com/sa/zentao/dao/Code.java] [CODE:conf/GlobalExceptionHandler.java:28-32] |
|
||
| 3. 接口1 | 字段集/upsert/finished 守卫与结算 | [CODE:entity/ZtStoryExpand.java] [CODE:ZtStoryExpandServiceImpl.java:40-79,120-150] |
|
||
| 4. 接口2 | 字段/整批拒绝/防重/留痕形状 | [CODE:dao/ZtTaskAiBatchDTO.java] [CODE:ZtTaskServiceImpl.java:1357-1470] |
|
||
| 5. 接口3 | 白名单映射/事务顺序/落库字段 | [CODE:CommonsController.java:120-187] [CODE:ZtFileServiceImpl.java:74-154] [CODE:enums/FileTypes.java] [CODE:dao/UploadDTO.java] |
|
||
| 1.1/运行实证 | 8085 默认地址、token 自动携带、中文标题正确 | [RUNTIME:dev_log CHG-061 闭环记录] [RUNTIME:summary.md 2026-08-06] |
|
||
|
||
## 8. 假设与缺口
|
||
|
||
| 项 | 状态 | 说明 |
|
||
|---|---|---|
|
||
| 生产 Base URL | ⚠️ [ASSUMPTION] | 8015 端口见于 dev_log CHG-070；生产主机/域名以部署实为准，发布时确认 |
|
||
| `evaluationTime` 单位 | ✅ 已确认 | 人日（demand-assessor W 定义，summary 附录口径一致） |
|
||
| `deadlineTime` 精度 | ✅ 已验证 | 秒级时间戳（ZtTaskServiceImpl.java:1425） |
|
||
| ai 永久 token 过期策略 | ✅ 已确认 | 永久 token（CHG-061 决策，存 `.claude/ai_token.txt`） |
|
||
|
||
---
|
||
|
||
> 下一步（Check）：本文档与 `outputs/dev_plan.md`、`06_test_docs/test_cases.md` §0 环境约定一致；如发现不一致以运行代码为准修正本文档（Runtime 事实优先）。
|