From fd728042cd6a3ed8a6d933c62039d5f263d66937 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E9=B9=8F?= <wangpengv@yonyou.com>
Date: Sun, 28 Jun 2026 16:30:17 +0800
Subject: [PATCH] Document business loop generation engine design

---
 ...-business-loop-generation-engine-design.md | 280 ++++++++++++++++++
 1 file changed, 280 insertions(+)
 create mode 100644 RuoYi-Vue/docs/superpowers/specs/2026-06-28-business-loop-generation-engine-design.md

diff --git a/RuoYi-Vue/docs/superpowers/specs/2026-06-28-business-loop-generation-engine-design.md b/RuoYi-Vue/docs/superpowers/specs/2026-06-28-business-loop-generation-engine-design.md
new file mode 100644
index 0000000..4e8d4e3
--- /dev/null
+++ b/RuoYi-Vue/docs/superpowers/specs/2026-06-28-business-loop-generation-engine-design.md
@@ -0,0 +1,280 @@
+# 通用业务闭环生成引擎设计
+
+## 目标
+
+把一键模式从“生成完整 CRUD 项目”升级为“生成可运行的完整业务闭环项目”。用户只输入项目名称，例如“图书借阅系统”，系统也应自动推断核心业务闭环，并生成后端、用户前台、后台管理端、SQL、业务动作按钮和在线运行预览。
+
+第一版聚焦通用闭环生成引擎，不依赖行业模板包。成功标准不是项目能打开，也不是表结构能维护，而是生成项目至少包含一条从入口动作、状态流转、数量变化或关联记录写入，到后续完成动作的可执行闭环。
+
+## 已确认决策
+
+- 方向选择通用业务闭环生成引擎。
+- 第一版覆盖状态流转、数量或库存变化、关联记录生成。
+- 只填项目名称也要自动推断闭环。常见系统不能降级成 CRUD。
+- 闭环生成失败时，一键任务应失败并给出明确原因，而不是静默生成 CRUD 项目。
+- 现有业务动作安全 DSL 继续作为执行层，不允许 AI 生成任意 Java 或 SQL。
+
+## 背景
+
+当前 `one_click_project` 已经能串联应用蓝图、数据库、业务动作、页面初始化、源码结构和运行预览。问题在于编排链路本身不表达“业务闭环必须完整”。如果 AI 在数据库或业务动作阶段输出偏保守，一键模式仍会生成一个看起来完整、实则以表维护为主的项目。
+
+已有能力可以复用：
+
+- `IAiGenerateService` 生成应用蓝图、数据库和业务动作 DSL。
+- `AiBusinessBlueprintValidator` 校验业务动作只引用已保存表字段。
+- `qing` 模板已支持业务动作 Controller、Service、Vue 按钮和弹窗。
+- `FrontendPageDesignService` 能初始化前台和后台页面设计。
+- `OneClickProjectGenerationServiceImpl` 已有阶段化任务编排、结果报告和运行预览。
+
+缺口不是底层模板，而是缺少一个结构化的“业务闭环契约”，让数据库、业务动作和页面按钮围绕同一条业务路径生成。
+
+## 非目标
+
+第一版不建设行业模板市场，不做可视化流程编排器，不支持任意复杂 BPMN，不支持多级会签、分布式事务、支付网关真实对接、幂等键、库存锁、财务总账或生产部署。
+
+行业模板包可以作为后续增强，但本设计优先让通用引擎在没有模板命中的情况下也能生成合理闭环。
+
+## 总体架构
+
+在一键编排中新增业务闭环计划层 `BusinessLoopPlan`。它位于应用蓝图之后、数据库生成之前，作为后续生成的结构化约束。
+
+新的主链路为：
+
+1. 生成应用蓝图。
+2. 生成业务闭环计划。
+3. 根据闭环计划生成数据库。
+4. 审计数据库是否覆盖闭环计划。
+5. 根据闭环计划生成业务动作 DSL。
+6. 审计业务动作是否覆盖必需闭环。
+7. 根据闭环计划和业务动作初始化页面动作绑定。
+8. 生成源码结构。
+9. 启动在线运行预览。
+
+`OneClickProjectGenerationServiceImpl` 只负责编排这些阶段，不在编排器里硬编码行业流程。AI 输出必须被 DTO、校验器和覆盖审计约束。
+
+## 业务闭环计划
+
+`BusinessLoopPlan` 是业务闭环的中间契约，不是最终代码，也不是模板。它描述生成项目必须具备的核心对象、状态机、动作链、数量变化、关联记录和页面入口。
+
+建议字段：
+
+- `domainName`：业务域名称，例如图书借阅、订单交易、请假审批。
+- `coreObjects`：核心对象列表，例如图书、读者、借阅记录、罚金记录。
+- `stateMachines`：状态机定义，包含对象、状态字段、状态值和流转。
+- `actions`：必需业务动作，包含 actor、ownerObject、触发页面、前置条件、状态变化、数量变化和记录写入。
+- `quantityRules`：数量或库存变化规则。
+- `recordRules`：关联记录生成或更新规则。
+- `pageBindings`：动作应该出现在哪类页面和哪个位置。
+- `acceptanceScenarios`：闭环验收场景。
+
+示例：用户只输入“图书借阅系统”时，计划层应推断：
+
+- 核心对象：图书、读者、借阅记录、罚金记录。
+- 状态机：借阅记录从申请中到借阅中，再到已归还、已取消或已逾期。
+- 动作链：申请借阅、确认借出、取消申请、归还图书、标记逾期、缴纳罚金。
+- 数量变化：确认借出减少可借数量，归还或取消恢复可借数量。
+- 关联记录：申请借阅创建借阅记录，逾期创建或更新罚金记录。
+- 页面入口：图书列表有申请借阅，我的借阅有取消和归还，后台借阅列表有确认借出和标记逾期。
+- 验收场景：借出后库存减少，归还后库存恢复，记录状态正确变化。
+
+## DTO 边界
+
+第一版可以新增轻量 DTO，不新增数据库表。计划 JSON 可存入 `front_project` 的扩展字段，或先复用项目草稿 JSON 字段；任务执行结果也要带上计划摘要和审计结果。若现有表没有合适字段，优先以最小 SQL 增量新增 `business_loop_plan`。
+
+建议 DTO：
+
+```java
+BusinessLoopPlan
+BusinessLoopObject
+BusinessLoopStateMachine
+BusinessLoopStateTransition
+BusinessLoopAction
+BusinessLoopQuantityEffect
+BusinessLoopRecordEffect
+BusinessLoopPageBinding
+BusinessLoopAcceptanceScenario
+BusinessLoopAuditResult
+```
+
+`BusinessLoopAction` 至少包含：
+
+- `code`
+- `name`
+- `actor`
+- `ownerObject`
+- `triggerPage`
+- `required`
+- `preconditions`
+- `stateTransitions`
+- `quantityEffects`
+- `recordEffects`
+
+## AI 生成约束
+
+新增 `generateBusinessLoopPlan` 能力。Prompt 必须要求返回 JSON only，并强调：
+
+- 不生成 CRUD 动作。
+- 不生成代码、SQL 或表结构。
+- 必须生成至少一条端到端业务闭环。
+- 必须包含状态流转。
+- 必须包含数量变化或关联记录生成，第一版推荐两者都尽量包含。
+- 动作必须能映射到后续安全 DSL 支持的效果类型：`INSERT_ROW`、`UPDATE_FIELDS`、`SET_STATUS`、`INCREASE_NUMBER`、`DECREASE_NUMBER`。
+- 项目名足够明确时必须自动推断，不要求用户额外补充描述。
+
+数据库生成 Prompt 增加 `businessLoopPlan`：
+
+- 表和字段必须覆盖计划中的核心对象。
+- 状态机对象必须有状态字段。
+- 数量规则涉及对象必须有数量字段。
+- 关联记录规则必须有记录表和必要外键或引用字段。
+- 用户前台相关记录应有当前用户字段，例如 `user_id`。
+
+业务动作生成 Prompt 增加 `businessLoopPlan`：
+
+- 每个 required action 必须生成对应 DSL。
+- DSL 必须体现计划中的前置条件、状态变化、数量变化和记录写入。
+- 不能把闭环动作降级为普通编辑接口。
+
+## 校验与审计
+
+新增 `BusinessLoopPlanValidator` 校验计划本身：
+
+- `coreObjects` 不能为空。
+- `actions` 中至少有一个 `required=true`。
+- 至少包含一个状态流转。
+- 至少包含一个数量变化或关联记录规则。
+- 动作 code 必须稳定、唯一、符合安全标识符规则。
+- 页面绑定只能使用受支持的位置，例如列表行按钮、详情主按钮、后台行按钮。
+
+新增 `BusinessLoopCoverageValidator` 做两次覆盖审计。
+
+数据库覆盖审计：
+
+- 计划中的核心对象能映射到已生成表。
+- 状态机对象有状态字段，状态字段可保存计划状态值。
+- 数量规则对象有数值字段。
+- 记录规则对象有记录表。
+- 动作所需引用字段存在，例如图书 ID、用户 ID、借阅记录 ID。
+
+业务动作覆盖审计：
+
+- 每个 required action 都有对应 `BusinessActionDesign`。
+- 需要状态变化的动作必须有 `SET_STATUS` 或等价 `UPDATE_FIELDS`。
+- 需要数量变化的动作必须有 `INCREASE_NUMBER` 或 `DECREASE_NUMBER`。
+- 需要记录生成的动作必须有 `INSERT_ROW` 或记录表更新。
+- 必要前置条件必须有 `ruleChecks`，例如库存大于 0、状态必须为申请中、当前用户只能操作自己的记录。
+
+审计失败时，一键任务失败在明确阶段，并返回可读错误，例如“业务闭环不完整：缺少归还图书动作的库存恢复效果”。
+
+## 页面动作落位
+
+闭环计划中的 `pageBindings` 驱动页面初始化。目标是让用户能在生成项目里直接走业务流程，而不是只看到表格。
+
+用户前台建议规则：
+
+- 资源列表页放入口动作，例如申请借阅、立即下单、提交预约。
+- 我的记录页放个人流程动作，例如取消申请、归还、支付、确认完成。
+- 详情页放主动作按钮，例如立即借阅、提交申请。
+
+后台管理端建议规则：
+
+- 待处理记录页放审核、确认、驳回、发货、标记完成等动作。
+- 业务记录页放状态流转按钮和详情入口。
+- 基础资料表保留 CRUD，但只作为维护入口。
+
+实现上复用现有页面设计和模板能力，把计划动作自动转成 `pageDesignToolbarBusinessActions`、`pageDesignRowBusinessActions` 或详情页主按钮配置。第一版不要求用户在一键模式中手动确认按钮位置。
+
+## 任务阶段与结果
+
+`OneClickProjectGenerationResult` 增加闭环相关报告字段，或在 report 中扩展：
+
+```json
+{
+  "businessLoopComplete": true,
+  "loopActions": 6,
+  "stateTransitions": 5,
+  "quantityRules": 2,
+  "recordRules": 2,
+  "missingRequiredActions": []
+}
+```
+
+新增阶段建议：
+
+- `BUSINESS_LOOP_PLAN`：生成并校验闭环计划。
+- `DATABASE_LOOP_AUDIT`：数据库覆盖审计。
+- `BUSINESS_LOOP_AUDIT`：业务动作覆盖审计和页面动作落位检查。
+
+失败时保留已完成产物。若数据库已生成但动作审计失败，用户仍可进入专家模式查看数据库和计划，但一键任务不标记为成功。
+
+## 专家模式
+
+专家模式继续保留现有蓝图、数据库、业务流程和页面设计能力。新增闭环计划摘要面板，用于展示：
+
+- 核心对象。
+- 必需动作。
+- 状态机。
+- 数量和记录规则。
+- 覆盖审计结果。
+
+第一版不要求支持可视化编辑闭环计划。若用户修改数据库或业务动作，专家模式可以重新运行闭环审计，指出缺失项。
+
+## 测试策略
+
+后端单测：
+
+- `BusinessLoopPlanValidator` 接受有效闭环，拒绝空计划、无状态流转、无数量或记录规则、重复动作 code。
+- `BusinessLoopCoverageValidator` 能发现缺状态字段、缺库存字段、缺记录表、缺 required action、缺库存恢复效果。
+- `AiGenerateServiceImpl` 生成数据库和业务动作时会把 `businessLoopPlan` 传入 Prompt。
+- `OneClickProjectGenerationServiceImpl` 按新阶段顺序调用闭环计划、数据库审计、业务动作审计和页面初始化。
+
+后端集成或模板测试：
+
+- 图书借阅系统生成 `borrow_record` 相关动作，并渲染业务动作 Controller、Service 和前台按钮。
+- 商城订单系统生成订单记录、订单明细、库存扣减和状态流转。
+- 请假审批系统生成提交、审批通过、驳回动作和状态流转。
+
+前端测试：
+
+- 一键结果报告展示闭环完成状态和缺失项。
+- 专家模式能显示闭环计划摘要和审计错误。
+- 页面设计初始化后，闭环动作进入合适页面按钮集合。
+
+人工验收：
+
+1. 输入“图书借阅系统”，不填写描述。
+2. 一键生成成功后，用户前台图书列表有申请借阅入口。
+3. 执行申请借阅后产生借阅记录。
+4. 后台确认借出后图书可借数量减少。
+5. 用户归还后借阅状态变为已归还，图书可借数量恢复。
+6. 生成报告显示 `businessLoopComplete=true`。
+
+## 分期
+
+第一阶段：
+
+- 新增闭环计划 DTO、生成 Prompt、计划校验。
+- 一键编排接入 `BUSINESS_LOOP_PLAN`。
+- 数据库和业务动作 Prompt 接收闭环计划。
+- 新增数据库覆盖审计和动作覆盖审计。
+- 报告中展示闭环完成状态。
+
+第二阶段：
+
+- 页面初始化自动落位闭环按钮。
+- 专家模式展示闭环计划摘要和审计结果。
+- 完成图书借阅、商城订单、请假审批三个验收场景。
+
+第三阶段：
+
+- 支持从审计失败阶段继续生成。
+- 引入可选行业模板包，提高常见场景稳定性。
+- 支持用户在专家模式调整闭环计划。
+
+## 自检
+
+- 本设计聚焦通用闭环生成，不转向行业模板市场。
+- 执行层继续使用安全 DSL，不开放任意代码生成。
+- 只填项目名称也能触发闭环推断。
+- 一键模式不会把 CRUD 项目伪装成闭环成功。
+- 页面按钮、数据库结构和业务动作都围绕同一份闭环计划生成。