Files

T

TanWenyan 3d6305376b docs: 添加 PostgREST 使用情况分析和删除确认功能文档

1. PostgREST 使用情况分析文档
   - PostgREST使用情况-后端API替代建议.md: 完整的迁移建议和优先级分析
   - PostgREST实际使用清单.md: 当前使用的 PostgREST 接口清单
   - PostgREST未使用函数清单.md: 已封装但未使用的函数列表
   - PostgREST请求模块清单.md: 所有请求模块的使用情况

2. 删除操作延迟确认功能实施文档
   - 功能设计和实现细节
   - 使用示例和最佳实践
   - 技术实现说明

这些文档用于：
- 追踪 PostgREST 到 FastAPI 的迁移进度
- 指导后续的接口迁移工作
- 记录 UI 改进的实施细节

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-11-25 18:18:20 +08:00

21 KiB

Raw Permalink Blame History

PostgREST 实际使用清单

本文档记录项目中实际使用 PostgREST 的模块 更新时间: 2025-11-25 PostgREST 客户端: app/api/postgrest-client.ts

📋 目录

实际使用的模块
排除列表
统计数据

实际使用的模块

1. 认证服务

文件路径: app/api/login/auth.server.ts

PostgREST 函数使用情况

函数名	行号	操作	表名	功能说明
`saveUserInfo()`	583	`postgrestGet`	`sso_users`	查询用户是否已存在
`saveUserInfo()`	625	`postgrestPut`	`sso_users`	更新已存在用户信息
`saveUserInfo()`	653	`postgrestPost`	`sso_users`	插入新用户记录
`addDefaultRole()`	696	`postgrestGet`	`user_role`	查询用户是否已有角色
`addDefaultRole()`	716	`postgrestPost`	`user_role`	为用户添加默认角色
`getUserBySub()`	750	`postgrestGet`	`sso_users`	根据 sub 查询用户信息

使用场景

✅ OAuth2.0 登录后保存用户信息到数据库
✅ 自动为新用户添加默认角色（common 角色）
✅ 更新用户信息（如部门、手机号等）
✅ 查询用户信息用于会话管理

被哪些路由使用

app/routes/callback.tsx - OAuth 回调处理
app/root.tsx - 全局认证检查
其他 17 个路由文件

2. 首页与统计

文件路径: app/api/home/home.ts

PostgREST 函数使用情况

函数名	行号	操作	表名	功能说明
`getEntryModules()`	-	`postgrestGet`	`entry_modules`	获取用户可访问的入口模块
`getEntryModules()`	-	`postgrestGet`	`document_types`	查询入口模块关联的文档类型

使用场景

✅ 根据用户角色和地区过滤可访问的入口模块
✅ 查询入口模块关联的文档类型
✅ 客户端地区启用状态过滤

被哪些路由使用

app/routes/home.tsx - 首页展示

3. 文档管理

文件路径: app/api/files/documents.ts

PostgREST 函数使用情况

函数名	行号	操作	表名	功能说明
`getEvaluationResults()`	147-159	`postgrestGet`	`evaluation_results`	获取文档评查结果
`deleteDocument()`	256	`postgrestDelete`	`documents`	删除文档
`getDocument()`	300	`postgrestGet`	`documents`	获取单个文档（带用户ID过滤）
`getDocumentWithNoUserId()`	351	`postgrestGet`	`documents`	获取单个文档（无用户ID限制）
`updateDocument()`	432	`postgrestPut`	`documents`	更新文档信息
`getDocumentHistory()`	685	`postgrestPost` (RPC)	`rpc/documents_get_document_history`	获取文档历史版本

权限控制

✅ deleteDocument() - 只能删除自己的文档
✅ getDocument() - 只能查看自己的文档
❌ getDocumentWithNoUserId() - 可跨用户查看（交叉评查场景）
✅ updateDocument() - 只能更新自己的文档

被哪些路由使用

app/routes/home.tsx - 首页文档展示
app/routes/documents.list.tsx - 文档列表
app/routes/documents.edit.tsx - 文档编辑
app/api/evaluation_points/reviews.ts - 评审结果查询

4. 文件上传

文件路径: app/api/files/files-upload.ts

PostgREST 函数使用情况

函数名	行号	操作	表名	功能说明
`getTodayDocuments()`	500	`postgrestGet`	`documents`	获取当天上传的文档列表
`getDocumentTypes()`	555	`postgrestGet`	`document_types`	获取文档类型列表
`getDocumentsStatus()`	603	`postgrestGet`	`documents`	查询主文档状态
`getDocumentsStatus()`	616	`postgrestGet`	`contract_structure_comparison`	查询合同附件状态

