提交

openspec/changes/zkxw-engineering-standards/specs/ui-conventions/spec.md

@@ -307,6 +307,51 @@ Web 管理端弹窗 SHALL 遵循规范：表单 `label-position="top"`；遮罩
 - **WHEN** PR 新增或修改列表页 `.filter-block` 筛选字段
 - **THEN** 审查者 SHALL 确认存在关键词字段时其位于 `.filter-grid` 第一位
 
+### Requirement: 列表筛选自动触发搜索
+
+`web-admin` 所有列表页的筛选表单（`.filter-block` 内 `searchForm` / `filterForm`）SHALL 使用 `watchDebounced`（来自 `@vueuse/core`，已 auto-import）对筛选表单做 deep watch，当任意字段值变更后 **300ms** 防抖自动触发搜索（重置页码为 1 并调用数据加载函数），无需用户手动点击「搜索」按钮。「搜索」按钮 SHALL 保留作为手动触发入口。
+
+#### 实现模式
+
+```typescript
+watchDebounced(
+  searchForm, // 或 filterForm
+  () => {
+    pagination.page = 1
+    loadData()
+  },
+  { debounce: 300, deep: true }
+)
+```
+
+对于含有**独立日期范围选择器**（`dateRange` ref，不属于 searchForm）的页面（如 `material-stock-log`、`qc-material-usage`），SHALL 额外添加 `watch(dateRange, ...)` 监听，在日期变更时同样触发搜索。
+
+#### Scenario: 单字段筛选自动搜索
+
+- **WHEN** 用户在筛选区关键词输入框中键入内容
+- **THEN** 停止输入 300ms 后 SHALL 自动执行搜索，无需点击「搜索」按钮
+
+#### Scenario: 多字段筛选自动搜索
+
+- **WHEN** 列表页筛选区包含关键词、下拉选择、日期选择等多个筛选控件
+- **AND** 用户修改其中任意一个筛选字段的值
+- **THEN** 变更后 300ms SHALL 自动执行搜索
+
+#### Scenario: 日期范围筛选
+
+- **WHEN** 页面使用独立的 `dateRange` ref（非 searchForm 内字段）进行日期范围筛选
+- **THEN** SHALL 额外使用 `watch(dateRange, ...)` 监听变更并触发搜索
+
+#### Scenario: 保留手动搜索
+
+- **WHEN** 用户点击筛选区的「搜索」按钮
+- **THEN** SHALL 立即执行搜索（无防抖），与自动搜索行为并行可用
+
+#### Scenario: Code review 自动搜索
+
+- **WHEN** PR 新增或修改列表页筛选区
+- **THEN** 审查者 SHALL 确认筛选表单已添加 `watchDebounced` 自动搜索，且 `debounce` 不超过 500ms
+
 ### Requirement: 附件上传卡片化布局
 
 `web-admin` 弹窗表单中的附件上传与展示 SHALL 采用**卡片化布局**，实现与交互以 `web-admin/src/views/cell-storage/protocol/ProtocolFormDialog.vue` 中「协议附件」为权威参考；储存证等业务弹窗（如 `web-admin/src/views/cell-storage/storage-cert/index.vue`）SHALL 复用同一套 DOM 结构、类名与样式规则，仅调整 `el-form-item` 的 `label` 与上传 `folder` 等业务参数。