From 5c4682bbbdb8252566213dd0b1afb71a0d1d78d5 Mon Sep 17 00:00:00 2001
From: SugarChes <T884096904@126.com>
Date: Fri, 31 Jul 2026 10:13:14 +0800
Subject: [PATCH] docs: design extended return search filters

---
 ...nded-return-search-column-filter-design.md | 130 ++++++++++++++++++
 1 file changed, 130 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-31-extended-return-search-column-filter-design.md

diff --git a/docs/superpowers/specs/2026-07-31-extended-return-search-column-filter-design.md b/docs/superpowers/specs/2026-07-31-extended-return-search-column-filter-design.md
new file mode 100644
index 0000000..074f416
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-31-extended-return-search-column-filter-design.md
@@ -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 界面对上述十个场景进行人工验证。