项目交付验收摘要与下载门禁设计

状态： 已实现（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. 证据计算

查询项目最近一个会改变源码的任务：one_click_project 或 database_change_sync。
previewStatus=1 且任务结果确认 downloadReady=true 时，源码草稿可用；没有任务的旧项目只按 previewStatus 进入兼容草稿模式。
一键任务本身必须为 SUCCEEDED，其结果或源码阶段必须关联一个属于当前用户和项目的成功 Generation Run。
Generation Run 必须包含 Spec 版本/哈希、Adapter 版本、Template 版本、聚合内容哈希和非空文件清单。
最新尝试的 RUN_PREVIEW 阶段必须为 SUCCEEDED；旧阶段账本为空时可回退到结果中的 previewStatus=RUNNING。
数据库变更同步产生的源码只能作为草稿，直到后续质量运行创建新的可追溯认证证据。

6. API

新增：

GET /front/project/{projectId}/delivery-readiness

现有下载接口增加参数：

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 解析与开发服务检查均已通过。

5.9 KiB Raw Blame History Unescape Escape