yidaima/RuoYi-Vue/docs/superpowers/specs/2026-07-10-ai-software-factory-roadmap.md

# AI Software Factory 产品架构与项目改造路线

> 日期：2026-07-10
> 状态：产品总纲与改造基线
> 盘点范围：当前工作区代码和已有设计文档，包含尚未提交的在研改动
> 核心结论：EasyCode 已经具备“软件工厂原型”的主要零件，下一阶段不应继续横向堆功能，而应先建立统一 DSL、版本、生成内核和质量门禁。

## 1. 文档目的

本文记录 EasyCode 从“AI 代码生成器”升级为“AI Software Factory（AI 软件工厂）”的长期方案，并回答三个问题：

1. 最终产品应该是什么。
2. 当前项目已经做到什么、还缺什么。
3. 应按什么顺序改造，才能保留现有能力并逐步收敛到目标架构。

这不是一次推倒重写方案。当前一键生成、业务闭环、页面设计、模板包、在线预览、论文与图表等能力都应保留，通过兼容层逐步迁移到统一工厂内核。

## 2. 产品定位

产品目标：

> 用户输入一句话需求，系统自动生成可运行、可验证、可继续修改的企业级或毕业设计级项目。

典型输入：

```text
社区服务小程序

一期功能：
商品预定
送货上门
代取快递
二手交易
AI 客服
推荐系统
```

目标输出：

- Spring Boot 后端。
- Vue 3 管理端和用户前台。
- UniApp 等多端应用。
- MySQL 数据库与初始化数据。
- 后台管理、前台页面、菜单、角色和权限。
- 可执行的业务闭环。
- AI 问答、推荐等可选功能插件。
- Docker 部署与在线预览。
- 自动测试、质量报告和页面截图。
- 论文、PPT、系统图表等项目文档。

产品的核心交付物不只是源码压缩包，而是：

```text
可版本化的项目 DSL
+ 可重复执行的生成流水线
+ 通过质量门禁的运行制品
+ 可追溯的生成与修改记录
```

## 3. 不可动摇的设计原则

### 3.1 AI 只负责设计，不负责直接写项目源码

AI 负责：

- 需求理解与补全。
- 业务模块识别。
- 领域对象和数据库设计。
- 业务流程与状态机设计。
- 页面结构建议。
- 插件、主题和行业知识包推荐。
- 论文、PPT、说明文档等内容生成。

AI 不直接负责：

- Java、Vue、SQL 源码。
- Mapper、Service、Controller 实现。
- 运行部署脚本。
- 文件路径和工程结构拼装。

AI 的正式输出必须是结构化 DSL。源码只能由确定性的 Adapter、Plugin 和 Template 生成。

### 3.2 DSL 是唯一事实来源

数据库、流程、页面、菜单、权限、主题和插件不能分别成为互不一致的草稿。它们必须属于同一个 `ProjectSpec`，并通过稳定 ID 和引用关系连接。

所有二次修改遵循：

```text
读取 DSL -> 产生 DSL Patch -> 校验 -> 生成新版本 -> 重新生成
```

源码修改不参与标准回生链路。确需自定义源码时，应进入明确的扩展区或自定义插件，不能悄悄修改生成文件后再期待无损重生成。

### 3.3 相同输入必须得到可重复结果

同一份 DSL、同一组 Adapter/Plugin/Template 版本和同一套生成参数，应得到相同的文件清单和内容哈希。时间、随机数、模型输出等不确定因素必须在进入生成器前固化。

### 3.4 先校验，再生成；先通过质量门禁，再发布

任何无效引用、插件冲突、Adapter 能力缺失或业务闭环不完整，都必须在生成前被发现。生成成功不等于交付成功，最终制品必须经过编译、构建、接口、启动和页面检查。

### 3.5 演进优先于重写

第一阶段先在 `ruoyi-generator` 内建立清晰的 `factory` 包边界，不立即拆成大量 Maven 模块。接口和数据契约稳定后，再提取独立模块或服务。

## 4. 目标生成流程

```mermaid
flowchart TD
    A["用户一句话需求"] --> B["AI 需求分析"]
    B --> C["统一 ProjectSpec DSL"]
    C --> D["Schema 与语义校验"]
    D --> E{"校验是否通过"}
    E -- "否" --> F{"是否可修复"}
    F -- "是" --> G["确定性修复与人工确认"]
    G --> D
    F -- "否" --> H["阻断并返回诊断"]
    E -- "是" --> I["Generator Orchestrator"]
    I --> J["Backend / Frontend / Database Adapters"]
    I --> K["Feature Plugins"]
    I --> L["Theme / Page / Document Templates"]
    J --> M["生成源码与制品"]
    K --> M
    L --> M
    M --> N["Quality Gate"]
    N --> O{"全部通过"}
    O -- "否" --> P["诊断报告与 DSL 修正"]
    P --> C
    O -- "是" --> Q["Docker 在线预览"]
    Q --> R["认证制品下载"]
    R --> S["DSL 二次编辑、Diff、回滚、再生成"]
```

推荐的逻辑分层：

1. AI 分析与 Prompt 层。
2. 统一 DSL 层。
3. DSL 校验与修复层。
4. 生成编排层。
5. Adapter 与 Plugin 层。
6. 模板与运行时生成层。
7. 质量检测层。
8. 在线预览与制品层。
9. 版本与治理层。

## 5. 统一 DSL 设计

### 5.1 根模型

建议把原方案中的多个 DSL 收敛为一个带版本的根对象：

```json
{
  "schemaVersion": "1.0",
  "project": {},
  "domain": {
    "objects": [],
    "tables": [],
    "fields": []
  },
  "flows": [],
  "pages": [],
  "menus": [],
  "permissions": [],
  "plugins": [],
  "theme": {},
  "dashboard": {},
  "deliverables": {
    "targets": ["backend", "frontend", "admin_frontend", "sql"],
    "documents": ["thesis", "ppt"]
  }
}
```

对应关系：

| 原方案 DSL | 统一模型位置 | 说明 |
| --- | --- | --- |
| Project DSL | `project` | 名称、包名、技术目标、语言、交付要求 |
| Domain/Table/Field DSL | `domain` | 领域对象、表、字段、关联和约束 |
| Flow DSL | `flows` | 状态机、动作、规则、Effect 和验收场景 |
| Page DSL | `pages` | Scene、Template、Section、Slot 和动作位 |
| Menu DSL | `menus` | 前台与后台导航树 |
| Permission DSL | `permissions` | 角色、资源、动作和数据范围 |
| Plugin DSL | `plugins` | 插件版本、配置、依赖和能力声明 |
| Theme DSL | `theme` | 设计 token、密度、组件变体 |
| Dashboard DSL | `dashboard` | 指标、图表、数据集和布局 |

### 5.2 DSL 必备约束

- 每个可引用节点必须有不可变 `id` 和稳定 `code`。
- 跨 DSL 引用使用 ID，不依赖表名或页面名称做模糊匹配。
- `schemaVersion` 必须显式存在，并提供升级器。
- 枚举、表达式和 Effect 必须使用白名单。
- 所有插件可以扩展 DSL，但只能通过命名空间化的 `extensions`。
- DSL 保存前必须规范化，字段顺序、默认值和空集合处理保持稳定。
- DSL Patch 必须记录操作者、来源、父版本和修改原因。

### 5.3 DSL 调试器

需要提供：

- 树形和 JSON 双视图。
- JSON Schema 语法校验。
- 跨对象引用与业务语义校验。
- 错误路径、错误码、严重级别和建议修复。
- 可预览的自动修复 Patch，用户确认后才生成新版本。
- 导入、导出和版本 Diff。
- 从错误节点跳转到数据库、流程或页面设计器。

## 6. 业务闭环目标

目标链路：

```text
Flow DSL -> Flow Compiler -> State Machine -> Effect Engine -> Unified Executor
```

AI 只生成 `Step`、`Status`、`Action`、`Rule`、`Effect` 和页面绑定。执行层必须由平台提供。

当前和近期建议支持的 Effect：

- `SET_STATUS`。
- `UPDATE_FIELD` / `UPDATE_FIELDS`。
- `INSERT_ROW`。
- `INCREASE_NUMBER` / `DECREASE_NUMBER`。
- `EMIT_EVENT`。
- `SEND_NOTIFICATION`。
- `WRITE_AUDIT_LOG`。

统一执行器必须补齐：

- 事务边界。
- 幂等键。
- 乐观锁或并发检查。
- 操作权限和数据范围。
- 前置条件与状态迁移合法性。
- 失败回滚。
- 审计日志。
- Effect 执行结果和可观测信息。

生成项目应携带独立可运行的 Flow Runtime。Adapter 负责把同一份 Flow DSL 编译为目标后端可执行配置，不能继续为每个业务动作拼一套专用实现。

## 7. 页面、模板和主题目标

### 7.1 用户前台

使用固定语义层级：

```text
Scene -> Page Template -> Section -> Slot -> Component
```

AI 决定“需要什么内容和动作”，模板决定按钮位置、响应式布局和交互细节。

页面设计器主要编辑 Section、Slot、属性、顺序、显隐和绑定。仅首页、Dashboard、门户等自由组合页面开放更强拖拽，普通列表、详情和表单保持确定性模板。

### 7.2 后台页面

后台业务页默认按 CRUD 约定生成：

- 查询区。
- 工具栏。
- 表格。
- 分页。
- 新增与编辑表单。
- 详情。
- 行操作和批量操作。

业务 Flow 只向预定义动作位绑定，不让 AI 自由摆放按钮。

### 7.3 模板体系

完整模板体系包括：

- Layout Template。
- Page Template。
- Component Template。
- Theme Template。
- Backend Template。
- Plugin Template。
- Document Template。

同一份 Page DSL 可以通过不同模板和 Theme DSL 生成不同视觉结果。主题只能影响视觉 token 和组件变体，不能偷偷改变业务布局。

## 8. Plugin 与 Adapter 目标

### 8.1 Adapter

技术栈扩展必须通过能力接口实现：

```text
ProjectSpec
  -> Spring Boot Adapter
  -> Vue 3 Adapter
  -> React Adapter
  -> UniApp Adapter
  -> Flutter Adapter
  -> MySQL Adapter
```

Adapter 需要声明：

- Adapter ID 和版本。
- 支持的 DSL schema 版本。
- 输出目标和运行环境。
- 支持的页面类型、Effect、插件扩展点。
- 依赖的模板包。
- 校验器、生成器和质量检查器。

### 8.2 Plugin

推荐内置的功能插件：

- 推荐算法。
- AI 问答。
- 审批流。
- 大屏。
- 消息通知。
- Excel 导入导出。
- 评论、评分、收藏和浏览历史。
- 支付模拟。
- 地图。
- 短信模拟。

每个插件必须有 manifest，至少包含：

- `code`、`version`、`provider`。
- `requires`、`provides`、`conflicts`。
- Adapter 兼容范围。
- DSL schema 扩展。
- 数据库迁移。
- 模板和静态资源。
- 校验器和质量检查。
- 权限、菜单和配置项。

第一阶段只允许内置或受信任插件。第三方插件上传、签名、依赖解析和沙箱执行属于市场阶段，不能一开始就允许任意代码在主服务进程执行。

## 9. 当前项目现状盘点

总体判断：

> 当前项目不是普通 RuoYi 代码生成器，而是“多个软件工厂能力已经可用，但尚未被统一内核收口”的状态。

| 能力 | 当前状态 | 代码现状 | 与目标的差距 |
| --- | --- | --- | --- |
| 一句话一键生成 | 已具备并绑定版本 | `GenerateView.vue` 已有一键/高级模式；`OneClickProjectGenerationServiceImpl` 串联蓝图、闭环、数据库、页面、源码和预览，并在源码渲染前固化 specVersion | 编排仍直接依赖多个草稿对象，尚未按指定 ProjectSpec 版本驱动生成 |
| AI 任务与成本 | 已具备 | 有任务队列、重试、额度、生成记录、Token 和人民币成本台账 | 模型网关偏 DeepSeek 单实现，Prompt 版本未进入任务追踪 |
| 应用/数据库/流程 DSL | 已建立统一投影基础 | `ProjectSpecV1`、JSON Schema、稳定引用、规范化 JSON 和 Legacy Assembler 已实现；旧字段仍保存 appBlueprint、businessLoopPlan、businessBlueprint | ProjectSpec 目前由旧数据实时投影，尚未成为唯一可编辑事实来源，也没有 schema migrator |
| DSL 校验与修复 | 已建立统一校验与 Patch 基础 | 已有 ProjectSpec 结构/引用/业务语义校验，统一输出 ValidationIssue；支持受限 JSON Patch 预览、校验和不可变版本写入 | 尚无原始 JSON Schema 错误映射、自动修复确认流和 Adapter/Plugin 能力校验，旧修复仍会直接改持久化对象 |
| 业务闭环 | 部分具备 | 已有 BusinessLoopPlan、覆盖审计、安全 Effect DSL、页面动作绑定 | Effect 主要在 Velocity 模板中展开为专用代码，尚未形成独立 Flow Compiler/Runtime |
| 页面 DSL 与设计器 | 部分具备且较成熟 | 有 `layoutJson`、`actionJson`、PageComposition、页面类型、业务块和可视化设计器 | JSON 仍以 Map 和约定为主，Section/Slot 类型契约、schema 版本和统一 Patch 尚未形成 |
| 后台 CRUD 生成 | 已具备 | qing 模板可生成后端、前台、管理端和 SQL | 仍与模板细节耦合，尚未归入 Adapter 能力模型 |
| 代码模板包 | 部分具备 | 有 `sys_template_bundle`、模板导入、模板管理和 qing 默认包 | 模板包只是渲染资源集合，不等于技术栈 Adapter；版本与质量认证不足 |
| 业务块 | 部分具备 | 已有轮播、新闻、通知、购物车、订单、主从和多类图表业务块 | 可视为插件雏形，但缺统一 manifest、依赖、冲突、版本和迁移生命周期 |
| 主题 | 部分具备 | 有四组内置 PageStylePreset 和视觉 token | 主题硬编码在 Java，缺 Theme DSL、持久化、导入导出和市场能力 |
| 二次编辑 | 已建立 DSL Patch 基础 | 支持基于当前投影或指定版本执行 `add/remove/replace/test`，预览同时返回校验结果和语义变更；应用后生成 `PATCH` 来源新版本 | 现有设计器尚未改为提交 Patch，Patch 版本也尚未反投影到旧数据对象 |
| 版本管理 | 已建立快照与语义 Diff 基础 | `factory_project_spec_version` 保存完整规范化快照、父版本、来源和内容哈希；支持快照、列表、详情、相同内容复用、冲突安全的 Patch 子版本和稳定 ID 语义 Diff | 尚无回滚、分支/rebase 和按历史版本重新生成；历史版本暂未增量压缩 |
| 在线运行预览 | 部分具备 | 独立工作目录、独立数据库、端口分配、子进程、HTTP 就绪检查、TTL 和过期清理已实现 | 仍在宿主机直接启动 Maven/npm 进程；没有 Docker 隔离、Nginx 路由、资源配额和持久会话 |
| 质量门禁 | 部分具备 | 结构渲染前有一致性校验，运行预览会真实启动后端和前端 | `markPreviewReady` 发生在完整运行检查前；后端跳过测试，前端跑 dev 而非 build；没有截图和认证制品 |
| 图表与论文 | 部分具备 | 已有多类图表 DSL、导出、论文提纲和正文生成 | 还没有统一从 ProjectSpec 取数的文档流水线，PPT 未形成完整交付 |
| Prompt 管理中心 | 缺失 | 多数 Prompt 直接写在 `AiGenerateServiceImpl` | 缺模板、版本、模型映射、在线调试、A/B 测试和回滚 |
| Knowledge Pack | 缺失 | 有 `industryTemplate` 字段和行业提示概念 | 没有可版本化的行业术语、流程、字段、页面和验收规则包 |
| Adapter 体系 | 缺失 | 目前按 templateType 和 template bundle 选择生成资源 | 缺标准 SPI、能力声明和 React/UniApp/Flutter 等独立实现 |
| 模板/插件市场 | 早期基础 | 有模板管理、模板导入和源码商店页面 | 还不是带版本、审核、依赖、签名和兼容矩阵的市场 |
| 平台后台 | 部分具备 | 有项目、模板、AI 用量和 RuoYi 基础后台 | 缺 DSL、Prompt、Plugin、Theme、Version、Preview、Quality、Knowledge 管理中心 |
| 安全基线 | 开发阶段暂缓 | 当前配置中存在明文模型凭据和跳过 TLS 校验的配置 | 当前不作为改造阻塞项，共享测试或生产发布前再完成凭据轮换、环境变量接入和 TLS 校验 |

说明：`easycode-web` 本身使用 Vue 3 + Element Plus，不代表所有“生成项目”已经统一为 Vue 3。当前生成目标仍受 qing 模板和数据库模板内容约束。

## 10. 当前架构的主要问题

### 10.1 没有唯一事实来源

`front_project`、表字段记录、页面设计记录、业务动作 JSON、图表记录各自持久化。当前一致性服务可以发现和修复部分引用，但本质上仍是“生成后对齐多个副本”，不是“从一个规范投影多个视图”。

### 10.2 AI 服务职责过重

`AiGenerateServiceImpl` 同时负责 Prompt 拼接、模型调用、响应解析、规范化、校验、保存和多类内容生成。新增模型、Prompt 版本或 DSL schema 时，改动面会继续扩大。

### 10.3 编排器与具体能力直接耦合

`OneClickProjectGenerationServiceImpl` 已有很好的阶段化基础，但每加一个生成步骤都要直接注入并调用新服务。长期需要从固定方法链升级为可恢复、可观察的 Stage Handler 流水线。

### 10.4 模板、业务块、插件和 Adapter 概念尚未分开

- Template 负责“怎么渲染”。
- Adapter 负责“目标技术栈如何实现 DSL”。
- Plugin 负责“增加什么业务能力”。
- Theme 负责“视觉如何表达”。

当前这些能力部分混合在 qing 模板、模板包、业务块资源和 Java 分支中。

### 10.5 版本和可追溯性不足

重新生成前会重置部分生成产物，但没有不可变 DSL 快照。出现回归时，无法精确回答“哪份 DSL、哪个 Prompt、哪个模型、哪个 Adapter/Plugin/Template 版本生成了这个文件”。

### 10.6 质量状态与下载状态未完全一致

当前“源码可渲染”即可标记可预览和下载，而真实编译、前端构建、接口检查、截图与 Docker 启动还不是独立质量门禁。

### 10.7 本机预览适合开发，不适合多租户生产

当前子进程和独立数据库已经满足本地验证，但生成代码仍能接触宿主网络、文件系统和工具链。公开预览必须迁移到受限容器或独立执行节点。

## 11. 目标代码边界

第一阶段建议在 `ruoyi-generator` 新增以下包，不马上拆 Maven 模块：

```text
com.ruoyi.generator.factory
  dsl
    model
    schema
    migration
    patch
  validation
  orchestration
  adapter
  plugin
  template
  flow
  version
  quality
  artifact
  prompt
  knowledge
```

接口稳定后，可再提取为：

- `generator-core`。
- `generator-adapter-spi`。
- `generator-plugin-spi`。
- `generator-quality`。
- `preview-worker`。

## 12. 分层改造方案

### 12.1 统一 ProjectSpec

新增：

- `ProjectSpecV1` 及所有强类型子模型。
- `ProjectSpecAssembler`：从现有 FrontProject、表字段、页面设计和业务蓝图组装 DSL。
- `LegacyProjectProjection`：从 DSL 回写现有结构，供旧模板和旧页面继续使用。
- `ProjectSpecNormalizer`：补默认值并产生稳定 JSON。
- `ProjectSpecMigrator`：负责 schema 版本升级。
- JSON Schema 文件和契约测试。

迁移期规则：

1. 旧字段先保留。
2. 一键生成结束 AI 规划后，先固化一份 ProjectSpec。
3. 旧生成器通过 Projection 消费 ProjectSpec。
4. 新页面只允许提交 DSL Patch。
5. 当所有生成入口都从 ProjectSpec 派生后，再停止直接写旧 JSON 字段。

### 12.2 Prompt 与模型层

把 `AiGenerateServiceImpl` 拆为：

- `ModelGateway`：统一模型调用、流式输出、Token 与错误。
- `PromptRegistry`：按用途、版本、模型和语言解析 Prompt。
- `RequirementPlanner`：一句话需求转 ProjectSpec Draft。
- `StructuredOutputParser`：只接受结构化输出。
- `SpecPlanningService`：规范化、校验、修复和保存。
- `DocumentGenerationService`：论文、PPT、说明书等非源码内容。

Prompt 中心支持：

- 模板与变量定义。
- 草稿、发布、停用状态。
- 不可变版本。
- 不同模型绑定不同版本。
- 在线调试。
- A/B 实验。
- 回滚。
- 每次任务记录 promptVersion、model、参数和 DSL schemaVersion。

发布前安全要求：

- 开发阶段暂时保留当前模型凭据和 TLS 配置，不作为本轮改造范围。
- 进入共享测试或生产环境前轮换模型密钥，并改为环境变量或密钥服务。
- 进入共享测试或生产环境前将 `skipSslVerify` 默认改为 false。
- 对外环境的日志、生成记录和 Prompt 调试结果必须脱敏。

### 12.3 DSL 校验与修复

把现有多个 Validator 纳入统一 `DslValidationPipeline`：

1. JSON Schema 校验。
2. 命名和类型校验。
3. 引用完整性校验。
4. 菜单、页面、权限一致性校验。
5. Flow 状态机和 Effect 校验。
6. 业务闭环覆盖审计。
7. Plugin 依赖和冲突校验。
8. Adapter 能力兼容校验。
9. 交付目标完整性校验。

统一问题模型：

```json
{
  "code": "PAGE_TABLE_NOT_FOUND",
  "severity": "ERROR",
  "path": "/pages/3/tableRef",
  "message": "页面引用的数据表不存在",
  "suggestedPatch": []
}
```

现有自动修复逻辑应输出 Patch，不再直接静默重写多个持久化对象。

### 12.4 生成编排内核

将一键生成阶段抽象为 `GenerationStageHandler`：

- `PLAN_REQUIREMENT`。
- `BUILD_SPEC`。
- `VALIDATE_SPEC`。
- `RESOLVE_EXTENSIONS`。
- `GENERATE_SOURCE`。
- `RUN_QUALITY_GATE`。
- `PUBLISH_ARTIFACT`。
- `START_PREVIEW`。
- `GENERATE_DOCUMENTS`。

每个阶段必须：

- 幂等。
- 可重试。
- 可从已完成检查点恢复。
- 记录输入、输出、耗时、日志和失败原因。
- 绑定 specVersion、adapterVersion、pluginVersions、templateVersions。

可以继续复用 `front_ai_generation_task`，但应增加生成运行所需的版本引用；不必另起一套重复任务中心。

### 12.5 Flow Engine

改造顺序：

1. 保留现有安全 Effect 类型和校验器。
2. 把 Velocity 中的 Effect 分支提取为 `FlowCompiler` 的目标无关中间模型。
3. 在 qing 后端 Adapter 中生成统一 Flow Runtime 和 Effect Handler。
4. 业务动作 Controller 只提交 actionCode、目标记录和参数。
5. Runtime 负责规则、状态、事务、权限、Effect 和审计。
6. 增加状态迁移、并发、幂等和回滚测试。

这一步完成后，新增业务动作通常只改 DSL，不再新增专用 Service 方法模板。

### 12.6 Page DSL 和设计器

后端：

- 把 `layoutJson` / `actionJson` 收敛为强类型 Page DSL。
- 定义 Scene、Section、Slot、FieldBinding、ActionBinding。
- PageComposition 输出 Page DSL Patch。
- 后台 CRUD 页由约定生成，不保存冗余布局时也能恢复。

前端：

- `FrontendPageDesigner.vue` 改为读取和提交 ProjectSpec 中的页面 Patch。
- 保留当前可视化体验和业务块能力。
- 普通业务页限制在模板允许的 Section/Slot 内。
- 首页、门户、Dashboard 再开放自由布局。
- JSON 编辑切换为 DSL 调试器高级入口。

### 12.7 Adapter、Plugin、Template 和 Theme

新增核心接口：

- `GeneratorAdapter`。
- `FeaturePlugin`。
- `TemplatePack`。
- `ThemeProvider`。
- `CapabilityDescriptor`。

现有资产迁移：

- qing 模板包先包装成第一个兼容 Adapter，不立即重写模板。
- `sys_template_bundle` 作为 Adapter 下的 TemplatePack 管理。
- BusinessBlock 转成 `page-block` 类型 Plugin。
- PageStylePreset 转成 Theme DSL 种子数据。
- 模板导入功能增加 manifest、版本和兼容检查。

不要把“复制一套 Vue 模板”当作新增 Adapter。Adapter 必须同时实现能力声明、DSL 映射、生成、质量检测和预览启动约定。

### 12.8 版本管理

项目版本必须是不可变 ProjectSpec 快照。

支持：

- 从当前版本创建新版本。
- DSL 语义 Diff。
- 回滚，回滚本身生成一个新版本。
- 按任意历史版本重新生成。
- 比较生成文件清单和哈希。
- 记录 AI、人工、自动修复、导入等变更来源。

页面、图表和论文现有 `version` 字段继续用于并发控制，不能代替项目版本历史。

### 12.9 Quality Gate

建议的检查流水线：

1. DSL 与插件兼容检查。
2. SQL 解析和临时数据库导入。
3. Java 编译。
4. 后端单元测试。
5. 前端依赖锁定安装。
6. 前端生产构建。
7. API 启动与 smoke test。
8. Docker Compose 启动。
9. 核心页面访问与截图。
10. 最低限度的控制台错误、空白页和接口失败检查。

