leaudit-platform-backend/docs/合同模板搜索合同起草/合同模板前端切换新接口改造清单.md

目标

将 contract-template 相关页面从旧的 PostgREST 直连方式切换到新的 FastAPI 业务接口，范围仅覆盖：

• 模板分类
• 模板列表
• 模板搜索
• 模板详情

本清单不包含“起草合同”能力，后续会作为独立模块重新开发。

当前前端依赖点

当前前端核心依赖集中在：

• legal-platform-frontend/lib/api/legacy/contract-template/templates.ts

这个文件现在直接调用：

• /api/postgrest/proxy/contract_categories
• /api/postgrest/proxy/contract_templates

受影响页面：

• app/(audit)/contract-template/search/page.tsx
• app/(audit)/contract-template/search/results/page.tsx
• app/(audit)/contract-template/list/page.tsx
• app/(audit)/contract-template/detail/[id]/page.tsx

推荐新接口

建议前端最终切换为：

1. GET /api/v3/contract-templates/categories
2. GET /api/v3/contract-templates
3. GET /api/v3/contract-templates/search
4. GET /api/v3/contract-templates/{id}

改造步骤

第 1 步：新增新接口客户端文件

建议新增：

• legal-platform-frontend/lib/api/contract-template/index.ts

职责：

• 仅封装新的业务后端接口
• 不再依赖 postgrest-client.ts
• 返回字段尽量与页面现有消费结构兼容

建议方法：

• getContractTemplateCategories
• getContractTemplateList
• searchContractTemplateList
• getContractTemplateDetail

第 2 步：定义前端接口类型

建议在新客户端文件中定义或复用以下类型：

• ContractTemplateCategory
• ContractTemplateListItem
• ContractTemplatePage
• ContractTemplateDetail
• ContractTemplateSearchResult

字段建议优先与新后端对齐，然后在页面边界做一次轻量转换，避免业务层长期保留 snake_case 和 camelCase 混用。

第 3 步：改造搜索首页

文件：

• app/(audit)/contract-template/search/page.tsx

当前行为：

• 调 getContractCategoriesWithCount

改造后：

• 改为调用 getContractTemplateCategories
• 直接消费后端返回的 templateCount

页面影响：

• transformCategory 中的 template_count 改为新接口字段

第 4 步：改造列表页

文件：

• app/(audit)/contract-template/list/page.tsx

当前行为：

• 调 getContractTemplates
• 同时调 getContractCategoriesWithCount

改造后：

• 列表数据改为 getContractTemplateList
• 分类数据改为 getContractTemplateCategories

注意事项：

• 当前页面把 sortBy=relevance 映射成 id.asc，这是旧 PostgREST 兼容逻辑
• 切换新接口后应明确排序语义：
  • relevance 仅搜索场景有效
  • 列表页默认建议改为 updated_at desc

第 5 步：改造搜索结果页

文件：

• app/(audit)/contract-template/search/results/page.tsx

当前行为：

• 调 searchContractTemplates
• 额外循环所有分类，再逐类搜索统计命中数

改造后：

• 改为一次调用 searchContractTemplateList
• 直接使用后端返回的 categoryStats

收益：

• 避免当前每次搜索都发起多次分类二次查询
• 页面搜索耗时会明显降低

第 6 步：改造详情页

文件：

• app/(audit)/contract-template/detail/[id]/page.tsx

当前行为：

• 调 getContractTemplate

改造后：

• 改为调用 getContractTemplateDetail

注意事项：

• 页面中依赖：
  • template_code
  • file_path
  • pdf_file_path
  • placeholder_schema
  • category.name
  • category.description
• 新接口最好直接扁平返回，前端减少再拼装

第 7 步：保留旧文件作为过渡，避免一次性大改

建议不要立刻删除：

• lib/api/legacy/contract-template/templates.ts

更稳妥的做法：

1. 新建新接口客户端文件
2. 页面逐个切换
3. 确认没有页面再引用旧文件
4. 再删除旧实现

字段映射建议

建议后端返回使用 camelCase 还是 snake_case，前后端尽量统一一次定死。

如果后端沿用当前 Python VO 风格的 snake_case，那么前端建议统一在 API client 中做转换：

• template_code -> templateCode
• category_id -> categoryId
• file_path -> filePath
• pdf_file_path -> pdfFilePath
• placeholder_schema -> placeholderSchema
• updated_at -> updatedAt

不要把这类转换分散在页面组件里。

具体函数替换建议

当前旧函数：

• getContractCategories
• getContractCategoriesWithCount
• getContractTemplates
• getContractTemplate
• searchContractTemplates

建议替换为新函数：

• getContractTemplateCategories
• getContractTemplateList
• getContractTemplateDetail
• searchContractTemplateList

风险点

1. 排序语义变化

   • 旧逻辑混入了 PostgREST 风格排序拼接
   • 新接口需要明确合法排序字段白名单

2. 搜索分类统计变化

   • 旧页面自己循环查询分类统计
   • 新接口如果不返回 categoryStats，页面逻辑还要保留一部分旧实现

3. 详情页字段结构变化

   • 旧页面默认拿 template.category?.name
   • 新接口若改成扁平字段，需要同步调整页面 transform

4. token 传递方式变化

   • 旧实现依赖 postgrest-client.ts
   • 新接口应统一走 axios-client.ts 或新业务客户端

建议落地顺序

1. 新增 lib/api/contract-template/index.ts
2. 先切 search/page.tsx
3. 再切 list/page.tsx
4. 再切 search/results/page.tsx
5. 最后切 detail/[id]/page.tsx
6. 全部验证通过后删除旧 legacy/contract-template/templates.ts

验收标准

1. contract-template/search 能正常展示分类和数量
2. contract-template/list 能分页、筛选、排序
3. contract-template/search/results 能搜索并展示分类统计
4. contract-template/detail/[id] 能正常查看详情与预览
5. 页面不再直接请求 /api/postgrest/proxy/contract_categories
6. 页面不再直接请求 /api/postgrest/proxy/contract_templates