@das-fed/upf-ui 6.4.0-dev.311 → 6.4.0-dev.313

package/packages/components/search-form/skills/DasSearchForm/345/215/207/347/272/247/346/214/207/345/215/227.md

@@ -0,0 +1,139 @@
+# DasSearchForm 升级指南
+
+本文随 `@das-fed/upf-ui` 发布，供 AI 根据业务页面路径和页面目标完成 DasSearchForm 迁移。业务方不需要重复描述组件内部实现；AI 必须检查运行项目实际安装的包及页面请求链路。
+
+## 业务最短提问
+
+```text
+请按当前项目实际安装的 @das-fed/upf-ui search-form skills，升级
+<相对项目根目录的页面路径> 中的 DasSearchForm。保留页面现有业务筛选和请求行为，
+按页面设计决定是否使用园区/楼栋筛选；空间参数由组件/公共请求层处理，业务 handler 和 payload
+不处理 park/building。检查首次查询、日期、重置、分页时序，完成必要修改和验证，
+并报告改动及未验证项。
+```
+
+示例：
+
+```text
+请按当前项目实际安装的 @das-fed/upf-ui search-form skills，升级
+src/views/myMeeting/pages/home/hooks/use-search/Search.vue 中的 DasSearchForm。保留页面现有
+业务筛选和请求行为，按页面设计决定是否使用园区/楼栋筛选；空间参数由组件/公共请求层处理，
+业务 handler 和 payload 不处理 park/building。检查首次查询、日期、重置、分页时序，完成必要修改
+和验证，并报告改动及未验证项。
+```
+
+若截图/需求已明确空间控件行为，可只追加一句，例如“页面仅展示单选园区，不展示楼栋”。如果页面现状和设计均无法判断是否需要空间过滤，AI 只追问这个关键问题，不擅自开启空间筛选。
+
+## AI 执行约定
+
+1. 从启动项目 `package.json` 所在目录定位 `node_modules/@das-fed/upf-ui/packages/components/search-form/skills/`，先读取本指南、`das-search-form-toolbar-migration/SKILL.md` 和 `迁移要点与常见问题.md`。不要默认从 monorepo 根或另一个 checkout 读取依赖资料。
+2. 核对该项目 manifest 声明版本、锁文件解析版本和实际安装包目录/文件。只有运行项目实际解析到的包可证明其使用版本；三者不一致时明确报告，不得只凭截图或 lockfile 推断运行时能力。
+3. 若已安装包缺少所需 API/行为，说明版本阻塞并停止使用该 API；不得臆造 prop、复制其它 checkout 的源码到业务目录或静默升级依赖。未经明确要求，不修改 UPF 版本、锁文件或发布配置。
+4. 阅读目标 Search.vue、父级搜索状态、表格/分页查询、API 模块和页面设计，盘点普通字段、默认值、权限条件、日期/周期转换、异步回调、初始请求及所有列表查询入口。根据页面需求判定空间控件是否应启用。
+5. 尽量仅修改当前页面查询链路，保留原业务筛选语义。按影响执行定向类型检查/测试/构建。要求 Chrome 时，用外部 Chrome 检查目标页面和 Network；不能运行时明确说明，不得以单测代替浏览器验证。
+
+## 新旧布局
+
+`layoutMode` 支持 `legacy` 和 `toolbar`，默认 `legacy`；不设置时旧页面保持旧模式。只有页面明确采用新版工具栏时才设置 `layout-mode="toolbar"`。
+
+```vue
+<das-search-form layout-mode="toolbar" :options="options" @confirm="searchData" />
+```
+
+Toolbar 普通字段变化本身不自动查询。按钮查询、实例 `confirm()`、重置后的内部确认及空间初始化/选择联动会触发 `confirm`。迁移时要检查旧字段回调、父级首次查询和表格挂载顺序，避免重复或漏查。
+
+## 公共参数合同
+
+- `@confirm` 第一个参数 `formValues` 是普通筛选快照，不含空间条件。第二个参数 `selectedSpace` 是可选 UI 状态 `{ parkIds, buildingIds }`，用于受控展示等场景；通常业务无需消费它。
+- `park`、`building` 是后端从 URL query 读取的通用空间条件，不是业务 DTO 字段。业务 Search.vue、搜索状态、handler、分页状态、请求 payload 不定义、映射或兼容 `park`、`building`、`parkIds`、`buildingIds`。
+- 当前页面空间控件可见且初始化完成时，search-form 提供该页面的最新空间值；公共 `createService` 在发出 GET/POST 前把它们加入 query，数组用逗号序列化，并从 JSON body 删除同名键。
+- 业务照常使用现有 `createService`。不在业务层拼 URL/query，不把空间值复制到 body。显式 query 中同名参数优先于自动公共空间值，但业务不应依此实现空间处理。
+- 不配置空间控件时组件不请求园区数据、不主动注入空间条件，也不从其它页面/Tab 继承旧值。当前 createService 仍会把历史业务 JSON body 中已有的 `park/building` 移到 query；迁移后的业务因此必须删除这些字段，才能满足“空间条件不参与”的契约。不要为不需要园区过滤的页面强制启用空间筛选。
+- 控件隐藏时对应空间键不注入；控件可见但未选择时保留空值语义（数组序列化为空字符串），与键缺失不同。
+- `spaceValue` 内部 UI 状态可使用 `parkIds/buildingIds`，这不代表业务接口可以使用这些字段。
+
+正确的业务 handler 只映射业务字段：
+
+```ts
+function searchData(values: Record<string, any>) {
+  requestList({ params: { pageIndex: pageIndex.value, pageSize: pageSize.value }, data: mapBusinessFields(values) })
+}
+```
+
+`requestList` 应沿用页面既有 `createService` API。不要读取第二个参数并将空间字段合入 `data` 或 `params`。
+
+## Props 与空间配置
+
+| Prop          | 行为                                                                                   |
+| ------------- | -------------------------------------------------------------------------------------- |
+| `layoutMode`  | `legacy` / `toolbar`，默认 `legacy`。                                                  |
+| `options`     | 普通筛选项，允许 `null`；空数组时普通筛选区及查询/重置按钮隐藏，空间控件仍可单独显示。 |
+| `spaceConfig` | 默认 `{}`；只有实际需要空间条件时设置 `visible: true`。                                |
+| `spaceValue`  | 可选受控 UI 值 `{ parkIds: [], buildingIds: [] }`，不是业务请求参数。                  |
+| `searchOrder` | `last` 默认将搜索输入类字段置后；`original` 保留原顺序。                               |
+
+`spaceConfig`：
+
+| 字段               | 默认/说明                                                                                                |
+| ------------------ | -------------------------------------------------------------------------------------------------------- |
+| `visible`          | 默认 false。空间控件及数据加载总开关。                                                                   |
+| `showPark`         | 默认显示；关闭时不显示园区控件、不注入 `park`。                                                          |
+| `showBuilding`     | 默认显示；关闭时不显示楼栋/空间控件、不注入 `building`。                                                 |
+| `defaultPark`      | 默认 true；只决定是否自动选第一园区，不取消初始化和首次确认。false 时可见 `park` 是空值。                |
+| `parkMultiple`     | 默认 true；false 为单选园区。                                                                            |
+| `buildingMultiple` | 默认 false；控制楼栋/空间单选或多选。                                                                    |
+| `size`             | `small`、`middle`、`large`，默认 `small`。                                                               |
+| `load`             | 自定义 `(signal) => Promise<{ parks, buildings }>`，完全替代默认空间数据加载，须返回完整数据并处理取消。 |
+
+```vue
+<!-- 仅按园区过滤，不展示楼栋 -->
+<das-search-form
+  layout-mode="toolbar"
+  :options="options"
+  :space-config="{ visible: true, showPark: true, showBuilding: false, parkMultiple: false }"
+  @confirm="searchData"
+/>
+
+<!-- 按园区和楼栋/空间过滤 -->
+<das-search-form
+  layout-mode="toolbar"
+  :options="options"
+  :space-config="{ visible: true, showPark: true, showBuilding: true, defaultPark: true }"
+  @confirm="searchData"
+/>
+
+<!-- 不需要空间过滤 -->
+<das-search-form layout-mode="toolbar" :options="options" @confirm="searchData" />
+```
+
+若 `showPark=false, showBuilding=true`，默认数据源没有园区上下文，须由自定义 `load` 提供完整楼栋树。
+
+## 查询时序与事件
+
+- 启用空间后，首次业务确认等待园区列表/自定义数据加载；启用默认园区时先确定选择。显示楼栋时等待楼栋初始化流程结束后再确认；楼栋加载错误通过 `spaceError` 报告，当前实现可能以空楼栋值继续首次确认，需结合目标已安装版本和业务要求验证。
+- `defaultPark: false` 仍完成空间初始化并首次确认一次；它只关闭首项默认选择。
+- 园区变化由组件清空旧楼栋和普通筛选，加载新空间后确认一次；楼栋实际值变化后确认一次。重复写回相同值不应重复查询。
+- `spaceChange` 只用于 `{ parkIds, buildingIds }` UI 状态同步/界面联动，不能在此请求业务列表或手动调用 `confirm`。
+- `spaceError` 是空间加载错误诊断。不能把空间初始化失败当作成功的空值状态而盲发首次业务查询。楼栋加载错误的具体确认行为需以实际安装版本为准。
+- `resetSearch()` 重置普通字段，触发 `reset` 并内部确认一次，默认保留空间值。reset handler 和表格 watcher 不应再各发一遍。
+- 表格可能晚于 Search.vue 异步挂载，应能立即消费已经提交的搜索状态/ready 状态；不要额外保留无条件 `onMounted` 列表查询。
+- 日期/周期字段回调若自己触发业务请求，要与 toolbar confirm 协调，保证每次用户动作只有预期的一条列表查询路径。
+- 公共空间 query 对当前可见页面生效。缓存 Tab 隐藏/返回时要验证来源切换，不得把另一页面的空间值带入请求。
+
+## 暴露方法
+
+| 方法                           | 用途                                             |
+| ------------------------------ | ------------------------------------------------ |
+| `confirm()`                    | 提交普通筛选快照，等待异步字段和空间初始化门禁。 |
+| `resetSearch()`                | 重置普通筛选并确认，保留空间值。                 |
+| `closeSearch(target)`          | 清理指定普通筛选字段并触发 `clearSearch`。       |
+| `treeSelectResetLazyLoad(key)` | 重置普通树筛选项的懒加载。                       |
+| `getCollapseStatus()`          | 读取工具栏展开状态。                             |
+
+## 页面验收
+
+- 确认是否启用 toolbar 与空间筛选，并以页面 UI/业务需求为依据。
+- 检查首次进入、筛选、日期/周期、重置、分页、Tab 首次进入及缓存返回的请求次数和 initiator。
+- 若启用空间，确认园区/楼栋变化各只触发预期请求，query 稳定使用最新可见值。
+- Network 中空间值只在 query；JSON body 只有业务字段。隐藏空间控件或无空间配置，且业务 body 已移除历史空间字段时，不应出现空间键。
+- 报告运行的检查、Chrome 是否完成及未验证项。

