# 项目生成工厂 V1 收口设计

**状态：** 已实施并通过代码回归（P1-M / P1-N / P1-O，2026-07-12）

## 1. 目标

在 P1-L 持久化 Quality Run 之上完成三个剩余轮次：冻结认证源码制品；把运行预览迁移到持久化 Docker Preview Worker；使用黄金样例形成可追溯的 V1 端到端验收记录。完成后，项目生成工厂 V1 主线关闭，Knowledge Pack、多技术栈 Adapter 和插件市场继续留在 V2。

## 2. P1-M 认证制品固化

- 新增 `factory_project_certified_artifact`，唯一绑定通过的 Quality Run、Generation Run 和源码聚合哈希。
- Quality Worker 四项检查通过后，重新读取同一服务端源码 ZIP，计算 ZIP SHA-256，生成规范化质量报告并计算报告 SHA-256。
- ZIP 和报告通过 `CertifiedArtifactStore` 写入不可变对象路径；本地实现使用临时文件、原子移动和只读最终路径，接口允许后续替换 S3/OSS。
- 制品记录只在 ZIP、报告及两项哈希全部持久化后进入 `READY`。失败记录不可下载，不覆盖旧制品。
- `CERTIFIED` 下载必须读取当前 Quality Run 对应的 READY 冻结 ZIP，并返回制品 ID、ZIP SHA-256、报告 SHA-256 和冻结时间响应头；不得调用临时源码重新打包。
- `DRAFT` 下载保持兼容，仍可按当前项目即时打包。

## 3. P1-N 隔离容器预览

- 新增 `factory_project_preview_job`，状态为 `QUEUED`、`CLAIMED`、`STARTING`、`RUNNING`、`STOP_REQUESTED`、`STOPPED`、`FAILED`、`EXPIRED`。
- Web 请求只校验项目、创建或返回活动 Job，不解压、不分配本机进程、不直接运行生成项目。
- `ProjectPreviewJobWorker` 可独立部署，通过租约和 fencing token 认领 Job；Web 节点默认关闭 Worker，Preview Worker 部署显式开启。
- `PreviewContainerRuntime` 负责启动、检查和停止容器。本地生产实现只调用 Docker CLI，并强制 CPU、内存、PIDs、只读根文件系统、临时文件系统、标签、网络和 TTL 参数。
- 源码 ZIP 只写入 Worker 输入目录，容器以只读挂载读取；运行输出、脱敏日志和页面截图写入独立输出目录。
- Job 持久化公开 URL、容器 ID 哈希、截图 SHA-256、过期时间和有界日志，不公开宿主路径、Docker socket、数据库凭据或原始容器 ID。
- 过期 Job 由 Worker 停止容器并标记 `EXPIRED`；停止操作幂等。

## 4. P1-O 端到端验收

- 新增 `factory_project_v1_acceptance_run` 和有序检查表，绑定用户、项目、Generation Run、Quality Run、认证制品和 Preview Job。
- 固定五项黄金样例检查：`GENERATION`、`FAILURE_RECOVERY`、`VERSION_ROLLBACK`、`CONTAINER_PREVIEW`、`CERTIFIED_DOWNLOAD`。
- 验收器只调用项目工厂公开服务边界，不直接修改内部状态。每项记录脱敏摘要、证据 SHA-256、时间和耗时。
- 认证下载检查要求连续读取两次得到相同制品 ID、长度和 SHA-256；预览检查要求 Docker Job 为 RUNNING、截图存在且未过 TTL。
- 版本回滚必须产生新版本/Generation Run，不能覆写历史版本；失败恢复必须证明失败任务保留、重试产生新尝试且从可信检查点继续。
- 五项全部通过才将 V1 Acceptance Run 标记为 `PASSED`。失败保留证据，可新建下一次验收，不覆盖历史。
- 提供启动、最新和历史 API；EasyCode 交付区展示 V1 验收状态，不展示内部指纹和执行 Payload。

## 5. 数据与安全边界

- 三组新表同步写入独立升级脚本、`front_workbench.sql` 和 `db.sql`。
- 不自动连接或迁移外部数据库。
- 不修改开发阶段暂缓的模型明文凭据和 TLS 设置。
- Docker 不可用时 Preview Job 明确失败并保留诊断，不回退到主进程直接运行。
- 所有路径必须位于配置根目录下，ZIP 解压继续拒绝路径穿越，日志和错误信息继续脱敏和限长。

## 6. V1 完成标准

- Quality Run 通过后可查询且只能下载冻结认证制品。
- 相同认证下载重复读取字节和哈希完全一致。
- Web 进程不再直接启动生成项目进程；预览由持久化 Worker 和 Docker Runtime 执行。
- 预览具备截图、TTL、停止、资源限制和失败诊断。
- 黄金样例五项验收可持久化执行并形成可重跑证据。
- 旧临时认证下载入口和不一致文案清理完成，草稿与认证制品语义明确。

## 7. 实施与部署边界

- P1-M 已完成：Quality Worker 在终态前冻结 ZIP 和规范化质量报告；`CERTIFIED` 下载只读取 READY 对象并校验 SHA-256。
- P1-N 已完成：生产 Spring 边界改为持久化 Preview Job；旧宿主进程类不再注册。独立 Worker 使用 Docker CLI、资源限制、TTL、截图和 fencing，仓库包含可构建镜像。
- P1-O 已完成：五项黄金样例 Acceptance Run、生产探针、API 和 EasyCode 状态面板已落地。
- 本机没有 Docker CLI，因此没有在本机声称真实容器和黄金项目已经跑通。部署环境需构建 Worker 镜像、启用独立 Worker、准备黄金项目证据后执行 V1 验收 API。
- 本轮未连接或迁移外部数据库，未修改暂缓的模型凭据与 TLS 配置。