platforms/docs/项目文档_平台资源搜索配置_v1.0.md

平台资源搜索配置

项目概述

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

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

核心规则

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

目录结构

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 清理。