ai-contract-platform/project-docs/V2-unified-search-mvp-2026-06-24.md

AI 合同平台 V2 - T5 统一搜索 MVP 闭环记录

日期：2026-06-24

目标

对照《AI 合同平台 V2 重构版开发方案》，本轮进入 T5：统一搜索 MVP。目标是把搜索从前端 mock 数据切到真实业务状态，让用户能用一个入口查找：

• 合同。
• 合同附件。
• 合同审查任务。

本轮完成

后端

• 新增统一搜索模型：
  • SearchResult
  • SearchResultPage
• ContractRepository 增加 search() 抽象。
• 内存仓储和 SQLite 仓储均支持搜索。
• GET /api/v1/search 接入真实查询。
• 支持查询参数：
  • keyword
  • type=contract|review|file|template
  • status
  • sort=updated_at_desc|relevance
• 搜索结果统一返回：
  • 标题。
  • 摘要。
  • 主入口 URL。
  • 状态。
  • 更新时间。
  • 所属合同 ID。
  • 简单相关性分数。
• 审查任务结果入口指向合同详情的审查区域：/contracts/{id}#files-review。

前端

• /search 页面从 mock 数据切到真实 Contract API。
• 修复旧搜索页乱码文案。
• 增加类型、状态、排序筛选。
• 按合同、审查任务、文件分组展示结果。
• 结果标题作为主入口，不再提供重复“打开”按钮。
• 增加关键词命中高亮。

契约和测试

• OpenAPI 同步 /api/v1/search 的状态筛选和响应字段。
• 新增测试覆盖：
  • 搜索合同。
  • 搜索附件。
  • 搜索审查任务。
  • 按类型和状态过滤审查任务。

简化原则检查

本轮继续遵循“企业主线轻量化”原则：

• 搜索页只承担查找入口，不扩展成复杂检索控制台。
• 标题就是主入口，减少重复操作按钮。
• 筛选项保持最小集合：类型、状态、排序。
• 后端暂用数据库查询和简单相关性分数，不提前引入搜索引擎，避免架构过重。

验证结果

• python -m pytest yuqei-contract-platform\services\contract-api\tests -q：19 passed。
• python -m compileall yuqei-contract-platform\services\contract-api\src\yuqei_contract_api：通过。
• OpenAPI YAML 解析：通过。
• npm --prefix yuqei-contract-platform\apps\contract-web run build：通过。
• npm --prefix yuqei-contract-platform\apps\contract-web run typecheck：通过。

备注

前端仓库当前没有 ESLint 配置文件。直接运行 npm exec eslint 会拉取新版 ESLint 并报缺少 eslint.config.*，因此本轮前端验证以 Next build 和 TypeScript typecheck 为准。

后续建议

下一步进入 T6：部署与运行基线，收口 V2 的数据库迁移、环境变量、健康检查、Docker/compose 启动方式，保证从空库启动、迁移、运行、测试都有明确命令。