feat: 根目录文档、脚本、gitignore

2026-10-08 16:15:33 +08:00
commit e98660ce4e
284 changed files with 26838 additions and 0 deletions
@@ -0,0 +1,33 @@
+# 架构设计：AI 开发 SOP × IT 工作台现有功能（v1 待确认）
+
+设计原则：最大复用现有 zt_* 功能；AI 侧数据一律「框架算、平台存」（用户确认的边界）；新增一律沿用 `zt_story_extend` 扩展表先例，不改禅道老表结构（zt_task 等）。
+
+## 一、SOP 流程逐环节映射（证据：SRC-001；代码证据见行号）
+
+| # | SOP 环节 | 提交物 | 现有功能（证据） | 差距 | 方案 | 分期 |
+|---|---|---|---|---|---|---|
+| 1 | 需求提出→评审激活 | 用户需求 | 全流程已有：`/zt-story-user` userReview 评审通过→active+revieweddate（ZtStoryUserServiceImpl.java:562-578）；前端 userstoryinfo 评审按钮 | `approveddate/activateddate` 死字段（全库无写入） | 小改：userReview 通过时补写 activateddate | 二期 |
+| 2 | 初次讨论 | 会议纪要+PRD 附件 | `/zt-meeting` 有 result 富文本纪要、storyIds 关联需求、PDF 导出；后端附件绑定已就绪（FileTypes.meeting，ZtMeetingServiceImpl.java:159） | **前端附件 UI 已引入未渲染**（addDialog/editDialog 无 `<uploads>`） | 前端渲染 uploads 组件 + 详情页附件区块 | 二期 |
+| 3-5 | AI 生成 PRD→评审→最终版 | PRD 文档/原型图 | 通用上传 `/common/upload`+zt_file；需求/用户需求附件区块已有（FileTypes.story/userStory） | 无 PRD 版本记录 | 不建版本表：PRD 每版生成时间记入 zt_ai_work_log（log_type=prd_version）——KISS | 一期建表/二期打通 |
+| 6 | AI 评估工作量→生成研发需求 | 工作量指标 | **通道已通**：`/zt-story-expand/saveOrUpdate`（demand-assessor 已对接生产）；指标在统计页 /worktime/count 展示 | ①缺 AI 参与率字段 ②storyinfo 详情页无指标区块（孤岛） | ①zt_story_extend 加列 ai_participation_rate ②详情页加 AI 指标区块 | ①一期 ②二期 |
+| 7-8 | 架构设计/验收指标/测试用例 | 验收指标、用例文档 | 验收标准=zt_storyspec.verify 富文本；用例=zt_case+story-case 评审链；附件通道通用 | 验收指标无结构化（富文本可承载，暂不结构化） | 本期复用 verify+附件；结构化验收指标表→后续按需 | 复用 |
+| 9 | AI 拆分任务/评估工时/分配 | 研发任务 | 任务全流程已有（拆分/指派/zt_effort 工时） | 任务级 AI 工作量指数缺失；zt_task 是禅道老表不宜加列 | **新建 zt_task_extend 扩展表**（沿用 zt_story_extend 先例） | 一期建表 |
+| 10-11 | 开发→AI 代码审查（可回炉） | 代码审查报告 | 完全不存在（全库 grep 零命中） | 净新增 | **新建 zt_ai_code_review** + 上传接口（二期） | 一期建表 |
+| 12-13 | 测试→BUG→复测→报告 | BUG、测试报告 | BUG 全流程已有（/zt-bug）；测试报告无承载（zt_testtask.report 死字段） | 测试报告无上传入口 | FileTypes 加 testReport + 附件入口 | 二期 |
+| 14 | 工作日志/AI 文档更新 | AI 工作日志 | 完全不存在 | 净新增 | **新建 zt_ai_work_log**（8 类 log_type 覆盖 SRC-001 全部日志项） | 一期建表 |
+
+## 二、架构决策
+
+- **AD-1 扩展表模式**：AI 类指标一律进扩展表（zt_story_extend / zt_task_extend / zt_ai_*），不碰 zt_task、zt_story 等禅道老表。依据：zt_story_extend 先例 + 禅道升级兼容。
+- **AD-2 AI 数据统一上传模式**：所有 AI 侧数据（W 值、代码审查、工作日志、AI 参与率）由 AI 框架计算后经 saveOrUpdate 类接口写入，zentao 只存不算（用户确认边界）。上传接口鉴权策略待决（Q4-1：现状 saveOrUpdate 无 token 直连，见 itsm_post.py）。
+- **AD-3 文档类走 zt_file 通用通道**：PRD/原型图/测试报告不建专用表，FileTypes 扩展 testReport；PRD 版本时间进 zt_ai_work_log。
+- **AD-4 展示打通集中二期**：storyinfo 增 AI 区块（指标/审查/日志）、meeting 附件渲染、测试报告入口——均为前端轻改，后端一期仅落模型。
+- **AD-5 绩效消费三期**：IZtCountService 目前完全不消费 zt_story_extend（孤岛），三期按 SRC-002 公式接入工作量指数完成率等指标。
+
+## 三、分期方案
+
+| 期 | 内容 | 验收依据 |
+|---|---|---|
+| **一期（本期 MVP，W=10.2）** | 数据模型：zt_ai_code_review、zt_ai_work_log、zt_task_extend 三张新表 + zt_story_extend 加列；DDL+实体+Mapper+Service+单测 | acceptance v2（AC-1~5），注：任务侧字段落地形式由"加列"细化为"扩展表"，验收条目语义不变 |
+| 二期 | 上传接口（/zt-ai-code-review、/zt-ai-work-log）+ 展示打通（storyinfo AI 区块、meeting 附件、测试报告入口）+ activateddate 补写 | 待二期立项评估 |
+| 三期 | 绩效消费：IZtCountService 接入 AI 指标，9 岗位考核公式自动化（SRC-002） | 待三期立项评估 |
@@ -0,0 +1,53 @@
+# 数据模型设计（一期 DDL）
+
+风格约束：zt_ 前缀；审计字段沿用现有表惯例（create_user/create_time/update_user/update_time）；String 存数值沿用 zt_story_extend.workloadIndex 先例（框架传什么存什么，平台不计算）。DDL 脚本交付于 `codes/zentao/sql/`，含变更说明头。
+
+## 1. zt_ai_code_review（AI 代码审查报告）——SRC-001「审查事项、审查结果」
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | int PK AI | |
+| story_id | int NOT NULL | 关联研发需求 zt_story.id，建索引 |
+| task_id | int NULL | 可选关联任务（按任务审查时） |
+| round | int DEFAULT 1 | 审查轮次（SOP 允许打回重审） |
+| review_item | text | 审查事项（清单/JSON 文本） |
+| review_result | varchar(20) | 审查结果：pass / reject |
+| review_detail | text | 结果详情（问题列表、严重度） |
+| review_time | datetime | 审查时间 |
+| create_user / create_time / update_user / update_time | 审计字段 | |
+
+## 2. zt_ai_work_log（AI 工作日志）——SRC-001 八类日志
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | int PK AI | |
+| story_id | int NOT NULL | 关联研发需求，建索引 |
+| log_type | varchar(32) NOT NULL | 枚举：prd_version / workload_eval / arch_design / arch_review / task_split / gate_check / code_review / doc_update（与 SRC-001 思维导图 8 项一一对应），联合索引 (story_id, log_type) |
+| content | text | 日志内容（如 PRD 版本号、评估结果快照） |
+| result | varchar(255) | 结果（如评审通过/不通过） |
+| happen_time | datetime | 事件发生时间（AI 框架侧时间） |
+| create_time | datetime | 入库时间 |
+
+## 3. zt_task_extend（任务扩展表）——SRC-001「AI 评估的任务工作量指数」
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | int PK AI | |
+| task_id | int NOT NULL UNIQUE | 关联 zt_task.id |
+| ai_workload_index | varchar(16) | AI 评估任务工作量指数（只存不算，风格同 zt_story_extend.workloadIndex） |
+| evaluation_time | varchar(16) | AI 评估工时（对齐需求级字段命名） |
+| create_user / create_time / update_user / update_time | 审计字段 | |
+
+## 4. zt_story_extend 加列
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| ai_participation_rate | varchar(16) | AI 参与率（只存不算，口径由 AI 框架定，注释标「口径待定」） |
+
+## 5. 复用不改动的表（映射核对清单，AC-3）
+
+用户需求 zt_story_user（openeddate/revieweddate/activateddate*死字段二期补写）、会议 zt_meeting（result/storyIds + FileTypes.meeting）、附件 zt_file、验收标准 zt_storyspec.verify、任务工时 zt_task+zt_effort、BUG zt_bug、用例 zt_case、需求级 AI 指标 zt_story_extend。
+
+## 6. 二期预备（不进一期 DDL）
+
+FileTypes 枚举加 testReport；枚举实体 LogTypeEnums 随一期实体生成（Java 侧枚举，不落库表）。
@@ -0,0 +1,32 @@
+# 接口设计
+
+## 一期（本期）：无新增接口
+
+边界已确认（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。