每项输出结构化结果、日志和制品。

下载建议区分：

- Draft Source：仅供诊断，可在源码渲染后由管理员导出，明确标记未认证。
- Certified Artifact：面向普通用户，只有 Quality Gate 全部通过才允许下载。

这样既保留失败排查能力，又满足“通过检测才正式交付”的产品原则。

### 12.10 Docker 在线预览

现有本机预览保留为开发模式。生产预览新增独立 `preview-worker`：

- 每个会话独立容器、网络、数据库和工作卷。
- 后端、用户前台、管理端、MySQL、Nginx 分服务运行。
- 默认 30 分钟 TTL，可配置。
- CPU、内存、磁盘、进程数和网络访问受限。
- 会话状态持久化，不只保存在单机内存。
- 使用反向代理生成统一 Preview URL。
- 到期后停止容器、删除网络、卷和数据库。
- 生成代码不能挂载宿主源码目录或读取平台密钥。

### 12.11 Knowledge Pack

Knowledge Pack 不是一段长 Prompt，而是可版本化的结构化资产：

- 行业术语和角色。
- 领域对象与字段惯例。
- 常见状态机和业务闭环。
- 页面与菜单模式。
- 权限和数据范围规则。
- 验收场景。
- 禁止项和合规提示。
- 推荐插件和主题。

第一批建议选择当前测试最充分的 2 至 3 个场景，如图书借阅、社区服务、商城订单。先做深，不急于铺满医院、学校、物业等所有行业。

### 12.12 模板与插件市场

市场阶段提供：

- 页面模板。
- 主题。
- 功能插件。
- Adapter。
- 行业 Knowledge Pack。
- 完整项目模板。

必须先有：

- 版本与依赖解析。
- 兼容矩阵。
- 自动试生成和质量报告。
- 发布审核。
- 签名与来源追踪。
- 下架和安全公告机制。

## 13. 数据模型建议

第一阶段只强制新增一张核心版本表，避免一次性扩表过多：

### 13.1 `factory_project_spec_version`

建议字段：

- `spec_version_id`。
- `project_id`。
- `version_no`。
- `parent_version_id`。
- `schema_version`。
- `content_json`。
- `content_hash`。
- `change_source`。
- `change_summary`。
- `status`。
- `created_by`。
- `create_time`。

`front_project` 增加 `current_spec_version_id`，现有蓝图字段作为迁移期投影缓存。

后续按阶段增加：

- `factory_prompt_template` / `factory_prompt_version`。
- `factory_plugin` / `factory_plugin_version`。
- `factory_knowledge_pack` / `factory_knowledge_pack_version`。
- `factory_theme` / `factory_theme_version`。
- `factory_quality_run` / `factory_quality_check`。
- `factory_artifact`。
- `factory_preview_session`。

`front_ai_generation_task` 建议扩展：

- `spec_version_id`。
- `pipeline_version`。
- `adapter_versions_json`。
- `plugin_versions_json`。
- `prompt_versions_json`。
- `quality_run_id`。
- `artifact_id`。

## 14. API 改造建议

新增工厂 API，旧接口在迁移期继续保留：

```text
GET  /front/factory/projects/{projectId}/spec
POST /front/factory/projects/{projectId}/spec/validate
POST /front/factory/projects/{projectId}/spec/repair-preview
POST /front/factory/projects/{projectId}/spec/patch/preview
POST /front/factory/projects/{projectId}/spec/patch

GET  /front/factory/projects/{projectId}/versions
GET  /front/factory/projects/{projectId}/versions/{versionId}
GET  /front/factory/projects/{projectId}/versions/{leftId}/diff/{rightId}
POST /front/factory/projects/{projectId}/versions/{versionId}/rollback
POST /front/factory/projects/{projectId}/versions/{versionId}/generate

GET  /front/factory/projects/{projectId}/runs
GET  /front/factory/runs/{runId}
GET  /front/factory/runs/{runId}/quality
GET  /front/factory/runs/{runId}/artifact
```

后台管理 API 分别服务 Prompt、Plugin、Adapter、Theme、Knowledge Pack、Quality 和 Preview 管理。

## 15. 现有模块需要修改的部分

| 模块 | 保留内容 | 主要修改 |
| --- | --- | --- |
| `ruoyi-generator` | 现有模板、校验器、任务、业务闭环、页面组合和预览生成服务 | 新增 factory 内核；拆分 AI 职责；让旧生成器从 ProjectSpec Projection 取数 |
| `ruoyi-admin` | 登录、权限、FrontProjectController 和现有前台接口 | Controller 变薄；增加 factory、版本、质量、制品和预览会话 API；清理敏感配置 |
| `easycode-web` | 一键生成、高级调整、页面设计、图表、论文和预览页 | 增加工厂工作区、DSL 调试器、版本 Diff、质量报告；所有编辑改为 DSL Patch |
| `ruoyi-ui` | RuoYi 管理后台、模板和 AI 用量页面 | 增加 Prompt、Plugin、Adapter、Theme、Knowledge、Version、Quality、Preview 管理 |
| `sql` | 现有项目、任务、模板包和页面设计迁移脚本 | 增加 ProjectSpec 版本表及后续治理表；提供旧项目回填脚本 |
| `preview-workspaces` | 本地开发预览缓存约定 | 仅保留开发模式；生产迁到 preview-worker 的隔离工作卷 |
| `docs` | 现有分功能设计文档 | 本文作为总纲，后续子设计必须引用并遵守统一 DSL 和版本原则 |

## 16. 分阶段实施路线

### P0：开发基线冻结

目标：先固定现有生成能力，为统一 DSL 改造建立可回归基线。

- 对当前一键生成建立 2 至 3 个黄金样例。
- 固化现有生成文件清单、业务闭环和预览回归测试。
- 给现有 JSON 草稿补齐样例和字段说明。
- 开发阶段暂不处理模型凭据和 TLS 配置；将其保留为共享测试或生产发布前检查项。

完成标志：现有功能有稳定基线，统一 DSL 改造可以通过黄金样例持续回归。

### P1：统一 DSL 与项目版本

目标：建立唯一事实来源，同时不破坏旧生成器。

- 实现 ProjectSpecV1、JSON Schema、Normalizer 和 Migrator。
- 实现 Legacy Assembler/Projection。
- 新增不可变 spec version 表。
- 实现统一校验结果与 DSL 调试 API。
- 一键生成绑定 specVersion。
- 高级调整保存 DSL Patch。

完成标志：任一现有项目都能导出 ProjectSpec，并从同一版本重新生成等价结果。

### P2：生成内核与 Prompt 中心

目标：把 AI 和生成器彻底分界。

- 拆分 ModelGateway、PromptRegistry、RequirementPlanner。
- Prompt 模板、版本、发布和任务追踪。
- 一键生成改为 Stage Handler Pipeline。
- 支持检查点恢复。
- AI 只提交 ProjectSpec Draft/Patch。

完成标志：修改 Prompt 不需要发版；生成器不再读取模型自由文本。

### P3：Adapter、Plugin、Template、Theme

目标：让扩展能力有标准契约。

- qing 包装为首个 Adapter。
- 模板包归入 Adapter 的 TemplatePack。
- 业务块迁移为 Plugin manifest。
- 风格预设迁移为 Theme DSL。
- 加入依赖、冲突和能力校验。

完成标志：新增一个内置插件不需要修改一键编排器；模板、插件、Adapter 和主题职责分离。

### P4：Flow Runtime 与 Page DSL 收敛

目标：真正做到“改 DSL 即改业务和页面”。

- 生成项目内置统一 Flow Runtime。
- Effect、事务、幂等、权限和审计标准化。
- 页面模型升级为 Scene/Section/Slot 强类型 DSL。
- 页面设计器只提交 Patch。
- 后台 CRUD 页面按约定生成。

完成标志：增加常规业务动作无需生成专用业务代码分支。

### P5：Quality Gate 与容器预览

目标：交付从“能生成”升级为“已验证”。

- 独立质量运行和报告。
- Java test、前端 build、SQL 导入、API smoke、页面截图。
- 认证制品与 Draft Source 分离。
- preview-worker、Docker 隔离、Nginx URL、TTL 和资源配额。

完成标志：普通用户只能拿到通过门禁的认证制品，预览不在平台主进程直接运行生成代码。

### P6：Knowledge Pack、市场和更多 Adapter

目标：形成长期竞争壁垒。

- 上线首批行业 Knowledge Pack。
- 上线模板/插件/主题市场治理。
- 增加 Vue 3、UniApp 等 Adapter。
- 文档流水线补齐 PPT。
- 建立第三方发布、审核、签名和兼容测试。

完成标志：行业能力和技术栈可以独立安装、升级和复用。

## 17. 第一批建议直接实施的任务

建议下一轮先做以下工作，不先做 Docker 或市场：

1. 定义 `ProjectSpecV1` 和 JSON Schema。
2. 为当前“图书借阅系统”生成一份真实 ProjectSpec 样例。
3. 实现 `ProjectSpecAssembler`，从现有项目记录组装 DSL。
4. 实现 `LegacyProjectProjection`，证明旧模板能继续生成。
5. 新增 `factory_project_spec_version` 和回填脚本。
6. 把现有一致性校验包装为统一 ValidationIssue。
7. 增加 spec 获取、校验、Patch 和版本列表 API。
8. 让 `OneClickProjectGenerationServiceImpl` 在源码生成前固化 specVersion。
9. 增加“同一 Spec 重生成文件哈希一致”的契约测试。
10. 在 `easycode-web` 增加只读 DSL 调试器第一版，再逐步开放 Patch。

这是最小且最关键的一刀。完成后，Prompt、插件、Flow Engine、Docker 和市场都有稳定地基。

## 18. 验收标准

AI Software Factory v1 至少满足：

- AI 正式输出只能通过 ProjectSpec schema。
- 任意无效引用在生成前失败，并能定位到 DSL 路径。
- 相同 ProjectSpec 与扩展版本产生相同文件哈希。
- 每次生成可追溯到 Spec、Prompt、模型、Adapter、Plugin 和 Template 版本。
- 用户可以查看版本 Diff、回滚并重新生成。
- 业务闭环有状态、数量、关联记录和页面入口验收。
- 插件依赖和冲突在生成前完成解析。
- Java、前端、SQL、API、容器和页面检查形成质量报告。
- 认证下载只来自通过质量门禁的制品。
- 生产预览运行在隔离环境并自动销毁。
- 进入共享测试或生产环境前，仓库和日志中不存在可用的明文密钥。

## 19. 关键决策与非目标

需要尽早锁定的决策：

- ProjectSpec 是否为唯一可编辑事实来源：建议“是”。
- 回滚是否覆盖历史：建议“不覆盖，回滚生成新版本”。
- 是否允许用户直接改生成源码：建议“标准链路不允许，使用扩展区或插件”。
- 是否立即拆 Maven 多模块：建议“否，先稳定包级接口”。
- 是否允许第三方插件在主进程执行：建议“否”。
- 下载策略：建议区分 Draft Source 和 Certified Artifact。
- 生产预览是否继续使用宿主子进程：建议“否”。

近期非目标：

- 一开始就支持任意 BPMN。
- 一开始就开放第三方任意代码插件。
- 一次性支持所有行业和所有前端框架。
- 在统一 DSL 之前继续扩建大量独立设计器。
- 为追求架构形式而重写当前已工作的模板和一键生成链路。

## 20. 长期竞争力

真正的壁垒不是某一个模型，也不是某一套模板，而是四类持续积累的资产：

1. 统一 DSL：让 AI、设计器、模板、插件和 Adapter 使用同一种语言。
2. Flow Engine：把业务闭环变成安全、可验证、可执行的标准能力。
3. Plugin + Adapter 生态：让功能和技术栈独立扩展。
4. Knowledge Pack：沉淀行业对象、流程、页面和验收经验。

当前项目已经有一键生成、业务闭环、页面 DSL、模板包和本地运行预览这些关键起点。下一阶段最重要的不是继续增加页面或功能按钮，而是先把这些能力收敛为一个有版本、有契约、有门禁的工厂内核。

## 21. 实施进度

### 2026-07-10：P1-A 统一 DSL 只读兼容投影

已完成：

- 新增强类型 `ProjectSpecV1` 根模型，覆盖 project、domain、flows、pages、menus、permissions、plugins、theme、dashboard 和 deliverables。
- 新增旧项目组装器，从现有项目、数据库设计、业务蓝图和前后台页面设计生成 ProjectSpec。
- 生成内容不包含 `createTableSql` 等生成结果，保持“DSL 描述设计、Adapter 生成代码”的边界。
- 新增规范化 JSON 编解码和 SHA-256 内容哈希，Map 字段稳定排序，排除旧 DTO 的 transient 渲染字段。
- 新增 JSON Schema：`factory/schema/project-spec-v1.schema.json`。
- 新增只读接口：`GET /front/factory/projects/{projectId}/spec`。
- 已补充组装、错误处理、稳定哈希、Schema 资源、双页面域加载和接口用户隔离测试。

当前边界：

- ProjectSpec 仍由旧数据实时投影，不是持久化的唯一事实来源。
- 尚未建立 `factory_project_spec_version` 和版本 Diff。
- 尚未提供 DSL Patch、Schema 校验结果和自动修复 API。
- 一键生成与旧模板尚未改为消费 ProjectSpec。
- 前端 DSL 调试器尚未接入新接口。

P1-B 已完成，见下方记录。

### 2026-07-10：P1-B 不可变 ProjectSpec 版本

已完成：

- 新增 `factory_project_spec_version`，保存递增版本号、父版本、schema 版本、规范化 JSON、SHA-256、变更来源和摘要。
- 新增独立升级脚本 `sql/factory_project_spec_version.sql`，并同步完整 `db.sql` 与 `front_workbench.sql`。
- Mapper 只提供查询和插入，不提供更新、删除接口；项目删除时由外键级联清理版本。
- 新增事务快照服务，使用最新版本行锁和 `(project_id, version_no)` 唯一约束保护版本递增。
- 连续快照内容哈希相同时复用最新版，不制造空版本。
- 版本列表只读取元数据，版本详情才加载并解析完整 ProjectSpec。
- 所有列表和详情读取均先校验当前用户的项目归属。
- 新增接口：
  - `POST /front/factory/projects/{projectId}/versions`。
  - `GET /front/factory/projects/{projectId}/versions`。
  - `GET /front/factory/projects/{projectId}/versions/{specVersionId}`。

验证结果：

- ProjectSpec 与版本定向测试 16 个全部通过。
- Factory Controller 测试 4 个全部通过。
- `ruoyi-admin` 依赖链编译通过。
- `ruoyi-generator` 全量执行 538 个测试，其中 520 个通过；18 个失败集中在当前工作区已有的 AI 数据库生成、字典选项和 Qing 模板一致性改动，不在本轮 Factory 新增调用链内。

当前边界：

- 版本快照仍需显式调用，尚未接入一键生成阶段。
- 尚未提供版本 Diff、回滚和按历史版本重新生成。
- 尚未提供 DSL Patch 与统一 ValidationIssue API。
- 历史版本目前保存完整快照，不做增量压缩。

下一步进入 P1-C：统一校验结果、ProjectSpec 校验 API，并在一键生成源码前自动固化版本。

### 2026-07-10：P1-C 统一校验与一键生成版本绑定

已完成：

- 新增统一问题模型 `ValidationIssue`，包含稳定错误码、`ERROR/WARNING` 严重级别、JSON Pointer 路径、消息和 RFC 6902 风格 `suggestedPatch`。
- 新增 `ProjectSpecValidationResult`，统一返回 schemaVersion、contentHash、valid、错误/警告数量和稳定排序的问题清单。
- 新增 `ProjectSpecValidator`，覆盖 ProjectSpec 根结构、稳定 ID、重复定义、页面/菜单/角色/表引用、业务闭环对象/动作/状态/数量/记录引用、业务动作表字段引用、插件、主题和交付目标。
- 新增 `ProjectSpecValidationService`：无请求体时校验当前 Legacy 投影；提交 ProjectSpec 时先校验项目归属，再生成规范化内容哈希。
- 新增接口：`POST /front/factory/projects/{projectId}/spec/validate`。
- 一键生成在页面初始化和最终一致性修复后、源码结构渲染前，以 `AI` 来源自动创建或复用不可变 ProjectSpec 版本。
- 一键生成任务结果新增 `specVersionId`、`specVersionNo`、`specContentHash`，运行预览重试会保留这些追踪字段。
- 快照失败归属 `SOURCE_PREVIEW` 阶段，并阻止源码结构渲染、下载就绪标记和运行预览启动。

验证结果：

- ProjectSpec 组装、统一校验、校验服务和一键生成定向测试共 19 个全部通过。
- Factory Controller 测试 5 个全部通过。
- P1-A 至 P1-C 整组契约测试共 37 个全部通过。
- Legacy Assembler 的真实投影夹具已加入兼容回归，可被新校验器零错误接受。
- `ruoyi-admin` 完整依赖链编译和定向测试通过。
- `ruoyi-generator` 全量执行 545 个测试，其中 527 个通过；仍为之前记录的 18 个 AI 数据库生成、字典选项和 Qing 模板一致性失败，本轮未扩大失败面。

当前边界：

- ProjectSpec 仍是旧数据的只读实时投影；旧生成器尚未从指定 specVersion 反向投影并生成。
- `suggestedPatch` 目前只用于表达建议，尚未提供 Patch 预览、应用、冲突检测和持久化 API。
- 尚未把原始 JSON Schema 校验器的错误统一映射为 ValidationIssue；当前 API 依赖强类型模型和语义规则。
- 尚未提供版本 Diff、回滚和按历史版本重新生成。
- 启用一键生成自动快照前必须执行 `factory_project_spec_version` 数据库迁移脚本。

下一步进入 P1-D：实现 ProjectSpec Patch 预览/应用、生成新版本，并提供版本语义 Diff。

### 2026-07-10：P1-D ProjectSpec Patch 与语义 Diff

已完成：

- `ProjectSpecJsonCodec` 增加 ProjectSpec 与 Jackson Tree 的受控双向转换，继续复用规范化 JSON 和内容哈希规则。
- 新增受限 RFC 6902 Patch 引擎，支持 `add`、`remove`、`replace`、`test`；严格校验 JSON Pointer、数组下标、路径存在性和单次操作数量。
- Patch 全程在 JSON Tree 副本上执行，不修改作为基线的 ProjectSpec 对象。
- Patch 可基于当前 Legacy 投影或指定不可变版本预览，结果包含基线哈希、新内容哈希、完整校验结果、语义变更和预览 Spec。
- 正式应用时，无效 Patch 和无内容变化 Patch 均不创建版本；当前投影模式必须提交 `baseContentHash`。
- 版本写入在事务内锁定最新版本，并校验 `baseVersionId/baseContentHash`；过期基线不能覆盖新版本。
- 新版本使用 `PATCH` 来源，记录父版本和变更摘要；当前投影与最新快照哈希一致时自动衔接最新版本为父版本。
- 新增语义 Diff：对象字段稳定排序，实体数组优先按 `id/code/objectCode/actionCode/pageCode/tableName` 对齐，单纯数组重排不会产生噪声。
- 新增接口：
  - `POST /front/factory/projects/{projectId}/spec/patch/preview`。
  - `POST /front/factory/projects/{projectId}/spec/patch`。
  - `GET /front/factory/projects/{projectId}/versions/{leftVersionId}/diff/{rightVersionId}`。
- `easycode-web` 已补齐 Spec 获取/校验、Patch 预览/应用、快照、版本列表/详情和版本 Diff API 封装。

验证结果：

- P1-D JSON Codec、Patch、语义 Diff、版本冲突、统一校验和 Controller 定向测试共 39 个全部通过。
- P1-A 至 P1-D 整组契约测试共 57 个全部通过。
- Patch 测试覆盖有效应用、无效结果不落库、无变化不落库、基线哈希不匹配、历史版本过期和数组稳定 ID 对齐。
- `easycode-web` 生产构建通过；仅保留项目原有的大 chunk 警告。
- `ruoyi-generator` 全量执行 562 个测试，其中 544 个通过；仍为原先 18 个 AI 数据库生成、字典选项和 Qing 模板一致性失败，本轮未扩大失败面。

当前边界：

- Patch 新版本只写入不可变版本表，尚未反投影到 `FrontProject`、数据库表字段和页面设计等旧持久化对象。
- 现有一键生成仍读取旧对象，不能直接从 Patch 版本生成；在完成版本投影前，不应把 Patch 版本视为已部署配置。
- 语义 Diff 中的 `@stable-id` 路径用于展示和定位，不是可直接回放的 JSON Pointer。
- 尚未提供 Patch 合并/rebase、版本回滚、按历史版本生成和生成文件哈希对比。
- 前端目前只有 API 能力，DSL 调试器和版本 Diff UI 尚未实现。

下一步进入 P1-E：实现 Version -> Legacy Projection、按指定 specVersion 生成，并增加同一 Spec 重生成文件哈希一致性契约。

### 2026-07-10：P1-E 指定版本生成与稳定产物指纹

已完成：

- 新增无落库 `LegacyProjectProjection`，把 ProjectSpecV1 确定性投影为内存中的 `FrontProject`、表、字段和页面设计；表、字段、页面使用稳定合成 ID，不写回旧项目表。
- 投影覆盖项目元数据、模板与主题、表操作能力、字段生成属性、前后台页面、菜单、角色、业务闭环计划和业务动作，旧模板继续通过 `FrontProjectConverter` 消费这些数据。
- `IFrontProjectPreviewService` 新增内存项目渲染入口；旧 projectId 路径仍负责从数据库补齐数据，新入口直接复用 DDL/模拟数据刷新、一致性校验、页面过滤和实际模板渲染链路。
- 新增 `ProjectSpecGenerationService`：读取指定不可变版本、复算并校验 Spec 内容哈希、执行统一语义校验、投影旧模型，并只生成 Spec 已选择且模板包支持的交付目标。
- 每个实际生成 ZIP 被解析为按路径排序的文件清单，记录文件路径、大小和 SHA-256；同时生成目标级和整次生成的聚合内容哈希。
- 产物哈希不依赖 ZIP 条目顺序、压缩方式和时间戳；相同文件内容即使 ZIP 元数据不同也得到相同哈希。
- Factory 投影使用 ProjectSpecV1 schema 发布日期作为稳定模板 `datetime`；普通旧项目未设置该值时仍使用当前日期，避免改变原预览行为，同时消除跨日期重生成差异。
- ZIP 检查拒绝绝对路径、目录穿越、空路径和重复路径，并限制单次生成最多 10000 个文件、累计 256 MB 解压内容。
- 新增接口：`POST /front/factory/projects/{projectId}/versions/{specVersionId}/generate`。
- `easycode-web` 新增 `generateProjectSpecVersion(projectId, versionId)` API 封装，并沿用源码生成超时配置。

验证结果：

- P1-E 投影、内存预览、指定版本生成和 Controller 定向测试全部通过；生成契约覆盖无效 Spec、版本哈希不匹配、不支持的目标和 ZIP 元数据变化。
- Factory、真实生成服务和预览整组定向回归：`ruoyi-generator` 117 个测试、`ruoyi-admin` 9 个测试全部通过。
- `easycode-web` 生产构建通过；仅保留项目原有的第三方 PURE 注释和大 chunk 警告。
- `git diff --check` 无空白错误；仅有当前工作区既有的 LF/CRLF 转换提示。
- `ruoyi-generator` 全量执行 569 个测试，其中 551 个通过、18 个失败；失败集合仍为原有的 AI 数据库生成、字典选项和 Qing 模板一致性测试，本轮没有新增失败。

当前边界：

- 指定版本生成目前返回文件清单和内容指纹，不持久化 ZIP、生成运行或认证制品，也不提供该接口的制品下载。
- 文件哈希证明当前 Spec 与当前模板代码下的输出；Adapter、Plugin、Template Pack 版本尚未固化到生成运行记录，模板本身变化会合理地产生新哈希。
- Patch/历史版本现在可以直接生成，但不会反投影并覆盖 `FrontProject` 等旧持久化对象，因此“按版本生成”不等于“部署为当前配置”。
- 尚未提供版本回滚、两次生成清单对比、Factory 工作台 UI、DSL 调试器和版本 Diff UI。

下一步进入 P1-F：实现“历史版本回滚生成新版本”的后端契约，并在 `easycode-web` 建立只读 Factory 版本工作台，接入 Spec、校验、版本 Diff、按版本生成和产物指纹展示。

### 2026-07-10：P1-F 不可变回滚与只读 Factory 工作台

已完成：

- `ProjectSpecVersionService` 新增历史版本回滚能力：校验项目归属和目标版本内容哈希，锁定当前最新版本，并以目标内容创建新的 `ROLLBACK` 版本。
- 回滚不更新或覆盖任何历史记录；新版本号在当前最新版上递增，父版本指向回滚发生前的最新版本，从而保留完整时间线。
- 回滚到与当前最新版相同的内容会被拒绝，存储 JSON 与内容哈希不一致的目标版本也不会进入新版本链。
- 新增接口：`POST /front/factory/projects/{projectId}/versions/{specVersionId}/rollback`，并补齐 `easycode-web` API 封装。
- 新增只读 Factory 版本工作台路由：`/project/:projectId/factory`，项目列表通过“版本工厂”时钟图标进入。
- 工作台提供版本历史、版本摘要、统一校验结果、只读 ProjectSpec JSON、任意两版本语义 Diff、指定版本生成、目标与文件级 SHA-256 清单，以及回滚确认操作。
- 生成清单按目标展示文件数量、大小、聚合哈希和文件路径；页面刷新前保留在前端内存中，不伪装为已持久化制品。
- 工作台在窄屏下切换为纵向布局，版本区、JSON、Diff 表格和生成清单均保留独立滚动边界。

