docs: design extended return search filters
This commit is contained in:
@@ -0,0 +1,130 @@
|
||||
# 173/174 扩展返回搜索列与本地筛选设计
|
||||
|
||||
## 背景
|
||||
|
||||
173“模块选择返回 Id-扩展”和 174“搜索返回 Id-扩展”目前共用 `ExtendedReturnSearchPopup`。弹窗只提供一个搜索输入框，数据库查询会对数据源返回的全部列拼接 `OR LIKE`。结果表格已使用 DevExpress `GridView`，但没有显示自动筛选行。
|
||||
|
||||
本次改动在不改变现有数据源解析、ResultFields 回填、显示值翻译和键盘选择行为的前提下，增加数据库搜索列选择及结果集本地二次筛选。
|
||||
|
||||
## 目标
|
||||
|
||||
- 弹窗顶部增加搜索列下拉框。
|
||||
- 支持“所有列”数据库搜索和指定单列数据库搜索。
|
||||
- 下拉项显示与结果表头一致的中文标题，内部使用真实数据源字段名。
|
||||
- `_` 开头的隐藏技术列不进入下拉，也不参与“所有列”搜索。
|
||||
- 下方 DevExpress 表格显示自动筛选行，对数据库已返回的数据进行本地二次筛选。
|
||||
- 173、174 在表格控件和 MyControl 中保持一致行为。
|
||||
- 保留原有清空、选择、回填、显示和键盘操作。
|
||||
|
||||
## 非目标
|
||||
|
||||
- 不修改 173 的模块数据源解析规则。
|
||||
- 不修改 174 的 SourceSql 配置规则。
|
||||
- 不修改 ResultFields、ValueMember、TextMember 的含义或校验。
|
||||
- 不把 DevExpress 自动筛选条件发送到数据库。
|
||||
- 不在控件初始化阶段加载完整业务数据。
|
||||
- 不跨应用重启持久化搜索列选择。
|
||||
|
||||
## 交互设计
|
||||
|
||||
弹窗顶部从左到右排列：
|
||||
|
||||
1. 搜索列下拉框。
|
||||
2. 搜索文本输入框。
|
||||
3. “查询”按钮。
|
||||
4. “清空”按钮。
|
||||
|
||||
下拉框规则：
|
||||
|
||||
- 第一项固定为“所有列”。
|
||||
- 后续项来自实际数据源结构，只包含名称不以 `_` 开头的列。
|
||||
- 显示文本复用结果表格现有列标题翻译逻辑；选项内部保存真实字段名。
|
||||
- 每个 173/174 控件实例在内存中保留最后一次选择，关闭并重新打开弹窗时不重置。
|
||||
- 数据源结构变化且原选择字段已不存在时，自动回退到“所有列”。
|
||||
|
||||
输入框仍按现有方式仅在回车或点击“查询”时访问数据库。上下键进入结果表、结果表回车选择、鼠标点击选择和“清空”按钮行为保持不变。
|
||||
|
||||
## 数据结构加载
|
||||
|
||||
弹窗打开时只异步执行现有 `top 0` 结构查询，用于取得列名，不加载完整业务数据。
|
||||
|
||||
- 已有缓存结构时立即构建下拉项，不重复访问数据库。
|
||||
- 首次打开且尚无缓存时，下拉先保留“所有列”，结构查询完成后补充列项。
|
||||
- 如果当前业务值非空，现有首次搜索请求同时取得并缓存结构，无需额外加载完整数据。
|
||||
- 弹窗关闭、控件销毁或请求版本已过期时丢弃后台返回结果，不更新已经失效的界面。
|
||||
|
||||
## 数据库搜索
|
||||
|
||||
`ExtendedReturnSupport.BuildSearchSql` 增加可选搜索字段参数：
|
||||
|
||||
- “所有列”：只对所有可见业务列生成 `OR LIKE` 条件。
|
||||
- 指定列：校验字段存在且不是隐藏列，只为该列生成 `LIKE` 条件。
|
||||
- 返回结果仍保留数据源的全部列，包括隐藏技术列，以免破坏 ResultFields 回填。
|
||||
- 继续使用现有 `@lookupKeyword` 参数、LIKE 转义和字段名引用，不把输入文本或下拉显示标题直接拼入 SQL。
|
||||
- 最大返回行数继续保持 100。
|
||||
|
||||
搜索请求必须在提交时同时快照关键字和真实字段名，避免后台查询期间用户切换下拉导致请求含义变化。
|
||||
|
||||
## 本地二次筛选
|
||||
|
||||
共享结果 `GridView` 启用 DevExpress `OptionsView.ShowAutoFilterRow`。
|
||||
|
||||
- 自动筛选只作用于当前绑定的最多 100 行结果，不触发数据库查询。
|
||||
- 每次按回车或点击“查询”发起新的数据库搜索前，清除全部本地筛选条件和旧结果。
|
||||
- 关闭并重新打开弹窗时不保留上一次的本地筛选条件。
|
||||
- 自动筛选后的焦点行仍可通过回车或鼠标点击执行原有 ResultFields 回填。
|
||||
|
||||
## 代码边界
|
||||
|
||||
### `ExtendedReturnSearchPopup`
|
||||
|
||||
- 负责下拉框、输入框、按钮和结果表的布局。
|
||||
- 暴露当前真实搜索字段，不包含 SQL 或业务映射逻辑。
|
||||
- 接收调用方生成的“真实字段名 + 中文标题”选项。
|
||||
- 负责保留有效选择、无效选择回退、清空本地筛选及启用自动筛选行。
|
||||
|
||||
### `ExtendedReturnSupport`
|
||||
|
||||
- 统一生成“所有可见列”或“指定可见列”的参数化搜索 SQL。
|
||||
- 统一判定 `_` 开头的隐藏技术列，避免表格和 MyControl 产生不同规则。
|
||||
- 对不存在、隐藏或空白的指定字段给出明确配置错误。
|
||||
|
||||
### `LabelExtendedReturnSearchEdit`
|
||||
|
||||
- 为 MyControl 173/174 异步加载和缓存数据源结构。
|
||||
- 使用现有业务控件标签生成中文列标题。
|
||||
- 把下拉选择快照带入后台搜索请求。
|
||||
|
||||
### `GridControlEx.ExtendedReturn`
|
||||
|
||||
- 为表格 173/174 异步加载和缓存每个字段的数据源结构。
|
||||
- 使用现有表格列标题翻译逻辑生成中文列标题。
|
||||
- 把下拉选择快照带入现有每列串行查询状态机。
|
||||
|
||||
## 兼容性与错误处理
|
||||
|
||||
- 默认选择“所有列”时，用户操作方式与现有版本一致，但隐藏技术列不再参与模糊搜索。
|
||||
- 173 继续通过模块编号解析 SQL，174 继续直接使用配置 SQL。
|
||||
- 结构查询或业务查询失败时沿用现有提示机制，不能覆盖当前业务值或 ResultFields 字段。
|
||||
- 后台返回旧版本结果时继续丢弃，不覆盖更新的搜索结果。
|
||||
- 清空按钮仍清空当前业务行全部 ResultFields 映射字段并关闭弹窗。
|
||||
- 原业务列仍为只读弹出编辑器，弹窗搜索文本不参与业务字段显示或保存。
|
||||
|
||||
## 验收场景
|
||||
|
||||
1. 首次打开空值控件，只执行结构查询，下拉最终显示“所有列”和所有可见中文列名。
|
||||
2. 选择“所有列”搜索时，SQL 条件只包含非 `_` 开头的列。
|
||||
3. 选择单列搜索时，SQL 条件只包含该真实字段。
|
||||
4. 关闭后重开同一控件，保留上次有效搜索列；数据源缺少该列时回退到“所有列”。
|
||||
5. 新数据库搜索会清除旧自动筛选条件。
|
||||
6. 自动筛选行改变可见结果但不产生数据库请求。
|
||||
7. 筛选后鼠标点击、上下键和回车仍能选择正确 DataRow 并完成 ResultFields 回填。
|
||||
8. `_` 开头的列不显示、不进入下拉、不参与“所有列”搜索，但仍可作为 ResultFields 映射来源。
|
||||
9. 表格和 MyControl 的 173、174 四种组合行为一致。
|
||||
10. 原有清空、显示值翻译、实际值保存和模块数据源加载保持正常。
|
||||
|
||||
## 验证范围
|
||||
|
||||
- 对 SQL 构建规则、隐藏列排除、指定列校验和选择回退进行结构化检查。
|
||||
- 编译 `Lskj.Model`、`Lskj.Util`、`Lskj.Business`、`Lskj.Control`。
|
||||
- 运行时验收由实际 ERP 界面对上述十个场景进行人工验证。
|
||||
Reference in New Issue
Block a user