51 lines
3.0 KiB
Markdown
51 lines
3.0 KiB
Markdown
# 平台资源搜索配置
|
||
|
||
## 项目概述
|
||
|
||
平台总后台原先在所有标准列表页显示统一关键字输入框，但后端只会搜索安全白名单中的部分字符串列。无可搜索字段的页面会静默忽略关键字，枚举字段还存在“页面显示中文、只能输入英文编码”的语义断层。
|
||
|
||
本版本将搜索能力改为资源级配置：后端策略同时驱动实际 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 清理。
|