验证结果：

- P1 Factory、真实生成服务和预览定向回归通过：`ruoyi-generator` 120 个测试、`ruoyi-admin` 10 个测试全部通过。
- `easycode-web` 源码契约测试 297 个全部通过；同步修正了项目列表新增入口的列宽断言，以及一条与当前“代码解读入口集中在项目列表”交互相冲突的陈旧测试。
- Factory 工作台专项源码契约测试 3 个全部通过，覆盖路由、API、Spec/校验/Diff/生成/回滚连接和只读工作区主要控件。
- `easycode-web` 生产构建通过；仅保留项目原有的第三方 PURE 注释和大 chunk 警告。
- 本地 `http://localhost:5174` 与后端 `8080` 可访问；未登录访问 Factory 路由会正确跳转登录页。已有登录态已过期，因此本轮未提交默认凭据，真实项目数据下的页面视觉检查仍待有效登录态补做。

当前边界：

- 回滚创建的是新的 ProjectSpec 规范版本，不会写回或覆盖 `FrontProject`、旧数据库设计、页面设计等 Legacy 持久化对象；旧编辑器仍不等于已经切换到该版本。
- 指定版本生成结果和文件指纹尚未形成持久化 Generation Run，刷新页面后无法查询、下载或比较两次历史生成。
- 生成运行尚未固化 Adapter、Plugin、Template Pack、Prompt 和模型版本，当前哈希只证明“当前代码与扩展环境下”的文件内容一致性。
- 工作台当前为只读版本运维界面，尚未开放可视化 Patch 编辑、rebase/merge 或把版本部署为旧模型当前配置的操作。
- 真实数据视觉验收仍需有效登录会话；现阶段已有源码契约、响应式样式、生产构建和路由守卫验证。

下一步进入 P1-G：持久化 Generation Run、目标与文件清单，记录 Spec/Adapter/Plugin/Template 指纹，并提供两次生成的产物 Diff；完成后再进入 P2 生成内核与 Adapter 边界拆分。

### 2026-07-10：P1-G 持久化 Generation Run 与产物 Diff

已完成：

- 新增 `factory_generation_run`、`factory_generation_target`、`factory_generation_file` 三张不可变生成历史表，分别保存运行摘要、目标摘要和逐文件路径/大小/SHA-256。
- 新增独立迁移脚本 `sql/factory_generation_run.sql`，并同步完整 `db.sql` 与 `front_workbench.sql`；运行、目标和文件通过外键逐级级联，Mapper 不提供更新或删除操作。
- 成功生成在所有目标归档完成检查后才事务化写入运行记录；ProjectSpec 无效、版本哈希不匹配或目标不支持时不会留下伪成功运行。
- 运行记录绑定 `specVersionId`、Spec 版本号和 Spec 内容哈希，并记录 Adapter、Plugin 集合、Template 合约及完整生成环境指纹。
- 当前 Legacy Adapter 使用 `legacy-front-project-preview / legacy-projection-v1` 合约；Template 使用所选模板代码与 `legacy-template-contract-v1`，为 P2 的正式 Adapter/Template Pack 版本模型保留清晰迁移点。
- Plugin 指纹在计算前按插件代码和版本稳定排序；生成目标同样稳定排序，插件或目标输入顺序不会制造环境哈希噪声。
- 新增运行查询和产物 Diff：文件以 `templateType + relativePath` 对齐，返回新增、删除、修改、未变化数量，并标记 Spec、Adapter、Plugin、Template 和完整环境是否变化。
- 新增接口：
  - `GET /front/factory/projects/{projectId}/generation-runs`。
  - `GET /front/factory/projects/{projectId}/generation-runs/{generationRunId}`。
  - `GET /front/factory/projects/{projectId}/generation-runs/{leftRunId}/diff/{rightRunId}`。
- 原指定版本生成接口现在返回持久化 `generationRunId`、完成时间、状态和环境指纹。
- Factory 工作台“生成清单”升级为“生成运行”：支持刷新后读取历史、选择任意运行、查看四类环境指纹、比较两次运行并展开持久化目标/文件清单。

验证结果：

- P1 Factory、生成仓储、真实生成服务和预览整组定向回归通过：`ruoyi-generator` 127 个测试、`ruoyi-admin` 13 个测试全部通过。
- 新增指纹稳定性、事务写入、运行详情、文件 Diff、SQL 三表和 Mapper 不可变契约测试；专项新增测试 7 个全部通过。
- `easycode-web` 源码契约测试 297 个全部通过，Factory 工作台专项测试 3 个全部通过。
- `easycode-web` 生产构建通过，2312 个模块完成转换；仅保留项目已有的第三方 PURE 注释和大 chunk 警告。
- `ruoyi-generator` 全量执行 579 个测试，其中 561 个通过、18 个失败；失败集合仍是原有 AI 数据库生成、字典选项和 Qing 模板一致性测试，本轮没有新增失败。

当前边界：

- P1-G 只记录成功的同步生成；失败运行、阶段日志、重试关系和耗时指标尚未形成统一运行状态机。
- 持久化内容是运行元数据和哈希清单，不保存 ZIP 或文件正文，因此历史运行当前只能审计和比较，不能直接重新下载当时的字节制品。
- 当前 Adapter/Template 指纹是明确版本的 Legacy 合约描述，不是模板资源目录的逐文件哈希；P2 拆分后应由正式 Adapter 和 Template Pack 发布物提供自身版本与签名。
- Plugin 指纹来自 ProjectSpec 选择和配置，尚未解析真实插件包依赖、冲突、发布版本或签名。
- Generation Run 是可追溯的 Draft Source 证据，不是通过 Quality Gate 的 Certified Artifact，也不代表部署成功。
- 启用持久化生成前必须先执行 `factory_project_spec_version.sql`，再执行 `factory_generation_run.sql`。

下一步进入 P2：拆分确定性 Generation Kernel 和首个 Legacy RuoYi Adapter，定义 Adapter 输入/输出、版本描述、能力声明和模板资源指纹，让运行环境指纹从临时 Legacy 合约升级为正式发布物身份。

### 2026-07-10：P2-A 确定性 Generation Kernel 与 Legacy RuoYi Adapter

已完成：

- 新增正式 `GeneratorAdapter` SPI、生成请求/结果、原始归档、能力描述、Adapter 描述和 Template Pack 描述契约，并由 `GeneratorAdapterRegistry` 统一解析 Adapter 代码与版本。
- ProjectSpecV1 的交付描述支持可选 `adapterCode` / `adapterVersion`；旧 V1 快照缺省时兼容解析为 `ruoyi-legacy@1.0.0`，新组装的 Spec 显式固定该版本。
- 首个 `LegacyRuoYiGeneratorAdapter` 接管 `LegacyProjectProjection` 与现有内存预览渲染，声明 Schema、backend/frontend/admin_frontend/sql 输出目标和 Java/Node/MySQL 运行时能力。
- 新增 `DeterministicGenerationKernel`，统一校验 Adapter 返回目标集合，并接管 ZIP 路径安全、重复文件、文件数量、解压体积、稳定排序和逐文件/目标/聚合哈希计算。
- `ProjectSpecGenerationService` 退回到版本读取、内容哈希校验、语义校验、Kernel 调用和 Generation Run 持久化，不再直接依赖 Legacy 投影或预览服务。
- Template Pack 指纹现在覆盖有效数据库模板内容，以及 classpath 中 qing、VM 和 business-block 模板资源；资源路径稳定排序，模板内容变化会进入运行环境身份。
- Generation Run 新增 Adapter 能力指纹与规范化能力 JSON 快照，Factory 工作台显示生成当时的 Adapter 版本、能力指纹和输出目标摘要。
- 新库脚本已同步 `factory_generation_run.sql`、`front_workbench.sql` 和 `db.sql`；已部署 P1-G 表结构的环境可追加执行 `factory_adapter_release_upgrade.sql`。

验证结果：

- Adapter、Kernel、Factory、运行持久化、真实预览和 Controller 定向回归通过：`ruoyi-generator` 137 个测试、`ruoyi-admin` 13 个测试全部通过。
- `easycode-web` 源码契约测试 297 个全部通过，生产构建通过，2312 个模块完成转换；仅保留项目已有的第三方 PURE 注释和大 chunk 警告。
- `ruoyi-generator` 全量执行 589 个测试，其中 571 个通过、18 个失败；失败集合仍是既有 AI 数据库生成、字典选项和 Qing 模板一致性测试，本轮没有新增失败。

当前边界：

- 当前只有 `ruoyi-legacy@1.0.0` 一个 Adapter；Registry 已具备契约边界，但版本选择暂未实现完整 SemVer 约束、兼容矩阵或远程发布物解析。
- Template Pack 目前是 Legacy 版本标签加真实资源内容指纹，还不是可发布、签名、回滚和质量认证的独立实体。
- Plugin 指纹仍来自 ProjectSpec 选择与配置，尚未进入真实依赖解析、冲突检测和发布物治理。
- Kernel 仍是同步成功链路；失败运行、Stage 日志、检查点恢复、重试关系和 Certified Artifact 属于后续 Pipeline/Quality 阶段。
- Prompt、模型和 AI 任务尚未进入统一发布物追踪；生成器边界已经拆开，但 AI 侧仍需从自由文本与内联 Prompt 收敛到 ProjectSpec Draft/Patch。
- 全新环境执行顺序为 `factory_project_spec_version.sql`、`factory_generation_run.sql`；已经执行过前两者的环境再执行 `factory_adapter_release_upgrade.sql`。

下一步进入 P2-B：拆分 `ModelGateway` 与 `PromptRegistry`，建立 Prompt 模板/版本/发布解析和模型调用契约，并把 Prompt、模型身份固化到 AI 任务与后续 Generation Run 追踪中。

### 2026-07-10：P2-B1 ModelGateway 与 Prompt 运行身份

已完成：

- 新增 provider-neutral `ModelGateway`、模型请求/结果、流式处理、Gateway 描述和 `ModelGatewayRouter` 契约；未知 provider 与重复 provider 在调用前失败。
- 新增首个 `DeepSeekModelGateway`，在保留 `IDeepSeekClient` 兼容接口的同时支持显式模型 ID；任务锁定的模型会真实进入请求，而不是重新读取执行时默认模型。
- DeepSeek 非流式与流式用量记录现在按本次显式模型归属，避免配置默认模型与真实调用模型不一致时产生错误成本台账。
- 新增 `PromptRelease` / `PromptRegistry`，为现有 requirement、蓝图、数据库、图表、论文、代码解读、同步和一键生成用途发布内置 `1.0.0` 身份。
- 每个内置 Prompt 发布包含 Prompt code、版本、system Prompt、现有 user Prompt builder 合约、provider 映射和 canonical SHA-256；未知版本与指纹漂移会被拒绝。
- 新增 `AiInvocationPlanner` 和 `AiModelInvoker`；`AiGenerateServiceImpl` 保留现有领域 Prompt builder、解析、校验与修复逻辑，但生产模型调用统一从 ModelGateway 出口执行。
- 新增线程隔离的 `AiModelExecutionContext`；异步 Worker 在任务执行期间注入 Prompt/provider/model 锁定身份，嵌套调用与异常退出后恢复原上下文，防止线程池污染。
- `front_ai_generation_task` 新增 `prompt_code`、`prompt_version`、`prompt_fingerprint`；创建任务时将 Prompt 指纹、provider 和 model 一起写入幂等哈希，并通过任务状态响应返回。
- 新增 `factory_prompt_model_identity_upgrade.sql`：旧任务明确回填为 `legacy-unversioned` 并生成迁移指纹，不伪装成新的内置 Prompt 发布。

验证结果：

- Prompt/Gateway/调用器/上下文/任务/Mapper/SQL 专项与跨模块回归通过：`ruoyi-generator` 122 个测试、`ruoyi-admin` 13 个测试全部通过。
- `easycode-web` 源码契约测试 297 个全部通过，生产构建通过，2312 个模块完成转换；仅保留项目已有的第三方 PURE 注释和大 chunk 警告。
- `ruoyi-generator` 全量执行 604 个测试，其中 586 个通过、18 个失败；失败集合仍是既有 AI 数据库生成、字典选项和 Qing 模板一致性测试，本轮没有新增失败。

当前边界：

- P2-B1 发布的是代码内置 Prompt 身份，尚未建立数据库 Prompt Template/Version/Publication 表、发布与回滚 API，也没有 RuoYi Prompt 管理页面；因此“修改 Prompt 不发应用版本”尚未达成。
- 现有 user Prompt 正文仍由 `AiGenerateServiceImpl` 的领域 builder 生成，当前通过 `legacy-builder:{generateType}:v1` 合约进入指纹；后续需要逐类迁移为参数化模板或专用 Requirement Planner。
- 单一 AI 任务可以精确锁定一个 Prompt 发布；`one_click_project` 当前记录聚合 pipeline 合约，子阶段仍解析各自内置发布。数据库 Prompt 上线前必须升级为逐阶段 Prompt manifest。
- 当前只有 DeepSeek Gateway；多 provider 凭据、限流、熔断、模型能力矩阵和路由策略尚未实现。
- Prompt/模型身份已进入 AI Task 和关联 Generation Record 摘要，但尚未写入源码 Generation Run；两类运行需要在 Stage Pipeline 建立关联后统一追踪。
- 全新数据库由 `front_ai_task_upgrade.sql` / `front_workbench.sql` / `db.sql` 创建字段；已有 AI 任务表需追加执行 `factory_prompt_model_identity_upgrade.sql`。

下一步进入 P2-B2：建立 `factory_prompt_template`、`factory_prompt_version` 和发布指针，提供精确版本/当前发布解析、发布与回滚服务，并在 `ruoyi-ui` 增加 Prompt 管理入口；同时让一键生成记录逐阶段 Prompt manifest。

### 2026-07-10：P2-B2 数据库 Prompt 发布中心

已完成：

- 新增 `factory_prompt_template` 与 `factory_prompt_version`：模板保存稳定 Prompt code、生成类型、启用状态和当前发布指针，版本保存不可变的 system Prompt、user Prompt builder 合约、provider/model、规范化 SHA-256 和发布状态。
- Prompt 版本正文创建后不可更新；版本号在模板行锁内单调递增，草稿发布与历史版本回滚会在同一事务中退役旧版本、切换状态并移动当前指针。
- 新增 `PromptFingerprintService`，内置发布、数据库发布和发布服务复用同一规范化指纹算法；运行时会重新计算数据库内容哈希并拒绝漂移。
- 新增主运行实现 `DatabasePromptRegistry`：显式开启数据库开关后按生成类型解析当前发布，并支持按 Prompt code/version 精确解析已发布或已退役版本，保证排队任务可重放。
- 数据库功能未开启、没有当前数据库发布或模板被停用时继续回落到内置 Prompt，确保迁移前和逐步启用期间不阻断现有生成链路。
- 发布与回滚前校验内容指纹、当前代码真实实现的 user Prompt builder 合约和已注册 ModelGateway provider，避免发布无法执行的虚假版本。
- 新增带权限控制的模板列表、详情、创建、元数据编辑、版本创建、发布和回滚 API；Prompt code 与生成类型创建后不可变。
- 新增 RuoYi Prompt 管理页面和 API：可搜索模板、查看当前发布与指纹、创建不可变草稿、发布草稿、回滚已退役版本，并从内置发布预填首个数据库版本。
- 新增 `prompt_registry_menu.sql` 菜单权限脚本；`factory_prompt_registry.sql` 提供现有库升级和 11 类内置生成用途的模板元数据种子，完整建库脚本同步更新。

启用顺序：

1. 执行 `sql/factory_prompt_registry.sql` 创建表并写入模板元数据。
2. 执行 `sql/prompt_registry_menu.sql` 创建 Prompt 管理菜单和权限。
3. 设置 `FACTORY_PROMPT_REGISTRY_DATABASE_ENABLED=true`。
4. 重启后端；首个数据库版本可在管理页基于内置发布创建并发布。

验证结果：

- 数据库 Registry、发布服务和 Schema/API 源码契约专项测试 11 个全部通过，RuoYi Prompt 页面源码契约测试 2 个全部通过。
- P2-B2 相关后端跨模块回归通过：`ruoyi-generator` 49 个测试、`ruoyi-admin` 13 个测试全部通过。
- `ruoyi-ui` 全部 Node 测试通过，生产构建通过；仅保留项目已有的缺失导出、Browserslist 和 chunk 大小警告。
- `easycode-web` 源码契约测试 297 个全部通过，生产构建通过。
- `ruoyi-generator` 全量执行 615 个测试，其中 597 个通过、18 个失败；失败集合仍是既有 AI 数据库生成、字典选项和 Qing 模板一致性测试，本轮没有新增失败。
- 本地 RuoYi 前端开发服务在 `http://localhost:5174` 正常响应。

当前边界：

- P2-B2 数据库化的是 system Prompt 和发布身份；user Prompt 正文仍由 `AiGenerateServiceImpl` 的领域 builder 构造，管理页只展示并锁定当前已实现的 `legacy-builder:{generateType}:v1` 合约。
- 当前仅注册 DeepSeek provider；管理页不会管理 provider 凭据，模型凭据与 TLS 开发配置按当前决策暂不纳入本轮改造。
- 数据库开关需要配置后重启，不是运行时热切换；Prompt 发布和回滚本身即时生效。
- 模板停用或缺少数据库当前发布时会回落内置版本，当前没有“彻底禁止该生成类型”的运行策略。
- 尚未提供 A/B 实验、多人审批、在线模型调试、参数化 user Prompt 模板和模型能力路由。
- 单任务已锁定精确 Prompt 身份，但一键生成的各 AI 阶段尚未形成统一 stage manifest、检查点、失败恢复和 Generation Run 关联。

下一步进入 P2-C：建立 Stage Handler Pipeline，把一键生成拆成可识别、可记录、可恢复的阶段；在任务创建时固化逐阶段 Prompt/provider/model manifest，并把阶段运行、ProjectSpec 版本和源码 Generation Run 串成统一追踪链路。

### 2026-07-10：P2-C1 Stage Pipeline 与逐阶段 Prompt Manifest

已完成：

- 新增规范化 `AiStageManifest`，使用 schemaVersion、pipelineCode 和稳定排序的阶段列表描述一键生成的 11 个阶段。
- 一键任务入队时一次性解析并锁定应用蓝图、业务闭环计划、数据库和业务蓝图四个 AI 子阶段的 Prompt code/version/fingerprint、provider 和 model；非 AI 阶段也进入同一顺序清单。
- Stage manifest 使用规范化 JSON 和 SHA-256，完整哈希进入任务幂等键；同一请求在任一子阶段 Prompt 发布变化后会形成新的任务身份。
- `front_ai_generation_task` 新增 `stage_manifest_json` 和 `stage_manifest_hash`，创建后 Mapper 不提供更新路径；重试保留原 manifest，不追随之后发布的新 Prompt。
- 新增 `GenerationStagePipeline`：阶段切换时自动完成上一阶段，记录当前任务尝试号、阶段顺序、开始/结束时间、耗时和成功/失败状态，并在异常后清理线程状态。
- AI 子阶段通过嵌套 `AiModelExecutionContext` 切换到 manifest 中的精确身份；阶段结束后恢复外层任务上下文，避免线程池和相邻阶段污染。
- 新增 `factory_ai_task_stage` 阶段尝试账本，同一任务、阶段和尝试号唯一；Prompt/provider/model 身份随尝试记录保存，正文不随重试更新。
- 一键生成原有阶段顺序、业务闭环审计、ProjectSpec 快照、源码预览和运行预览重试语义保持不变；没有 manifest 的历史任务继续按兼容路径执行。
- 运行预览失败仍兼容返回可下载源码，但 `RUN_PREVIEW` 阶段账本会准确记录为失败，不再被最终汇总阶段误标为成功。
- AI 任务状态响应新增 manifest、manifest 哈希和按尝试/顺序排列的阶段记录，可直接用于后续工作台时间线。
- 新增可重复执行的 `factory_stage_pipeline.sql`；完整 `front_workbench.sql`、`db.sql` 和 AI 任务建表脚本同步更新，并修复了完整建库脚本中 Prompt 表行首残留字符。

升级顺序：

1. 确保已执行 `front_ai_task_upgrade.sql` 和 `factory_generation_run.sql`，已有任务表包含 P2-B1 Prompt 身份列。
2. 执行 `factory_stage_pipeline.sql`；脚本会检测 manifest 列是否已存在，并安全创建阶段账本。
3. 重启后端。新建任务开始写入 manifest 和阶段记录；历史任务保持兼容，但不会伪造历史阶段身份。

验证结果：

- Manifest、Pipeline、Schema/Mapper、任务创建、Worker 和一键编排定向测试 46 个全部通过；最终相关链路复测 31 个全部通过。
- 真实一键编排测试确认四个 AI 子调用分别读取 `app_blueprint`、`business_loop_plan`、`database` 和 `business_blueprint` 的固定阶段身份。
- `ruoyi-admin` 全部 38 个测试通过；本地前端开发服务在 `http://localhost:5174` 正常响应。
- `ruoyi-generator` 全量执行 621 个测试，其中 603 个通过、18 个失败；失败集合仍是既有 AI 数据库生成、字典选项和 Qing 模板一致性测试，本轮没有新增失败。
- `git diff --check` 没有内容错误，仅保留工作区已有的 CRLF 转换提示。

当前边界：

- P2-C1 已建立 durable stage contract，但阶段业务体仍集中在 `OneClickProjectGenerationServiceImpl`；尚未拆成可独立替换、单测和声明输入输出的 Spring Handler。
- 当前失败重试会保留 manifest，但除运行预览外仍从头重新生成；尚未持久化可从任意成功阶段恢复的 checkpoint payload。
- 阶段账本预留 `generationRunId`，尚未在源码生成时回填；AI Task、ProjectSpec Version 和 Generation Run 还没有完全串成一条运行链。
- 阶段取消、心跳、超时策略、按阶段重试、并行分支和补偿动作尚未实现。
- 用量台账仍按任务聚合；尚未把 token/cost 精确分摊到单个阶段尝试。
- 本轮没有新增前端页面；任务状态 API 已提供时间线数据，工作台可视化留到 Handler/Checkpoint 稳定后接入。

下一步进入 P2-C2：把 11 个阶段拆成独立 `GenerationStageHandler`，定义阶段输入/输出与 checkpoint codec；优先实现从数据库完成、ProjectSpec 固化和运行预览三个安全检查点恢复，并在源码生成后回填 `generationRunId`。

### 2026-07-10：P2-C2a 不可变 Checkpoint 与 Generation Run 贯通

已完成：

- 新增 `factory_ai_task_checkpoint`，以任务、阶段和尝试号唯一保存数据库审计、源码预览和运行预览检查点；记录阶段顺序、schema、规范化 payload、SHA-256、ProjectSpec 版本和 Generation Run 关联。
- 新增 `AiTaskCheckpointService`：写入前使用 canonical JSON 计算内容哈希，读取恢复时重新解析 envelope、校验 schema/stage/hash，拒绝正文漂移和阶段错配。
- Checkpoint Mapper 仅提供插入、最新读取和历史列表，不提供 payload/content hash 更新路径；不同任务尝试生成独立检查点，不覆盖历史证据。
- 数据库闭环审计与一致性修复完成后保存 appBlueprint、businessLoopPlan 和当前报告上下文，为后续从数据库安全边界恢复准备输入。
- ProjectSpec 固化后调用正式 `ProjectSpecGenerationService`，通过确定性 Kernel 生成文件清单并持久化 Generation Run；一键结果新增 `generationRunId`。
- `SOURCE_PREVIEW` 阶段账本回填同一个 `generationRunId`，源码检查点同时绑定 specVersionId 与 generationRunId，AI Task、ProjectSpec Version 和 Generation Run 形成可追踪链路。
- 源码结构预览、下载就绪标记和运行预览流程继续保留，正式 Generation Run 不替代现有用户侧源码预览行为。
- 重试恢复优先读取并验证 `SOURCE_PREVIEW` 检查点；检查点有效且源码已就绪时只重启运行预览，不再依赖可能被后续进度覆盖的 `resultPayload`。
- 没有检查点的历史任务继续使用原有任务结果兼容路径；不会为历史执行伪造 Checkpoint 或 Generation Run。
- 任务状态响应新增检查点元数据列表，暴露阶段、尝试号、哈希、Spec/Run 关联和时间；内部恢复 payload 使用 `JsonIgnore`，不直接发送到前端。
- 新增 `factory_stage_checkpoint.sql`，完整 `front_workbench.sql` 和 `db.sql` 同步建表与正确的外键删除顺序。

升级顺序：

1. 先完成 P2-C1 升级并执行 `factory_stage_pipeline.sql`。
2. 执行 `factory_stage_checkpoint.sql` 创建不可变检查点表。
3. 重启后端。新任务开始生成 Checkpoint 和 Generation Run；历史任务继续走兼容路径。

验证结果：

- Checkpoint 服务、Schema/Mapper、阶段关联、任务状态和一键恢复专项测试 32 个全部通过。
- 测试覆盖 payload 篡改拒绝、源码 Generation Run 回填、阶段账本关联，以及检查点优先于无效任务结果恢复运行预览。
- `ruoyi-admin` 全部 38 个测试通过；本地前端开发服务在 `http://localhost:5174` 正常响应。
- `ruoyi-generator` 全量执行 626 个测试，其中 608 个通过、18 个失败；失败集合仍是既有 AI 数据库生成、字典选项和 Qing 模板一致性测试，本轮没有新增失败。
- `git diff --check` 没有内容错误，仅保留工作区已有的 CRLF 转换提示。

当前边界：