package/packages/components/search-form/skills/das-search-form-toolbar-migration/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: das-search-form-toolbar-migration
+description: 将业务页面的 DasSearchForm 迁移到 toolbar 布局，并接入可选的园区/楼栋通用筛选，保证空间初始化、confirm 时序、query 参数和业务查询行为正确。适用于按页面逐项升级，不用于无关组件重构。
+---
+
+# DasSearchForm Toolbar 迁移 Skill
+
+## 业务最短提问
+
+业务通常只需提供目标页面路径及空间控件期望，AI 应自行检查当前启动项目安装的版本、随包指南、页面链路和请求实现：
+
+```text
+按当前项目实际安装的 @das-fed/upf-ui search-form skills，升级 <页面路径> 中的 DasSearchForm。
+保留页面现有业务筛选和请求行为，按页面设计决定是否使用园区/楼栋筛选；空间参数由组件/公共请求层处理，
+业务 handler 和 payload 不处理 park/building。检查首次查询、日期、重置、分页时序，完成必要修改和验证，
+并报告改动及未验证项。
+```
+
+业务只需补充截图/明确行为（例如“只展示单选园区，不展示楼栋”）。若空间过滤需求无法从页面/设计确定，先追问，不得猜测。
+
+## 版本和资料核对
+
+1. 从启动项目的 `package.json` 所在目录读取 `node_modules/@das-fed/upf-ui/packages/components/search-form/skills/` 下的主指南、本 Skill 和常见问题。不要误读 monorepo 根或另一个 checkout 的包。
+2. 分别核对 `package.json` 声明、lockfile 解析和实际安装目录/文件。仅实际运行项目解析到的安装包能证明其能力；版本不一致时明确说明，不凭 lockfile 或截图推断。
+3. 已安装版本不含所需 API 时，报告版本阻塞并停止该 API 迁移；不得臆造 prop、从其它源码副本拷贝实现或擅自升级依赖。未经要求不改版本和 lockfile。
+4. 文档与目标已安装包的公开类型/导出/实现不符时，以安装包为准并报告冲突。
+
+## 先理解公共契约
+
+本 Skill 的核心不是把 `legacy` 改成 `toolbar`，而是把空间筛选从业务请求参数中抽离：
+
+- 业务 JSON payload 不定义 `park`、`building`；需要空间过滤时才配置空间控件。
+- Toolbar 内部空间 UI 状态为 `parkIds`、`buildingIds`；`confirm` 第一参数只包含普通筛选快照，第二参数（如有）是 UI 空间状态，不是业务请求 DTO。
+- `createService` 从当前可见 search-form 来源获取空间值，在发送前放进 query，并从 JSON body 删除；后端统一从 query 读取。
+- `spaceChange` 只通知空间状态变化；业务列表请求只从 `@confirm` 触发。
+- 空间初始化、园区切换和楼栋变化都必须保证 query 使用稳定的最新空间值，不能通过业务页面 watcher 另行补请求。
+
+源码和测试优先于本文档：
+
+- 组件入口：`packages/das-ui/packages/components/search-form/src/Index.vue`
+- toolbar 实现：`.../src/Toolbar.vue`
+- 空间类型：`.../src/toolbar-types.ts`
+- 空间值映射：`.../src/hooks/toolbar-state.ts`
+- 默认空间 API：`.../src/api/park-space.ts`
+- 主指南：`../DasSearchForm升级指南.md`
+
+## 迁移步骤
+
+1. 读取目标页面和真实 API，盘点普通字段、异步字段回调、分页、日期/重复规则、弹窗提交和所有列表请求路径。
+2. 确认页面是否需要空间筛选。无空间筛选时不要配置 `spaceConfig.visible`，也不要为通用接口强行补 `park/building`。
+3. 若需要空间筛选，逐项确认 `visible`、`showPark`、`showBuilding`、`defaultPark`、`parkMultiple`、`buildingMultiple` 和是否自定义 `load`。
+4. 仅在页面实际采用新版布局时设置 `layout-mode="toolbar"`；保留原 `options`、字段 key/value、业务 handler 和页面辅助状态。
+5. `@confirm` 只处理普通字段；不要在业务层处理空间字段，也不要在 `spaceChange`、字段 `change` 回调或 `@reset` 中重复请求。
+6. 使用 `createService` 发送请求；不在业务 API 手动拼 `park/building` query，不在业务 DTO 保留 `park/building/parkIds/buildingIds`。
+7. 盘点父级首次查询、日期回调、表格挂载、reset 和分页；验证首次进入、默认值、园区/楼栋、重置和 Tab 返回的请求次数与参数。
+
+## 空间配置决策
+
+| 配置               | 默认           | 关键含义                                         |
+| ------------------ | -------------- | ------------------------------------------------ |
+| `visible`          | `false`        | 总开关；关闭时不加载默认园区数据。               |
+| `showPark`         | 跟随 `visible` | 显示园区并决定是否输出 `park`。                  |
+| `showBuilding`     | 跟随 `visible` | 显示空间树并决定是否输出 `building`。            |
+| `defaultPark`      | `true`         | 是否自动选中首园区；关闭不等于跳过首次查询。     |
+| `parkMultiple`     | `true`         | 园区多选模式。                                   |
+| `buildingMultiple` | `false`        | 楼栋/空间多选模式。                              |
+| `size`             | `small`        | 空间控件尺寸。                                   |
+| `load`             | 默认数据源     | 返回 `{ parks, buildings }` 的自定义数据适配器。 |
+
+重要边界：
+
+- 仅园区控件且 `defaultPark=true`：首项加载后查询一次并带 `park`。
+- 仅园区控件且 `defaultPark=false`：仍加载园区并完成首次查询，但首次不带有效 `park`。
+- 园区+楼栋控件：首次查询必须等待园区和楼栋数据初始化完成。
+- `showPark=false, showBuilding=true`：默认数据源没有园区上下文；需要自定义 `load` 提供完整树。
+- 无空间控件：不初始化空间数据，不改变普通业务首次请求。
+
+## 事件与方法
+
+- `@confirm="searchData"`：toolbar 业务查询入口；第一参数是普通筛选快照，第二参数（若有）是 UI 空间快照，不是 API DTO。
+- `@reset="resetAuxiliary"`：清理业务页面在组件外维护的辅助状态；组件随后自动确认一次。
+- `@space-change="handleSpaceChange"`：接收 `{ parkIds, buildingIds }` 状态快照，只做同步或 UI 联动，不发列表请求。
+- `@space-error="handleSpaceError"`：空间加载错误诊断入口。园区列表初始化失败会阻止首次确认；楼栋树加载错误当前会报告错误并可能继续用空 building 确认，须按已安装版本验证。
+- `v-model:space-value`：需要受控空间状态时使用，值结构为 `{ parkIds, buildingIds }`。
+- `confirm()`：等待字段异步回调和空间门禁后提交查询。
+- `resetSearch()`：恢复普通字段、触发 reset 并确认，默认保留空间值。
+- `closeSearch(target)`：清理普通字段，不清理空间值。
+- `treeSelectResetLazyLoad(key)`：重置普通树字段的懒加载。
+- `getCollapseStatus()`：读取 toolbar 折叠状态。
+
+## 推荐接入
+
+```vue
+<das-search-form
+  ref="searchFormRef"
+  layout-mode="toolbar"
+  :options="options"
+  :space-config="{
+    visible: true,
+    showPark: true,
+    showBuilding: true,
+    defaultPark: true,
+    parkMultiple: true,
+    buildingMultiple: false,
+  }"
+  @confirm="searchData"
+  @reset="resetAuxiliary"
+  @space-change="handleSpaceChange"
+/>
+```
+
+业务 handler 只映射普通筛选字段，沿用既有 `createService` API；不要从 `values` 读取空间字段，不要把第二参数并入 payload/query。空间 UI 值由组件和公共请求层处理。
+
+## 验收清单
+
+- 首次空间初始化只提交一次业务查询，且不会在空间初始化完成前发送请求；控件可见但无选择时对应 query 值为空。
+- 园区切换后旧楼栋被清空；新空间数据完成后 query 使用新 `park`。
+- 楼栋选择后 query 同时包含最新 `park` 和 `building`，相同值重复回写不重复请求。
+- `park/building` 在 query，JSON body 不包含它们；未配置空间控件的业务不出现这些字段。
+- reset、字段变化、分页和业务回调不会各自重复请求。
+- `options=null/[]` 时普通过滤区域和按钮隐藏，但空间控件仍可独立工作。
+- 运行定向测试、受影响包类型检查和真实页面 Chrome 验证；未验证项必须在结论中说明。