特性说明

✅ getTodayDocuments() - 支持从 sessionStorage 读取文档类型 ID 进行动态过滤
✅ getDocumentTypes() - 支持按文档类型 ID 数组过滤
✅ getDocumentsStatus() - 支持批量查询文档和合同附件的处理状态

被哪些路由使用

app/routes/documents.list.tsx - 文档列表
app/routes/files.upload.tsx - 文件上传页面
app/components/reviews/ReviewTabs.tsx - 评审标签页

5. 评查点管理

文件路径: app/api/evaluation_points/rules.ts

PostgREST 函数使用情况

函数名	行号	操作	表名	功能说明
`getRulesList()`	-	`postgrestGet`	`evaluation_points`	获取评查点列表
`getRulesList()`	-	`postgrestGet`	`evaluation_point_groups`	查询规则组（类型筛选）
`getRule()`	-	`postgrestGet`	`evaluation_points`	获取单个评查点详情
`getRule()`	-	`postgrestGet`	`evaluation_point_groups`	获取评查点所属分组
`createRule()`	-	`postgrestPost`	`evaluation_points`	创建新评查点
`updateRule()`	-	`postgrestPut`	`evaluation_points`	更新评查点
`deleteRule()`	-	`postgrestDelete`	`evaluation_points`	删除评查点
`getRuleTypes()`	-	`postgrestGet`	`document_types`	获取文档类型
`getRuleTypes()`	-	`postgrestGet`	`evaluation_point_groups`	获取评查点类型
`getRuleGroupsByType()`	-	`postgrestGet`	`evaluation_point_groups`	根据类型获取规则组
`getEvaluationPoint()`	-	`postgrestGet`	`evaluation_points`	获取评查点数据（编辑用）
`getEvaluationPointGroups()`	-	`postgrestGet`	`evaluation_point_groups`	获取所有评查点组
`saveEvaluationPoint()`	-	`postgrestPut` / `postgrestPost`	`evaluation_points`	保存评查点（新建或更新）

高级特性

✅ 使用 PostgREST 双连接查询获取父子分组关系
✅ 支持分页、排序、多条件筛选
✅ 支持按地区过滤（省级管理员可见所有）
✅ 评查点编码清洗（移除地区后缀）

被哪些路由使用

app/routes/rules.list.tsx - 评查点列表

6. 评查点分组

文件路径: app/api/evaluation_points/rule-groups.ts

PostgREST 函数使用情况

函数名	行号	操作	表名	功能说明
`getRuleGroups()`	-	`postgrestGet`	`evaluation_point_groups`	获取顶级评查点分组
`getChildGroups()`	-	`postgrestGet`	`evaluation_point_groups`	获取子分组列表
`getChildGroups()`	-	`postgrestGet`	`evaluation_points`	查询子分组的评查点数量
`getAllRuleGroups()`	-	`postgrestGet`	`evaluation_point_groups`	获取所有分组（树形）
`getAllRuleGroups()`	-	`postgrestGet`	`evaluation_points`	查询每个子分组的评查点数量
`getRuleGroup()`	-	`postgrestGet`	`evaluation_point_groups`	获取单个分组详情
`getRuleGroup()`	-	`postgrestGet`	`evaluation_points`	查询分组的评查点数量
`createRuleGroup()`	-	`postgrestPost`	`evaluation_point_groups`	创建新分组
`updateRuleGroup()`	-	`postgrestPut`	`evaluation_point_groups`	更新分组
`deleteRuleGroup()`	-	`postgrestDelete`	`evaluation_point_groups`	删除分组
`deleteEvaluationPointsByGroupId()`	-	`postgrestDelete`	`evaluation_points`	级联删除评查点

特性说明

✅ 支持树形结构查询（一级分组 + 二级分组）
✅ 级联删除子分组和评查点
✅ 查询分组关联的评查点数量

被哪些路由使用

app/routes/rule-groups.new.tsx - 创建/编辑分组
app/routes/rule-groups._index.tsx - 分组列表
app/routes/document-types.new.tsx - 文档类型关联分组

7. 评查文件审核

文件路径: app/api/evaluation_points/rules-files.ts

PostgREST 函数使用情况

函数名	行号	操作	表名	功能说明
`updateDocumentAuditStatus()`	138	`postgrestPut`	`documents`	更新文档审核状态

审核状态说明

-1 - 不通过
0 - 待审核
1 - 通过
2 - 警告

权限控制

✅ 确保只能更新用户自己的文档（通过 user_id 过滤）

被哪些路由使用

app/routes/documents.list.tsx - 文档列表审核操作
app/routes/files.upload.tsx - 文件上传后审核