- P2-C2a 只自动恢复已经稳定使用的 SOURCE_PREVIEW -> RUN_PREVIEW 边界；数据库检查点已经持久化，但尚未从该点重建内存上下文并继续业务蓝图/页面阶段。
- 11 个阶段业务体仍集中在 `OneClickProjectGenerationServiceImpl`，独立 Handler、声明式输入输出和 Handler 能力注册留到 P2-C2b。
- Generation Run、阶段关联和 Checkpoint 是连续写入，不是同一数据库事务；检查点写入失败时可能保留一条成功 Generation Run，重试会产生新的可审计运行，而不会覆盖旧运行。
- Checkpoint 当前保存完整规范化 payload，不做增量压缩、TTL 或归档；状态接口只返回元数据，不返回正文。
- 尚未支持手动选择恢复点、从数据库检查点恢复、阶段取消/超时/心跳、并行分支和按阶段 token/cost 统计。

下一步进入 P2-C2b：建立独立 `GenerationStageHandler` Registry，把数据库审计后的业务蓝图、页面初始化、源码和运行预览阶段先迁出编排器；定义 handler input/output schema，并实现从 `DATABASE_LOOP_AUDIT` 检查点恢复。

### 2026-07-10：P2-C2b 独立 Stage Handler 与数据库检查点恢复

已完成：

- 新增 `OneClickGenerationStageHandler` 契约，每个 Handler 显式声明稳定阶段代码、进度、当前步骤和 `execute` 入口；阶段业务不再依赖编排器私有方法。
- 新增 `OneClickGenerationContext`，集中携带 task、请求、结果、报告、项目、前端开关、应用蓝图、业务闭环计划、数据库审计状态和业务动作，作为后半程 Handler 的类型化输入/输出边界。
- 新增 `OneClickStageHandlerRegistry`，Spring 自动收集 Handler；空阶段代码、重复阶段代码和执行时缺失 Handler 都会明确失败。
- 编排器通过 Registry 解析 Handler，并复用 `GenerationStagePipeline.runPinned` 执行；业务蓝图阶段继续使用任务创建时固化的精确 Prompt/provider/model 身份。
- `BUSINESS_BLUEPRINT` 迁移到独立 Handler：根据数据库闭环状态决定生成或跳过业务动作，并回填动作数量。
- `BUSINESS_LOOP_AUDIT` 迁移到独立 Handler：执行业务动作覆盖审计、记录降级警告，并在一致性修复后刷新业务闭环计划。
- `PAGE_INITIALIZE` 迁移到独立 Handler：分别初始化用户端和管理端页面、绑定业务闭环并执行一致性修复。
- `SOURCE_PREVIEW` 迁移到独立 Handler：固化 ProjectSpec、执行确定性 Kernel、记录 Generation Run、关联阶段、生成源码结构、标记下载就绪并保存源码检查点。
- 新增共享 `OneClickStageSupport`，统一 Handler 的一致性修复、任务中间结果落盘、业务闭环审计指标和警告语义。
- 重试时在源码检查点之后继续检查 `DATABASE_LOOP_AUDIT` 检查点；仅当任务尝试号大于 1 且 payload 通过 schema/stage/hash 校验后才恢复。
- 数据库恢复会重建结果、报告、appBlueprint 和 BusinessLoopPlan 上下文，从业务蓝图 Handler 继续；不会停止现有预览、清空项目产物，也不会重新调用应用蓝图、闭环计划和数据库 AI 阶段。
- 编排器中已删除业务蓝图、页面初始化和源码预览的旧私有实现，避免新旧两套路径并存。

验证结果：

- Handler Registry、固定身份执行、Checkpoint、Generation Run 和数据库恢复专项测试 18 个全部通过。
- 数据库恢复测试确认前四个 AI/数据库阶段、`resetGeneratedArtifacts` 和旧预览停止均不会再次执行，后半程 Handler 会正常生成到完成。
- `ruoyi-admin` 全部 38 个测试通过；本地前端开发服务在 `http://localhost:5174` 正常响应。
- `ruoyi-generator` 全量执行 629 个测试，其中 611 个通过、18 个失败；失败集合仍是既有 AI 数据库生成、字典选项和 Qing 模板一致性测试，本轮没有新增失败。
- `git diff --check` 没有内容错误，仅保留工作区已有的 CRLF 转换提示。

当前边界：

- 当前独立 Handler 覆盖数据库之后的业务蓝图、业务审计、页面和源码四个阶段；项目准备、应用蓝图、闭环计划、数据库、数据库审计、运行预览和完成汇总仍由编排器推进。
- 运行预览仍包含编排器内的启动、轮询、超时、失败降级和 URL 回填逻辑，下一轮应迁移为独立 Handler/Coordinator。
- 数据库检查点校验 payload 身份和哈希，但尚未保存数据库表/字段内容哈希；恢复时依赖项目持久化数据未被外部修改。
- Handler 上下文是 Java 类型契约，尚未为每个 Handler 发布独立 JSON input/output schema、版本号和兼容策略。
- 尚未支持手动选择恢复点、跨节点阶段租约、阶段取消、分支并行、补偿动作和阶段级 token/cost。
- 本轮不新增数据库表，部署继续依赖 P2-C1/P2-C2a 的 `factory_stage_pipeline.sql` 与 `factory_stage_checkpoint.sql`。

下一步进入 P2-C2c：迁移运行预览为独立 Handler/Coordinator，并把项目准备、应用蓝图、闭环计划、数据库和数据库审计逐步迁入同一 Registry；补充 Handler 版本/输入输出描述，为阶段级取消、超时和手动恢复打基础。

### 2026-07-10：P2-C2c 全阶段 Handler 与版本化执行契约

已完成：

- `OneClickGenerationStageHandler` 新增 Handler code、version、input contract 和 output contract；当前首个发布统一使用 `1.0.0` 与 `one-click-generation-context:v1`。
- `factory_ai_task_stage` 新增 `handler_code`、`handler_version`、`input_contract` 和 `output_contract`；阶段启动后立即绑定 Handler 描述，已有描述不会被同尝试重写。
- 新增可重复执行的 `factory_stage_handler_descriptor.sql`，使用 `information_schema` 逐列检测；完整 `front_workbench.sql` 和 `db.sql` 同步更新。
- 新增项目准备 Handler：完整生成时停止旧预览并清空生成产物，数据库检查点恢复时只加载项目与前端开关，不执行破坏性操作。
- 新增应用蓝图、业务闭环计划和数据库 Handler；四个 AI 阶段现在全部通过 Registry 与 `runPinned` 消费任务创建时的逐阶段 Prompt manifest。
- 新增数据库闭环审计 Handler：对齐表引用、更新持久化计划、执行审计与一致性修复，并写入数据库安全检查点。
- 运行预览启动、状态轮询、超时、中断、失败降级、URL 回填、Checkpoint 和失败阶段记录全部迁入 `RunPreviewStageHandler`。
- 新增完成汇总 Handler；项目准备到完成汇总的 11 个 manifest 阶段均有独立 Spring Handler。
- 一键编排器重写为 216 行的恢复决策与顺序推进器，只负责选择 SOURCE/DATABASE/FULL 路径、构造 Context、解析 Handler、更新任务进度和包装异常。
- SOURCE 检查点恢复执行 `RUN_PREVIEW -> COMPLETED`；DATABASE 检查点恢复执行非破坏性 `PROJECT_PREPARE` 后从业务蓝图继续；完整生成按 11 阶段顺序执行。
- 阶段状态响应会随原有 `AiTaskStage` 元数据返回 Handler 发布身份，可以审计某次尝试实际执行的阶段实现契约。

升级顺序：

1. 先完成 `factory_stage_pipeline.sql` 与 `factory_stage_checkpoint.sql`。
2. 执行 `factory_stage_handler_descriptor.sql` 增加 Handler 发布身份列。
3. 重启后端；旧阶段记录保持 Handler 身份为空，新执行自动写入 `1.0.0` 描述。

验证结果：

- Handler、Registry、Pipeline、Checkpoint 和三份 Schema 专项测试 22 个全部通过。
- 一键测试继续覆盖完整生成、轮询成功、超时、运行预览失败降级、SOURCE 恢复、DATABASE 恢复、闭环不完整降级和前端禁用路径。
- `ruoyi-admin` 全部 38 个测试通过；本地前端开发服务在 `http://localhost:5174` 正常响应。
- `ruoyi-generator` 全量执行 631 个测试，其中 613 个通过、18 个失败；失败集合仍是既有 AI 数据库生成、字典选项和 Qing 模板一致性测试，本轮没有新增失败。
- `git diff --check` 没有内容错误，仅保留工作区已有的 CRLF 转换提示。

当前边界：

- Registry 当前每个阶段代码只允许一个已安装 Handler，尚未支持同阶段多版本并存、版本约束解析、兼容矩阵或热切换。
- Handler 输入输出已有稳定名称和版本，但尚未发布独立 JSON Schema，也没有在执行前做结构化 schema validation。
- 数据库检查点仍依赖项目持久化表未被外部修改，尚未加入表/字段内容哈希。
- 运行预览超时策略已归属 Handler，但仍是单节点同步轮询，没有分布式租约、心跳续租或异步事件回调。
- 尚未提供阶段级取消、手动恢复点选择、重跑单阶段、并行分支、补偿动作和阶段级 token/cost。
- 本轮没有新增前端页面；现有任务状态接口已经具备阶段、Prompt、Handler、Checkpoint、Spec 和 Run 时间线数据。

P2-C 的核心主干至此完成。下一步进入 P2-D1：建立 Plugin Manifest、版本化插件 Registry、依赖/冲突解析和稳定插件执行计划，让 ProjectSpec 中的插件选择从字符串指纹升级为真实发布物图。

### 2026-07-10：P2-D1a Plugin Manifest 与发布图解析核心

已完成：

- 新增 `FeaturePlugin` SPI 和 `PluginManifest` 1.0。Manifest 覆盖 code、version、provider、trusted、requires、provides、conflicts、Adapter 兼容范围、ProjectSpec schema、DSL 扩展、数据库迁移、模板、静态资源、Validator、Quality Check、权限、菜单和配置键。
- 新增 `FeaturePluginRegistry`，允许同一插件代码安装多个语义版本；启动时拒绝重复发布、非法 SemVer、缺失兼容声明、自依赖、不受信任发布以及重复或空的资源声明。
- 第一阶段继续只允许内置或受信任 Spring 插件进入 Registry；没有开放第三方 JAR 上传或在主进程执行任意代码。
- 新增 SemVer 约束解析，支持精确版本、`^`、`~` 和组合比较范围；Registry 中同插件版本按语义版本降序稳定排列。
- 新增 `PluginResolver`：从 `ProjectSpec.plugins` 建立直接选择和传递依赖约束，使用候选版本回溯处理后加入的收窄约束，并校验精确 Adapter 发布、ProjectSpec schema 和该版本声明的配置键。
- 解析器会双向检查插件代码冲突和 capability 冲突，拒绝依赖环，最终输出依赖优先、同层按插件代码稳定排序的 `PluginExecutionPlan`。
- 执行计划记录直接/传递来源、精确 code/version/provider、Manifest 指纹、直接配置、依赖和能力，并生成规范化 SHA-256 解析指纹。
- `ProjectSpecValidationService` 已把解析异常转换为 `/plugins` 路径上的 `PLUGIN_RESOLUTION_FAILED`；正式版本生成会在调用 Adapter 之前拒绝不可解析的插件图。
- `GenerationEnvironmentFingerprintService` 不再直接哈希 ProjectSpec 中的插件字符串；Generation Run 的 `pluginFingerprint` 现在来自真实解析后的发布图，Manifest、传递依赖、精确版本或配置变化都会改变指纹。

验证结果：

- Plugin Registry、SemVer、依赖回溯、冲突、循环、兼容性、配置、ProjectSpec 校验、生成阻断和发布图指纹聚焦测试 26 个全部通过。
- `ruoyi-admin` 全部 38 个测试通过；本地前端开发服务继续在 `http://localhost:5174` 正常响应。
- `ruoyi-generator` 全量执行 646 个测试，其中 628 个通过、18 个失败；失败集合仍是既有 AI 数据库生成、字典选项和 Qing 模板一致性基线，本轮没有新增失败。

当前边界：

- 当前 Registry 来源是受信任 Spring Bean，尚未建立 `factory_plugin` / `factory_plugin_version`、草稿/发布/停用状态和当前发布指针。
- `PluginExecutionPlan` 已在生成前确定并进入运行指纹，但尚未单独持久化完整计划 JSON，Generation Run 当前仍只保存聚合插件指纹。
- Manifest 已声明数据库迁移、模板、资源、Validator、Quality Check、权限和菜单，但本轮只解析和审计这些声明，尚未执行插件贡献。
- 尚未把现有 BusinessBlock 迁移为内置 `page-block` 插件；在迁移前，现有页面业务块继续走旧实现。
- 尚未实现插件签名、制品校验、上传审核、沙箱、卸载迁移和市场能力。

下一步进入 P2-D1b：增加插件与不可变版本持久化表、发布/回滚解析服务和管理 API，并把每次生成的完整 `PluginExecutionPlan` 固化到 Generation Run；完成后选择一个低风险 BusinessBlock 迁移为首个内置插件发布物。

### 2026-07-10：P2-D1b 插件发布持久化与执行计划留痕

已完成：

- 新增 `factory_plugin` 与 `factory_plugin_version`。插件定义保存稳定 code、provider、启停状态和当前发布指针；版本表保存单调版本号、SemVer、Manifest schema、规范化 Manifest JSON、SHA-256、父版本和 DRAFT/PUBLISHED/RETIRED 生命周期。
- 插件版本正文只提供插入路径；Mapper 不提供 Manifest、版本标签或内容哈希更新。发布只切换生命周期状态与定义表当前指针，历史发布不会被覆盖。
- 新增 `FeaturePluginServiceImpl`，提供定义列表/详情/创建/编辑、版本创建、发布与回滚。版本创建只允许引用当前进程已经安装的受信任 `FeaturePlugin` 发布，数据库不能创建主进程中不存在的可执行代码。
- 发布和回滚会在事务内锁定插件定义、校验版本归属和状态、重新校验存储行 code/provider/version/schema 与 Manifest 身份、规范化哈希以及本机实现指纹，然后退役旧发布并原子移动当前指针。
- 新增 `DatabasePluginReleaseCatalog` 并作为 `PluginReleaseCatalog` 的主实现。数据库开关关闭时继续使用 Spring 内置 Registry；开启后只暴露启用插件的 PUBLISHED/RETIRED 版本，并要求每个数据库发布与本机安装 Manifest 完全一致。
- 新增 `factory.plugin-registry.database-enabled`，默认 `false`，可通过 `FACTORY_PLUGIN_REGISTRY_DATABASE_ENABLED` 开启；未执行迁移的现有开发环境不会访问新表。
- 新增 `/generator/plugin` 管理 API，覆盖列表、详情、定义创建/编辑、不可变版本创建、发布和回滚，并使用 `generator:plugin:*` 权限保护。本轮没有增加 `ruoyi-ui` 管理页面或指向不存在页面的菜单。
- `factory_generation_run` 新增 `plugin_plan_json`；正式生成现在同时持久化插件聚合指纹和完整规范化 `PluginExecutionPlan`，运行查询可恢复直接/传递发布、执行顺序、Manifest 指纹与当次配置。
- 历史 Generation Run 的升级列允许为空；新生成在记录运行前强制要求完整执行计划，避免继续产生只有指纹、没有证据正文的新记录。
- 新增可重复执行的 `factory_plugin_registry.sql`，并同步 `factory_generation_run.sql`、`front_workbench.sql` 和 `db.sql`。

升级顺序：

1. 先完成 P1-G 的 `factory_generation_run.sql`。
2. 执行 `factory_plugin_registry.sql`，创建插件发布表并为 Generation Run 增加 `plugin_plan_json`。
3. 部署包含受信任 `FeaturePlugin` Spring Bean 的应用版本，通过管理 API 建立定义、创建不可变版本并发布。
4. 确认 ProjectSpec 所选插件均有已发布且本机已安装的匹配版本后，再设置 `FACTORY_PLUGIN_REGISTRY_DATABASE_ENABLED=true` 并重启后端。

验证结果：

- Plugin Registry、数据库目录、发布/回滚服务、Schema/Mapper、Resolver、ProjectSpec 校验和 Generation Run 计划留痕聚焦测试 42 个全部通过。
- `ruoyi-admin` 全部 38 个测试通过；本地前端开发服务继续在 `http://localhost:5174` 正常响应。
- `ruoyi-generator` 全量执行 659 个测试，其中 641 个通过、18 个失败；失败集合仍是既有 AI 数据库生成、字典选项和 Qing 模板一致性基线，本轮没有新增失败。

当前边界：

- 当前项目尚无正式 BusinessBlock `FeaturePlugin` Bean，因此发布中心只能治理后续安装的可信实现；现有 BusinessBlock 仍走旧页面组合逻辑。
- 数据库目录每次解析直接读取发布记录，尚未增加发布事件、缓存失效或跨节点通知。
- 已提供管理 API，但尚未提供 `ruoyi-ui` Plugin 管理页面和菜单。
- Manifest 中声明的迁移、模板、资源、Validator、Quality Check、权限和菜单仍只参与发布身份与审计，尚未进入插件贡献执行生命周期。
- 第三方制品上传、签名、扫描、审核、沙箱、卸载和市场能力仍明确排除。

下一步进入 P2-D2：选择一个低风险、边界清晰的现有 BusinessBlock 迁移为首个内置 `page-block` Feature Plugin，并让插件贡献真正进入校验与生成上下文；随后再补 Plugin 管理页面。

### 2026-07-10：P2-D2 首个内置 PageBlock 插件

已完成：

- 选择现有 Carousel BusinessBlock 作为首个迁移对象，正式发布身份为 `page-block.carousel@1.0.0`，provider 为 `ruoyi-factory`，插件类型为 `page-block`。
- `PluginManifest` 新增 `pluginType`；Carousel Manifest 声明 `page-block:carousel` capability、RuoYi Legacy Adapter `^1.0.0` 兼容范围、ProjectSpec 1.0、页面 DSL 扩展、配置 Validator、`block.json` 和原有 7 个前后端模板资源。
- 新增 `PageBlockFeaturePlugin`、`PageBlockValidationContext` 和 `PageBlockGenerationContext`。PageBlock 插件在统一 FeaturePlugin 发布治理之上，可以拥有页面块定义、实例校验和确定性生成上下文贡献。
- `BusinessBlockRegistryService` 现在优先使用 PageBlock 插件提供的定义；classpath 扫描仍保留其他旧 BusinessBlock，但会跳过已由插件接管的同 code 资源，避免重复定义。
- Carousel 插件 Validator 会在原有表/字段/必填校验之后拒绝未在 `block.json` 声明的配置键；校验由 BusinessBlock Registry 正式调用，不是独立旁路检查。
- Carousel 渲染所需的 `carouselPkColumn`、`hasCarouselLink`、`hasCarouselSort` 和 `hasCarouselStatus` 已从共享 `BusinessBlockGenerationService` 迁入插件贡献；主键解析和默认回退由结构化生成上下文提供。
- 原 Carousel `block.json`、Velocity 模板、输出路径、API 路径和生成源码内容保持不变，旧页面设计器数据不需要迁移。
- `ProjectSpecAssembler` 会递归检查普通页面和 embedded layout；发现 Carousel 实例时自动写入精确 `page-block.carousel@1.0.0` 选择。
- `PluginResolver` 会检查已迁移 PageBlock 的选择完整性。手工 ProjectSpec 使用 Carousel 但漏选插件时，会在 Adapter 执行前以插件解析错误拒绝生成。
- Carousel 发布随后进入 D1a/D1b 的依赖解析、Manifest 指纹和 `plugin_plan_json`，每次生成可还原实际使用的插件发布。

启用说明：

- `FACTORY_PLUGIN_REGISTRY_DATABASE_ENABLED=false` 时，Carousel 直接由内置可信 Registry 提供，不需要数据库记录。
- 开启数据库发布目录前，先通过 `/generator/plugin` 创建 code 为 `page-block.carousel`、provider 为 `ruoyi-factory` 的定义；创建版本时只需指定 `1.0.0`，服务会读取本机 Manifest 生成不可变正文；发布后再开启数据库目录。
- 本轮不新增数据库结构，继续使用 P2-D1b 的 `factory_plugin_registry.sql`。

验证结果：

- BusinessBlock 生成、Registry、页面设计、ProjectSpec 投影、插件解析、Manifest 和旧生成器聚焦兼容测试 161 个全部通过。
- `ruoyi-admin` 全部 38 个测试通过；本地前端开发服务继续在 `http://localhost:5174` 正常响应。
- `ruoyi-generator` 全量执行 665 个测试，其中 647 个通过、18 个失败；失败集合仍是既有 AI 数据库生成、字典选项和 Qing 模板一致性基线，本轮没有新增失败。

当前边界：

- Notice、News、Cart、Order、MasterDetail 和四个 Chart BusinessBlock 仍由旧 classpath Registry 与共享生成服务负责。
- PageBlock 插件当前贡献配置校验和模板上下文，尚未拥有独立文件生成器、数据库迁移执行器、权限/菜单贡献执行器或 Quality Check 生命周期。
- ProjectSpec 只为已迁移的 Carousel 自动声明插件；旧 BusinessBlock 暂时不要求插件选择，以保持渐进迁移兼容。
- 管理 API 已具备，但 `ruoyi-ui` Plugin 管理页面仍未实现。

下一步进入 P2-D3：提取通用 PageBlock 模板文件贡献与执行生命周期，迁移 Notice/News 这组相近内容块，并让插件声明的 Validator、模板和 Quality Check 从身份元数据升级为可执行贡献。

### 2026-07-10：P2-D3 PageBlock 可执行贡献生命周期

已完成：

- 新增资源型 PageBlock 基类。插件继续复用原有 `business-blocks/<code>/block.json` 和 Velocity 模板，但 Manifest 模板清单改为从结构化定义生成，不再在 Java 中维护第二份路径列表。
- 新增统一贡献协调器，在 Registry 加载时核对插件类型、`page-block:<code>` capability、定义身份、Validator、Quality Check 以及模板资源；Manifest 与 `block.json` 模板集合不一致或资源不存在时立即拒绝启动该贡献。
- Validator、生成上下文和渲染后 Quality Check 现在都经同一生命周期执行。内置资源插件发布 `page-block.rendered-source-nonempty:v1`，会检查输出路径、模板归属和非空源码。
- Carousel 已重构到通用资源插件基类，发布身份和生成结果保持 `page-block.carousel@1.0.0` 不变。
- Notice 和 News 完成迁移，分别发布 `page-block.notice@1.0.0`、`page-block.news@1.0.0`。主键、状态启用值、发布时间及 News 摘要/图片等专属变量已从共享生成服务移入插件贡献。
- 状态注释解析下沉到结构化 `PageBlockGenerationContext`，共享 `BusinessBlockGenerationService` 不再包含 Notice/News 特判。
- `ProjectSpecAssembler` 会为普通和 embedded layout 中的 Notice/News 自动选择精确版本；既有通用 `PluginResolver` 完整性检查同时覆盖三个已迁移 PageBlock。
- 原 `block.json`、7 个前后端模板、输出路径、API 路径和生成源码语义保持不变，已有页面设计数据无需迁移。

验证结果：

- PageBlock 生命周期、Registry、生成服务、ProjectSpec 和插件解析聚焦测试 66 个全部通过。
- `ruoyi-generator` 全量执行 671 个测试，其中 653 个通过、18 个失败；失败仍为 11 个 AI 数据库生成、1 个字典选项和 6 个 Qing 模板一致性基线，本轮没有新增失败。
- `ruoyi-admin` 全部 38 个测试通过；本地前端开发服务继续在 `http://localhost:5174` 正常响应。

当前边界：

- Cart、Order、MasterDetail 和四个 Chart BusinessBlock 仍由旧 classpath Registry 与共享生成上下文负责。
- 当前 Quality Check 执行器只覆盖模板归属和非空源码；编译、静态分析、测试生成与运行仍属于后续质量阶段。
- 数据库迁移、权限和菜单仍是 Manifest 发布声明，尚未纳入 PageBlock 可执行贡献。
- `ruoyi-ui` Plugin 管理页面仍未实现。

下一步进入 P2-D4：迁移 Cart/Order/MasterDetail 这组交易与主从块，提取可组合的表关系生成贡献；随后再处理 Chart 插件族和 Plugin 管理页面。

### 2026-07-10：P2-D4 交易与主从 PageBlock 插件

已完成：

- `PageBlockGenerationContext` 新增可链式组合的表主键贡献和可选字段开关贡献。插件只声明配置键与模板变量的映射，主键优先级、缺表回退和空值语义由统一上下文负责。
- Cart 完成迁移并发布为 `page-block.cart@1.0.0`，拥有购物车表主键、商品图片和库存开关贡献。
- Order 完成迁移并发布为 `page-block.order@1.0.0`，组合订单、订单明细、商品三张表的主键，以及下单时间和商品图片开关贡献。
- MasterDetail 完成迁移并发布为 `page-block.master_detail@1.0.0`，组合主表、子表主键和描述、辅助值、时间字段开关贡献。
- 共享 `BusinessBlockGenerationService` 中 Cart、Order、MasterDetail 的 13 个模板变量特判和旧主键解析方法已删除。六个已迁移 PageBlock 均通过统一插件生命周期贡献生成上下文。
- 三个插件继续复用原有 `block.json` 和各 7 个前后端模板，输出路径、API 路径、SQL 关系、生成源码和已有页面设计数据保持兼容。
- `ProjectSpecAssembler` 会为普通和 embedded layout 自动选择精确插件版本并稳定排序；`PluginResolver` 会拒绝使用关系型块但漏选插件发布的 ProjectSpec。

启用说明：

