新增信息维护页面头部按钮统一设计文档

docs/superpowers/specs/2026-04-23-info-maintenance-toolbar-unification-design.md

@@ -0,0 +1,338 @@
+# 信息维护页面头部按钮统一设计文档
+
+## 1. 背景
+
+当前“信息维护”菜单下各页面的头部结构并不统一。
+
+多数页面仍沿用若依常见写法：查询条件表单位于上方，`搜索 / 重置` 按钮放在查询表单最后一个 `el-form-item` 中；查询表单下方再单独放一行业务按钮，如 `新增`、`导入`、`查看导入失败记录` 等。
+
+这导致同属“信息维护”目录的页面在操作起点上表现不一致：
+
+- 用户需要先在查询表单区域找到 `搜索 / 重置`，再把视线切到下一行找 `新增 / 导入`
+- 页面首屏操作被拆成两层，视觉上不够统一
+- 特殊页如“征信维护”“中介库管理”也各自使用不同结构，进一步放大了差异
+
+本次需求非常明确：将“信息维护”菜单下所有页面统一调整为把 `搜索 / 重置` 移到 `新增 / 导入` 同一行，并放在这些业务按钮左边。
+
+## 2. 目标
+
+在“信息维护”菜单下所有页面中，统一实现以下头部规则：
+
+- 查询条件区域继续保留在上方
+- 查询条件下方保留一条统一操作行
+- `搜索 / 重置` 从查询表单内部移出，进入统一操作行
+- 统一操作行的顺序固定为：`搜索 -> 重置 -> 页面原有业务按钮 -> right-toolbar`
+- 页面原有业务按钮文案、权限、显隐条件、点击行为保持不变
+
+## 3. 范围
+
+本次范围覆盖“信息维护”菜单下全部当前前端页面：
+
+- 员工信息维护
+- 招聘信息维护
+- 员工调动记录
+- 员工亲属关系维护
+- 员工实体关系维护
+- 征信维护
+- 实体库管理
+- 中介库管理
+- 账户库管理
+- 信贷客户家庭关系
+- 信贷客户实体关联
+- 招投标信息维护
+
+其中两类特殊页面也纳入本次统一范围：
+
+- 征信维护：业务按钮不是“新增 / 导入”，而是 `批量上传征信HTML`
+- 中介库管理：查询条件与 `搜索 / 重置` 目前封装在独立 `SearchForm` 组件中
+
+## 4. 非目标
+
+- 不新增头部公共组件
+- 不重构查询表单字段布局
+- 不新增或删除任何业务按钮
+- 不修改接口、数据结构、权限点和页面路由
+- 不调整失败记录按钮的显示逻辑
+- 不顺带处理与本次需求无关的样式问题
+
+## 5. 当前现状分析
+
+### 5.1 常规页面
+
+常规页面的结构基本一致：
+
+1. 查询表单
+2. 查询表单中最后一个 `el-form-item` 放 `搜索 / 重置`
+3. 下一行 `el-row.mb8` 放 `新增 / 导入 / 失败记录 / right-toolbar`
+
+这类页面包括：
+
+- 员工信息维护
+- 员工调动记录
+- 员工亲属关系维护
+- 员工实体关系维护
+- 招聘信息维护
+- 实体库管理
+- 账户库管理
+- 信贷客户家庭关系
+- 信贷客户实体关联
+- 招投标信息维护
+
+### 5.2 征信维护
+
+“征信维护”页面没有 `新增 / 导入` 组合，当前写法为：
+
+1. 查询表单中放 `搜索 / 重置`
+2. 下一行操作区只放 `批量上传征信HTML` 和 `right-toolbar`
+
+虽然语义不同，但本质上仍属于“查询按钮与业务按钮分两行”的问题。
+
+### 5.3 中介库管理
+
+“中介库管理”页面的查询条件被拆到 `SearchForm.vue` 组件中，当前结构为：
+
+1. 父页渲染 `SearchForm`
+2. `SearchForm` 内部自己渲染查询字段和 `搜索 / 重置`
+3. 父页下方单独渲染 `新增 / 两类导入 / 两类失败记录 / right-toolbar`
+
+这类页面不能像常规页那样只移动模板片段，需要同时调整父子职责边界。
+
+## 6. 方案比较
+
+### 6.1 方案一：逐页手工挪动按钮
+
+做法：
+
+- 每个页面各自把 `搜索 / 重置` 从查询表单中移到下方操作行
+- 中介库管理单独做特殊适配
+
+优点：
+
+- 改法直接
+- 不引入新抽象
+
+缺点：
+
+- 页面数量较多，重复改动偏多
+- 容易因为逐页处理导致结构细节不一致
+
+### 6.2 方案二：抽头部公共组件
+
+做法：
+
+- 新增一个统一头部组件，接收查询按钮、业务按钮和 `right-toolbar`
+- 所有信息维护页面接入该组件
+
+优点：
+
+- 理论上后续最统一
+
+缺点：
+
+- 需要同步改造事件透传、插槽结构和特殊页适配
+- 对本次“只改按钮位置”的需求来说路径偏长
+
+### 6.3 方案三：统一骨架，页内最小改动
+
+做法：
+
+- 不抽公共组件
+- 仅把各页 `搜索 / 重置` 调整到统一操作行
+- 保留每页现有业务按钮定义与语义
+- 中介库管理只收敛 `SearchForm` 的职责，不扩展为组件体系重构
+
+优点：
+
+- 满足最短路径要求
+- 风险最低
+- 能覆盖常规页、征信维护和中介库管理三类结构
+
+缺点：
+
+- 统一规则仍分散在各页面模板中
+
+### 6.4 结论
+
+采用方案三：统一骨架，页内最小改动。
+
+## 7. 总体设计
+
+### 7.1 统一头部骨架
+
+所有信息维护页面统一收敛为以下结构：
+
+1. 查询条件表单
+2. 统一操作行
+3. 表格与分页区域
+
+统一操作行内部顺序固定为：
+
+- 搜索
+- 重置
+- 当前页面原有业务按钮
+- `right-toolbar`
+
+其中：
+
+- `搜索 / 重置` 总是排在最左侧
+- 当前页面原有业务按钮保持原有顺序与文案
+- `right-toolbar` 继续保持在最右侧
+
+### 7.2 查询表单边界
+
+查询表单只保留查询字段本身，不再承担查询按钮展示职责。
+
+这意味着：
+
+- 常规页删除查询表单末尾的按钮型 `el-form-item`
+- 查询条件字段、`@keyup.enter.native="handleQuery"` 等行为保留
+- `resetQuery` 方法语义保持不变，只是触发入口位置改变
+
+### 7.3 业务按钮边界
+
+页面当前已有的业务按钮全部保留，不因为统一布局而更名或改语义。
+
+例如：
+
+- 征信维护继续使用 `批量上传征信HTML`
+- 中介库管理继续使用 `导入中介和亲属信息`、`导入中介实体关联关系`
+- 实体库管理继续保留 `删除`
+- 各页面失败记录按钮继续保留各自原有文案和显隐条件
+
+## 8. 页面分类设计
+
+### 8.1 常规页面
+
+常规页面直接采用相同处理方式：
+
+1. 从查询表单中删掉 `搜索 / 重置`
+2. 在 `el-row.mb8` 左侧新增 `搜索 / 重置`
+3. 原有业务按钮整体顺延
+
+适用于：
+
+- 员工信息维护
+- 招聘信息维护
+- 员工调动记录
+- 员工亲属关系维护
+- 员工实体关系维护
+- 实体库管理
+- 账户库管理
+- 信贷客户家庭关系
+- 信贷客户实体关联
+- 招投标信息维护
+
+### 8.2 征信维护
+
+征信维护页面也按统一骨架处理，但不强行改成“新增 / 导入”语义。
+
+目标结构为：
+
+- `搜索`
+- `重置`
+- `批量上传征信HTML`
+- `right-toolbar`
+
+即仅统一布局，不改按钮名称和后续上传链路。
+
+### 8.3 中介库管理
+
+中介库管理页面需要额外收敛 `SearchForm` 的职责边界。
+
+调整后职责如下：
+
+- `SearchForm` 只负责渲染查询字段
+- 父页面负责渲染 `搜索 / 重置`
+- 父页面继续负责 `新增 / 导入 / 失败记录 / right-toolbar`
+
+事件口径保持不变：
+
+- `搜索` 仍触发父页 `handleQuery`
+- `重置` 仍清空查询条件并触发列表刷新
+
+但 `搜索 / 重置` 的展示位置统一收口到父页操作行中。
+
+## 9. 实现边界
+
+### 9.1 本次允许改动
+
+- 各页面模板中查询按钮的位置
+- 少量样式，用于保证统一操作行换行时可读
+- 中介库管理父子组件的头部展示职责划分
+
+### 9.2 本次禁止改动
+
+- 查询参数字段
+- 列表字段
+- 按钮权限控制
+- 接口调用方式
+- 导入、上传、失败记录、详情弹窗等业务逻辑
+- 页面菜单、路由和 SQL
+
+## 10. 测试与验收设计
+
+### 10.1 页面验收点
+
+所有纳入范围的页面都需要满足：
+
+- 查询表单内不再显示 `搜索 / 重置`
+- `搜索 / 重置` 均位于统一操作行最左侧
+- 业务按钮位于 `搜索 / 重置` 右侧
+- `right-toolbar` 位于操作行最右侧
+
+### 10.2 行为验收点
+
+所有页面都需要保证以下行为不回归：
+
+- 输入查询条件后点击 `搜索` 能正常刷新列表
+- 点击 `重置` 能正常清空条件并刷新列表
+- 查询条件回车搜索能力保留
+- 原有业务按钮点击行为不变
+- 权限控制与失败记录显隐逻辑不变
+
+### 10.3 特殊页面验收点
+
+征信维护：
+
+- `批量上传征信HTML` 仍可正常打开上传弹窗
+
+中介库管理：
+
+- `搜索 / 重置` 虽然移出 `SearchForm`，但查询与重置行为保持一致
+- 两类导入按钮和两类失败记录按钮行为不变
+
+### 10.4 浏览器实测口径
+
+实现完成后至少需要使用真实浏览器验证三类代表页面：
+
+- 常规页：员工信息维护
+- 特殊业务按钮页：征信维护
+- 组件拆分页：中介库管理
+
+实测重点：
+
+- 页面加载后头部布局是否符合统一规则
+- `搜索`、`重置` 是否可用
+- 业务按钮点击是否仍按原链路工作
+
+## 11. 风险与控制
+
+### 11.1 风险
+
+- 页面较多，逐页调整时可能遗漏个别信息维护页面
+- 直接移动按钮后，某些页面在窄屏下可能出现换行拥挤
+- 中介库管理如果只移动视觉位置但没处理好重置逻辑，可能出现父子状态不同步
+
+### 11.2 控制措施
+
+- 以“信息维护菜单全部页面”为清单逐页核对，不按模糊搜索结果做不完整改动
+- 样式只做最小补充，优先保证按钮换行后仍可点、可读
+- 中介库管理调整后单独验证重置行为，确保查询参数与列表刷新保持一致
+
+## 12. 预期交付
+
+- 设计文档 1 份
+- 后续前端实施计划 1 份
+- 后续实施完成记录 1 份
+
+本次设计只涉及前端页面布局调整，不涉及后端改造，因此不拆分后端实施计划。