@das-fed/upf-ui 6.4.0-dev.312 → 6.4.0-dev.314

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

@@ -5,13 +5,33 @@ description: 将业务页面的 DasSearchForm 迁移到 toolbar 布局，并接
 
 # 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 内部状态为 `parkIds`、`buildingIds`；`confirm` 对外映射为 `park`、`building`。
-- `createService` 在发送前把这两个字段放进 query，并从 JSON body 删除；后端统一从 query 读取。
+- Toolbar 内部空间 UI 状态为 `parkIds`、`buildingIds`；`confirm` 第一参数只包含普通筛选快照，第二参数（如有）是 UI 空间状态，不是业务请求 DTO。
+- `createService` 从当前可见 search-form 来源获取空间值，在发送前放进 query，并从 JSON body 删除；后端统一从 query 读取。
 - `spaceChange` 只通知空间状态变化；业务列表请求只从 `@confirm` 触发。
 - 空间初始化、园区切换和楼栋变化都必须保证 query 使用稳定的最新空间值，不能通过业务页面 watcher 另行补请求。
 
@@ -29,23 +49,23 @@ description: 将业务页面的 DasSearchForm 迁移到 toolbar 布局，并接
 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，也不保留旧 `parkIds/buildingIds` 兼容字段。
-7. 验证首次进入、默认值开关、园区切换、楼栋选择、重置、分页和快速重复操作的请求次数与参数。
+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 }` 的自定义数据适配器。 |
+| 配置               | 默认           | 关键含义                                         |
+| ------------------ | -------------- | ------------------------------------------------ |
+| `visible`          | `false`        | 总开关；关闭时不加载默认园区数据。               |
+| `showPark`         | 跟随 `visible` | 显示园区并决定是否输出 `park`。                  |
+| `showBuilding`     | 跟随 `visible` | 显示空间树并决定是否输出 `building`。            |
+| `defaultPark`      | `true`         | 是否自动选中首园区；关闭不等于跳过首次查询。     |
+| `parkMultiple`     | `true`         | 园区多选模式。                                   |
+| `buildingMultiple` | `false`        | 楼栋/空间多选模式。                              |
+| `size`             | `small`        | 空间控件尺寸。                                   |
+| `load`             | 默认数据源     | 返回 `{ parks, buildings }` 的自定义数据适配器。 |
 
 重要边界：
 
@@ -57,10 +77,10 @@ description: 将业务页面的 DasSearchForm 迁移到 toolbar 布局，并接
 
 ## 事件与方法
 
-- `@confirm="searchData"`：唯一推荐的业务查询入口，参数为 `(formValues, selectedSpace)`。
+- `@confirm="searchData"`：toolbar 业务查询入口；第一参数是普通筛选快照，第二参数（若有）是 UI 空间快照，不是 API DTO。
 - `@reset="resetAuxiliary"`：清理业务页面在组件外维护的辅助状态；组件随后自动确认一次。
 - `@space-change="handleSpaceChange"`：接收 `{ parkIds, buildingIds }` 状态快照，只做同步或 UI 联动，不发列表请求。
-- `@space-error="handleSpaceError"`：空间数据加载失败诊断入口；失败时组件不会拿空空间条件抢先查询。
+- `@space-error="handleSpaceError"`：空间加载错误诊断入口。园区列表初始化失败会阻止首次确认；楼栋树加载错误当前会报告错误并可能继续用空 building 确认，须按已安装版本验证。
 - `v-model:space-value`：需要受控空间状态时使用，值结构为 `{ parkIds, buildingIds }`。
 - `confirm()`：等待字段异步回调和空间门禁后提交查询。
 - `resetSearch()`：恢复普通字段、触发 reset 并确认，默认保留空间值。
@@ -89,25 +109,14 @@ description: 将业务页面的 DasSearchForm 迁移到 toolbar 布局，并接
 />
 ```
 
-```ts
-function searchData(values: Record<string, any>) {
-  const data = { ...mapBusinessFields(values) }
-  if (Object.prototype.hasOwnProperty.call(values, 'park')) data.park = values.park
-  if (Object.prototype.hasOwnProperty.call(values, 'building')) data.building = values.building
-
-  requestList({ params: { project: projectId }, data })
-}
-```
-
-`park` 单选是标量、多选是数组；`building` 是 ID 数组。不要在这里把字段改回 `parkIds/buildingIds`，也不要手动同时放入 query 和 body。
+业务 handler 只映射普通筛选字段，沿用既有 `createService` API；不要从 `values` 读取空间字段，不要把第二参数并入 payload/query。空间 UI 值由组件和公共请求层处理。
 
 ## 验收清单
 
-- 首次空间初始化只提交一次业务查询，且不会先发空 `park` 的请求。
+- 首次空间初始化只提交一次业务查询，且不会在空间初始化完成前发送请求；控件可见但无选择时对应 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

@@ -1,47 +1,82 @@
 # DasSearchForm Toolbar 迁移要点与常见问题
 
-## 参数边界
+## 一句话理解
 
-`park`、`building` 是跨业务的通用 query 条件，不是业务 payload 字段。只有页面配置并展示对应空间控件时，`confirm` 才会输出对应字段；未配置时组件不请求园区数据，也不生成空字段。
+业务只负责普通筛选与业务请求；页面是否配置并展示园区/楼栋控件决定空间过滤是否启用；空间值由 search-form 和公共 `createService` 请求层写入 URL query，业务 `confirm`、handler、payload 不处理空间字段。
 
