# 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。
- 当前图书参数自动带入。
- 表单提交只发送一次请求。
- 取消不发送请求。
- 成功后页面按配置刷新。