功能：按资源配置平台列表搜索

docs/操作日志_平台资源搜索配置_20260811.md

@@ -0,0 +1,43 @@
+# 平台资源搜索配置操作日志
+
+操作时间：2026-08-11 22:12:26
+操作类型：扩展
+影响模块：平台总后台 5173、平台 API 搜索、资源契约
+
+## 操作前状态
+
+- 标准列表页无条件显示“关键字”输入框。
+- 后端没有搜索元数据，零搜索字段资源会静默返回未筛选列表。
+- 工作人员角色等字段页面显示中文，但只能按数据库英文编码搜索。
+- 用户地址页面显示搜索框，但实际没有允许搜索的字段。
+
+## 具体操作
+
+- 新增平台路由专用的配置化搜索中间件，其他后台保留原有行为。
+- 新增资源搜索策略注册和启动期安全校验。
+- 普通文本继续模糊搜索；固定枚举改为中文标签包含匹配并参数化查询编码。
+- 资源契约新增 `searchFields`，前端资源定义和可搜索枚举选项消费同一生成契约。
+- 标准列表搜索提示与实际显示列求交集；空集合隐藏表单并清除陈旧 `keyword`。
+- 抽离列表搜索组合函数，使 `CrudListPage.vue` 降至 500 行以内。
+- 新增后端单元测试、平台契约测试和前端资源搜索检查脚本。
+
+## 行为变化
+
+- 变更前：所有列表显示笼统搜索框；可能无效或只能输入隐藏英文编码。
+- 变更后：仅支持搜索的页面显示，例如“可搜索：用户名、角色”；用户地址等页面不显示。
+- 输入“配送”可匹配“配送人员”；输入 `delivery` 不再通过角色枚举字段命中。
+- 动态关系名称本轮保持不可搜索，避免扩大个人信息和关联查询边界。
+
+## 验证结果
+
+- 后端 `common`、`platform`、`routers` 相关测试通过。
+- 前端 `resource-search:check`、`contract:check`、`type:check` 通过。
+- 用户地址既有展示检查通过，前端生产构建通过（2615 个模块）。
+- `git diff --check` 通过；相关核心文件均控制在 500 行以内。
+- 5173 服务可访问且登录页无控制台错误；当前内置浏览器会话未登录，无法对受保护列表进行登录后人工点击验证。
+
+## 风险评估
+
+- 平台总后台的搜索结果集合会按明确可见字段收敛，隐藏字段和枚举英文编码不再产生隐式命中；这是已确认的产品行为。
+- 中文枚举匹配在内存中的小型可信目录完成，不拼接用户输入；SQL 列名和编码均来自静态策略。
+- 当前未开放动态关系名称搜索；若后续开放，需要额外权限审计和数据库索引评估。

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

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