# 平台资源搜索配置

## 项目概述

平台总后台原先在所有标准列表页显示统一关键字输入框，但后端只会搜索安全白名单中的部分字符串列。无可搜索字段的页面会静默忽略关键字，枚举字段还存在“页面显示中文、只能输入英文编码”的语义断层。

本版本将搜索能力改为资源级配置：后端策略同时驱动实际 SQL 和生成契约，前端只展示“当前可见列”与“后端搜索字段”的交集。

## 核心规则

- 普通文本字段按页面显示的原始文本执行不区分大小写的包含匹配。
- 固定枚举按中文名称模糊匹配，再转换为可信编码执行参数化 `IN` 查询。
- 枚举英文编码不作为搜索入口，例如 `delivery`、`on_duty` 不用于枚举搜索。
- 用户姓名、平台角色名称等动态关系字段本轮不开放关系搜索。
- 没有合格字段的页面隐藏搜索表单，不发送 `keyword`，并清除 URL 中遗留参数。
- 搜索提示明确列出字段，例如“可搜索：用户名、角色”。
- 用户地址页面只有动态用户关系和受保护地址数据，因此隐藏搜索框。

## 目录结构

```text
backend/api/internal/logic/common/
└── keyword_search.go                 # 配置注册、中文枚举匹配和 SQL 条件编译
backend/api/internal/logic/platform/
└── resource_search.go                # 平台资源搜索策略与中文枚举目录
frontend/platform_admin/src/api/
└── resource-search-contract.ts       # 消费后端生成的搜索契约
frontend/platform_admin/src/views/shared/
└── use-resource-list-search.ts       # 可见列交集、提示、URL 与关键字状态
```

## 核心文件说明

- `keyword_search.go`：注册模型字段策略；启动时校验列必须是直接字符串列、安全白名单字段且非敏感字段。
- `resource_search.go`：按资源声明 `text` 或 `enum` 字段。新增搜索能力必须先在此处明确授权。
- `resource_contract.go` 与 CLI：将同一策略输出为 `searchFields`，避免文档能力与 SQL 漂移。
- `resource-search-contract.ts`：读取生成契约；可搜索枚举的页面选项也从契约生成。
- `use-resource-list-search.ts`：按实际列表列求交集，控制显示、请求和陈旧 URL 参数清理。

## 维护指南

1. 在后端 `resource_search.go` 为资源增加字段，只允许列表实际可见且安全的直接文本字段。
2. 固定枚举必须同时声明编码和中文名称；动态关系不得伪装成枚举。
3. 执行 `pnpm contract:sync` 更新前端生成契约。
4. 执行 `pnpm resource-search:check`、`pnpm contract:check`、`pnpm type:check` 和后端相关测试。
5. 若未来开放关系名称搜索，必须单独设计受控 `EXISTS` 查询、权限边界和索引，不可由前端关系配置自动推断。

## 变更记录

- v1.0：新增平台资源级搜索策略、中文枚举模糊搜索、动态字段提示、无能力隐藏和 URL 清理。