docs: 补充合同模板与文档质量方案文档
This commit is contained in:
wren
@@ -0,0 +1,253 @@
|
||||
## 目标
|
||||
|
||||
将 `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`
|
||||
Reference in New Issue
Block a user