- `FACTORY_PLUGIN_REGISTRY_DATABASE_ENABLED=false` 时，六个 PageBlock 均直接由内置可信 Registry 提供。
- 开启数据库发布目录前，需要为 `page-block.carousel`、`page-block.notice`、`page-block.news`、`page-block.cart`、`page-block.order`、`page-block.master_detail` 创建 provider 为 `ruoyi-factory` 的 `1.0.0` 发布记录。
- 本轮不新增数据库结构，继续复用 `factory_plugin_registry.sql`。

验证结果：

- PageBlock、Registry、页面设计、项目生成、真实模板渲染、ProjectSpec 和插件解析扩大回归 167 个全部通过。
- `ruoyi-generator` 全量执行 676 个测试，其中 658 个通过、18 个失败；失败仍为 11 个 AI 数据库生成、1 个字典选项和 6 个 Qing 模板一致性基线，本轮没有新增失败。
- `ruoyi-admin` 全部 38 个测试通过；本地前端开发服务继续在 `http://localhost:5174` 正常响应。

当前边界：

- 四个 Chart BusinessBlock 仍使用旧 classpath 定义和 Chart 专用生成分支，尚未形成一个插件族。
- 关系字段当前沿用已有表/字段存在性校验；外键类型兼容、基数和级联语义尚未形成独立 Relation Contract。
- Quality Check 仍只覆盖模板归属和非空源码，数据库迁移、权限和菜单尚未进入 PageBlock 可执行贡献。
- `ruoyi-ui` Plugin 管理页面仍未实现。

下一步进入 P2-D5：把四类 Chart BusinessBlock 收敛为共享 Chart 插件族，提取数据集校验、共享运行时资源和图表查询生成贡献；随后实现 Plugin 管理页面。

### 2026-07-10：P2-D5 Chart PageBlock 插件族

已完成：

- PageBlock 生命周期新增共享文件贡献上下文。插件可以在常规模板文件之外贡献共享生成文件，但模板必须由 Manifest 发布，输出路径和模板身份必须完整。
- 共享文件按输出路径确定性去重：多个 Chart 插件贡献完全相同的 `chartRuntime.js` 时只生成一份；同路径但模板、类别或类型不一致时立即拒绝，避免静默覆盖。
- 模板资源解析统一支持块内相对路径与 classpath 绝对路径，Chart 定义继续复用 `business-blocks/chart` 下的 7 个模板，不复制资源。
- 新增共享 Chart PageBlock 基类，统一执行 `single-table-aggregate-v1` 数据集校验、默认 span/limit、查询模型生成、显示配置 JSON 安全编码、指标参数和后台 API 路径贡献。
- 折线图、柱状图、饼图、指标卡分别发布为 `page-block.admin_line_chart@1.0.0`、`page-block.admin_bar_chart@1.0.0`、`page-block.admin_pie_chart@1.0.0`、`page-block.admin_metric_chart@1.0.0`。
- 四个 Chart Manifest 各自声明块定义、7 个共享业务模板、`chartRuntime.js` 模板、数据集 Validator、Quality Check、ProjectSpec 1.0 和 RuoYi Legacy Adapter `^1.0.0` 兼容范围。
- `BusinessBlockRegistryService` 不再直接调用 Chart Validator；`BusinessBlockGenerationService` 不再识别 Chart 类型、拼装查询上下文或硬编码共享运行时文件。三条能力全部由插件生命周期执行。
- `ProjectSpecAssembler` 会按稳定 code 顺序选择实际使用的 Chart 插件版本，随后进入统一依赖解析、Manifest 指纹和 Generation Run `plugin_plan_json`。
- 现有 10 个 BusinessBlock 定义现已全部由内置 PageBlock 插件接管；原 `block.json`、模板、SQL、API、页面组件、图表展示和已有设计数据均保持兼容。

启用说明：

- `FACTORY_PLUGIN_REGISTRY_DATABASE_ENABLED=false` 时，10 个 PageBlock 直接由内置可信 Registry 提供。
- 开启数据库发布目录前，除前六个插件外，还需为 `page-block.admin_line_chart`、`page-block.admin_bar_chart`、`page-block.admin_pie_chart`、`page-block.admin_metric_chart` 创建 provider 为 `ruoyi-factory` 的 `1.0.0` 发布记录。
- 本轮不新增数据库结构，继续复用 `factory_plugin_registry.sql`。

验证结果：

- Chart 插件族、PageBlock、Registry、页面设计、项目生成、真实模板渲染、ProjectSpec 和插件解析扩大回归 190 个全部通过。
- `ruoyi-generator` 全量执行 681 个测试，其中 663 个通过、18 个失败；失败仍为 11 个 AI 数据库生成、1 个字典选项和 6 个 Qing 模板一致性基线，本轮没有新增失败。
- `ruoyi-admin` 全部 38 个测试通过；本地前端开发服务继续在 `http://localhost:5174` 正常响应。

当前边界：

- Quality Check 仍只覆盖模板归属和非空源码，尚未执行生成项目编译、静态分析和自动化测试。
- 数据库迁移、权限和菜单仍是 Manifest 发布声明，尚未进入 PageBlock 可执行贡献。
- 第三方插件制品上传、签名、扫描、审核、沙箱和卸载仍明确排除。
- 后端 Plugin 管理 API 已具备，但 `ruoyi-ui` 尚无发布管理页面和菜单。

下一步进入 P2-D6：实现 `ruoyi-ui` Plugin 管理页面，接入插件定义、版本创建、发布/停用、Manifest 查看和数据库发布目录启用检查。

### 2026-07-10：P2-D6 Plugin 发布管理中心

已完成：

- 新增 `GET /generator/plugin/registry-status`，向管理端提供当前插件解析模式和运行实例中已安装的可信 Manifest。接口只返回发布管理需要的插件元数据，不暴露模型凭据或其他运行配置。
- `ruoyi-ui` 新增 Plugin 发布管理页面及完整 API 封装，支持按代码、Provider 和状态筛选插件定义，查看当前发布版本、Manifest 指纹和启停状态。
- 新增定义只能从运行实例已安装的可信插件中选择，避免通过管理页面登记一个服务端并不存在、无法执行的插件身份。
- 版本抽屉同时展示本机已安装版本和数据库版本历史；只能将尚未登记的已安装版本创建为草稿，随后执行发布。已退役版本可通过显式确认恢复为当前发布。
- 已安装 Manifest 与数据库存储 Manifest 均可在只读窗口中格式化查看，便于核对 capability、模板、Validator、Quality Check 和 Adapter 兼容声明。
- 页面明确展示 `BUILTIN` 或 `DATABASE` 解析模式。内置模式下可准备数据库发布记录，但页面会提示这些记录暂不参与生成解析；数据库模式下生成任务只解析启用定义的已发布版本。
- 新增独立菜单迁移 `sql/plugin_registry_menu.sql`，提供查询、新增定义、编辑、创建版本、发布和恢复六类按钮权限。执行迁移并重新登录后，动态路由会加载 `generator/plugin/index` 页面。

验证结果：

- Plugin 页面静态契约测试 3 个全部通过；`ruoyi-ui` 生产构建通过。构建仍有既有的 `listStructureExcludeChild` 导出和包体积警告，本轮未新增构建错误。
- Registry 状态、Schema 和发布服务聚焦测试 9 个全部通过。
- `ruoyi-generator` 全量执行 682 个测试，其中 664 个通过、18 个失败；失败仍为 11 个 AI 数据库生成、1 个字典选项和 6 个 Qing 模板一致性基线，本轮没有新增失败。
- `ruoyi-admin` 关键链路 38 个测试全部通过；`ruoyi-ui` 与 EasyCode 前端开发服务分别在 `http://localhost:9528`、`http://localhost:5174` 返回 HTTP 200。

当前边界：

- 页面当前管理运行实例中已经随应用发布的可信插件，不包含第三方制品上传、签名、扫描、审核、沙箱、热加载或卸载。
- 首次启用数据库发布目录仍需逐个创建 10 个内置 PageBlock 的定义和版本；批量初始化及发布就绪检查尚未实现。
- Quality Check 仍只覆盖模板归属和非空源码，尚未执行生成项目编译、静态分析和自动化测试。
- 数据库迁移、权限和菜单仍是 Manifest 声明元数据，尚未形成随插件执行、预检和回滚的贡献生命周期。

下一步进入 P2-D7：实现插件发布就绪检查与内置发布批量初始化，保证切换到数据库 Registry 前可以一次性核对并补齐全部可信发布记录。

### 2026-07-10：P2-D7 Plugin Registry 就绪检查与批量初始化

已完成：

- 新增数据库发布就绪报告，逐个核对运行实例中所有可信插件 release 的定义、Provider、启停状态、版本记录、规范化 Manifest、SHA-256 指纹、可执行状态和当前发布指针。
- 就绪状态明确区分 `MISSING_DEFINITION`、`PROVIDER_MISMATCH`、`DEFINITION_DISABLED`、`MISSING_VERSION`、`RELEASE_MISMATCH`、`NOT_PUBLISHED` 和 `READY`，不再通过“数据库里有几行记录”推测是否可以切换 Registry。
- 最新安装版本必须是定义的当前 `PUBLISHED` 版本；历史安装版本必须处于 `PUBLISHED` 或 `RETIRED` 可执行历史中。草稿、缺失指针或指纹漂移都会阻止就绪。
- 新增事务化批量初始化。定义和版本只能从进程内可信 `FeaturePluginRegistry` 创建，Manifest 使用规范化 JSON，content hash 直接使用已安装 release 指纹。
- 批量初始化具有幂等语义：缺失定义和版本会补齐；定义没有当前发布时会按安装版本顺序完成发布；已经存在的当前发布不会被替换，停用定义、Provider 冲突和 Manifest/指纹冲突会跳过并保留原值。
- 可修复“版本已发布但定义缺少 current pointer”的不完整状态；初始化结果分别返回新建定义、创建版本、发布版本、指针修复、保持不变和跳过数量。
- Plugin 中心顶部新增数据库就绪计数；新增 release 级就绪明细窗口和“批量初始化”操作。数据库模式已启用但未就绪时使用错误状态提示，避免误以为切换已经成功。
- `sql/plugin_registry_menu.sql` 新增 `generator:plugin:bootstrap` 权限；执行更新后的迁移并重新登录后，授权用户可以使用批量初始化。

验证结果：

- 就绪检查和批量初始化后端聚焦测试 13 个全部通过，覆盖缺定义、匹配当前发布、首次初始化发布和重复执行保持不变。
- Plugin 页面 API、工作流和菜单契约测试 3 个全部通过；`ruoyi-ui` 生产构建通过。仍只有既有的 `listStructureExcludeChild` 导出、包体积和 Browserslist 数据警告。
- `ruoyi-generator` 全量执行 686 个测试，其中 668 个通过、18 个失败；失败仍为 11 个 AI 数据库生成、1 个字典选项和 6 个 Qing 模板一致性基线，本轮没有新增失败。
- `ruoyi-admin` 关键链路 38 个测试全部通过；`ruoyi-ui` 与 EasyCode 前端开发服务分别在 `http://localhost:9528`、`http://localhost:5174` 返回 HTTP 200。

当前边界：

- 批量初始化只处理已经随应用部署的可信 Spring 插件，不支持上传或安装第三方制品，也不会绕过 Registry 的启动校验。
- 对已有当前发布采取保守策略；即使本机存在更新版本，也只补版本记录而不自动升级当前指针，升级仍需管理员显式发布。
- 数据库迁移、权限和菜单仍是 Manifest 声明元数据，尚未形成带预检、执行记录和逆向操作的贡献生命周期。
- Quality Check 仍只覆盖模板归属和非空源码，生成项目编译、静态分析、自动化测试、启动与页面检查属于后续 Quality Gate 阶段。

下一步进入 P2-D8：实现插件数据库迁移、权限和菜单的可执行贡献生命周期，先做确定性预检和执行留痕，再接入发布与回滚边界。

### 2026-07-10：P2-D8a Plugin 交付贡献计划与确定性预检

已完成：

- 新增 `PluginContributionPlan` 1.0 和 `PluginContributionStep`。每个步骤记录稳定序号、贡献类型、声明 key、所属插件 code/version、执行器契约和预检状态。
- 数据库迁移、权限、菜单分别绑定版本化执行器身份 `plugin.database-migration:v1`、`plugin.permission:v1`、`plugin.menu:v1`，后续执行器升级会形成明确的新运行环境身份。
- `ResolvedPlugin` 不再只保存 requires/provides；每次解析会同时固化该 release 的 database migrations、permissions 和 menus，防止运行记录丢失交付声明。
- 贡献步骤遵循插件依赖拓扑顺序；同一插件内按数据库迁移、权限、菜单分组，并按稳定 key 排序。Manifest 中声明顺序不同不会制造计划噪声。
- 解析器会拒绝两个已解析插件同时拥有相同“贡献类型 + key”。错误会同时给出冲突 key 和两个 release 身份，在 Adapter 生成之前终止。
- 空贡献和非空贡献都会生成规范化计划及 SHA-256；贡献计划指纹进入 Plugin Resolution Fingerprint，因此执行器或交付声明变化会改变 Generation Environment Fingerprint。
- 完整贡献计划嵌入现有 `PluginExecutionPlan`，继续通过不可变 Generation Run 的 `plugin_plan_json` 持久化，不新增重复数据库字段或旁路记录。
- 每个已规划步骤当前状态为 `PREFLIGHT_PASSED`，只表示身份、顺序、所有权和执行器契约预检通过，不表示数据库迁移、权限或菜单已经实际执行。
- 本版本会让包含插件的首次新 Generation Run 产生新的 Plugin Resolution Fingerprint，即使贡献步骤为空；这是贡献计划契约正式进入运行环境身份后的预期一次性版本变化，历史运行记录保持不变。

验证结果：

- Contribution Planner、Plugin Resolver、Generation Environment 和 Generation Run 聚焦测试 19 个全部通过，覆盖稳定排序、执行器映射、跨插件所有权冲突、计划 JSON 和指纹传播。
- `ruoyi-generator` 全量执行 690 个测试，其中 672 个通过、18 个失败；失败仍为 11 个 AI 数据库生成、1 个字典选项和 6 个 Qing 模板一致性基线，本轮没有新增失败。
- `ruoyi-admin` 关键链路 38 个测试全部通过；EasyCode 与 Plugin 管理前端开发服务分别在 `http://localhost:5174`、`http://localhost:9528` 返回 HTTP 200。

当前边界：

- 现有 10 个 PageBlock Manifest 尚未声明数据库迁移、权限或菜单，因此会生成预检通过、步骤数为 0 的贡献计划，现有输出保持不变。
- 当前执行器是计划中的版本化契约身份，尚未读取结构化 payload、向 SQL/后端/前端制品写入文件或执行目标数据库变更。
- 贡献步骤尚未产生 `EXECUTED`、`FAILED`、`ROLLED_BACK` 状态，也没有独立的逐步骤运行日志；Generation Run 只保存不可变预检计划。
- 发布和回滚当前仍只切换插件 release 指针，不会自动执行迁移或逆向菜单/权限操作。

下一步进入 P2-D8b：定义受信任的结构化贡献 payload 与 Adapter 执行器，把迁移、权限和菜单确定性写入生成制品，并记录每个步骤的执行结果和输出文件指纹。

### 2026-07-10：P2-D8b Plugin 结构化贡献与制品执行

已完成：

- `FeaturePlugin` 新增结构化 `PluginContributionPayload`，由 type、稳定 key、目标、相对输出路径和正文组成。只有运行实例中已安装且指纹与 Resolved Plugin 一致的可信实现可以提供 payload。
- Payload 必须与 D8a 的预检步骤一一对应。缺失 payload、重复 payload、实现额外提供 Manifest 未声明的 payload 都会终止生成，插件不能绕过执行计划偷偷写文件。
- Deterministic Generation Kernel 会在调用 Adapter 前解析精确 `PluginExecutionPlan`，并通过 `AdapterGenerationRequest` 传递；Adapter 返回同一份执行后计划，避免生成与环境指纹分别解析出两份状态。
- 新增 `PluginContributionArtifactExecutor`，将数据库迁移、权限和菜单 payload 写入其声明的已选择目标 ZIP。执行器拒绝未选择目标、空正文、绝对路径、盘符路径、空路径段、`.`/`..`、超长路径、超大条目和已有文件路径冲突。
- ZIP 重写按 target 和文件路径稳定排序，并使用固定 entry 时间戳。贡献文件因此进入 Kernel 的真实文件数量、大小、目标 hash 和 Aggregate Content Hash。
- 空贡献计划只记录完成状态和空执行指纹，原始 Adapter ZIP 字节原样返回；现有 10 个未声明交付贡献的 PageBlock 不会产生压缩包变化。
- 每个成功步骤从 `PREFLIGHT_PASSED` 更新为 `EXECUTED`，记录 target、outputPath 和正文 SHA-256；Contribution Plan 同时记录 execution fingerprint。
- 非空贡献执行完成后，Resolution Fingerprint 与 Contribution Execution Fingerprint 会合成为最终 Plugin Fingerprint；即使插件错误地复用了 code/version，只要 payload 正文变化，Generation Environment Fingerprint 也会变化。空计划保持原 Plugin Fingerprint。
- Generation Environment 直接使用 Adapter 返回的执行后计划，Generation Run 的 `plugin_plan_json` 因而保存逐步骤执行结果和输出文件身份。Kernel 会拒绝任何未执行非空贡献计划的 Adapter。
- Legacy RuoYi Adapter 已接入执行器；其他 Adapter 若将来支持 Feature Plugin，也必须显式执行贡献计划，不能静默忽略。

验证结果：

- Payload、ZIP 执行、空计划兼容、路径/目标/声明冲突、Legacy Adapter、Kernel 强制执行、环境计划传播和 Generation Run 聚焦测试 24 个全部通过。
- `ruoyi-generator` 全量执行 696 个测试，其中 678 个通过、18 个失败；失败仍为 11 个 AI 数据库生成、1 个字典选项和 6 个 Qing 模板一致性基线，本轮没有新增失败。
- `ruoyi-admin` 关键链路 38 个测试全部通过；EasyCode 与 Plugin 管理前端开发服务分别在 `http://localhost:5174`、`http://localhost:9528` 返回 HTTP 200。

当前边界：

- 本轮执行是“把可执行迁移、权限和菜单文件写入生成制品”，不会连接或修改目标项目数据库；真正应用 SQL 仍由部署或预览数据库阶段负责。
- 现有 10 个 PageBlock 尚未声明交付 payload；基础设施已经可用，但还没有选择一个现有块引入新的权限或菜单语义。
- Payload 当前由可信 Java 插件实现直接提供；大型 SQL/JSON 贡献还需要资源型 payload loader、资源内容指纹和发布时完整性预检。
- Generation Run 只记录成功执行计划。执行中失败会阻止成功 Run 落库，但尚未形成独立失败步骤日志。
- 插件发布、恢复和停用尚未核对 payload 完整性，也没有逆向迁移、权限或菜单回滚策略。

下一步进入 P2-D8c：把 payload 完整性预检接入插件发布/恢复边界，增加资源型 payload loader 和可逆性声明，并阻止缺少回滚策略的破坏性贡献自动恢复。

### 2026-07-10：P2-D8c Plugin Payload 完整性与发布可逆性门禁

已完成：

- `PluginContributionPayload` 新增 classpath resource、destructive、rollback resource 和 rollback content 元数据；新增统一 `PluginContributionResourceLoader`，以 UTF-8 加载 apply/rollback 资源并拒绝空资源和不安全资源路径。
- 新增 Registry 启动级 Payload Validator。Manifest 中 database migration、permission、menu 声明必须与插件实现提供的 typed payload 精确一致；缺失、额外、重复 identity 都会阻止应用加载该 release。
- Validator 同时检查目标类型、相对输出路径、正文、同目标重复输出和 rollback resource 正文；payload 按 type/key 稳定排序后形成 SHA-256。
- `PluginRelease` 现在分别保存 Manifest Fingerprint、Payload Fingerprint 和完整 Descriptor Fingerprint，并记录 payload 数量及是否可逆。
- 非空贡献 release 的 descriptor 由 Manifest Fingerprint 与 Payload Fingerprint 共同生成。apply 正文、rollback 正文、resource 身份或 destructive 声明变化都会改变 release descriptor。
- 空贡献 release 继续使用原 Manifest Fingerprint 作为 descriptor；现有 10 个 PageBlock 和已经初始化的数据库发布记录不需要因本轮升级重建。
- Database Plugin Catalog 分开验证存储 Manifest 与完整 release descriptor，不再把 Manifest hash 错当成包含 payload 的完整制品身份。
- 发布、恢复和批量初始化在切换 current pointer 前执行可逆性门禁。破坏性 payload 没有 rollback content 时不能发布；恢复时目标 release 与即将被替换的当前 release 都必须通过门禁。
- Registry 就绪报告新增 payloadCount、payloadFingerprint 和 contributionReversible。历史上已经发布但缺回滚策略的 release 会进入 `IRREVERSIBLE_CONTRIBUTION` 不就绪状态。
- Plugin 中心“数据库发布就绪明细”新增贡献数量和回滚状态列，明确显示“无需 / 可逆 / 缺策略”，不必等到发布失败才发现问题。

验证结果：

- Registry、Payload Loader、Artifact Executor、Database Catalog、发布/恢复服务、Plugin Resolver 和环境指纹聚焦测试 40 个全部通过。
- Plugin 页面契约测试 3 个全部通过；`ruoyi-ui` 生产构建通过。仍只有既有的 `listStructureExcludeChild` 导出、包体积和 Browserslist 数据警告。
- `ruoyi-generator` 全量执行 701 个测试，其中 683 个通过、18 个失败；失败仍为 11 个 AI 数据库生成、1 个字典选项和 6 个 Qing 模板一致性基线，本轮没有新增失败。
- `ruoyi-admin` 关键链路 38 个测试全部通过；EasyCode 与 Plugin 管理前端开发服务分别在 `http://localhost:5174`、`http://localhost:9528` 返回 HTTP 200。

当前边界：

- destructive 当前是可信插件作者的显式声明，系统尚未通过 SQL AST 或菜单差异自动判断 DROP、DELETE、重命名等破坏性操作。
- rollback content 已加载、校验并进入 release 指纹，但尚未作为独立逆向文件写入生成制品，也不会在恢复 release 时自动连接目标数据库执行。
- 发布切换仍只保存版本状态和 current pointer，没有独立的 Contribution Transition Journal 记录 apply/rollback 执行批次。
- 现有 PageBlock 没有交付 payload，因此管理页会显示“贡献 - / 回滚无需”；基础设施需要由后续首个真实交付插件开始使用。

下一步进入 P2-D8d：生成独立 rollback artifact，建立 Contribution Transition Journal，并把发布/恢复动作与可审计的正向、逆向执行批次关联起来。

### 2026-07-10：P2-D8d Rollback Artifact 与 Contribution Transition Journal

已完成：

- `PluginContributionPayload` 和执行步骤新增 rollback output path、rollback content hash 元数据。有 rollback content 且未指定路径时，稳定生成 `rollback/<apply-output-path>`，并继续执行相对路径、目录穿越和长度校验。
- Contribution Artifact Executor 会把 apply 与 rollback 内容写入同一目标 ZIP 的独立文件，分别记录原始 UTF-8 SHA-256；回滚路径与 Adapter 文件、正向贡献或其他回滚文件冲突时立即终止生成。
- 空贡献计划仍原样返回 Adapter ZIP；没有 rollback content 的既有贡献不会产生额外文件，保持现有制品兼容性。
- 新增规范 `PluginTransitionPlan` 与 `PluginTransitionPlanner`。`PUBLISH`、`BOOTSTRAP` 记录目标 release 的 APPLY 步骤；`RESTORE` 先记录当前 release 的 ROLLBACK，再记录目标 release 的 APPLY；`REPAIR` 记录零步骤指针修复。
- 每个 Transition Step 固化方向、插件版本、贡献 type/key、目标、制品路径和内容哈希，步骤按 database migration、permission、menu 及 key 稳定排序。
- 新增 append-only `factory_plugin_transition`。每条记录保存 from/to version、操作类型、规范计划 JSON、SHA-256、步骤数、操作人和时间；Mapper 只提供 insert 与按插件倒序查询，不提供 update/delete。
- 发布、恢复、初始化和指针修复在 `updateCurrentVersion` 后写 Journal。Journal 插入失败会抛出异常，并由同一 Spring 事务撤销版本状态和 current pointer 变更。
- Plugin 详情 API 返回 transition history；管理页版本抽屉新增“发布变更记录”，可查看动作、版本切换、步骤数、批次指纹、操作人、时间和完整 Transition Plan。
- 基础脚本、全量初始化脚本和升级脚本均加入 Transition Journal 表；升级脚本使用 `create table if not exists`，支持现有开发库重复执行。

验证结果：

- Plugin Registry、Payload、Artifact、Transition Planner、Schema、发布服务、Resolver 和版本约束聚焦测试 49 个全部通过。
- Plugin 管理页契约测试 3 个全部通过；`ruoyi-ui` 生产构建通过。仍只有既有的 `listStructureExcludeChild` 导出、包体积和 Browserslist 数据警告。
- `ruoyi-generator` 全量执行 708 个测试，其中 690 个通过、18 个失败；失败仍为 11 个 AI 数据库生成、1 个字典选项和 6 个 Qing 模板一致性基线，本轮没有新增失败。
- `ruoyi-admin` 关键链路 38 个测试全部通过；EasyCode 与 Plugin 管理前端开发服务分别在 `http://localhost:5174`、`http://localhost:9528` 返回 HTTP 200。

当前边界：

