certflow.widgets.quick_search_preset module

FilterBar 的「快查框 + preset 下拉」宿主侧公共逻辑（可复用控件）。

query_view 与 report_view 都需要「切换 preset → 刷新快查候选 → 选中/输入按 字段逐段回填筛选行」这一套逻辑，原先各自内联实现，容易在「空字段段数对齐」上踩坑 （如 project_name 为空时，后续 plan_no 被错位填入 project_name 位，导致查不到结果）。

这里抽成 QuickSearchPresetMixin，约定宿主提供：

  • self.filter_bar：已开启 show_quick_search / show_preset_selector 的 FilterBar

  • self._qs_service：含 get_distinct_field_combos(fields) 的查询服务（候选默认来源）

  • on_quick_search()：取 self.filter_bar.get_conditions() 并触发查询的宿主方法

可选重写的取数钩子（数据源无关）：

  • qsp_get_quick_search_items(fields)：快查候选数据源，默认走 _qs_service； 宿主若用其它取数（如本视图默认范围、controller.get_distinct_combos）应重写。

  • qsp_get_field_label(field)：字段中文标签（占位提示），默认走 _qs_columns。

修复点（对齐 BLUEPRINT §1.7）： - 严格按 preset 字段数解析，空段保留不丢弃，避免中间空字段被吞导致后续字段错位填入； - 动态搜索模式切换（状态管理）：QuickSearch 区分「用户输入（typing / 模糊）」与

「选中条目（activated / 精确）」两类交互——

  • 模糊模式：用户在输入框键入时，下拉由 completer 做模糊匹配，宿主再做【防抖】的初步数据 筛选（在主字段上做 contains 匹配），给出较宽的结果集；

  • 精确模式：用户点击/回车选中某个具体候选条目时，自动切换为精确模式，按字段逐段回填 （保留空段），对全部字段做精确匹配，确保最终结果准确。

当前模式存于 self._qs_mode``（``QUICK_SEARCH_MODE_FUZZY / QUICK_SEARCH_MODE_EXACT）， 可通过 get_quick_search_mode() 读取；每次切换会回调 qsp_on_mode_changed(mode) （宿主可重写以反映 UI 状态，如状态标签），默认空实现。

certflow.widgets.quick_search_preset.build_quick_search_plan(text, fields)[源代码]

根据快查输入文本与 preset 字段，返回查询方案（纯函数，便于单测）。

用于「模糊输入」场景（用户输入、未选中具体候选条目）：

  • 若 text 含分隔符（半角 | / 半角 , / 全角 ，）：按字段数严格切分为 多段，返回 AND 回填方案（mode="and"）。空段保留，段数与字段数一致， 避免中间空字段被吞导致后续字段错位。 - complete 标记：分隔符个数是否已达 字段数 - 1。不足说明用户仍在逐段

    填写中，宿主应**暂缓**发起 AND 查询（等用户填完或回车），避免半截输入 触发错误/空结果（即「防抖真正生效」）。

  • 否则：返回 OR 方案（mode="or", complete=True），在 preset **全部**字段上 做 contains 匹配，任一字段命中即返回（避免「只匹配首字段 → 0 条」）。

参数:

  • text (str) -- 用户输入的快查文本

  • fields (list[dict]) -- preset 字段列表（每个含 field / operator 等键）

返回:

{"mode": "and"|"or", "complete": bool, "rows": [(field, operator, value), ...], "or_filters": [{field, operator, value}, ...]}

返回类型:

dict

certflow.widgets.quick_search_preset.split_quick_search_text(text, n)[源代码]

把快查文本拆成【恰好 n 段】，严格按字段数对齐、空段保留不丢弃。

分隔符兼容：半角 | / 空格环绕的 `` | `` / 全角 ｜ 都归一化为半角无空格 | 再切分，避免中文输入法的全角竖线导致只切出部分段（如 ``天津荣程1100｜ `` 被整段当成 project_name），进而后续字段错位、查询结果为空。

手动模糊输入（无竖线）按逗号切分回退。最终按 n 对齐：段数不足补空、多余截断， 杜绝中间空字段被吞导致后续字段错位填入。

参数:
返回类型:

list[str]

class certflow.widgets.quick_search_preset.QuickSearchPresetMixin[源代码]

基类：object

封装 FilterBar 快查 + preset 的宿主胶水逻辑，供各视图复用。

通过 setup_quick_search_preset(presets, columns) 初始化；FilterBar 构造时把 quick_search_callback / preset_changed_callback 指向本 Mixin 的 qsp_on_quick_search / qsp_on_preset_changed 即可。

setup_quick_search_preset(presets, columns=None)[源代码]

初始化 preset / 快查逻辑；默认选中首个 preset 并刷新候选。

参数:

  • presets (list[dict]) -- 与 ui.yaml query_page.presets 同构的预设列表

  • columns (list[dict] | None) -- 字段中文标签表（{label, field}），用于占位提示

返回类型:

None

get_quick_search_mode()[源代码]

返回当前快查模式：QUICK_SEARCH_MODE_FUZZY / QUICK_SEARCH_MODE_EXACT。

返回类型:

str

qsp_on_mode_changed(mode)[源代码]

模式切换钩子（默认空实现），宿主可重写以反映 UI 状态（如状态标签）。

参数:

mode (str)

返回类型:

None

qsp_on_preset_changed(name)[源代码]

preset 下拉切换：更新快查框提示并重算候选项。

参数:

name (str)

返回类型:

None

qsp_get_quick_search_items(fields)[源代码]

快查候选数据源钩子。

默认实现走 self._qs_service.get_distinct_field_combos(fields)``（report_view 使用）。 宿主若用其它取数方式（如 query_view 用 ``controller.get_distinct_combos 并基于 视图默认范围取稳定候选）应重写本方法，返回 list[str] 候选。

参数:

fields (list[str])

返回类型:

list[str]

qsp_get_field_label(field)[源代码]

字段中文标签钩子（用于快查框占位提示），默认走 _qs_columns。

参数:

field (str)

返回类型:

str

qsp_on_typing(text)[源代码]

模糊模式：用户在输入框键入。

下拉已由 completer 做模糊匹配；此处切换到模糊模式，并【防抖】地对主字段做 contains 初步筛选，给出较宽的结果集。选中条目时会取消本防抖并切换精确模式。

参数:

text (str)

返回类型:

None

确认（选中候选/回车）：按 active preset 字段发起查询。

  • 含分隔符（| / , / 全角 ，）：按字段数严格切分，逐段精确回填并 AND 组合；

  • 无分隔符的单关键字：在 preset **全部**字段上做 contains OR 匹配， 任一字段命中即返回（避免「只匹配首字段 → 漏结果」），与查询页行为一致。

参数:

text (str)

返回类型:

None