8. 评审结果

文件路径: app/api/evaluation_points/reviews.ts

PostgREST 函数使用情况

函数名	行号	操作	表名	功能说明
`getReviewPoints()`	-	`postgrestGet`	`contract_structure_comparison`	获取文档附件数据
`getReviewPoints()`	-	`postgrestGet`	`evaluation_results`	获取评查结果
`getReviewPoints()`	-	`postgrestGet`	`evaluation_points`	获取评查点详情
`getReviewPoints()`	-	`postgrestGet`	`evaluation_point_groups`	获取评查点组信息
`getReviewPoints()`	-	`postgrestGet`	`audit_status`	获取人工审核状态
`getReviewPoints()`	-	`postgrestGet`	`cross_scoring_proposals`	获取交叉评分提案
`updateReviewResult()`	-	`postgrestGet`	`evaluation_results`	获取当前评查结果
`updateReviewResult()`	-	`postgrestPut`	`evaluation_results`	更新评查结果
`updateReviewResult()`	-	`postgrestPut`	`audit_status`	更新审核状态
`updateReviewResult()`	-	`postgrestPost`	`audit_status`	创建新审核状态记录
`confirmReviewResults()`	-	`postgrestPut`	`documents`	确认评查并更新文档状态

数据关联复杂度

✅ 跨 6 个表查询完整的评查结果
✅ 关联评查点、分组、审核状态、交叉提案等

被哪些路由使用

app/routes/reviews.tsx - 文档评审页面
app/routes/cross-checking.result.tsx - 交叉评查结果

9. 文档类型

文件路径: app/api/document-types/document-types.ts

PostgREST 函数使用情况

函数名	行号	操作	表名	功能说明
`getDocumentTypes()`	-	`postgrestGet`	`document_types`	获取文档类型列表
`getDocumentType()`	-	`postgrestGet`	`document_types`	获取文档类型详情
`createDocumentType()`	-	`postgrestPost`	`document_types`	创建文档类型
`updateDocumentType()`	-	`postgrestPut`	`document_types`	更新文档类型
`deleteDocumentType()`	-	`postgrestDelete`	`document_types`	删除文档类型
`getAllEvaluationPointGroups()`	-	`postgrestGet`	`evaluation_point_groups`	获取所有评查点分组
`getParentEvaluationPointGroups()`	-	`postgrestGet`	`evaluation_point_groups`	获取父级分组
`getEntryModules()`	-	`postgrestGet`	`entry_modules`	获取入口模块列表
`getEvaluationPointGroupsByIds()`	-	`postgrestGet`	`evaluation_point_groups`	根据 ID 获取分组信息

特性说明

✅ 支持资源嵌入查询（关联入口模块）
✅ 支持按文档类型 ID 数组过滤
✅ 文档类型关联评查点分组和提示词配置

被哪些路由使用

app/routes/documents.list.tsx - 文档类型筛选
app/routes/document-types.new.tsx - 创建/编辑文档类型
app/routes/document-types._index.tsx - 文档类型列表
app/api/files/documents.ts - 文档类型查询
app/routes/documents.edit.tsx - 文档编辑

10. 入口模块

文件路径: app/api/entry-modules/entry-modules.ts

PostgREST 函数使用情况

函数名	行号	操作	表名	功能说明
`getEntryModules()`	85	`postgrestGet`	`entry_modules`	获取入口模块列表
`getEntryModuleById()`	131	`postgrestGet`	`entry_modules`	根据 ID 获取入口模块
`createEntryModule()`	163	`postgrestPost`	`entry_modules`	创建入口模块
`updateEntryModule()`	194	`postgrestPut`	`entry_modules`	更新入口模块
`deleteEntryModule()`	224	`postgrestDelete`	`entry_modules`	删除入口模块

高级特性

✅ 支持 JSONB 数组查询（areas 字段）

filter: { 'areas': 'cs.{"梅州"}' }  // cs = contains

✅ 支持分页、排序、按名称和地区筛选
✅ 返回 Content-Range 头获取总数

被哪些路由使用

app/routes/entry-modules._index.tsx - 入口模块列表
app/routes/entry-modules.new.tsx - 创建/编辑入口模块

11. 交叉评查

文件路径: app/api/cross-checking/

11.1 cross-files.ts

函数名	行号	操作	表名	功能说明
`updateDocumentAuditStatus()`	486	`postgrestPut`	`documents`	更新文档审核状态

11.2 cross-file-result.ts

函数名	行号	操作	表名	功能说明
`findIsProposer()`	93	`postgrestGet`	`cross_examination_tasks`	查找是否是任务发起人
`confirmReviewResults()`	365	`postgrestPut`	`documents`	完成评查并更新文档状态