package/packages/components/search-form/skills/das-search-form-toolbar-migration//350/277/201/347/247/273/350/246/201/347/202/271/344/270/216/345/270/270/350/247/201/351/227/256/351/242/230.md

@@ -0,0 +1,82 @@
+# DasSearchForm Toolbar 迁移要点与常见问题
+
+## 一句话理解
+
+业务只负责普通筛选与业务请求；页面是否配置并展示园区/楼栋控件决定空间过滤是否启用；空间值由 search-form 和公共 `createService` 请求层写入 URL query，业务 `confirm`、handler、payload 不处理空间字段。
+
+## 业务只给页面路径时，AI 应做什么
+
+1. 从启动应用 `package.json` 所在目录读取当前安装包随附的 search-form skills，并核对 manifest、lockfile 及实际安装包版本。
+2. 读取目标 Search.vue、父级搜索状态、列表/分页组件和 API，梳理首次加载、`@confirm`、watch、日期回调、reset、分页和 Tab 缓存请求路径。
+3. 根据页面 UI/需求判定是否要空间过滤。行为不明确时先追问，不擅自添加园区控件。
+4. 保留普通筛选和业务映射，消除旧首次请求与 toolbar 自动确认、日期回调与 confirm 等重复/遗漏请求。
+5. 按影响验证并说明证据；要求 Chrome 时需实际查看页面及 Network，不可用时明确写出。
+
+业务方最短提示词见主指南“业务最短提问”。一般只需提供页面路径和必要的 UI 期望，不必复述公共参数实现规则。
+
+## 空间行为速查
+
+| 页面需求              | 配置与行为                                                                              |
+| --------------------- | --------------------------------------------------------------------------------------- |
+| 不按园区/楼栋过滤     | 不启用空间控件；不加载园区、不创建空间 query。                                          |
+| 只按园区过滤          | `visible: true, showPark: true, showBuilding: false`；园区初始化稳定后才首次确认。      |
+| 按园区和楼栋/空间过滤 | `visible: true, showPark: true, showBuilding: true`；等待园区和所需空间数据就绪后确认。 |
+| 显示楼栋但不显示园区  | 用自定义 `load` 返回完整且有关联信息的楼栋树；默认数据源没有园区上下文。                |
+| 不自动选择首园区      | `defaultPark: false`；仍会初始化和首次确认，可见 park query 是空值语义。                |
+
+控件隐藏时组件不注入对应条件。控件可见但未选择时，当前实现保留空值语义，数组经请求层序列化为空字符串；这不同于字段不存在。无空间控件页面不继承其它页面/Tab 的空间值。注意 createService 还会兼容地把调用方旧 JSON body 里的 park/building 移到 query；无空间过滤的业务需移除 body 中遗留字段，不能只看 UI 是否有控件。
+
+## 正确的业务请求方式
+
+handler 只构造业务字段并沿用项目现有 `createService`：
+
+```ts
+function searchData(values: Record<string, any>) {
+  const data = mapBusinessFields(values)
+  requestList({ params: { pageIndex: pageIndex.value, pageSize: pageSize.value }, data })
+}
+```
+
+不要读取 confirm 的第二个空间 UI 参数，也不要将 park/building 合入 data 或 params。公共请求层会对 GET/POST 注入当前可见页面的空间 query、将数组逗号序列化，并从 JSON body 删除空间字段。
+
+## 常见问题
+
+### `defaultPark=false` 是否不再有首次查询？
+
+不是。它只关闭自动选第一项；空间控件仍会完成初始化，并首次确认一次。可见园区控件未选择时对应 query 为空值。不要为了跳过默认选择而在业务层重新控制首次请求。
+
+### 为什么不能在 `spaceChange` 请求列表？
+
+该事件通知 `{ parkIds, buildingIds }` 的 UI 状态变化。园区切换还要等待空间树加载；在此事件请求会与组件自己的 confirm 竞争，造成空条件、重复请求或闪烁。它只用于受控 UI 同步/界面联动，列表请求走 `@confirm`。
+
+### 园区/楼栋变更后谁负责查询？
+
+组件在园区切换并完成新空间加载后确认一次；楼栋实际值变化后确认一次。同值重复回写不应重复确认。展开未加载节点可能产生空间子节点请求，那不是业务列表请求。楼栋树加载错误会触发 `spaceError`；当前实现可能继续以空 building 确认，目标业务不能接受该行为时应基于实际版本复现并报告，不应默认为园区列表失败的阻断语义。
+
+### 页面显示园区，Network 却没有 park？
+
+依次检查：实际运行的 `@das-fed/upf-ui`/`upf-utils` 版本和导入解析路径；空间控件是否在当前可见页面注册；公共请求是否经过 `createService`；首次请求是否在 ready 之前发出；是否有多份搜索组件/缓存 Tab 导致来源不匹配。不要先在业务 handler 手工加 park，那会掩盖根因并违反参数合同。
+
+### 首次结果错误后又刷新/闪一下？
+
+在 Network 检查是否同时有父级无条件 `onMounted`、表格初次加载、日期回调和 toolbar 首次 confirm。空间首次请求必须等组件初始化完成；异步表格晚挂载时 watcher 应立即消费已存在的 search/ready 状态，不要增加第二条无条件查询。
+
+### 怎么避免日期、重置或分页重复请求？
+
+追踪一次用户动作对应的 Network initiator：日期 change/debounce、confirm handler、父级 watcher、reset handler、分页回调是否各自发请求。迁移后保留单一业务查询链，reset 后由组件确认一次，分页通过同一公共请求层读取当前 query。
+
+## 禁止模式
+
+- 业务 DTO/payload/search state 中出现 `park`、`building`、`parkIds`、`buildingIds`。
+- 在 `spaceChange`、字段 change、watch 或 reset 中补业务列表请求，与组件自动确认竞争。
+- 无视页面需求无条件打开 `spaceConfig.visible`。
+- 依据另一个 checkout 的源码、截图或 lockfile 猜测实际安装包 API。
+- 同时保留旧页面首次请求与 toolbar 自动首次确认。
+
+## 验收清单
+
+- 说明页面是否启用 toolbar/空间控件及依据。
+- 首次进入、搜索、日期、reset、分页、Tab 首次进入/返回的业务请求次数符合预期。
+- 启用空间时园区/楼栋变化只发生预期查询，query 对应当前页面最新值。
+- Network 中空间条件只在 query，JSON body 只含业务字段；无空间配置时无空间 query。
+- 列出已做的 typecheck/test/build/Chrome 验证及未验证项。

