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

操作日志：气站列表搜索能力显式化

操作时间：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 类。
• 前端类型检查：通过。
• 前端生产构建：通过。

风险评估

• 影响范围仅限标准资源列表的关键字搜索展示与过滤字段，不改变增删改查接口。
• 无契约资源将不再发送关键字，避免页面提示与服务端行为不一致。
• 搜索字段采用显式白名单，降低误搜敏感字段和未来模型字段变化带来的风险。