# 接口设计

## 一期（本期）：无新增接口

边界已确认（Q2-1）：一期只到 实体+Mapper+Service，不含 Controller。新表 Service 接口（Java 层）：

- `IZtAiCodeReviewService`：saveOrUpdate(ZtAiCodeReview)、listByStoryId(storyId)
- `IZtAiWorkLogService`：saveBatch(storyId, List<ZtAiWorkLog>)、listByStoryId(storyId, logType)
- `IZtTaskExtendService`：saveOrUpdate(ZtTaskExtend)、getByTaskId(taskId)
- `IZtStoryExpandService`：既有方法不变，实体加 aiParticipationRate 字段（saveOrUpdate 自动携带）

## 二期（预设计，立项时评审）

### AI 框架上传接口（参照 /zt-story-expand 模式，platform 只存不算）

| 端点 | 方法 | 报文要点 |
|---|---|---|
| `/zt-ai-code-review/saveOrUpdate` | POST | storyId, taskId?, round, reviewItem, reviewResult(pass/reject), reviewDetail, reviewTime |
| `/zt-ai-work-log/saveBatch` | POST | storyId, logs[{logType, content, result, happenTime}] |

### 前端页面改动清单

| 页面 | 改动 | 证据/备注 |
|---|---|---|
| meeting add/editDialog + info | 渲染 `<uploads>`（组件已 import 未渲染）+ 附件区块 | FileTypes.meeting 后端已就绪 |
| storyinfo 详情 | 新增「AI 指标」区块（读 zt_story_extend 含 AI 参与率）、「代码审查」「工作日志」区块 | 参照 projectWork.vue 既有指标列 |
| bug/testtask 相关页 | 测试报告上传入口 | FileTypes.testReport（二期 DDL） |
| userstoryinfo | 无改动（activateddate 后端补写即可） | |

## 鉴权决策点（Q4-1，二期前必须回答）

现状：`/zt-story-expand/saveOrUpdate` 无 token 直连（itsm_post.py 实证，仅 Content-Type 头）。新上传接口三选一：沿用内网直连 / 加签名 / 纳入 JWT。倾向：沿用现状保持通道一致，风险记入 risks.md。