- Journal 的 `RECORDED` 表示插件目录切换和对应制品批次已原子记录，不表示目标数据库、权限系统或菜单系统已经执行该计划。
- 当前仍由可信插件作者声明 destructive 和 rollback content；系统尚未通过 SQL AST 或目标环境差异自动生成补偿动作。
- 现有 PageBlock 仍没有真实交付 payload，因此基础设施已完整但尚无内置插件产生 rollback 文件或非零 Transition Step。
- Transition Journal 当前与 Plugin 定义同库保存；尚未建立目标环境 execution receipt、步骤级 RUNNING/SUCCEEDED/FAILED 状态、幂等重试和人工补偿入口。

下一步进入 P2-D8e：建立目标环境 Contribution Executor 与 Execution Receipt，把 Journal 中的计划推进为可重试、可补偿、可核验的步骤执行状态机。

### 2026-07-10：P2-D8e1 Transition 执行批次与步骤回执

已完成：

- `PluginTransitionPlan` 升级为 1.1，每个可逆步骤同时固化正向和补偿方向、制品路径及正文 SHA-256。历史 1.0 计划仍可执行正向步骤，但包含步骤时会拒绝缺少补偿身份的伪补偿成功。
- 新增可信贡献内容解析器。执行前从运行实例中已安装的精确 plugin/version 重新加载 apply 或 rollback payload，并逐项核对 type、key、direction、artifact path 和 content hash；Transition Journal 不被当作可直接执行的正文来源。
- 新增 `PluginContributionTargetExecutor` SPI、配置化 Executor Registry 和默认 `dry-run:v1`。默认执行器只验证 backend、frontend、admin_frontend、sql 目标并生成确定性回执，不连接或修改目标数据库、权限系统、菜单系统及生成项目。
- 新增 `factory_plugin_transition_execution` 与 `factory_plugin_transition_step_receipt`。执行批次记录 APPLY、RETRY、COMPENSATE 模式及 RUNNING、SUCCEEDED、FAILED 状态；步骤回执独立记录逻辑幂等键、外部回执、错误和起止时间。
- 新增显式执行状态机。首次执行、失败重试和成功后的反向补偿分别受状态门禁约束；正向重复提交、成功补偿重复提交保持幂等，Executor 抛出的运行时失败会先落 FAILED 回执再作为执行结果返回。
- 每个逻辑步骤的幂等键由 Transition Fingerprint、正向或补偿语义、计划序号、方向和正文 hash 稳定生成。同一步骤在 APPLY 与 RETRY 间复用同一幂等键，后续真实 Executor 可据此抵御超时后的重复外部写入。
- 补偿按原计划逆序执行，只处理拥有完整 compensation identity 的步骤；所有正文会在创建执行批次前完成可信解析，完整性失败不会留下一个无法推进的 RUNNING 批次。
- Plugin 管理 API 新增 execute、retry、compensate 和 execution history；新增 `generator:plugin:execute` 权限。管理页可查看最新执行状态、显式发起三类动作，并展开批次与逐步骤回执，同时醒目标注 dry-run 不会修改外部系统。
- 基础脚本、全量初始化脚本和升级脚本均加入执行批次与步骤回执表；Transition 列表会关联展示最新执行摘要。

验证结果：

- Plugin 发布、可信 payload、制品、Transition、Executor、Schema 和执行服务聚焦测试 61 个全部通过；两份 Factory Mapper XML 均可解析。
- `ruoyi-generator` 全量执行 719 个测试，其中 701 个通过、18 个失败；失败仍为 11 个 AI 数据库生成、1 个字典选项和 6 个 Qing 模板一致性基线，本轮没有新增失败。
- `ruoyi-admin` 关键链路 38 个测试全部通过；Plugin 页面契约测试 3 个全部通过，`ruoyi-ui` 生产构建通过，仍只有既有的导出、包体积和 Browserslist 警告。
- EasyCode 与 Plugin 管理前端开发服务分别在 `http://localhost:5174`、`http://localhost:9528` 返回 HTTP 200。

当前边界：

- 系统当前只内置 `dry-run:v1`，所以已经具备可审计状态机，但尚未对目标数据库、权限服务或菜单服务产生真实副作用；不能把 SUCCEEDED dry-run 解读为部署已完成。
- 当前同步服务会在调用 Executor 期间持有 Transition 数据库行锁，这对无网络 I/O 的 dry-run 可接受。启用真实远程 Executor 前必须增加持久化执行租约或 Outbox、超时接管和结果对账，避免长事务与进程崩溃留下悬挂状态。
- 现有 10 个 PageBlock 仍没有交付 payload，因此它们产生的 Transition 通常是零步骤；执行能力需要由首个真实交付插件或隔离部署环境开始验证。
- 补偿内容继续由可信插件显式提供，系统尚未通过 SQL AST 或目标环境差异证明其语义可逆；真实 Executor 仍需使用逻辑步骤幂等键并保存可核验的目标侧 receipt。

下一步进入 P2-D8e2：引入持久化执行租约与 Outbox/对账机制，在隔离预览或部署环境实现 SQL、权限、菜单目标适配器，再用首个真实交付插件验证执行、超时重试和补偿闭环。

### 2026-07-11：P2-D8e2a 持久化租约、Outbox 与对账恢复

已完成：

- Transition 执行入口不再同步调用 Executor。execute、retry、compensate 现在只在一个短事务中校验不可变计划、应用状态门禁，并原子创建 `QUEUED` 执行批次、有序 `PENDING` 步骤回执和一条 `PENDING` Outbox 命令。
- 新增 `factory_plugin_transition_outbox`，每个 execution 唯一对应一条持久命令，记录 PENDING、PROCESSING、DELIVERED、FAILED 状态、可领取时间、lease owner/token/until、投递次数、最后错误和终态时间。
- 新增 `PluginTransitionOutboxCoordinator`。领取、开始步骤、完成步骤、失败批次、完成批次和续租分别使用短 Spring 事务；状态写回必须持有当前 lease token，旧 Worker 在租约被接管后不能覆盖新 Worker 的结果。
- 新增非事务化 `PluginTransitionOutboxWorker`。Worker 通过 MySQL 5.7 兼容的条件 UPDATE 原子领取 PENDING 或已过期 PROCESSING 命令，在事务外重新核验 Transition 指纹、可信 payload 与回执身份，再调用配置的 Executor。
- 一条 Outbox 按批次保持正向或逆向顺序。接管过期批次时，已经 SUCCEEDED 的步骤直接跳过，模糊 RUNNING 步骤重置为 PENDING，并使用 D8e1 的同一逻辑 `stepIdempotencyKey` 重新投递。
- Executor 或目标错误会在同一短事务中把当前 receipt、execution 和 Outbox 标记为 FAILED；数据库在外部调用后写回失败时，租约自然过期并触发幂等重投，不再依赖长事务假装外部副作用与数据库原子。
- 新增可配置轮询：`FACTORY_PLUGIN_OUTBOX_POLLING_ENABLED`、`FACTORY_PLUGIN_OUTBOX_POLL_INTERVAL_SECONDS`、`FACTORY_PLUGIN_OUTBOX_BATCH_SIZE` 和 `FACTORY_PLUGIN_OUTBOX_LEASE_SECONDS`，默认分别为 true、5、5、60，并在配置对象中限制为安全正数范围。
- 新增 execution reconcile API。它只允许将确认过期的 PROCESSING 租约恢复为 PENDING/QUEUED；活跃租约不能被人工抢占，DELIVERED 和 FAILED 终态也不会被 reconcile 重放。
- Plugin 管理页的执行动作改为“批次已入队”，回执窗口新增 Outbox 状态、投递次数和租约截止时间；只有浏览器判断已经过期的运行租约才显示对账图标，后端仍会做最终并发校验。
- 升级脚本会新增 Outbox 表，并把 execution/receipt 的 started_at 改为可空；两套全量脚本同步更新了外键 drop/create 顺序和 QUEUED/PENDING 状态说明。

验证结果：

- Plugin 发布、计划、Payload、Execution、Outbox、租约、对账、Schema 和 Controller 聚焦测试 71 个全部通过；两份 Factory Mapper XML 均可解析。
- `ruoyi-generator` 全量执行 729 个测试，其中 711 个通过、18 个失败；失败仍为 11 个 AI 数据库生成、1 个字典选项和 6 个 Qing 模板一致性基线，本轮没有新增失败。
- `ruoyi-admin` 关键链路 38 个测试全部通过；Plugin 页面契约测试 3 个全部通过，`ruoyi-ui` 生产构建通过，仍只有既有的导出、包体积和 Browserslist 警告。
- EasyCode 与 Plugin 管理前端开发服务分别在 `http://localhost:5174`、`http://localhost:9528` 返回 HTTP 200。

当前边界：

- 默认 Executor 仍是 `dry-run:v1`，Outbox 的 DELIVERED 只表示计划已被可靠投递给 dry-run，不代表目标数据库、权限或菜单已经修改。
- Worker 会在每个步骤前续租，但不会在单次阻塞 Executor 调用内部启动额外心跳。调用超过租约时可能发生并发重投，因此真实目标适配器必须以 `stepIdempotencyKey` 实现目标侧查重并返回同一 receipt。
- 当前采用一执行批次一条 Outbox，批次内部顺序处理；尚未实现按目标限流、优先级、独立死信队列和跨环境并发配额。
- 现有 10 个 PageBlock 仍没有真实交付 payload，因而通常形成零步骤批次；本轮没有启用任何真实外部写入。
- 启动轮询前必须先应用更新后的 `factory_plugin_registry.sql` 或全量数据库脚本，否则运行库不存在 Outbox 表。

下一步进入 P2-D8e2b：先建立隔离目标环境和目标侧 receipt ledger，实现首个幂等 SQL Executor，并用可逆测试迁移验证成功投递、超时重投、目标侧查重和补偿；权限与菜单适配器在 SQL 契约稳定后复用同一执行框架。

### 2026-07-11：P2-D8e2b 隔离 SQL 目标执行器与目标侧回执

已完成：

- Plugin 贡献新增不可变 `idempotent` 声明，Transition Plan 升级为 1.2。发布指纹包含该声明，执行时会重新解析可信安装制品并拒绝声明漂移；1.1 历史计划仍可在 dry-run 下补偿，但不能提升为真实 SQL 执行。
- 新增默认关闭的 `factory.plugin-execution.sql-target` 配置，覆盖环境代码、MySQL JDBC 连接、允许 catalog 和 30 至 3600 秒目标租约。连接工厂同时校验目标 catalog、规范化 JDBC URL 和 RuoYi master DataSource，拒绝控制库与目标库重合。
- 新增基于 Druid MySQL AST 的严格解析器。单个 payload 上限为 1 MiB 和 100 条语句，只接受 `CREATE TABLE IF NOT EXISTS`、`DROP TABLE IF EXISTS`、`INSERT IGNORE` 或 `ON DUPLICATE KEY UPDATE`、带 `WHERE` 的 `DELETE`，并拒绝跨 catalog 引用及所有其他语句类型。
- 新增隔离目标初始化脚本 `sql/factory_plugin_sql_target.sql`。`factory_plugin_target_receipt` 以 `step_idempotency_key` 唯一约束保存环境、Plugin 版本、方向、内容哈希、RUNNING/SUCCEEDED/FAILED 状态、租约、执行次数和确定性外部回执。
- 新增 `sql-jdbc:v1`。首次投递先提交目标端 RUNNING 回执，再执行规范化 SQL；重复 SUCCEEDED 投递直接返回同一回执，活跃租约不能被抢占，FAILED 或过期 RUNNING 可使用新 token 接管。执行失败会尽力回滚并写入不含连接信息的通用错误。
- 真实 SQL 只接受 `DATABASE_MIGRATION + sql + idempotent=true`。H2 MySQL 模式集成测试实际执行了建表、幂等插入、失败恢复、过期租约接管和 DROP TABLE 补偿，没有用 mock 替代核心数据库路径。
- Registry 状态接口只返回执行器代码、SQL 目标启用/配置就绪状态、环境代码和允许 catalog，不返回 JDBC URL、用户名或密码。Plugin 管理页会按 `dry-run:v1`、就绪的 `sql-jdbc:v1` 和未就绪配置显示不同提示，不再把所有执行动作描述为 dry-run。

启用顺序：

1. 在与 RuoYi 控制库隔离的 MySQL catalog 中先执行 `sql/factory_plugin_sql_target.sql`。
2. 配置 `FACTORY_PLUGIN_SQL_TARGET_ENVIRONMENT_CODE`、`FACTORY_PLUGIN_SQL_TARGET_JDBC_URL`、`FACTORY_PLUGIN_SQL_TARGET_USERNAME`、`FACTORY_PLUGIN_SQL_TARGET_PASSWORD` 和 `FACTORY_PLUGIN_SQL_TARGET_ALLOWED_CATALOG`。
3. 设置 `FACTORY_PLUGIN_SQL_TARGET_ENABLED=true` 与 `FACTORY_PLUGIN_EXECUTOR_CODE=sql-jdbc:v1`，重启后先在 Plugin 管理页确认 SQL 目标显示配置就绪。
4. 只发布经过审查、同时提供 apply/rollback 且声明 `idempotent=true` 的数据库迁移贡献，再在隔离预览环境执行批次。

验证结果：

- Plugin、Outbox、SQL AST、目标隔离、目标回执、Schema 和 Controller 聚焦测试 103 个全部通过；H2 真实数据库路径 5 个场景全部通过。
- `ruoyi-generator` 全量执行 746 个测试，其中 728 个通过、18 个失败；失败仍为 11 个 AI 数据库生成、1 个字典选项和 6 个 Qing 模板一致性基线，本轮没有新增失败。
- `ruoyi-admin` 关键链路 38 个测试全部通过；Plugin 页面契约测试 3 个全部通过，`ruoyi-ui` 生产构建通过，仍只有既有的缺失导出、包体积和 Browserslist 警告。
- EasyCode 与 Plugin 管理前端开发服务分别在 `http://localhost:5174`、`http://localhost:9528` 返回 HTTP 200。

当前边界：

- SQL 目标的“就绪”只表示非敏感配置通过本地校验，不代表网络连通、账号权限或目标回执表已探测成功；首次真实执行前仍必须按启用顺序完成隔离环境演练。
- MySQL 5.7 DDL 可能隐式提交，系统不能提供跨多条 DDL 的数据库事务原子性。恢复安全依赖不可变内容哈希、严格可重复 SQL、逻辑步骤幂等键和目标端回执查重。
- `sql-jdbc:v1` 只支持数据库迁移。配置该全局 Executor 后，包含权限或菜单贡献的批次会因目标不受支持而失败；权限与菜单仍未实现真实适配器，也不会静默退回 dry-run。
- 现有 10 个 PageBlock 仍没有真实交付 payload，本轮没有配置生产目标，也没有对任何外部数据库执行真实写入。
- URL 和 catalog 隔离校验是必要保护，但不能替代部署层的独立实例、最小权限账号、网络策略、备份和人工变更审批。

下一步进入 P2-D8e2c：先制作首个经过审查的真实数据库交付 Plugin，在隔离预览环境完成发布、执行、重复投递、故障恢复和补偿演练；这条链路稳定后，再按同一幂等回执契约扩展权限与菜单目标适配器。

### 2026-07-11：P2-D8e2c 首个 SQL 交付 Plugin 与目标探测

已完成：

- 新增 Spring 安装发布 `delivery.preview-baseline@1.0.0`，类型为 `delivery`，由 `ruoyi-factory` 提供。它声明一个 `DATABASE_MIGRATION` 贡献 `V1__preview_delivery_baseline`，正式结束“所有已安装 Plugin 都是零交付 payload”的状态。
- apply SQL 是不可变 classpath 资源，只使用 `CREATE TABLE IF NOT EXISTS` 创建专属 `factory_delivery_baseline_marker` 表，并使用 `INSERT IGNORE` 写入固定版本标记；payload 声明 `idempotent=true`。rollback 只使用 `DROP TABLE IF EXISTS` 删除该 Plugin 专属表。
- 新增真实资源全链路 H2 演练。测试从 FeaturePlugin Registry 和发布指纹开始，经 Plan 1.2、可信内容重解析、Druid AST、`sql-jdbc:v1` 和目标回执账本完成 apply；同一逻辑步骤重复投递返回相同 receipt 且只保留一条标记，随后使用计划中冻结的 compensation 身份删除表。
- 新增只读 `PluginSqlTargetProbeService`。关闭与配置无效状态不会打开连接；有效配置会复用隔离连接工厂，再以零行查询确认 `factory_plugin_target_receipt` 可见，区分 READY、UNAVAILABLE 和 LEDGER_UNAVAILABLE。
- 新增 `POST /generator/plugin/sql-target/probe`，复用 `generator:plugin:list` 权限。响应只包含状态、启用/配置/连通/账本布尔值、环境代码、catalog 和通用消息，不包含 URL、用户名、密码、SQLState 或驱动异常。
- Plugin 管理页仅在 SQL 目标启用时显示“检测 SQL 目标”命令，浏览器初始状态为 NOT_CHECKED，并用紧凑标签显示连接与回执就绪、配置无效、连接不可用或回执表不可用。探测不会发布、执行或补偿任何 Transition。

启用与演练顺序：

1. 在隔离预览 catalog 执行 `sql/factory_plugin_sql_target.sql`，配置并启用 `sql-jdbc:v1` 后重启服务。
2. 在 Plugin 管理页执行手动目标探测，并要求返回“连接与回执就绪”。
3. 批量初始化或手动创建 `delivery.preview-baseline` 定义与 `1.0.0` 版本，再显式发布。
4. 检查 PUBLISH Transition Plan 中只有一个 `DATABASE_MIGRATION + sql + idempotent=true` 步骤，再人工加入 Outbox。
5. 在目标 catalog 核对 marker 和 SUCCEEDED receipt，重复投递确认不重复执行，最后执行 compensation 并确认专属表被删除。

验证结果：

- Plugin、Outbox、SQL、目标探测、首个真实交付资源和 Controller 聚焦测试 111 个全部通过；其中 2 个 baseline Plugin 测试实际覆盖资源契约和 H2 apply/重复投递/compensation 闭环。
- `ruoyi-generator` 全量执行 754 个测试，其中 736 个通过、18 个失败；失败仍为 11 个 AI 数据库生成、1 个字典选项和 6 个 Qing 模板一致性基线，本轮没有新增失败。
- `ruoyi-admin` 关键链路 38 个测试全部通过；Plugin 页面契约测试 3 个全部通过，`ruoyi-ui` 生产构建通过，仍只有既有的缺失导出、包体积和 Browserslist 警告。
- EasyCode 与 Plugin 管理前端开发服务分别在 `http://localhost:5174`、`http://localhost:9528` 返回 HTTP 200。

当前边界：

- 本轮没有配置或连接任何外部 MySQL。真实 SQL 执行验证发生在 H2 MySQL 模式；运营环境仍需按启用顺序完成独立预览 catalog 演练。
- 安装 `delivery.preview-baseline` 不会自动创建数据库定义、发布版本或执行 SQL。人工“批量初始化”会按既有行为创建并发布缺失的可信版本，但执行 Transition 仍需单独授权和点击。
- 手动探测只证明隔离身份校验、连接建立和目标回执表查询成功，不证明账号具备 CREATE/DROP/INSERT 权限，也不证明业务迁移一定成功。探测结果只保存在当前浏览器页面，不持久化为审批证据。
- 当前仍是一个全局 Executor code。选择 `sql-jdbc:v1` 后，混合权限或菜单贡献的批次不会路由到其他适配器，而会明确失败；不存在静默 dry-run 回退。
- 10 个 PageBlock 仍保持零交付 payload；本轮新增的是独立的第 11 个已安装 release，不改变 PageBlock 生成语义。

下一步进入 P2-D8e2d：把全局 Executor 选择升级为冻结在执行计划中的按目标路由配置，并加入环境级执行策略与审批证据；先保证 SQL、权限、菜单可以在同一批次中选择不同适配器且不能静默降级，再实现权限与菜单的真实目标回执适配器。

### 2026-07-11：P2-D8e2d 按步骤 Executor 路由与真实执行审批证据

已完成：

- `factory.plugin-execution.executor-code` 保留为显式默认路由，并新增环境代码、非 dry-run 审批开关和按 `lower-kebab(type-target)` 归一化的路由表。空覆盖继承默认值，但这种继承只发生在入队前，不是运行失败后的降级。
- 新增 `PluginExecutionRoutingPolicy`。它在任何执行记录写入前解析全部可信贡献，验证 Executor 已安装且支持对应类型/目标，并按环境、默认 Executor、排序后的非空路由和审批策略生成稳定 SHA-256 路由指纹。
- 每个步骤回执冻结实际 Executor code；同一批次只有一个 code 时批次记录该 code，混合路由记录 `routed:v1`。Worker 只按回执中的 code 精确分发，配置变化和目标失败都不会触发运行时 fallback。
- 执行幂等身份加入环境、路由指纹和逐步骤 Executor 列表。重投旧 Outbox 时仍使用创建批次时的路由快照，而不是当前配置。
- execute、retry 和 compensate 接口新增可选审批请求，绑定精确 Transition 指纹、路由指纹和环境。只含 `dry-run:v1` 的批次继续兼容空请求体；包含真实 Executor 且审批开关启用时，缺失、过期或不匹配证据会在创建执行记录前失败。
- `factory_plugin_transition_execution` 新增环境、路由指纹、是否要求审批、审批人、审批时间和审批理由字段。独立升级脚本使用 `information_schema` 为 MySQL 5.7 已有表逐列幂等补齐，两个完整建库脚本同步包含新列。
- Registry 状态只暴露非敏感的执行环境、路由指纹、审批开关、是否配置真实 Executor、非空路由覆盖和默认 Executor，不返回任何目标凭据。
- Plugin 管理页会显示环境和短路由指纹；配置真实 Executor 且要求审批时，首次执行、重试和补偿都会要求填写 500 字以内理由，并提交当前 Transition/路由/环境身份。执行历史展示环境、路由、审批人/时间/理由和每个步骤的实际 Executor。

配置与升级顺序：

1. 先执行更新后的 `sql/factory_plugin_registry.sql`，或在新环境使用更新后的 `sql/front_workbench.sql` / `sql/db.sql` 建库。
2. 设置 `FACTORY_PLUGIN_EXECUTION_ENVIRONMENT_CODE`；真实执行默认保持 `FACTORY_PLUGIN_APPROVAL_REQUIRED_FOR_NON_DRY_RUN=true`。
3. 建议继续保留 `FACTORY_PLUGIN_EXECUTOR_CODE=dry-run:v1`，只将 `FACTORY_PLUGIN_DATABASE_MIGRATION_SQL_EXECUTOR_CODE` 设置为 `sql-jdbc:v1`。权限和菜单覆盖变量分别为 `FACTORY_PLUGIN_PERMISSION_BACKEND_EXECUTOR_CODE` 与 `FACTORY_PLUGIN_MENU_ADMIN_FRONTEND_EXECUTOR_CODE`。
4. 重启后先核对 Registry 状态中的环境和路由指纹，再完成 SQL 目标探测。任何配置修改都会改变路由指纹，旧页面提交的审批会被服务端拒绝并要求刷新后重新确认。

验证结果：

- Plugin、路由、Outbox、审批、SQL 目标、Schema 和 Controller 聚焦测试 119 个全部通过。
- `ruoyi-generator` 全量执行 762 个测试，其中 744 个通过、18 个失败；失败仍为 11 个 AI 数据库生成、1 个字典选项和 6 个 Qing 模板一致性基线，本轮没有新增失败。
- `ruoyi-admin` 关键链路 38 个测试全部通过；Plugin 页面契约测试 3 个全部通过，`ruoyi-ui` 生产构建通过，仍只有既有的缺失导出、包体积和 Browserslist 警告。
- EasyCode 与 Plugin 管理前端开发服务分别在 `http://localhost:5174`、`http://localhost:9528` 返回 HTTP 200。

当前边界：

- 只有 `sql-jdbc:v1` 是真实目标适配器。权限和菜单路由变量已经预留，但在对应适配器安装前配置这些 code 会在入队阶段明确失败；它们不会静默改走 dry-run。
- 当前审批是单个已认证操作人的环境绑定确认与持久化证据，不是多角色、多人或外部工单审批；尚未实现审批过期、撤销、职责分离和签名证明。
- UI 只要发现任意真实 Executor 配置就会保守地要求理由；服务端仍以该批次实际解析出的步骤决定是否强制审批，是最终可信边界。
- 已经创建的执行批次不会因配置变化重路由。数据库列必须先于新版本应用部署完成，否则查询执行历史和新批次写入会因缺列失败。
- 本轮没有连接或写入任何外部 MySQL，明文开发凭据和 TLS 校验问题继续按用户决定暂缓处理。
- 本地管理端页面服务可访问，但登录页的验证码后端接口当前返回 500，因此本轮登录后视觉验收未完成；静态页面契约与生产构建已通过。

下一步进入 P2-D8e2e：实现首个权限后端真实适配器及其目标端幂等回执，优先支持角色、权限标识与菜单授权的可审计 apply/compensate；随后再实现管理端菜单适配器，并把单人确认升级为可配置的职责分离审批策略。

### 2026-07-11：P2-D8e2e 权限后端真实适配器与目标所有权

已完成：

