104 lines
5.9 KiB
Markdown
104 lines
5.9 KiB
Markdown
# 项目交付验收摘要与下载门禁设计
|
||
|
||
**状态：** 已实现（P1-K）
|
||
|
||
## 1. 背景
|
||
|
||
当前 `previewStatus=1` 和 `downloadReady=true` 代表项目结构已经可以渲染成 ZIP，但不代表运行预览成功，也不代表生成产物具备可追溯的 ProjectSpec、Generation Run 和文件清单。项目列表、个人中心、源码预览和一键生成工作台都把这一状态统一显示为“可下载”，公开下载接口也没有服务端质量门禁。
|
||
|
||
运行预览服务内部需要调用现有打包方法创建隔离工作区，因此不能在底层 `downloadAll` 上增加公开下载门禁。本轮把“草稿源码”和“基础验收产物”明确分开，并在 HTTP 下载边界执行最终校验。
|
||
|
||
## 2. 用户目标
|
||
|
||
- 明确区分源码已生成、运行预览已通过、基础验收已通过和允许认证下载。
|
||
- 运行预览失败时仍能下载源码草稿排查问题，但不能把它误称为验收产物。
|
||
- 一键生成成功且具备版本、Generation Run、文件清单和运行预览证据时，可以下载基础验收产物。
|
||
- 高级调整或旧项目仍可下载草稿，不因新门禁突然失去已有能力。
|
||
- 服务端拒绝伪造的认证下载请求，不能只依赖按钮禁用。
|
||
|
||
## 3. 产物类型
|
||
|
||
### `DRAFT`
|
||
|
||
- 条件：项目当前 `previewStatus=1`，且最新源码生产任务确认源码已经生成。
|
||
- 用途：预览、调试、运行预览工作区和人工排查。
|
||
- 不声明已经通过运行或质量验收。
|
||
|
||
### `CERTIFIED`
|
||
|
||
- 条件：源码草稿可用；最新源码生产任务是一键生成；绑定的 Generation Run 成功且包含 Spec、Adapter、Template 和文件清单身份；最新尝试的 `RUN_PREVIEW` 阶段成功。
|
||
- 当前认证等级：`BASELINE`。
|
||
- 后续 Java 测试、前端 Build、SQL 导入和 API Smoke 会继续加入同一门禁，当前不得把 BASELINE 描述为完整生产认证。
|
||
|
||
## 4. 交付状态
|
||
|
||
| 状态 | 含义 |
|
||
| --- | --- |
|
||
| `DRAFT` | 尚无可下载源码 |
|
||
| `SOURCE_READY` | 源码草稿已生成 |
|
||
| `PREVIEW_PASSED` | 运行预览通过，但版本追踪或基础验收尚未齐全 |
|
||
| `ACCEPTED` | 基础验收通过，允许认证下载 |
|
||
|
||
交付摘要固定返回四个用户检查项：源码生成、运行预览、基础验收、认证下载。每项状态为 `PASSED`、`PENDING` 或 `FAILED`，并附短说明和下一步动作。
|
||
|
||
## 5. 证据计算
|
||
|
||
1. 查询项目最近一个会改变源码的任务：`one_click_project` 或 `database_change_sync`。
|
||
2. `previewStatus=1` 且任务结果确认 `downloadReady=true` 时，源码草稿可用；没有任务的旧项目只按 `previewStatus` 进入兼容草稿模式。
|
||
3. 一键任务本身必须为 `SUCCEEDED`，其结果或源码阶段必须关联一个属于当前用户和项目的成功 Generation Run。
|
||
4. Generation Run 必须包含 Spec 版本/哈希、Adapter 版本、Template 版本、聚合内容哈希和非空文件清单。
|
||
5. 最新尝试的 `RUN_PREVIEW` 阶段必须为 `SUCCEEDED`；旧阶段账本为空时可回退到结果中的 `previewStatus=RUNNING`。
|
||
6. 数据库变更同步产生的源码只能作为草稿，直到后续质量运行创建新的可追溯认证证据。
|
||
|
||
## 6. API
|
||
|
||
新增：
|
||
|
||
```http
|
||
GET /front/project/{projectId}/delivery-readiness
|
||
```
|
||
|
||
现有下载接口增加参数：
|
||
|
||
```http
|
||
GET /front/project/{projectId}/download?artifactType=DRAFT|CERTIFIED
|
||
```
|
||
|
||
- 未传参数继续按 `DRAFT` 处理，兼容现有调用。
|
||
- `CERTIFIED` 必须通过服务端门禁。
|
||
- `DRAFT` 也必须确认当前源码草稿可用。
|
||
- 响应增加 `X-Factory-Artifact-Type` 和 `X-Factory-Certification-Level`，不改变 ZIP 内部生成方式。
|
||
|
||
## 7. 前端交互
|
||
|
||
- 一键生成结果区新增交付验收带，显示四项检查和下一步。
|
||
- 基础验收通过时按钮显示“下载验收源码”，请求 `CERTIFIED`。
|
||
- 只有源码就绪时按钮显示“下载源码草稿”，请求 `DRAFT`。
|
||
- 项目列表、个人中心和源码预览页现有下载入口明确改名为“下载源码草稿”。
|
||
- 交付摘要加载失败不覆盖已经完成的生成任务，只降级为草稿状态并让服务端做最终判断。
|
||
|
||
## 8. 边界
|
||
|
||
- 不新增数据库表或迁移。
|
||
- BASELINE 门禁暂不纳入生成项目的 Java 测试、前端 Build、SQL 导入和 API Smoke；本轮只建立可扩展门禁与基础证据。
|
||
- 不改变运行预览内部打包流程。
|
||
- 不修改开发阶段暂缓处理的模型凭据和 TLS 配置。
|
||
|
||
## 9. 验收标准
|
||
|
||
- 运行预览失败的一键任务只能下载草稿，认证下载被服务端拒绝。
|
||
- 一键任务具有完整 Generation Run 与成功运行阶段时可以认证下载。
|
||
- 数据库同步或旧项目不会被误认证，但保留草稿下载。
|
||
- 项目修改导致 `previewStatus=0` 后，草稿和认证下载均被拒绝。
|
||
- 前端四种状态、按钮文案和实际请求产物类型一致。
|
||
|
||
## 10. 实施结果
|
||
|
||
- 新增 `ProjectDeliveryReadinessService`、交付摘要 API、四项用户检查和公开下载边界的服务端门禁。
|
||
- `CERTIFIED` 只接受当前源码对应的完整一键 Generation Run 与最新尝试运行预览证据；数据库同步和兼容旧项目只保留草稿能力。
|
||
- 阶段账本非空时不会回退任务结果中的旧预览状态；最新尝试尚未执行 `RUN_PREVIEW` 时保持待验收。任务非 `SUCCEEDED` 时，即使残留旧证据也不能认证。
|
||
- 项目编辑将 `previewStatus` 复位后，旧的阶段或 Generation Run 证据不能继续开放下载。
|
||
- 一键生成工作台展示交付验收摘要并按服务端结果选择产物类型；项目列表、个人中心和源码预览入口均明确为草稿下载。
|
||
- 独立运行预览重启仍是调试能力，不会补写认证证据。运行预览失败后，用户必须重新执行完整一键生成才能建立新的可追溯验收事实。
|
||
- P1-J/P1-K 后端聚焦测试 32 项、管理端全量测试 42 项、EasyCode 主流程测试 73 项、生产构建、Mapper XML 解析与开发服务检查均已通过。
|