-业务使用 `createService` 发送请求即可：公共请求层会把数组参数按逗号放入 query，并从 JSON body 删除 `park/building`。后端无论 POST 还是 GET 都从 query 读取。不要在业务层自行拼接认证头、URL 或重复拆装空间参数。
+## 业务只给页面路径时，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，不可用时明确写出。
 
-### `defaultPark=false` 是否意味着没有首次请求？
+业务方最短提示词见主指南“业务最短提问”。一般只需提供页面路径和必要的 UI 期望，不必复述公共参数实现规则。
 
-不是。它只关闭“自动选择园区列表第一项”，不关闭空间初始化，也不关闭首次业务查询。组件仍会完成初始化并提交一次 `confirm`，此时没有有效默认园区，业务请求不应带有效 `park`。
+## 空间行为速查
 
-### 为什么不能在 `spaceChange` 中请求列表？
+| 页面需求              | 配置与行为                                                                              |
+| --------------------- | --------------------------------------------------------------------------------------- |
+| 不按园区/楼栋过滤     | 不启用空间控件；不加载园区、不创建空间 query。                                          |
+| 只按园区过滤          | `visible: true, showPark: true, showBuilding: false`；园区初始化稳定后才首次确认。      |
+| 按园区和楼栋/空间过滤 | `visible: true, showPark: true, showBuilding: true`；等待园区和所需空间数据就绪后确认。 |
+| 显示楼栋但不显示园区  | 用自定义 `load` 返回完整且有关联信息的楼栋树；默认数据源没有园区上下文。                |
+| 不自动选择首园区      | `defaultPark: false`；仍会初始化和首次确认，可见 park query 是空值语义。                |
 
-`spaceChange` 发生在内部空间状态发布时，适合做受控同步和 UI 联动；园区切换还需要等待楼栋数据加载，楼栋选择也可能发生重复回写。若业务在这里请求，会与组件自己的 `confirm` 竞争，产生空条件请求、重复请求或页面闪烁。列表请求统一放在 `@confirm`。
+控件隐藏时组件不注入对应条件。控件可见但未选择时，当前实现保留空值语义，数组经请求层序列化为空字符串；这不同于字段不存在。无空间控件页面不继承其它页面/Tab 的空间值。注意 createService 还会兼容地把调用方旧 JSON body 里的 park/building 移到 query；无空间过滤的业务需移除 body 中遗留字段，不能只看 UI 是否有控件。
 
-### 楼栋选择为什么现在会查询？
+## 正确的业务请求方式
 
-楼栋是业务过滤条件。选择值实际变化后，toolbar 会用最新 `park/building` 快照确认一次；同一值重复回写会被组件忽略。展开未加载节点触发的是空间子节点懒加载，不等同于业务列表查询。
+handler 只构造业务字段并沿用项目现有 `createService`：
 
-### 为什么首次请求不应该先发一次空 `park`？
+```ts
+function searchData(values: Record<string, any>) {
+  const data = mapBusinessFields(values)
+  requestList({ params: { pageIndex: pageIndex.value, pageSize: pageSize.value }, data })
+}
+```
 
-园区是全局通用条件，业务接口可能依赖它。toolbar 对空间初始化增加了门禁：园区列表、默认值和必要的楼栋数据完成后才允许首次 `confirm`，避免先展示错误结果再被第二次响应覆盖。
+不要读取 confirm 的第二个空间 UI 参数，也不要将 park/building 合入 data 或 params。公共请求层会对 GET/POST 注入当前可见页面的空间 query、将数组逗号序列化，并从 JSON body 删除空间字段。
 
-## 快速排查
+## 常见问题
 
-1. 看 `spaceConfig.visible/showPark/showBuilding` 是否与页面实际显示一致。
-2. 看 `defaultPark` 是否被显式关闭，以及业务是否接受首次无 `park` 查询。
-3. 看业务是否在 `spaceChange`、字段 change 回调、watcher 和 `@confirm` 中重复请求。
-4. 看 Network：`park/building` 应在 query，request payload 不应包含它们。
-5. 看是否误用了旧 `parkIds/buildingIds`。它们只属于组件内部 `spaceValue`，不是对外业务参数。
-6. `showPark=false` 但楼栋为空时，检查自定义 `load` 是否提供了完整楼栋树和园区归属。
+### `defaultPark=false` 是否不再有首次查询？
 
-## 预期请求次数
+不是。它只关闭自动选第一项；空间控件仍会完成初始化，并首次确认一次。可见园区控件未选择时对应 query 为空值。不要为了跳过默认选择而在业务层重新控制首次请求。
 
-| 操作 | 预期业务列表请求 |
-| --- | ---: |
-| 无空间控件首次进入 | 按业务原有逻辑 |
-| 空间控件首次初始化 | 1 |
-| 园区切换 | 1，等待新空间数据完成后发送 |
-| 楼栋实际变化 | 1 |
-| 楼栋重复回写同一值 | 0 |
-| toolbar 重置 | 1 |
-| 仅展开未加载楼栋节点 | 0，只有空间子节点请求 |
+### 为什么不能在 `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 验证及未验证项。