混合使用说明

✅ PostgREST 用于文档状态更新和权限判断
✅ 后端 API 用于任务、意见、投票管理
⚠️ 无用户 ID 过滤（交叉评查需要跨用户操作）

被哪些路由使用

app/routes/cross-checking._index.tsx - 交叉评查任务列表
app/routes/cross-checking.result.tsx - 评查结果页面
app/components/cross-checking/DocumentListModal.tsx - 文档列表弹窗
app/components/cross-checking/ReviewPointsList.tsx - 评查点列表

12. 提示词模板

文件路径: app/api/prompts/prompts.ts

PostgREST 函数使用情况

函数名	行号	操作	表名	功能说明
`getPromptTemplates()`	-	`postgrestGet`	`prompt_templates`	获取提示词模板列表
`getPromptTemplate()`	-	`postgrestGet`	`prompt_templates`	获取模板详情
`createPromptTemplate()`	-	`postgrestPost`	`prompt_templates`	创建提示词模板
`updatePromptTemplate()`	-	`postgrestPut`	`prompt_templates`	更新提示词模板
`deletePromptTemplate()`	-	`postgrestDelete`	`prompt_templates`	删除提示词模板
`getPromptTemplateOptions()`	-	`postgrestGet`	`prompt_templates`	获取模板选项列表

资源嵌入查询

select: `
  id, template_name, template_type,
  sso_users!created_by(username)
`

模板类型

LLM_Extraction - LLM 抽取
VLM_Extraction - VLM 抽取
Evaluation - 评查
Summary - 总结
Common - 通用

被哪些路由使用

app/routes/prompts.new.tsx - 创建/编辑提示词
app/routes/prompts._index.tsx - 提示词列表
app/routes/document-types.new.tsx - 文档类型关联提示词
app/routes/rules.new.tsx - 评查点关联提示词

13. 合同模板

文件路径: app/api/contract-template/templates.ts

PostgREST 函数使用情况

函数名	行号	操作	表名	功能说明
`getContractCategories()`	-	`postgrestGet`	`contract_categories`	获取合同分类列表
`getContractCategoriesWithCount()`	-	`postgrestGet`	`contract_categories`	获取分类及模板数量
`getContractCategoriesWithCount()`	-	`postgrestGet`	`contract_templates`	统计每个分类的模板数量
`getContractTemplates()`	-	`postgrestGet`	`contract_categories`	查询分类（关键词搜索）
`getContractTemplates()`	-	`postgrestGet`	`contract_templates`	获取合同模板列表
`getContractTemplate()`	-	`postgrestGet`	`contract_templates`	获取单个模板详情
`getFeaturedTemplates()`	-	`postgrestGet`	`contract_templates`	获取推荐模板

高级特性

✅ 支持 OR 条件查询（多字段模糊搜索）

or: [
  { title: 'ilike.*关键词*' },
  { description: 'ilike.*关键词*' },
  { template_code: 'ilike.*关键词*' }
]

✅ 使用资源嵌入查询分类信息

被哪些路由使用

app/routes/contract-template.detail.$id.tsx - 模板详情
app/routes/contract-template.search._index.tsx - 模板搜索
app/routes/contract-template.search.results.tsx - 搜索结果
app/routes/contract-template.list._index.tsx - 模板列表

14. 评查点编辑页面

文件路径: app/routes/rules.new.tsx

PostgREST 函数使用情况

函数名	行号	操作	表名	功能说明
`fetchEvaluationPoint()`	-	`postgrestGet`	`evaluation_points`	获取评查点数据（编辑模式）
`fetchEvaluationPointGroups()`	-	`postgrestGet`	`evaluation_point_groups`	获取评查点组数据
`handleSave()`	-	`postgrestPut`	`evaluation_points`	更新评查点（编辑模式）
`handleSave()`	-	`postgrestPost`	`evaluation_points`	创建评查点（新建模式）

特性说明

✅ 支持评查点创建、编辑、复制模式
✅ 评查点编码清洗（移除地区后缀）
✅ 表单验证（必填字段、规则完整性）

排除列表

❌ 已删除或未使用的模块

模块名	路径	状态	原因
`config-lists.ts`	`app/api/system_setting/config-lists.ts`	✅ 已删除	不再使用

统计数据

模块统计

类型	数量
API 模块	13
路由模块	1
总计	14

数据库表使用频率