package/packages/components/search-form/src/Index.vue.d.ts

@@ -1,56 +1,18 @@
-import type { SearchFormProp } from './hooks/searchFormItem';
-interface DasSearchFormProp {
-    title?: string;
-    options?: SearchFormProp[];
-    labelLength?: string | number;
-    showFilterPanel?: boolean;
-    layout?: 'horizontal' | 'vertical';
-    /**当无过滤面板时，部分设计右侧有间距 */
-    isMarginRight?: boolean;
-    labelPosition?: 'left' | 'top' | 'right';
-    hasBtn?: boolean;
-    isExpandAtFocus?: boolean;
-    isExpandFilter?: boolean;
-}
-declare var __VLS_1: {}, __VLS_18: any, __VLS_19: {}, __VLS_31: any, __VLS_32: {}, __VLS_50: {}, __VLS_92: any, __VLS_93: {}, __VLS_105: any, __VLS_106: {}, __VLS_119: any, __VLS_120: {};
+type __VLS_Props = {
+    layoutMode?: 'legacy' | 'toolbar';
+};
+declare var __VLS_8: string | number, __VLS_9: {};
 type __VLS_Slots = {} & {
-    [K in NonNullable<typeof __VLS_18>]?: (props: typeof __VLS_19) => any;
-} & {
-    [K in NonNullable<typeof __VLS_31>]?: (props: typeof __VLS_32) => any;
-} & {
-    [K in NonNullable<typeof __VLS_92>]?: (props: typeof __VLS_93) => any;
-} & {
-    [K in NonNullable<typeof __VLS_105>]?: (props: typeof __VLS_106) => any;
-} & {
-    [K in NonNullable<typeof __VLS_119>]?: (props: typeof __VLS_120) => any;
-} & {
-    left?: (props: typeof __VLS_1) => any;
-} & {
-    right?: (props: typeof __VLS_50) => any;
+    [K in NonNullable<typeof __VLS_8>]?: (props: typeof __VLS_9) => any;
 };
