完善气站资源列表搜索契约

docs/06-气站管理系统需求.md

@@ -85,6 +85,8 @@
 
 工作人员支持新增、编辑、启停和归档；资质支持新增、编辑、启停和归档。工作人员只能归属当前气站，可选归属当前气站的一个配送点。存在未完成订单时不得归档。删除工作人员和资质均更新为已归档。
 
+安装人员、配送人员和运维人员列表统一支持按“用户名、角色”模糊搜索，输入框必须明确提示“可搜索：用户名、角色”。
+
 ### 4.4 用户管理
 
 - 用户账户是平台全局账户；当前气站可管理由总后台分配到本站的用户，也可自行创建用户并在同一事务内建立本站服务关系。
@@ -163,6 +165,8 @@
 
 标准列表资源使用独立记录页，不在列表抽屉中承载新建、详情或编辑：
 
+- 列表搜索能力由后端资源契约声明；支持搜索时输入框必须逐项显示“可搜索：字段名”，不得使用“关键字段”等含义不明确的兜底文案。
+- 后端资源契约未声明可搜索字段时，前端必须隐藏“模糊搜索”、输入框、“查询”和“重置”组成的完整搜索区域，刷新和新建操作不受影响。
 - 新建页：`列表路径/new`，仅为支持新建的资源生成。
 - 详情页：`列表路径/:identity`，20 类标准资源全部提供，并支持刷新和直达。
 - 编辑页：`列表路径/:identity/edit`，仅为支持通用编辑的资源生成。

docs/操作日志_气站列表搜索能力显式化_20260819.md

@@ -0,0 +1,53 @@
+# 操作日志：气站列表搜索能力显式化
+
+操作时间：2026-08-19
+操作类型：扩展
+影响模块：气站管理系统标准资源列表、后端资源契约
+
+## 操作前状态
+
+- 气站端所有标准资源列表都会显示搜索区域。
+- 未配置搜索字段的资源使用“关键字段模糊搜索”兜底提示，用户无法判断实际可搜索内容。
+- 工作人员列表的接口虽可接收关键字，但前后端契约未明确限定和展示“用户名、角色”。
+
+## 具体操作
+
+- 为气站资源契约增加可搜索字段声明，并在生成的前端契约中同步输出。
+- 工作人员账号统一声明“用户名、角色”为可搜索字段，覆盖安装人员、配送人员和运维人员列表。
+- 前端仅在契约存在可搜索字段时显示完整搜索区域，并按实际字段生成“可搜索：……”提示。
+- 为气站路由启用已配置关键字搜索策略，确保提示字段与服务端过滤语义一致。
+- 增加契约测试和静态检查，防止重新出现模糊兜底提示或无能力页面错误展示搜索区域。
+
+## 操作后状态
+
+- 工作人员列表显示“可搜索：用户名、角色”。
+- 其他支持搜索的资源按契约逐项显示具体字段。
+- 未声明搜索能力的资源隐藏“模糊搜索”、输入框、“查询”和“重置”，保留刷新与新建操作。
+- 现有资源接口、路由路径和非搜索操作保持兼容。
+
+## 代码变更
+
+- `backend/api/internal/logic/gas/resource_contract.go`：资源契约增加搜索字段。
+- `backend/api/internal/logic/gas/resource_search.go`：集中声明气站资源可搜索字段。
+- `backend/api/internal/logic/gas/resource_contract_test.go`：验证工作人员及无搜索资源契约。
+- `backend/api/internal/routers/gas.go`：启用已配置关键字搜索中间件。
+- `backend/api/cmd/cli/main.go`：生成前端契约时输出搜索字段。
+- `frontend/gas_admin/src/views/shared/use-resource-list-search.ts`：按契约显示或隐藏搜索并生成明确提示。
+- `frontend/gas_admin/scripts/check-backend-contract.mjs`：增加搜索展示规则回归检查。
+- `frontend/gas_admin/src/contracts/gas-resources.json`：同步生成气站资源搜索契约。
+- `docs/06-气站管理系统需求.md`：补充列表搜索展示规则。
+
+## 验证结果
+
+- 后端全量测试 `go test ./...`：通过。
+- 前端契约同步：通过。
+- 前端契约检查：通过，20 个资源与后端契约一致。
+- 前端资源页面检查：通过，详情 20 类、新建 11 类、编辑 8 类。
+- 前端类型检查：通过。
+- 前端生产构建：通过。
+
+## 风险评估
+
+- 影响范围仅限标准资源列表的关键字搜索展示与过滤字段，不改变增删改查接口。
+- 无契约资源将不再发送关键字，避免页面提示与服务端行为不一致。
+- 搜索字段采用显式白名单，降低误搜敏感字段和未来模型字段变化带来的风险。