Design unified Qing business action dialog

RuoYi-Vue/docs/superpowers/specs/2026-06-18-qing-business-action-dialog-design.md

@@ -0,0 +1,148 @@
+# Qing 通用业务操作弹窗设计
+
+## 目标
+
+所有 Qing 前台业务按钮使用统一、符合实际项目习惯的交互：
+
+- 不再按 `requestFields` 逐个弹出输入框。
+- 当前登录用户、当前记录、详情数据和现有页面表单能够提供的参数自动填充。
+- 仍需用户输入的参数集中显示在一个表单弹窗中。
+- 用户提交表单即执行操作，不再出现第二层确认弹窗。
+- 没有待输入参数时，保留页面设计器配置的确认提示；未配置确认提示则直接执行。
+
+该行为由通用生成模板提供，借书、预约、归还、审核、上下架等业务按钮自动获得相同行为，不为某个动作编写特例。
+
+## 现状与根因
+
+`qing/index.vue.vm` 当前通过 `collectBusinessActionPayload` 遍历缺失字段，并为每个字段调用一次 Element UI `$prompt`。业务动作需要多个参数时，用户会连续处理多个彼此割裂的弹窗。
+
+当前系统已经具备可复用的上下文：
+
+- 行按钮传入当前行数据。
+- 详情页持有 `detailRecord`。
+- 页面持有 `form` 和 `queryParams`。
+- 登录结果保存在 `portal-user`，请求令牌由请求拦截器携带。
+- 后端业务动作控制器能够从令牌解析可信的当前用户，并注入 `__currentUserId`。
+- 数据库字段包含字段注释和表单控件类型，可用于生成友好的输入项。
+
+## 方案选择
+
+### 采用：通用动态业务操作弹窗
+
+模板先解析参数来源，再将全部未解析参数放入同一个 Element UI 对话框。此方案覆盖全部业务按钮，不增加逐按钮配置负担，也与现有页面样式和技术栈一致。
+
+### 未采用：页面设计器逐按钮配置业务表单
+
+它能处理高度定制的表单，但要求每个生成项目继续人工配置，无法从根本上修复默认生成体验。
+
+### 未采用：每个业务动作使用独立页面
+
+它适合多步骤、长流程业务，但会让借书、预约、审核等轻量动作变得笨重。独立业务页可作为未来扩展，不属于本次范围。
+
+## 参数解析规则
+
+执行按钮时，按以下顺序构建请求参数：
+
+1. 当前按钮携带的行数据。
+2. 当前详情页的 `detailRecord`。
+3. 当前页面的 `form`。
+4. 当前页面的 `queryParams`。
+5. 可信登录用户上下文。
+6. 单次弹窗中由用户填写的值。
+
+字段同时支持 snake_case 和 camelCase，例如 `book_id` 可从记录的 `bookId` 获取。
+
+登录用户字段不能依赖用户手工输入。业务动作生成上下文应标记由 `${current_user.id}` 提供的请求字段；前端不渲染这些字段，后端在执行规则和效果前使用认证用户 ID 覆盖对应参数。客户端即使伪造这些值也不能替换认证用户。
+
+无法由上下文提供的字段才进入动态表单。字段标题优先使用数据库字段注释，控件优先使用数据库字段的 `htmlType`：
+
+- 日期字段使用日期选择器。
+- 字典或枚举字段使用选择器。
+- 长文本使用多行输入。
+- 普通字段使用文本输入。
+
+第一期不增加页面设计器中的逐字段表单编排功能。
+
+## 交互流程
+
+### 有待输入参数
+
+点击业务按钮后打开一个以业务动作名称为标题的弹窗。弹窗包含：
+
+- 当前操作的简短说明或已有 `confirmMessage`。
+- 所有待输入字段。
+- 取消按钮。
+- `${buttonLabel}` 或“确认执行”按钮。
+
+用户提交时统一校验必填字段。校验通过后关闭输入能力、显示提交状态并发送一次请求。提交按钮本身就是确认动作，不再显示第二个确认弹窗。
+
+### 无待输入参数
+
+- 配置了 `confirmMessage`：显示一次确认框，确认后执行。
+- 未配置 `confirmMessage`：直接执行。
+
+### 执行结果
+
+- 成功时显示配置的 `successMessage`，并按 `refreshTarget` 刷新列表、详情、整页或不刷新。
+- 业务失败时保留弹窗和用户输入，显示后端返回消息，允许修正后重试。
+- 用户取消时不发送请求。
+- 请求进行中禁止重复提交。
+
+## 组件与模板边界
+
+`qing/index.vue.vm` 增加一个通用业务操作对话框状态和方法：
+
+- 当前动作和当前记录。
+- 自动解析后的请求载荷。
+- 待输入字段定义与表单值。
+- 打开、校验、提交、取消和错误处理。
+
+业务按钮仍统一调用 `handleBusinessAction`。该方法不直接串联 `$prompt`，而是选择以下路径：
+
+- 打开动态表单。
+- 显示一次简单确认。
+- 直接执行。
+
+`BusinessActionDesign` 或生成期等价结构提供渲染所需的临时字段元数据，包括显示名、控件类型、选项和当前用户绑定信息。业务蓝图持久化格式保持向后兼容；已有项目没有新元数据时，生成器从已保存数据库结构推导默认值。
+
+`controller.java.vm` 和 `serviceImpl.java.vm` 继续以认证令牌为用户身份来源，并在参数校验、规则检查和效果执行之前注入或覆盖当前用户绑定字段。
+
+SQL 中的 Qing 模板副本必须与资源模板同步，保证新数据库和已有模板回退路径行为一致。
+
+## 兼容性
+
+- 保留现有业务按钮的标签、类型、图标、确认提示、成功提示和刷新目标配置。
+- 保留现有业务动作 API 路径、HTTP 方法和请求字段名称。
+- 行按钮、详情按钮和工具栏按钮使用同一套运行时。
+- 已能从行或详情数据解析全部参数的动作不会多出表单。
+- 旧业务蓝图无需迁移即可生成；缺少字段元数据时使用通用输入控件。
+
+## 测试
+
+先增加失败测试，再修改实现。
+
+模板渲染测试覆盖：
+
+- 页面不再包含逐字段 `$prompt`。
+- 页面只渲染一个通用业务操作对话框。
+- 多个缺失字段在同一表单中生成。
+- 行数据和详情数据可自动解析 snake_case/camelCase 参数。
+- 当前用户绑定字段不显示为输入项。
+- 没有待输入字段时保留一次确认或直接执行。
+- 成功提示、错误提示和刷新目标保持原行为。
+- SQL 模板副本与资源模板一致。
+
+后端测试覆盖：
+
+- 当前用户字段由认证用户覆盖。
+- 缺失普通参数仍返回明确业务错误。
+- 客户端伪造用户字段不能代表其他用户执行操作。
+
+浏览器验收至少覆盖借书和另一个多参数业务按钮：
+
+- 点击后最多出现一个弹窗。
+- 不需要输入 user id。
+- 当前图书参数自动带入。
+- 表单提交只发送一次请求。
+- 取消不发送请求。
+- 成功后页面按配置刷新。