- 新增 `permission-jdbc:v1`，只支持 `PERMISSION + backend + idempotent=true`。它复用已有隔离 JDBC 连接、目标租约和 `factory_plugin_target_receipt`，但不执行 Plugin 提供的任意 SQL；对 `sys_menu`、`sys_role`、`sys_role_menu` 的写入全部来自平台内置 PreparedStatement。
- 定义权限文档 1.0，字段固定为 schema、权限标识、显示名、父权限标识和角色 key。文档限制 64 KiB，权限标识必须是三段小写 code、禁止通配符，角色为 1 至 20 个唯一小写 key，未知字段和贡献 key 漂移在打开目标连接前失败。
- 角色 key 排序后生成语义 SHA-256；apply 与 rollback 资源允许排版不同，但权限标识、显示名、父权限和角色集合必须完全相同。
- 目标初始化脚本新增 `factory_plugin_target_permission` 和 `factory_plugin_target_permission_role`。前者保存 Plugin/version/贡献 key、语义指纹、父菜单和生成 menu ID、ACTIVE/REMOVED 生命周期；后者只记录适配器实际创建的角色授权。
- apply 要求父权限和全部角色在目标 RuoYi 库中唯一且启用，拒绝接管任何已有同名 `sys_menu.perms`。按钮使用目标库生成的 menu ID，所有权、按钮和角色授权在同一 DML 事务提交。
- 重投 SUCCEEDED 步骤直接返回 `permission:<environment>:<step-key>`；失败或过期租约可接管。若业务事务已经提交但回执尚未成功，重试会逐项验证所有权、菜单字段、角色 ID 和已拥有授权，不会覆盖漂移。
- compensate 先完成全部只读校验，再删除任何数据。权限非本 Plugin 所有、语义身份变化、已有按钮/授权缺失、存在人工追加角色授权或子菜单时都会整笔拒绝；成功后只删除已拥有授权和按钮，并保留 REMOVED tombstone 支持补偿重投与后续版本重新激活。
- 新增可信安装发布 `delivery.preview-permission@1.0.0`，贡献 `generator:delivery:verify`，挂在现有 `generator:plugin:list` 父权限下并授权给 `common` 角色。H2 MySQL 模式从 Registry、发布指纹、Plan 1.2、可信资源重解析一直验证到 apply、重复投递、角色授权、compensate 和 tombstone。
- 手动 JDBC 目标探测会检查当前路由。仅当默认或覆盖路由选择 `permission-jdbc:v1` 时，才额外探测两张权限所有权表；SQL-only 环境保持兼容。缺表返回独立 `PERMISSION_LEDGER_UNAVAILABLE`，响应不包含 URL、凭据或 SQL 异常。
- Plugin 管理页将原“SQL 目标”提升为共享“JDBC 目标”，识别 `permission-jdbc:v1` 与权限所有权就绪状态；SQL 和权限 JDBC 路由都受同一配置就绪与手动探测保护。

启用与演练顺序：

1. 在隔离的 RuoYi 预览 catalog 重新执行幂等脚本 `sql/factory_plugin_sql_target.sql`，创建通用回执和两张权限所有权表。
2. 确认目标库包含兼容的 `sys_menu`、`sys_role`、`sys_role_menu`，并为 baseline 准备唯一启用的 `generator:plugin:list` 父权限和 `common` 角色。适配器不会自动创建角色或父菜单。
3. 保持 `FACTORY_PLUGIN_EXECUTOR_CODE=dry-run:v1`，设置 `FACTORY_PLUGIN_PERMISSION_BACKEND_EXECUTOR_CODE=permission-jdbc:v1`；同时配置并启用既有 `FACTORY_PLUGIN_SQL_TARGET_*` 隔离连接参数。
4. 重启后核对环境与新路由指纹，在 Plugin 管理页执行“检测 JDBC 目标”，要求连接、通用回执和权限所有权全部 READY。
5. 初始化并发布 `delivery.preview-permission@1.0.0`，确认 PUBLISH Plan 只有一个 `PERMISSION + backend + idempotent=true` 步骤，填写审批理由后加入 Outbox。
6. 在目标库核对按钮、`common` 角色授权、ACTIVE ownership 和 SUCCEEDED receipt；重复投递确认不重复创建，随后执行 compensation 并核对 REMOVED tombstone。

验证结果：

- Plugin、权限文档、权限 JDBC Executor、目标所有权、SQL、探测、路由和 Outbox 聚焦测试 131 个全部通过。
- `ruoyi-generator` 全量执行 774 个测试，其中 756 个通过、18 个失败；失败仍为 11 个 AI 数据库生成、1 个字典选项和 6 个 Qing 模板一致性基线，本轮没有新增失败。
- `ruoyi-admin` 关键链路 38 个测试全部通过；Plugin 页面契约测试 3 个全部通过，`ruoyi-ui` 生产构建通过，仍只有既有的缺失导出、包体积和 Browserslist 警告。
- EasyCode 与 Plugin 管理前端开发服务分别在 `http://localhost:5174`、`http://localhost:9528` 返回 HTTP 200。

当前边界：

- 当前真实权限适配器只创建按钮权限并绑定已有角色/父菜单，不创建角色、目录、页面菜单、用户或后端端点，也不接管目标库已经存在的权限 code。
- 安全补偿优先于强制清理。人工新增角色授权、子菜单或任何所有权漂移都会阻止删除，需要先人工对账；系统不会猜测哪些外部修改可以丢弃。
- 目标回执和权限所有权都在目标数据库中，但探测只证明表可查询，不证明账号拥有 INSERT/UPDATE/DELETE 权限，也不刷新运行中目标应用的权限缓存；真实演练后可能需要目标用户重新登录或按部署策略刷新缓存。
- 权限和 SQL Executor 共用一套隔离目标连接与通用步骤回执。当前仍未强制校验顶层执行环境代码与 JDBC 目标环境代码相同，启用前必须在状态栏人工核对；该一致性门禁应在下一阶段补齐。
- 本轮没有连接或写入任何外部 MySQL；所有真实授权验证均发生在 H2 MySQL 模式。明文开发凭据和 TLS 校验问题继续按用户决定暂缓处理。

下一步进入 P2-D8e2f：先增加执行环境与 JDBC 目标环境的强一致性门禁，再实现结构化 `MENU + admin_frontend` 真实适配器；菜单适配器复用所有权/tombstone/保守补偿原则，并补齐页面路径、组件、父菜单与角色可见性验证。

### 2026-07-11：P2-D8e2f 审批环境硬门禁与菜单真实适配器

已完成：

- `PluginContributionExecutionContext` 新增冻结环境，Outbox Worker 从持久化执行批次逐步骤传递。新增共享 `PluginJdbcTargetEnvironmentPolicy`，`sql-jdbc:v1`、`permission-jdbc:v1`、`menu-jdbc:v1` 都会在打开连接前要求审批环境与 JDBC 目标环境精确一致；空值或错配直接失败，不会连接目标或降级路由。
- 新增菜单文档 1.0，固定声明 menu key、显示名、父路径、页面 path、组件、route name、图标、顺序、依赖权限和角色集合。文档限制 64 KiB，拒绝未知字段、路径穿越、URL/任意组件、通配权限、非法路由和重复角色；角色排序后计算语义 SHA-256。
- 新增 `menu-jdbc:v1`，只支持 `MENU + admin_frontend + idempotent=true`。它不执行插件 SQL，也不接受目标 menu ID 或任意 `sys_menu` 字段；页面菜单固定创建为启用的 `C` 类型，`perms` 留空，实际接口授权由独立权限贡献负责。
- 目标脚本新增 `factory_plugin_target_menu` 与 `factory_plugin_target_menu_role`。所有权保存 Plugin/version/贡献 key、文档指纹、父菜单、路径/组件/路由、依赖权限目标 ID、生成 menu ID 和 ACTIVE/REMOVED 生命周期；角色表只记录适配器实际创建的授权。
- apply 先锁菜单所有权，再锁并验证 `factory_plugin_target_permission` 中 ACTIVE 的工厂权限，随后解析已有父菜单和角色；每个角色必须已经拥有完整父菜单祖先链和依赖权限按钮授权，否则页面路由或接口权限不完整时会提前失败。适配器拒绝接管未托管 path/route 冲突，重复执行必须逐项验证菜单字段、路由身份、权限依赖、角色 ID 和授权后才能返回成功。
- compensate 在任何删除前验证完整所有权、语义文档、父菜单、权限依赖、页面字段、角色授权和子菜单。人工追加角色或子菜单、权限先被移除、路径/组件漂移等情况都会整笔拒绝；成功后只删除已拥有授权和页面，并保留 REMOVED tombstone。
- 新增可信发布 `delivery.preview-menu@1.0.0`，显式依赖 `delivery.preview-permission@^1.0.0`。H2 MySQL 演练真实完成权限 apply、菜单 apply、重复投递、`common` 角色可见、菜单逆序补偿和权限最终补偿，共保留四条 SUCCEEDED 目标回执。
- JDBC 探针在路由选择 `menu-jdbc:v1` 时同时要求通用回执、权限所有权和菜单所有权表，缺菜单表返回独立 `MENU_LEDGER_UNAVAILABLE`。Plugin 中心识别菜单 Executor，并分别显示权限与菜单所有权就绪状态。
- 新增 `GET /generator/plugin/delivery-verification`，只允许 `generator:delivery:verify`，返回执行环境、路由指纹、Executor 路由、审批策略、安装 Plugin 数和脱敏探针结果。新增真实 `generator/delivery/index.vue` 页面，菜单贡献声明的组件不再是占位路径。

启用与演练顺序：

1. 在隔离 RuoYi 预览 catalog 重新执行幂等脚本 `sql/factory_plugin_sql_target.sql`，安装通用回执、权限和菜单共五张目标账本表。
2. 确认控制侧 `FACTORY_PLUGIN_EXECUTION_ENVIRONMENT_CODE` 与 `FACTORY_PLUGIN_SQL_TARGET_ENVIRONMENT_CODE` 完全相同；不建议依赖大小写或空白归一化。
3. 目标库必须已有唯一启用的 `generator` 父路径、`generator:plugin:list` 父权限和 `common` 角色，并让 `common` 已拥有 `generator` 父目录授权。先设置 `FACTORY_PLUGIN_PERMISSION_BACKEND_EXECUTOR_CODE=permission-jdbc:v1`，再设置 `FACTORY_PLUGIN_MENU_ADMIN_FRONTEND_EXECUTOR_CODE=menu-jdbc:v1`，默认 Executor 继续保持 `dry-run:v1`。
4. 重启后核对新路由指纹，执行“检测 JDBC 目标”，要求通用回执、权限所有权和菜单所有权全部 READY。
5. 先初始化、发布并执行 `delivery.preview-permission@1.0.0`，再发布和执行 `delivery.preview-menu@1.0.0`。目标角色重新登录后应获得交付验证菜单和受 `generator:delivery:verify` 保护的接口。
6. 补偿时必须先补偿菜单，再补偿权限；若存在人工授权或子菜单，先对账并移除外部依赖，系统不会强制删除。

验证结果：

- Plugin、环境门禁、菜单文档、菜单 JDBC Executor、目标所有权、权限依赖、父菜单可见性、探针、Controller、路由和 Outbox 聚焦测试 149 个全部通过；菜单 H2 核心路径 8 个场景、跨权限/菜单交付演练 2 个场景全部通过。
- `ruoyi-generator` 全量执行 792 个测试，其中 774 个通过、18 个失败；失败仍为 11 个 AI 数据库生成、1 个字典选项和 6 个 Qing 模板一致性基线，本轮没有新增失败。
- `ruoyi-admin` 关键链路 38 个测试全部通过；Plugin/交付页面契约测试 4 个全部通过。
- `ruoyi-ui` 生产构建通过，仍只有既有的 `listStructureExcludeChild` 缺失导出、包体积和 Browserslist 警告。
- EasyCode 与 RuoYi UI 开发服务分别在 `http://localhost:5174`、`http://localhost:9528` 返回 HTTP 200。

当前边界：

- 菜单适配器只登记目标 `sys_menu` 路由和角色可见性，不把 Vue 制品上传到任意外部目标。目标运行版本必须已经包含文档声明的组件；本仓库自身已包含首个 baseline 页面。
- 菜单必须依赖工厂拥有且 ACTIVE 的按钮权限。它不会采用已有页面、已有权限、角色、目录或人工授权，也不会创建多层菜单树。
- 同一贡献的目标 DML 与所有权在一个事务内，但 MySQL 目标回执的 RUNNING claim 会先独立提交。进程中断后依靠语义身份、所有权逐项验证和稳定步骤 key 恢复，不承诺跨 Plugin Transition 的分布式原子性。
- 旧执行记录若没有冻结环境会在真实 JDBC 适配器前安全失败，需要通过当前配置重新创建受审批的执行批次，不能手工绕过环境门禁。
- 探针证明表可查询，不证明角色缓存已刷新、目标前端包含组件或账号拥有全部写权限。生产启用前仍需独立预览 MySQL、重新登录和页面/API 联合验收。
- 本轮没有连接或写入任何外部 MySQL；所有真实目标写入验证发生在 H2 MySQL 模式。明文开发凭据和 TLS 校验问题继续按用户决定暂缓处理。

下一步进入 P2-D8e2g：把单人环境确认升级为可配置的职责分离审批策略，至少冻结申请人/审批人角色、禁止自批、增加有效期与撤销状态，并在隔离 MySQL 预览环境做 SQL、权限、菜单混合路由的部署级演练。

### 2026-07-11：P2-D8e2g 可撤销的双人职责分离审批

已完成：

- 新增 `factory_plugin_transition_approval` 持久审批日志，状态覆盖 PENDING、APPROVED、REVOKED、CONSUMED、EXPIRED；完整保存申请、批准、撤销、消费、有效期与关联 execution，`execution_id` 唯一约束保证一条凭证最多绑定一个执行批次。
- 新增职责分离策略：默认禁止申请人批准自己的请求；申请人与审批人的当前角色会去重、排序后冻结，可分别通过 requester/approver role allowlist 限制。账号、角色、理由和快照长度都有服务端边界。
- 新增申请 TTL 和批准凭证 TTL。读取、决定、撤销和消费前都会在 Transition 锁内惰性过期旧记录；Mapper 写条件再次限制状态与截止时间，避免陈旧请求覆盖并发终态。
- 路由指纹现在同时包含职责分离开关、两个 TTL 和排序后的角色策略。审批请求冻结精确 Transition 指纹、实际执行模式、路由指纹、环境和 Executor；任何计划或策略配置变化都会使旧凭证失效。
- execute、retry、compensate 只接受 `approvalId` 与精确身份，不再接受执行人临时填写的审批理由。真实执行会锁定并校验已批准记录，重新验证申请人与审批人不同及证据完整性，把全部角色/理由/有效期复制到 execution 审计快照，再原子消费凭证、作废同 Transition 的其他活动审批，最后创建步骤回执与 Outbox。
- 新增 `generator:plugin:approve` 权限。申请与执行继续要求 `generator:plugin:execute`，批准和撤销要求独立权限，两类权限均可查看审批记录；控制器契约测试固定了该权限边界。
- Plugin 中心新增 Transition 审批台，可申请、批准、撤销、刷新并查看角色、理由、期限、撤销、消费、Transition/路由指纹。真实执行不再出现“批准并入队”的单人提示，而是只选择模式、指纹、环境均匹配且未过期的 APPROVED 记录；执行历史永久显示申请人到审批人的完整证据链。
- Registry 与交付验证页面显示职责分离、申请有效期和批准有效期；配置新增 `FACTORY_PLUGIN_APPROVAL_SEPARATION_ENABLED`、`FACTORY_PLUGIN_APPROVAL_REQUEST_TTL_MINUTES`、`FACTORY_PLUGIN_APPROVAL_VALIDITY_MINUTES` 及两类角色 key allowlist。
- 三份完整建库脚本和 Plugin Registry MySQL 5.7 升级脚本已同步审批表、execution 审计列与索引；没有连接或修改外部 MySQL。

验证结果：

- Plugin、审批策略、路由、服务、Schema、Controller、目标适配器与 Outbox 聚焦测试 162 个全部通过；覆盖自批拒绝、角色策略、过期、撤销、消费竞争、消费后不可撤销和不可变审计快照。
- `ruoyi-generator` 全量执行 805 个测试，其中 787 个通过、18 个失败；失败仍严格为 11 个 AI 数据库生成、1 个字典选项和 6 个 Qing 模板一致性基线，本轮没有新增失败。
- `ruoyi-admin` 全量 38 个测试全部通过；Plugin/交付页面契约测试 4 个全部通过。
- `ruoyi-ui` 生产构建通过，仍只有既有的 `listStructureExcludeChild` 缺失导出、包体积和 Browserslist 警告。
- EasyCode 与 RuoYi UI 开发服务分别在 `http://localhost:5174`、`http://localhost:9528` 返回 HTTP 200。
- EasyCode 与 RuoYi UI 开发服务分别在 `http://localhost:5174`、`http://localhost:9528` 返回 HTTP 200。

当前边界：

- 审批记录是控制库中的可审计事实，不是密码学签名、外部工单或身份提供商证明；角色变更不会改写历史快照，但批准时和执行消费时都会重新校验被冻结的职责分离证据。
- 前端根据 Registry 是否配置真实 Executor 保守进入审批流程；某个 Transition 最终是否需要审批仍由服务端解析其实际贡献和路由决定，前端不能绕过或替代该判断。
- 当前只证明控制侧审批状态机与既有 H2 MySQL 模式目标适配器；本轮没有被授权连接隔离外部 MySQL，因此 SQL、权限、菜单混合路由的真实部署验收仍需单独执行。
- 已消费凭证不能撤销；若目标异步执行失败，应按现有 retry/compensate 状态机重新申请对应模式的新审批，而不是复用旧证据。
- 明文开发凭据与 TLS 校验继续按用户决定暂缓处理。

下一步进入 P2-D8e2h：增加按 Transition 返回的路由/审批预检与部署验收编排，消除前端全局保守判断；随后在用户明确授权的隔离 MySQL 预览实例完成 SQL、权限、菜单混合路由的 apply、失败重试、补偿、审批过期与撤销联合演练。

### 2026-07-11：P2-D8e2h Transition 级预检与部署验收报告

已完成：

- 新增 Transition 执行预检 API。请求 APPLY、RETRY 或 COMPENSATE 后，服务端复用实际执行的 Transition 锁、不可变计划校验、`nextMode` 状态机、可信 payload 解析和路由策略，返回实际模式、Transition/路由指纹、环境、汇总 Executor 与逐步骤路由，不再由浏览器推测。
- 预检明确区分 READY、APPROVAL_REQUIRED、NO_ACTION。失败补偿的 retry 会由服务端解析为 COMPENSATE；已成功或正在执行的幂等重复动作返回 NO_ACTION；非法状态继续按执行入口相同规则拒绝。
- 每个步骤返回执行序号、方向、贡献 type/key、目标、选中的 Executor 和是否产生真实副作用。只要实际步骤全部为 `dry-run:v1`，即使系统安装了其他真实 Executor，也不会误进入审批流程。
- 预检只返回状态为 APPROVED、未过期且模式、Transition、路由、环境、Executor 完全匹配的批准记录；同时补强执行消费门禁，要求申请/批准账号、角色、理由、时间和两个有效期快照全部存在，并再次验证非自批。
- Plugin 中心的 execute、retry、compensate 全部先调用预检。执行请求中的指纹和环境只取自预检响应；需要审批时打开审批台，已有凭证时明确确认消费，真实执行但审批关闭时显示独立副作用警告，dry-run 保持普通入队确认。
- 审批台会同时刷新预检与审批历史，展示该动作的实际模式、环境、汇总 Executor 和有序步骤路由；申请按钮只有在当前状态确实为 APPROVAL_REQUIRED 时才可用。
- 新增 `PluginDeliveryAcceptanceService`，统一返回基线交付插件、Plugin 发布目录、SQL/权限/菜单混合路由、环境绑定、双人审批策略、JDBC 配置、目标回执与所有权七项检查。全部通过才报告 READY。
- 交付验证页面新增部署验收表，并继续展示脱敏路由、审批、Registry 和 JDBC 快照。目标探针只执行零行 SELECT，不返回 URL、账号、密码、SQLState 或原始异常。

验证结果：

- Plugin、预检、审批、部署验收、目标适配器与 Outbox 聚焦测试 169 个全部通过。
- `ruoyi-generator` 全量执行 812 个测试，其中 794 个通过、18 个失败；失败仍严格为 11 个 AI 数据库生成、1 个字典选项和 6 个 Qing 模板一致性基线，本轮没有新增失败。
- `ruoyi-admin` 全量 38 个测试全部通过；Plugin/交付页面契约测试 4 个全部通过。
- `ruoyi-ui` 生产构建通过，仍只有既有的 `listStructureExcludeChild` 缺失导出、包体积和 Browserslist 警告。

当前边界：

- Preflight 是同一状态机的只读快照，不是预留锁或执行授权。预检后发生审批过期、撤销、消费、计划或配置变化时，execute 会重新校验并安全失败。
- 部署验收报告证明配置和目标账本可查询，不会主动发布 Plugin、创建审批、投递 Outbox 或执行目标 DML。
- 本轮没有连接或修改任何外部 MySQL。真实 SQL、权限、菜单混合路由联合演练仍需用户明确指定隔离实例；当前目标写入测试继续使用 H2 MySQL 模式。
- 明文开发凭据与 TLS 校验继续按用户决定暂缓处理。

下一步进入 P2-D8e2i：建立可重复的部署演练 Run 与持久化验收报告，先在本地隔离环境编排申请、双人批准、混合 apply、故障重试、逆序补偿、过期和撤销场景；只有在用户明确授权目标实例后，才把同一演练计划切换到隔离 MySQL。

### 2026-07-11：P2-D8e2i 可追溯的部署演练 Run 与不可变验收快照

已完成：

- 新增 `factory_plugin_delivery_rehearsal_run` 与 `factory_plugin_delivery_rehearsal_scenario`。Run 保存唯一 SHA-256 身份、1.0 Schema、`PLAN_ONLY` 模式、READY/BLOCKED 状态、控制与目标环境、Catalog、路由指纹、验收/场景双指纹、冻结计数、创建人和时间；场景表保存固定顺序、稳定 code、状态、所需证据和计划结果。
- Run 与场景 Mapper 只提供 insert 和 select，不提供应用层 update/delete。三份建库脚本同步新增表、唯一 Run key、同 Run 内唯一场景 code/sequence 和级联外键；现有环境部署新代码前必须先执行更新后的 `sql/factory_plugin_registry.sql`。
- `PluginDeliveryRehearsalService` 调用统一验收服务并保存其完整脱敏 Canonical JSON。验收指纹覆盖原始 Canonical JSON；场景指纹使用排除数据库生成 ID 的有序投影，因此写入生成主键后仍可复算。
- 详情读取会关闭式校验验收指纹、场景指纹、Schema、模式、状态、控制/目标环境、Catalog、路由指纹、通过/总检查数和场景数。任一字段或场景被改写都会返回完整性错误；原始 JSON 通过 `@JsonIgnore` 不直接进入 REST 响应。
- 每个 Run 固定编排六类场景：双人申请与批准、审批过期、审批撤销、SQL/权限/菜单混合 apply、故障幂等 retry、逆序 compensation。验收通过时状态仅为 `PLANNED`，验收不通过时为 `BLOCKED`；本阶段没有 PASSED/SUCCEEDED 状态，避免把“计划已生成”冒充“演练已执行”。
- 新增创建、最近 50 条列表和完整详情三个 API，统一要求 `generator:delivery:verify`。创建只写控制库演练表，不发布 Plugin、不创建审批、不投递 Outbox，也不提供执行接口。
- 交付验证页新增“创建验收快照”、Run 历史和响应式报告弹窗。报告展示双指纹、环境、Catalog、冻结验收项与六个有序场景；POST 已成功但列表刷新失败时会保留成功事实并独立提示，不会诱导重复创建。
- 新增服务、Schema、Controller、API 和页面契约测试；设计与实施记录分别写入 `docs/superpowers/specs/2026-07-11-plugin-delivery-rehearsal-run-design.md` 与 `docs/superpowers/plans/2026-07-11-plugin-delivery-rehearsal-run.md`。

验证结果：

- Plugin 聚焦套件 175 个测试全部通过，覆盖 READY/BLOCKED Run、六场景顺序、双指纹、元数据篡改拒绝、操作人边界、append-only Schema 和 Controller 权限。
- `ruoyi-generator` 全量执行 818 个测试，其中 800 个通过、18 个失败；失败仍严格为 11 个 AI 数据库生成、1 个字典选项和 6 个 Qing 模板一致性基线，本轮没有新增失败。
- `ruoyi-admin` 全量 38 个测试全部通过；Plugin/交付页面契约测试 4 个全部通过。
- `ruoyi-ui` 生产构建通过，仍只有既有的 `listStructureExcludeChild` 缺失导出、资源/入口体积和 Browserslist 数据过旧警告。
- EasyCode 与 RuoYi UI 开发服务分别在 `http://localhost:5174`、`http://localhost:9528` 返回 HTTP 200。

当前边界：

- `READY` 只表示被冻结的前置条件允许后续隔离演练，不是执行成功证明。六个场景当前只有计划状态，没有 attempt、开始/结束时间、操作者链或执行回执。
- 创建 Run 会复用现有验收服务，因此可能对已配置 JDBC 目标执行既有零行只读探针；它不会执行目标 DML。控制库会新增 Run/Scenario 记录。
- 双指纹能检测通过应用读取的快照或场景改写，但不是密码学签名、外部时间戳或数据库防篡改存储。拥有数据库管理权限的人员仍可删除记录，后续可接外部审计归档。
- 本轮没有连接或修改任何外部 MySQL，也没有对当前运行数据库自动执行升级脚本。明文开发凭据与 TLS 校验继续按用户决定暂缓处理。

下一步进入 P2-D8e2j：新增本地 H2 隔离演练执行器、逐场景 attempt/receipt 与证据快照，真实跑通申请/双人批准、过期、撤销、混合 apply、故障 retry 和逆序 compensation；外部 MySQL 模式继续保持不可选，直到用户明确授权隔离目标。

### 2026-07-11：P2-D8e2j 本地 H2 六场景执行与证据回执

已完成：