表名	使用次数	主要操作
`evaluation_points`	🔥🔥🔥🔥🔥	GET, POST, PUT, DELETE（最高频）
`evaluation_point_groups`	🔥🔥🔥🔥	GET, POST, PUT, DELETE
`documents`	🔥🔥🔥🔥	GET, PUT, DELETE
`sso_users`	🔥🔥🔥	GET, PUT, POST
`evaluation_results`	🔥🔥🔥	GET, PUT
`document_types`	🔥🔥🔥	GET, POST, PUT, DELETE
`prompt_templates`	🔥🔥🔥	GET, POST, PUT, DELETE
`entry_modules`	🔥🔥	GET, POST, PUT, DELETE
`contract_templates`	🔥🔥	GET
`contract_categories`	🔥🔥	GET
`user_role`	🔥	GET, POST
`audit_status`	🔥	GET, PUT, POST
`cross_examination_tasks`	🔥	GET
`cross_scoring_proposals`	🔥	GET
`contract_structure_comparison`	🔥	GET

PostgREST 操作统计

操作类型	使用频率
`postgrestGet`	🔥🔥🔥🔥🔥
`postgrestPut`	🔥🔥🔥🔥
`postgrestPost`	🔥🔥🔥
`postgrestDelete`	🔥🔥

PostgREST 高级特性使用

特性	使用示例
资源嵌入查询	文档类型关联入口模块、提示词关联创建者
JSONB 数组查询	入口模块地区过滤 (`areas cs.{"梅州"}`)
OR 条件查询	合同模板多字段搜索
分页与排序	所有列表查询
RPC 函数调用	文档历史版本查询
批量查询	文档状态轮询 (`id in.(1,2,3)`)
总数统计	Content-Range 头获取 total

🔧 PostgREST 客户端核心函数

函数名	功能
`postgrestGet<T>()`	GET 请求，查询数据
`postgrestPost<T, U>()`	POST 请求，创建数据或调用 RPC
`postgrestPut<T, U>()`	PUT 请求，更新数据
`postgrestDelete()`	DELETE 请求，删除数据

⚠️ 重要说明

权限控制差异

严格用户权限控制（通过 user_id 过滤）：
- documents.ts 中的 CRUD 操作
- rules-files.ts 中的审核状态更新
跨用户访问（无 user_id 过滤）：
- cross-checking 模块（交叉评查需要）
- getDocumentWithNoUserId() 函数

数据提取统一方式

所有模块使用统一的 extractApiData<T>() 函数处理响应：

function extractApiData<T>(responseData: unknown): T | null {
  // 格式1: { code: number, msg: string, data: T }
  if (typeof responseData === 'object' && 'data' in responseData) {
    return (responseData as { data: T }).data;
  }
  // 格式2: 直接是数据对象
  return responseData as T;
}

JWT 认证

所有 PostgREST 请求都支持 JWT token 参数：

const response = await postgrestGet('table_name', {
  filter: { ... },
  token: frontendJWT  // JWT 认证
});

文档维护: 添加或删除 PostgREST 模块时，请及时更新此文档。

21 KiB Raw Permalink Blame History

PostgREST 实际使用清单

📋 目录

实际使用的模块

1. 认证服务

PostgREST 函数使用情况

使用场景

被哪些路由使用

2. 首页与统计

PostgREST 函数使用情况

使用场景

被哪些路由使用

3. 文档管理

PostgREST 函数使用情况

权限控制

被哪些路由使用

4. 文件上传

PostgREST 函数使用情况

特性说明

被哪些路由使用

5. 评查点管理

PostgREST 函数使用情况

高级特性

被哪些路由使用

6. 评查点分组

PostgREST 函数使用情况

特性说明

被哪些路由使用

7. 评查文件审核

PostgREST 函数使用情况

审核状态说明

权限控制

被哪些路由使用

8. 评审结果

PostgREST 函数使用情况

数据关联复杂度

被哪些路由使用

9. 文档类型

PostgREST 函数使用情况

特性说明

被哪些路由使用

10. 入口模块

PostgREST 函数使用情况

高级特性

被哪些路由使用

11. 交叉评查

11.1 cross-files.ts

11.2 cross-file-result.ts

混合使用说明

被哪些路由使用

12. 提示词模板

PostgREST 函数使用情况

资源嵌入查询

模板类型

被哪些路由使用

13. 合同模板

PostgREST 函数使用情况

高级特性

被哪些路由使用

14. 评查点编辑页面

PostgREST 函数使用情况

特性说明

排除列表

❌ 已删除或未使用的模块

统计数据

模块统计

数据库表使用频率

PostgREST 操作统计

PostgREST 高级特性使用

🔧 PostgREST 客户端核心函数

⚠️ 重要说明

权限控制差异

数据提取统一方式

JWT 认证

21 KiB

Raw Permalink Blame History