-declare const __VLS_component: import("vue").DefineComponent<DasSearchFormProp, {
-    /**treeSelect 调用懒加载树刷新 */
-    treeSelectResetLazyLoad: (key: string) => void;
-    closeSearch: (data: SearchFormProp | any[]) => Promise<void>;
-    resetSearch: (isTriggerEvent?: boolean) => Promise<void>;
+declare const __VLS_component: import("vue").DefineComponent<__VLS_Props, {
+    closeSearch: (...args: any[]) => any;
+    resetSearch: (...args: any[]) => any;
+    confirm: (...args: any[]) => any;
+    treeSelectResetLazyLoad: (...args: any[]) => any;
     getCollapseStatus: () => any;
-}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
-    confirm: (e: any) => any;
-    clearSearch: (e: any) => any;
-}, string, import("vue").PublicProps, Readonly<DasSearchFormProp> & Readonly<{
-    onConfirm?: ((e: any) => any) | undefined;
-    onClearSearch?: ((e: any) => any) | undefined;
-}>, {
-    options: SearchFormProp[];
-    title: string;
-    layout: "horizontal" | "vertical";
-    labelLength: string | number;
-    labelPosition: "left" | "top" | "right";
-    isExpandAtFocus: boolean;
-    showFilterPanel: boolean;
-    isMarginRight: boolean;
-    hasBtn: boolean;
-    isExpandFilter: boolean;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    layoutMode: "legacy" | "toolbar";
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
 export default _default;

package/packages/components/search-form/src/Legacy.vue.d.ts

@@ -0,0 +1,61 @@
+import type { SearchFormProp } from './hooks/searchFormItem';
+interface DasSearchFormProp {
+    title?: string;
+    options?: SearchFormProp[];
+    labelLength?: string | number;
+    showFilterPanel?: boolean;
+    layout?: 'horizontal' | 'vertical';
+    /**当无过滤面板时，部分设计右侧有间距 */
+    isMarginRight?: boolean;
+    labelPosition?: 'left' | 'top' | 'right';
+    hasBtn?: boolean;
+    isExpandAtFocus?: boolean;
+    isExpandFilter?: boolean;
+}
+declare var __VLS_1: {}, __VLS_18: any, __VLS_19: {}, __VLS_31: any, __VLS_32: {}, __VLS_50: {}, __VLS_92: any, __VLS_93: {}, __VLS_105: any, __VLS_106: {}, __VLS_119: any, __VLS_120: {};
+type __VLS_Slots = {} & {
+    [K in NonNullable<typeof __VLS_18>]?: (props: typeof __VLS_19) => any;
+} & {
+    [K in NonNullable<typeof __VLS_31>]?: (props: typeof __VLS_32) => any;
+} & {
+    [K in NonNullable<typeof __VLS_92>]?: (props: typeof __VLS_93) => any;
+} & {
+    [K in NonNullable<typeof __VLS_105>]?: (props: typeof __VLS_106) => any;
+} & {
+    [K in NonNullable<typeof __VLS_119>]?: (props: typeof __VLS_120) => any;
+} & {
+    left?: (props: typeof __VLS_1) => any;
+} & {
+    right?: (props: typeof __VLS_50) => any;
+};
+declare const __VLS_component: import("vue").DefineComponent<DasSearchFormProp, {
+    /**treeSelect 调用懒加载树刷新 */
+    treeSelectResetLazyLoad: (key: string) => void;
+    closeSearch: (data: SearchFormProp | any[]) => Promise<void>;
+    resetSearch: (isTriggerEvent?: boolean) => Promise<void>;
+    getCollapseStatus: () => any;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
+    confirm: (e: any) => any;
+    clearSearch: (e: any) => any;
+}, string, import("vue").PublicProps, Readonly<DasSearchFormProp> & Readonly<{
+    onConfirm?: ((e: any) => any) | undefined;
+    onClearSearch?: ((e: any) => any) | undefined;
+}>, {
+    options: SearchFormProp[];
+    title: string;
+    layout: "horizontal" | "vertical";
+    labelLength: string | number;
+    labelPosition: "left" | "top" | "right";
+    isExpandAtFocus: boolean;
+    showFilterPanel: boolean;
+    isMarginRight: boolean;
+    hasBtn: boolean;
+    isExpandFilter: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/packages/components/search-form/src/SearchDateRange.vue.d.ts

@@ -1,12 +1,15 @@
 import type { Props } from './hooks/searchFormItem';
-declare const _default: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
+type __VLS_Props = Props & {
+    size?: 'large' | 'default' | 'middle' | 'small' | 'table';
+};
+declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
     "update:modelValue": (value: any) => any;
     "update:optionValue": (value: string | number) => any;
     selectChange: (value: string | number) => any;
     dateRangeChange: (value: any) => any;
     openDialogHandle: () => any;
     openDialogChange: (value: any) => any;
-}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
     "onUpdate:modelValue"?: ((value: any) => any) | undefined;
     "onUpdate:optionValue"?: ((value: string | number) => any) | undefined;
     onSelectChange?: ((value: string | number) => any) | undefined;

package/packages/components/search-form/src/Toolbar.vue.d.ts

@@ -0,0 +1,57 @@
+import type { SearchFormProp } from './hooks/searchFormItem';
+import type { SpaceConfig, SpaceValue } from './toolbar-types';
+type __VLS_Props = {
+    title?: string;
+    options?: SearchFormProp[] | null;
+    spaceConfig?: SpaceConfig;
+    spaceValue?: SpaceValue;
+    searchOrder?: 'last' | 'original';
+};
+declare function confirm(): Promise<void>;
+declare function resetSearch(): Promise<void>;
+declare function closeSearch(target: SearchFormProp | SearchFormProp[]): void;
+declare var __VLS_1: {}, __VLS_3: {}, __VLS_31: {}, __VLS_33: {}, __VLS_99: string | undefined, __VLS_100: {};
+type __VLS_Slots = {} & {
+    [K in NonNullable<typeof __VLS_99>]?: (props: typeof __VLS_100) => any;
+} & {
+    left?: (props: typeof __VLS_1) => any;
+} & {
+    space?: (props: typeof __VLS_3) => any;
+} & {
+    space?: (props: typeof __VLS_31) => any;
+} & {
+    right?: (props: typeof __VLS_33) => any;
+};
+declare const __VLS_component: import("vue").DefineComponent<__VLS_Props, {
+    confirm: typeof confirm;
+    resetSearch: typeof resetSearch;
+    closeSearch: typeof closeSearch;
+    getCollapseStatus: () => boolean;
+    treeSelectResetLazyLoad: (key: string) => void;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    reset: (...args: any[]) => void;
+    confirm: (...args: any[]) => void;
+    clearSearch: (...args: any[]) => void;
+    "update:spaceValue": (...args: any[]) => void;
+    spaceChange: (...args: any[]) => void;
+    spaceError: (...args: any[]) => void;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onReset?: ((...args: any[]) => any) | undefined;
+    onConfirm?: ((...args: any[]) => any) | undefined;
+    onClearSearch?: ((...args: any[]) => any) | undefined;
+    "onUpdate:spaceValue"?: ((...args: any[]) => any) | undefined;
+    onSpaceChange?: ((...args: any[]) => any) | undefined;
+    onSpaceError?: ((...args: any[]) => any) | undefined;
+}>, {
+    options: SearchFormProp[] | null;
+    title: string;
+    spaceConfig: SpaceConfig;
+    searchOrder: "last" | "original";
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/packages/components/search-form/src/api/park-space.d.ts

@@ -0,0 +1,8 @@
+import type { SpaceId, SpaceNode } from '../toolbar-types';
+export declare function loadParkOptions(signal: AbortSignal): Promise<SpaceNode[]>;
+export declare function loadParkDetail(parkId: SpaceId, signal: AbortSignal): Promise<any>;
+export declare function extractRegions(detail: any): {
+    id: string;
+    name?: string;
+}[];
+export declare function loadSpaceChildren(spaceId: SpaceId | '', signal: AbortSignal): Promise<any[]>;

package/packages/components/search-form/src/hooks/common-query.d.ts

@@ -0,0 +1,7 @@
+import type { Ref } from 'vue';
+export declare function useCommonSpaceQuery(root: Ref<HTMLElement | undefined>, enabled: () => boolean, read: () => Record<string, any> | undefined, onActive: () => void): {
+    isActive: () => boolean;
+    notify(): void;
+    fail(error: unknown): void;
+    dispose(): void;
+};

package/packages/components/search-form/src/hooks/searchFormItem.d.ts

@@ -2,34 +2,36 @@ type DateType = 'date' | 'dateTime' | 'week' | 'month' | 'quarter' | 'year' | 't
 type DateRangeType = 'dateRange' | 'dateTimeRange' | 'weekRange' | 'monthRange' | 'yearRange' | 'timeRange';
 type FormType = 'input' | 'textarea' | 'password' | 'select' | 'treeSelect' | 'radio' | 'checkbox' | 'switch' | 'custom' | DateType | DateRangeType | 'cascader' | 'colorPicker' | 'selectInput' | 'inputDialogSelect' | 'inputNumber';
 export interface SearchFormProp {
-    /**过滤条件key值 */
+    /** 查询结果对象中的字段名；未配置时该项不进入查询值。 */
     key?: string;
-    /** v-model绑定值 */
+    /** 当前控件值，支持普通值或 Vue ref。 */
     value?: any;
-    /** 若type为treeSelect，且需要有默认值，checkedNodes必传，为选中node数组类型 */
+    /** treeSelect 当前选中节点；设置树默认值时同步提供，保证标签和节点状态一致。 */
     checkedNodes?: any[];
-    /** 过滤条件标签文本 */
+    /** 筛选字段显示名称。 */
     label?: any;
-    /** 过滤条件的类型 过滤条件内的普通搜索框使用searchInput类型；带select的搜索框使用selectSearch ；带select搜索框的日期范围使用selectDateRange*；inputSelect选择弹窗*/
+    /** 控件类型；toolbar 模式会把 searchInput/selectSearch 默认排到字段末尾。 */
     type?: FormType | 'searchInput' | 'selectSearch' | 'selectDateRange' | 'inputSelect';
-    /**过滤条件放顶部部还是过滤区内部 */
+    /** legacy 模式中控制字段位于顶部还是过滤面板内部；toolbar 模式不使用此布局字段。 */
     layout?: 'out' | 'inner';
-    /** 在顶部已选择筛选区-是否可删除 */
+    /** legacy 已选条件标签是否允许删除。 */
     closable?: boolean;
-    /** 是否启用自定义录入模式 */
+    /** 是否启用自定义录入与普通选项切换。 */
     custom?: boolean;
-    /**自定义录入模式下：是否处于自定义筛选 */
+    /** 自定义录入模式当前是否处于自定义输入状态。 */
     customerActive?: boolean;
-    /**自定义录入模式下：自定义项前面单选组的配置 */
+    /** 自定义录入模式的选项配置。 */
     customOption?: any;
-    /**当type为selectDateRange，日期type使用dateType字段 */
+    /** type 为 selectDateRange 时，指定实际日期范围类型。 */
     dateType?: string;
-    /**当type为selectDateRange，mode模式分为default,optional;默认default;其余组件mode赋值根据对应组件 */
+    /** 日期范围或底层控件的模式；具体取值由对应控件决定。 */
     mode?: string;
-    /**当前配置项change事件是否需要自动触发confirm查询事件:默认为true --isChangeTrigger为false的使用情景：change需要调用的事件和confirm事件不一样*/
+    /** legacy 模式字段变化后是否自动查询；toolbar 模式始终由查询按钮或实例方法提交。 */
     isChangeTrigger?: boolean;
-    /** 右边距 */
+    /** legacy 字段布局的右侧间距。 */
     marginRight?: string;
+    /** 单字段控件尺寸；toolbar 下未配置时，searchInput/selectDateRange/treeSelect 使用 middle。 */
+    size?: 'small' | 'middle' | 'large' | 'default' | 'table';
     [idx: string]: any;
 }
 export interface Props {