- 新增 `factory_plugin_delivery_rehearsal_attempt` 与 `factory_plugin_delivery_rehearsal_receipt`。Attempt 冻结父 Run key、验收/场景指纹、独立沙箱指纹、Attempt key、单调序号、重跑来源、操作人、计数、时间、耗时和脱敏错误；Receipt 冻结场景身份、状态、Canonical 证据、证据指纹和耗时。
- Attempt 状态覆盖 PENDING、RUNNING、SUCCEEDED、FAILED、ABORTED，Receipt 使用同组执行状态。开始、完成、失败和中止更新都带当前状态条件；同 Run 的 Attempt 序号、Attempt key、同 Attempt 场景 code/sequence 均有唯一约束。
- 重跑只允许引用同 Run 的 FAILED 或 ABORTED Attempt，并创建全新 Attempt 与全新 H2 沙箱。PENDING/RUNNING 可人工中止，未执行 Receipt 转为 ABORTED；终态历史不会被覆盖。
- H2 从 test scope 提升为 runtime scope，但生产代码只通过 `DriverManager` 动态加载。每个 Attempt 使用独立 MySQL 模式内存库和 keeper connection，结束后数据库立即销毁；H2 URL、内部账号和库名不持久化、不进入 API，只暴露 SHA-256 沙箱指纹。
- 沙箱只解析三个已安装、受信任、可逆 baseline Plugin，不接受请求提供的 SQL、文档、Plugin code 或连接信息。SQL、权限和菜单场景直接复用 `sql-jdbc:v1`、`permission-jdbc:v1`、`menu-jdbc:v1` 的生产解析、目标回执、所有权和保守补偿逻辑。
- 六个场景按冻结顺序真实执行：职责分离申请/批准、请求过期、批准撤销、SQL/权限/菜单混合 apply、带目标 FAILED Receipt 的稳定 key 重试、菜单/权限/SQL 逆序 compensation。故障重试先因缺表失败，再修复前置表并用完全相同的贡献与 key 重投，最终要求 `execution_count=2` 且 marker 只写一次。
- 逆序补偿后要求 SQL baseline marker 表不存在，权限与菜单 ownership 均为 REMOVED tombstone，目标端共有 7 条 SUCCEEDED Receipt、0 条 FAILED Receipt。任一断言不成立都会把当前 Scenario 和 Attempt 标记为 FAILED，后续场景标记 ABORTED。
- 证据详情会重新校验父 Run/Attempt 绑定、场景数和顺序、每条证据 SHA-256、成功计数与终态一致性。原始 `evidence_json` 使用 `@JsonIgnore`，只有校验后解析出的脱敏 Map 返回前端。
- 新增 Attempt 启动、列表、详情和中止四个 API，全部复用 `generator:delivery:verify`。交付报告新增本地 H2 启动、进度、重跑、中止和可展开证据视图，没有外部目标选择入口。
- 三份 Schema 脚本、Mapper 契约、Controller 权限、H2 真实集成、协调器、执行服务、API 与页面契约同步更新；设计与实施记录已写入对应 D8e2j 文档。

验证结果：

- Plugin 聚焦套件 182 个测试全部通过。H2 集成测试真实得到 7 条成功目标回执，故障场景 execution_count=2，补偿后 marker 消失且权限/菜单 ownership 均为 REMOVED。
- `ruoyi-generator` 全量执行 825 个测试，其中 807 个通过、18 个失败；失败仍严格为 11 个 AI 数据库生成、1 个字典选项和 6 个 Qing 模板一致性基线，本轮没有新增失败。
- `ruoyi-admin` 38 个测试全部通过；Plugin/交付页面契约测试 4 个全部通过。
- `ruoyi-ui` 生产构建通过，仍只有既有的 `listStructureExcludeChild` 缺失导出、资源/入口体积和 Browserslist 数据过旧警告。
- EasyCode 与 RuoYi UI 开发服务分别在 `http://localhost:5174`、`http://localhost:9528` 返回 HTTP 200。

当前边界：

- 本地审批使用固定合成身份与角色，只证明审批状态机和职责分离策略，不是人类审批凭证，也不能被真实 Transition 消费。
- 本阶段同步占用 HTTP 请求执行六个短场景。进程退出可能留下 PENDING/RUNNING 控制记录，而内存 H2 已消失；恢复方式是中止旧 Attempt 后新建重跑，不是恢复原沙箱。
- 多个全新 Attempt 可以并行运行，但每个沙箱完全隔离；重跑链只表达审计关系，不共享目标数据或 target receipt。
- 当前运行数据库不会自动获得四张演练表，部署前必须执行更新后的 `sql/factory_plugin_registry.sql`。本轮没有连接或修改任何外部 MySQL。
- 明文开发凭据与 TLS 校验继续按用户决定暂缓处理。

下一步进入 P2-D8e2k：把同步本地演练升级为带租约、心跳和可接管状态的 Durable Outbox Worker，增加 Attempt 对比与发布门禁报告；外部 MySQL 执行模式仍需用户明确授权后才能开放。

### 2026-07-11：P2-D8e2k 演练 Durable Outbox、语义对比与发布门禁

已完成：

- 新增 `factory_plugin_delivery_rehearsal_outbox`，每个 Attempt 恰好一条命令。PENDING、PROCESSING、DELIVERED、FAILED、ABORTED 状态，以及 available time、lease owner、私有 fencing token、lease deadline、最近心跳、delivery count、脱敏错误和终态时间均持久化；三份 Schema 脚本保持一致。
- Attempt、六条 Receipt 和 PENDING Outbox 在同一事务创建。启动 API 现在只入队并立即返回，不再占用 HTTP 请求打开或执行 H2；旧的无租约 `markAttemptRunning` Mapper 入口已删除。
- Worker 复用有界 Outbox 轮询配置，以条件更新原子认领到期 PENDING 或租约过期的 PROCESSING 命令。claim、心跳、Receipt 完成、Attempt 完成和 Outbox 完成都由随机 lease token fencing；场景执行期间按租期三分之一周期续租，控制事务不包围 H2 执行。
- claim、中止和人工协调统一按 Attempt 后 Outbox 的锁顺序执行。中止会原子封存 open Receipt、Attempt 和 Outbox 并清除 token；人工协调只释放已过期租约，活动租约不可被抢占。
- 因内存 H2 无法跨进程恢复，接管会重置非终态 Attempt 的临时 Receipt，重建独立沙箱并从第一个场景完整重放。终态证据不改写；delivery count 和心跳记录恢复次数，失去 token 的旧 Worker 无权落库。
- 新增 Attempt 语义对比。原始证据 SHA-256 继续用于单次完整性校验；对比会递归排除 sandbox、外部 target receipt、幂等 key 和生成 ID，再计算非持久化语义指纹。只有两个完整成功 Attempt 可比较，六个有序场景必须全部一致。
- 新增计算型发布门禁：父 Run READY、最新 Attempt SUCCEEDED、Outbox DELIVERED、六条证据完整且与上一成功 Attempt 语义一致时才 PASSED；首个成功 Attempt 建立初始基线。任何更新的排队、执行、失败、中止、篡改或漂移 Attempt 都会阻断。
- 新增过期租约协调、Attempt 对比和发布门禁 API，统一使用 `generator:delivery:verify`。交付页会自动轮询 open Attempt，展示 Outbox 状态、投递次数、Worker、心跳和租约截止，提供协调、语义对比和门禁检查视图；lease token、H2 URL 与内部账号不进入 REST。
- 设计与实施记录已写入 `docs/superpowers/specs/2026-07-11-plugin-rehearsal-durable-outbox-release-gate-design.md` 和 `docs/superpowers/plans/2026-07-11-plugin-rehearsal-durable-outbox-release-gate.md`。

验证结果：

- 受影响的演练、Worker、门禁、Schema 和 Controller 测试 29 个全部通过；Plugin 聚焦套件 193 个测试全部通过。
- `ruoyi-generator` 全量执行 836 个测试，其中 818 个通过、18 个失败；失败仍严格为 11 个 AI 数据库生成、1 个字典选项和 6 个 Qing 模板一致性基线，本轮没有新增失败。
- `ruoyi-admin` 38 个测试全部通过；Plugin/交付页面契约测试 4 个全部通过。
- `ruoyi-ui` 生产构建通过，仍只有既有的 `listStructureExcludeChild` 缺失导出、资源/入口体积和 Browserslist 数据过旧三类警告。
- EasyCode 与 RuoYi UI 开发服务分别在 `http://localhost:5174`、`http://localhost:9528` 返回 HTTP 200。

当前边界：

- 当前运行数据库不会自动获得第五张演练 Outbox 表，使用异步演练前必须执行更新后的 `sql/factory_plugin_registry.sql`；未迁移环境调用新 API 会失败。
- 接管会重放整个非终态 Attempt，而不是恢复旧 H2。重放前的成功 Receipt 属于临时证据，会被清空；只有 Attempt 与 Outbox 同时终态后，证据才视为不可变交付记录。
- 发布门禁是由控制库记录即时计算的本地交付判断，不是数字签名、外部审计时间戳或生产变更授权，也不会被真实 Transition 自动消费。
- 本轮没有连接或修改任何外部 MySQL；外部目标选择仍不存在。明文开发凭据与 TLS 校验继续按用户决定暂缓处理。

主线校正：暂停进入 P2-D8e2l。Plugin 交付基础设施已经具备较深的技术能力，但用户当前最需要的是看得见、能理解、可恢复的项目生成闭环。后续改造优先回到“创建项目 -> 一键生成 -> 查看进度 -> 失败恢复 -> 预览 -> 下载”的核心体验。

### 2026-07-11：P1-H 项目一键生成任务总览与跨会话恢复

已完成：

- 新增当前用户的一键生成任务总览接口，一次返回每个项目最新的 `one_click_project` 任务，只包含任务 ID、项目 ID、状态、进度、当前步骤、失败摘要、重试次数和时间，不返回请求 Payload、结果 Payload、Prompt、Stage 或 Checkpoint 大字段。
- “我的项目”新增一键生成状态列，展示等待、生成中、等待重试、成功、失败和取消状态，并显示紧凑进度条、当前步骤或失败原因。
- 项目列表的一键生成入口会携带 `projectId`、`mode=one-click` 和最新 `taskId` 打开生成工作台；没有任务时用于开始首次生成。
- 生成工作台新增路由任务恢复：优先从服务器读取指定 `taskId`，没有路由任务时才回退到原有 `localStorage`，因此清理缓存或换浏览器后仍可恢复服务器任务。
- 同一项目切换不同任务时会先使旧轮询失效，终态任务也不会再被旧轮询覆盖。
- 新建一键生成任务后立即把新 `taskId` 写入地址栏；路由同步失败不会中止已创建任务的轮询。
- 进度总览接口失败时只降级生成状态，不再阻断项目列表主体。
- 本轮没有新增数据库表或迁移，也没有修改明文开发凭据和 TLS 跳过配置。

验证结果：

- EasyCode 项目列表与生成工作台主流程契约测试 47 项全部通过，生产构建通过。
- AI 任务服务聚焦测试 16 项、项目控制器聚焦测试 12 项全部通过。
- `ruoyi-admin` 全量 39 项测试全部通过。
- MyBatis Mapper XML 已成功解析，EasyCode 开发服务在 `http://localhost:5174` 返回 HTTP 200。

设计与实施记录：

- `docs/superpowers/specs/2026-07-11-one-click-task-overview-resume-design.md`
- `docs/superpowers/plans/2026-07-11-one-click-task-overview-resume.md`

下一步沿项目工厂主线进入 P1-I：补齐项目级生成历史与可理解的失败诊断，让用户能查看历次生成、明确失败阶段，并从最近可恢复阶段继续，而不是继续扩展 Plugin 发布与交付层。

### 2026-07-11：P1-I 项目一键生成历史与阶段恢复

已完成：

- 新增项目级一键生成历史接口，按任务倒序返回最近 20 条记录。响应只包含状态、进度、尝试次数、失败阶段、最后完成阶段和恢复摘要，不读取或返回请求 Payload、结果 Payload、Prompt、检查点内容或模型凭据。
- 历史摘要复用现有 `front_ai_generation_task`、`factory_ai_task_stage` 和 `factory_ai_task_checkpoint`，没有新增表、迁移、双写或历史回填。
- 恢复位置与真实执行内核保持一致：存在源码检查点时从运行预览继续；否则存在数据库闭环检查点时从业务蓝图继续；没有可用检查点时重新执行项目准备。
- 只有失败和等待重试任务展示失败诊断与继续入口；成功或活动任务会清理旧尝试遗留的失败阶段和恢复提示。
- “我的项目”一键生成状态列新增生成记录时钟入口；一键生成工作台新增生成记录按钮和独立 Drawer，可查看状态、时间、尝试次数、失败位置、最后完成位置和将保留的成果。
- 查看历史任务会从服务器恢复精确 `taskId` 并同步地址栏，刷新后仍回到同一任务。继续生成前会确认恢复阶段和额度消耗，再复用原任务、原请求与现有轮询。
- 浏览器不能指定恢复阶段。同项目存在另一个活动的一键生成任务时，服务端会在预留额度前拒绝旧任务重试，避免并发写同一项目。
- 历史加载失败只影响 Drawer，不阻断项目列表或生成工作台；活动任务期间前端禁用历史重试，服务端保留最终并发门禁。
- 本轮没有新增数据库迁移，没有修改明文开发凭据和 TLS 跳过配置。

验证结果：

- AI 任务服务与 Mapper 契约测试 19 项全部通过；项目控制器聚焦测试 13 项全部通过。
- `ruoyi-admin` 全量 40 项测试全部通过。
- EasyCode 历史抽屉、项目列表与生成工作台主流程契约测试 53 项全部通过，生产构建通过。
- MyBatis Mapper XML 已成功解析，EasyCode 开发服务在 `http://localhost:5174` 返回 HTTP 200。

设计与实施记录：

- `docs/superpowers/specs/2026-07-11-one-click-generation-history-recovery-design.md`
- `docs/superpowers/plans/2026-07-11-one-click-generation-history-recovery.md`

下一步沿项目工厂主线进入 P1-J：把一键生成的当前阶段、已完成阶段和本次尝试明细直接呈现在任务进度区，并补齐失败后的“修复建议”，让用户不打开历史也能理解当前工厂正在做什么。

### 2026-07-11：P1-J 当前任务阶段事实与失败修复建议

已完成：

- 在现有任务状态响应中增加脱敏 `oneClickProgress`，复用已经读取的阶段账本和检查点，不新增接口、数据库查询、表或迁移。
- 摘要固定输出 11 个产品阶段，只包含阶段代码、顺序、尝试号、状态、时间和耗时；不复制 Prompt、模型、Handler 契约、Checkpoint Payload、请求 Payload 或结果 Payload。
- 当前尝试的阶段账本成为权威事实，不再只按进度百分比推断。界面可以明确区分待执行、执行中、已完成、失败和从可信检查点保留。
- 数据库检查点恢复会保留应用蓝图、业务闭环计划、数据库设计和数据闭环审计，项目准备由本次重跑；源码检查点恢复会保留源码生成之前的 9 个阶段，只重新启动运行预览。
- 手动继续后、Worker 尚未认领的排队窗口会显示“已执行 N 次，等待第 N+1 次”，并预先显示将复用的检查点阶段，不再残留上一轮失败状态。自动重试等待仍展示上一轮失败和建议。
- 服务端按失败阶段生成中文修复建议，覆盖项目准备、应用蓝图、闭环计划、数据库、数据审计、业务动作、页面、源码和运行预览；每条建议同时说明继续生成的起点和会保留的成果。
- 一键生成工作台用独立 `OneClickTaskProgressDetails` 替换固定步骤卡片，展示本次执行、阶段完成数、检查点保留数、每步状态和耗时。布局使用紧凑分隔线清单，桌面双列、移动端单列。
- 原始脱敏失败摘要、历史记录、任务路由恢复、重试、重启预览、查看预览和下载入口保持不变；旧后端响应仍有降级展示。
- 本轮没有修改明文开发凭据和 TLS 跳过配置。

验证结果：

- 一键任务 Composer、任务服务和历史 Mapper 契约测试 24 项全部通过。
- EasyCode 当前进度、历史、项目列表和生成工作台主流程契约测试 56 项全部通过，生产构建通过。
- `ruoyi-admin` 全量 40 项测试全部通过。
- EasyCode 开发服务在 `http://localhost:5174` 返回 HTTP 200。

设计与实施记录：

- `docs/superpowers/specs/2026-07-11-one-click-current-stage-guidance-design.md`
- `docs/superpowers/plans/2026-07-11-one-click-current-stage-guidance.md`

下一步沿项目工厂主线进入 P1-K：统一“源码已生成、运行预览已通过、质量验收已通过、允许正式下载”四种状态，先建立用户可见的交付验收摘要与下载门禁，再逐步接入 Java 测试、前端构建、SQL 导入和 API 冒烟结果。

### 2026-07-11：P1-K 交付验收摘要与分级下载门禁

已完成：

- 新增项目交付就绪度服务和只读 API，统一计算 `DRAFT`、`SOURCE_READY`、`PREVIEW_PASSED`、`ACCEPTED` 四种状态，并固定输出源码生成、运行预览、基础验收、认证下载四项用户检查。
- 明确区分 `DRAFT` 源码草稿与 `CERTIFIED` 基础验收产物。旧调用未传产物类型时继续按草稿处理，兼容已有预览和调试流程。
- 认证下载要求最新源码来自已成功完成的一键任务、Generation Run 成功且具有完整 Spec、Adapter、Template、内容聚合和文件清单身份，并且最新尝试的运行预览证据成功。
- 阶段账本非空时只接受最新尝试的 `RUN_PREVIEW`，不会回退旧结果中的预览状态；任务仍在运行、失败或取消时，即使残留历史成功证据也不会误认证。
- 公开下载控制器在生成 ZIP 前执行服务端门禁，并返回产物类型和认证等级响应头；伪造前端状态或直接请求认证下载不能绕过校验。
- 项目修改导致 `previewStatus=0` 后，旧阶段和 Generation Run 证据立即失效。数据库变更同步和兼容旧项目只保留草稿下载，不会被误认证。
- 一键生成结果区新增紧凑交付验收摘要，认证通过时显示“下载验收源码”，否则显示“下载源码草稿”；项目列表、个人中心和源码预览页也明确标记草稿下载。
- 交付摘要会在项目加载、任务终态和运行预览终态后刷新；加载失败不覆盖已完成任务，最终权限仍由服务端判断。
- 本轮没有新增数据库表或迁移，也没有修改明文开发凭据和 TLS 跳过配置。

验证结果：

- P1-J/P1-K 后端聚焦测试 32 项全部通过，其中 P1-K 交付服务与 Mapper 契约测试 8 项全部通过。
- `ruoyi-admin` 全量 42 项测试全部通过，交付摘要与认证下载控制器测试包含在内。
- EasyCode 交付面板、生成工作台、任务历史、项目列表、个人中心和源码预览主流程测试 73 项全部通过，生产构建通过。
- 两个相关 MyBatis Mapper XML 已成功解析，EasyCode 开发服务在 `http://localhost:5174` 返回 HTTP 200。

当前边界：

- `BASELINE` 目前只证明当前源码可追溯且运行预览成功，不代表生成项目已经通过 Java 测试、前端生产构建、SQL 导入或 API 冒烟，也不是生产发布认证。
- 独立“重启运行预览”用于调试，不会补写持久化认证证据。运行预览失败或源码发生变化后，需要重新执行完整一键生成并通过预览，才能开放认证下载。
- 旧项目没有可追溯 Generation Run 时仍可兼容下载草稿，但不会自动升级为认证产物。
- 明文开发凭据与 TLS 校验继续按用户决定暂缓处理。

下一步沿项目工厂主线进入 P1-L：建立持久化 Quality Run，把生成项目的 Java 测试、前端生产构建、SQL 隔离导入和 API 冒烟作为可重试、可追溯证据接入同一交付摘要，再据此提升认证下载门禁。

### 2026-07-12：P1-L 持久化 Quality Run

已完成：

- 新增项目 Quality Run 和四项 Check 持久化账本，绑定当前用户、项目、Generation Run 和源码聚合哈希；支持排队、执行、通过、失败和中断状态。
- Worker 使用条件认领、租约续期和 owner fencing，过期运行会封存为 `INTERRUPTED`；最终状态写入丢失租约时不会误报处理成功。
- 真实执行 Java 测试、所有启用前端的生产构建、独立 MySQL 数据库 SQL 导入和运行预览 API 冒烟，并清理临时数据库、预览进程和源码工作区。
- 新增创建、历史和最新 Quality Run API。响应只包含脱敏摘要、状态和耗时，不返回源码哈希、租约、数据库连接或完整日志。
- 交付门禁现在要求当前源码对应的四项检查全部通过。旧 Generation Run、旧源码哈希、失败、中断或检查不完整的记录不能开放 `CERTIFIED` 下载。
- EasyCode 交付区新增“开始质量验收/重新质量验收”、四项检查结果和运行中轮询；认证下载仍完全服从服务端就绪度。
- Quality Run 表结构已同步到独立升级脚本、`front_workbench.sql` 和 `db.sql`；Plugin 目标库 SQL 保持隔离，没有混入控制库。
- 本轮没有修改按用户决定暂缓的明文模型凭据和 TLS 配置。

验证结果：

- P1-H 到 P1-L 后端聚焦测试 50 项全部通过。
- `ruoyi-admin` 全量 43 项全部通过。
- EasyCode 主流程 73 项全部通过，生产构建通过。
- Mapper XML 解析、SQL 一致性和 whitespace 检查通过；`http://localhost:5174` 返回 HTTP 200。

当前边界：

- 当前 Quality Run 固化的是质量证据，不是 ZIP 字节本身。`CERTIFIED` 下载仍在请求时重新打包，因此尚不具备不可变制品、内容哈希和冻结质量报告。
- 本轮未连接或迁移任何外部 MySQL。部署前必须执行 `sql/factory_project_quality_run.sql` 或同步后的聚合建库脚本。

下一步进入 P1-M：将通过质量验收的源码 ZIP、SHA-256 和质量报告冻结为认证制品，下载时直接读取冻结对象，不再临时重新打包。

### 2026-07-12：P1-M 认证制品固化

已完成：

- 新增认证制品账本和不可变对象存储抽象。Quality Run 四项通过后冻结完整源码 ZIP 与规范化质量报告，并分别计算 SHA-256 和长度。
- 本地对象存储使用临时文件和原子移动，相同 key 重复写入必须字节一致，不允许路径穿越或覆盖不同内容。
- `CERTIFIED` 下载不再调用源码生成器临时打包，只读取当前 Quality Run 对应的 READY 制品并复验 ZIP SHA-256。
- 下载响应增加制品 ID、ZIP SHA-256 和报告 SHA-256；`DRAFT` 下载保持兼容。
- 交付就绪度现在同时要求匹配的通过 Quality Run 和 READY 制品记录。

### 2026-07-12：P1-N 隔离容器预览

已完成：

- 新增持久化 Preview Job、用户/项目幂等启动、停止请求、Worker claim、租约 token、TTL 和终态记录。
- Web 请求只入队和读取状态。旧直接宿主进程实现不再注册为 Spring 服务，也不存在 Docker 失败后的宿主进程回退。
- 独立 Preview Worker 使用 Docker CLI，并强制 CPU、内存、PIDs、只读根文件系统、`/tmp` tmpfs、只读源码挂载、输出挂载、网络和 Job label。
- 仓库新增 `deploy/preview-worker` 镜像：容器内解压源码、启动生成后端/前端、等待就绪、使用 Chromium 截图并写入 ready 证据。
- Worker 等待 ready 后才标记 RUNNING；用户停止、TTL 到期或最终 fencing 写入失败都会停止容器。截图通过鉴权接口读取并复验 SHA-256。
- Web 节点默认 `worker-enabled=false`，独立 Worker 部署显式开启。

### 2026-07-12：P1-O V1 黄金样例验收与收口

已完成：

- 新增 V1 Acceptance Run 和固定五项检查：生成闭环、失败恢复、版本回滚、容器预览、认证制品。
- 生产探针验证成功生成和质量证据、从可信检查点恢复的成功重试、保留历史的新回滚版本、带截图且未终止的 Preview Job，以及两次读取字节一致的冻结认证 ZIP。
- 验收只持久化脱敏摘要和证据 SHA-256，失败可新建重跑且不覆盖历史；新增启动、最新和历史 API。
- EasyCode 交付区新增 V1 验收入口、五项状态和容器截图，认证下载文案统一为“下载认证制品”。
- 三组表统一写入 `sql/factory_project_v1_closeout.sql`、`front_workbench.sql` 和 `db.sql`。

验证结果：

- P1-H 到 P1-O 后端聚焦测试 62 项全部通过，Preview Worker fencing 类 3 项全部通过。
- `ruoyi-admin` 全量 44 项全部通过。
- EasyCode 主流程 73 项全部通过，生产构建通过。
- Mapper XML、SQL 契约、Worker 入口脚本语法和 whitespace 检查通过；开发服务返回 HTTP 200。

部署边界：

- 当前机器没有 Docker CLI，未在本机实际构建或启动 Preview Worker 镜像，也未伪造真实黄金项目通过记录。
- 部署前必须执行 `sql/factory_project_v1_closeout.sql`，构建 `easycode/preview-worker:v1`，让 Web/Worker 共享控制库和 Worker 输出卷，再通过 V1 验收 API 跑真实黄金项目。
- 本轮未连接或修改任何外部 MySQL；明文开发凭据和 TLS 跳过配置继续按用户决定暂缓。

至此，AI 项目生成工厂 V1 的 P1-A 到 P1-O 代码主改造完成。Knowledge Pack、多技术栈 Adapter、插件市场等继续属于 V2。