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

22 KiB

Raw Permalink Blame History

PostgREST 请求模块完整清单

本文档记录了项目中所有直接使用 PostgREST 客户端发送请求的模块和函数。

更新时间: 2025-11-24 PostgREST 客户端位置: app/api/postgrest-client.ts

📚 目录

API 模块
路由模块
- 评查点编辑页面

API 模块

1. 首页与统计

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

使用的 PostgREST 函数

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

主要功能

✅ 获取首页统计数据（通过后端 API，非 PostgREST）
✅ 获取高频错误评查点（通过后端 API）
✅ 获取高风险用户（通过后端 API）
✅ 获取用户可访问的入口模块（使用 PostgREST）
- 根据用户角色和地区过滤模块
- 查询模块关联的文档类型
- 在客户端进行地区启用状态过滤

2. 认证服务

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

使用的 PostgREST 函数

函数名	操作	表名	说明
待补充	-	-	用户会话管理相关功能

主要功能

✅ 用户身份验证
✅ 会话管理
✅ 登出功能

3. 文档管理

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

使用的 PostgREST 函数

函数名	操作	表名	说明
`getDocument()`	`postgrestGet`	`documents`	获取单个文档详情
`getDocumentWithNoUserId()`	`postgrestGet`	`documents`	获取文档（无用户ID限制）
`getEvaluationResults()`	`postgrestGet`	`evaluation_results`	获取文档的评查结果
`updateDocument()`	`postgrestPut`	`documents`	更新文档信息
`deleteDocument()`	`postgrestDelete`	`documents`	删除文档
`getDocumentHistory()`	`postgrestPost`	`rpc/documents_get_document_history`	获取文档历史版本（RPC函数）

主要功能

✅ 获取单个文档详情（包含评查结果统计）
✅ 获取文档列表（使用后端 API /admin/versions/documents-list）
✅ 更新文档信息（文档编号、审核状态、备注等）
✅ 删除文档（仅限用户自己的文档）
✅ 获取文档历史版本列表
✅ 计算文档问题数量（基于评查结果）

4. 文件上传

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

使用的 PostgREST 函数

函数名	操作	表名	说明
`getTodayDocuments()`	`postgrestGet`	`documents`	获取当天上传的文档列表
`getDocumentTypes()`	`postgrestGet`	`document_types`	获取文档类型列表
`getDocumentsStatus()`	`postgrestGet`	`documents`	获取文档状态
`getDocumentsStatus()`	`postgrestGet`	`contract_structure_comparison`	获取合同附件状态

主要功能

✅ 获取当天文档列表
- 根据用户ID和文档类型过滤
- 从 sessionStorage 读取文档类型 ID
✅ 获取文档类型列表（支持动态类型过滤）
✅ 获取指定文档的状态（支持主文档和合同附件）
✅ 上传文件到服务器（使用后端 API，非 PostgREST）
✅ 上传合同模板（使用后端 API）
✅ 追加合同附件（使用后端 API）

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 双连接查询获取父子分组
✅ 评查点 CRUD 操作
✅ 评查点复制功能
✅ 评查点编码清洗（移除地区后缀）
✅ 评查点分组查询（支持嵌套父子关系）

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`	删除分组下的所有评查点

主要功能

✅ 评查点分组 CRUD 操作
✅ 分组树形结构查询（一级分组+二级分组）
✅ 查询分组关联的评查点数量
✅ 删除分组时级联删除子分组和评查点
✅ 支持父分组（pid=0）和子分组（pid>0）

7. 评查文件审核

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

使用的 PostgREST 函数

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

主要功能

✅ 更新文件的审核状态
- 确保只能更新用户自己的文档
- 支持状态：待审核(0)、通过(1)、不通过(-1)、警告(-2)

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`	确认评查并更新文档状态

主要功能

✅ 获取文档的完整评查结果
- 查询评查点结果（evaluation_results）
- 关联评查点详情（evaluation_points）
- 关联评查点分组（evaluation_point_groups）
- 获取人工审核状态（audit_status）
- 获取合同附件比对结果（contract_structure_comparison）
- 获取交叉评分提案（cross_scoring_proposals）
✅ 更新评查结果
- 修改评查意见和结果
- 更新或创建人工审核状态
- 支持重新审核操作
✅ 确认评查结果（将文档审核状态设为通过）

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获取分组信息

主要功能

✅ 文档类型 CRUD 操作
✅ 文档类型列表查询
- 支持分页、排序
- 支持按名称、分组筛选
- 支持按文档类型 ID 数组过滤
- 使用 PostgREST 外键关联查询入口模块
✅ 文档类型关联评查点分组
✅ 文档类型关联入口模块
✅ 文档类型提示词配置（LLM抽取、VLM抽取、评查、总结）

10. 入口模块

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

使用的 PostgREST 函数

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

主要功能

✅ 入口模块 CRUD 操作
✅ 入口模块列表查询
- 支持分页、排序
- 支持按名称、地区筛选
- 支持 JSONB 数组查询（areas字段）
✅ 入口模块地区配置管理

11. 交叉评查

文件路径:

app/api/cross-checking/cross-files.ts
app/api/cross-checking/cross-file-result.ts

使用的 PostgREST 函数

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

主要功能

cross-files.ts:

✅ 获取用户任务列表（使用后端 API）
✅ 获取任务文档列表（使用后端 API）
✅ 获取统计数据（使用后端 API）
✅ 更新文档审核状态（使用 PostgREST）

cross-file-result.ts:

✅ 提交交叉评查意见（使用后端 API）
✅ 获取交叉评查意见列表（使用后端 API）
✅ 执行意见操作（赞同、反对、撤销，使用后端 API）
✅ 完成评查（使用 PostgREST 更新文档状态）
✅ 检查提案投票状态（使用后端 API）
✅ 查找是否是任务发起人（使用 PostgREST）

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`	获取模板选项列表

主要功能

✅ 提示词模板 CRUD 操作
✅ 提示词模板列表查询
- 支持分页、排序
- 支持按名称、类型、状态筛选
- 使用 PostgREST 外键关联查询创建者信息（sso_users表）
✅ 提示词模板类型
- LLM抽取（LLM_Extraction）
- VLM抽取（VLM_Extraction）
- 评查（Evaluation）
- 总结（Summary）
- 通用（Common）
✅ 获取指定类型的模板选项（用于下拉选择）

13. 系统配置

文件路径: app/api/system_setting/config-lists.ts

使用的 PostgREST 函数

函数名	操作	表名	说明
`getConfigLists()`	`postgrestGet`	`configurations`	获取配置列表
`getConfigOptions()`	`postgrestGet`	`configurations`	获取配置类型和环境选项
`getConfigDetail()`	`postgrestGet`	`configurations`	获取配置详情
`createConfig()`	`postgrestPost`	`configurations`	创建配置
`updateConfig()`	`postgrestPut`	`configurations`	更新配置
`updateConfigStatus()`	`postgrestPut`	`configurations`	更新配置状态

主要功能

✅ 系统配置 CRUD 操作
✅ 配置列表查询
- 支持分页、排序
- 支持按名称、类型、环境、状态筛选
✅ 配置类型和环境动态选项查询
✅ 配置状态管理（启用/禁用）

14. 合同模板

文件路径: 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`	获取推荐模板

主要功能

✅ 合同分类管理
- 获取所有分类
- 统计每个分类的模板数量
✅ 合同模板查询
- 支持分页、排序
- 支持按分类、格式、推荐状态筛选
- 支持关键词搜索（标题、描述、模板编码、分类名）
- 使用 PostgREST 外键关联查询分类信息
✅ 获取推荐模板列表
✅ 智能搜索功能

路由模块

15. 评查点编辑页面

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

使用的 PostgREST 函数

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

主要功能

✅ 评查点创建/编辑/复制页面
✅ 评查点数据加载（支持编辑和复制模式）
✅ 评查点分组数据加载（用于下拉选择）
✅ 评查点保存（新建或更新）
- 基本信息设置
- 抽取设置（LLM、VLM、Regex）
- 评查设置（规则配置、消息配置）
✅ 评查点编码清洗（移除地区后缀）
✅ 表单验证（必填字段、规则完整性）

📊 统计信息

模块统计

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

数据库表统计

表名	操作频率	主要操作
`evaluation_points`	🔥🔥🔥🔥🔥	GET, POST, PUT, DELETE
`evaluation_point_groups`	🔥🔥🔥🔥	GET, POST, PUT, DELETE
`documents`	🔥🔥🔥🔥	GET, PUT, DELETE
`document_types`	🔥🔥🔥	GET, POST, PUT, DELETE
`evaluation_results`	🔥🔥🔥	GET, PUT
`prompt_templates`	🔥🔥🔥	GET, POST, PUT, DELETE
`entry_modules`	🔥🔥	GET, POST, PUT, DELETE
`contract_templates`	🔥🔥	GET
`contract_categories`	🔥🔥	GET
`configurations`	🔥	GET, POST, PUT
`audit_status`	🔥	GET, PUT, POST
`cross_examination_tasks`	🔥	GET
`cross_scoring_proposals`	🔥	GET
`contract_structure_comparison`	🔥	GET

PostgREST 操作统计

操作	使用次数
`postgrestGet`	🔥🔥🔥🔥🔥
`postgrestPost`	🔥🔥🔥
`postgrestPut`	🔥🔥🔥🔥
`postgrestDelete`	🔥🔥

🔧 PostgREST 使用特性

1. 资源嵌入（Resource Embedding）

使用示例:

// 查询文档类型并关联入口模块
select: `
  id, name, description,
  entry_modules!fk_document_types_entry_module(id, name)
`

// 查询提示词模板并关联创建者
select: `
  id, template_name, template_type,
  sso_users!created_by(username)
`

// 查询评查点并关联父子分组
select: `
  id, code, name,
  child_group:evaluation_point_groups!fk_evaluation_points_group(id,name),
  parent_group:evaluation_point_groups!fk_evaluation_points_parent_group(id,name)
`

使用场景:

文档类型查询（关联入口模块）
提示词模板查询（关联创建者信息）
评查点查询（关联父子分组）
合同模板查询（关联分类信息）

2. 过滤查询（Filtering）

使用示例:

// 精确匹配
filter: { 'id': 'eq.123' }

// 模糊搜索
filter: { 'name': 'ilike.*关键词*' }

// 数组包含（in）
filter: { 'id': 'in.(1,2,3)' }

// JSONB 数组包含（cs）
filter: { 'areas': 'cs.{"梅州"}' }

// 大于等于
filter: { 'status': 'gte.0' }

// NULL 判断
filter: { 'deleted_at': 'is.null' }

3. OR 条件查询

使用示例:

// 多字段模糊搜索
or: [
  { name: 'ilike.*关键词*' },
  { code: 'ilike.*关键词*' }
]

// 或者使用字符串格式
or: `(title.ilike.*关键词*,description.ilike.*关键词*)`

4. 分页与排序

使用示例:

// 分页
limit: 10,
offset: (page - 1) * 10,

// 排序
order: 'created_at.desc',
order: 'sort_order.asc,name.asc',

// 获取总数
headers: {
  'Prefer': 'count=exact'
}

5. RPC 函数调用

使用示例:

// 调用存储过程
await postgrestPost(
  'rpc/documents_get_document_history',
  {
    p_document_name: documentName,
    p_user_id: parseInt(userId, 10),
    p_exclude_id: excludeId
  },
  token
);

⚠️ 注意事项

1. 数据提取

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

function extractApiData<T>(responseData: unknown): T | null {
  if (!responseData) return null;

  // 格式1: { code: number, msg: string, data: T }
  if (typeof responseData === 'object' && responseData !== null &&
      'code' in responseData && 'data' in responseData) {
    return (responseData as { data: T }).data;
  }

  // 格式2: 直接是数据对象
  return responseData as T;
}

2. JWT 认证

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

const params: PostgrestParams = {
  // ... 其他参数
  token: frontendJWT
};

3. 错误处理

统一的错误处理模式：

const response = await postgrestGet(...);

if (response.error) {
  return { error: response.error, status: response.status };
}

const data = extractApiData<T>(response.data);
if (!data) {
  return { error: '获取数据失败', status: 500 };
}

4. 用户权限控制

大多数更新/删除操作都会检查 user_id 确保用户只能操作自己的数据
省级管理员（provincial_admin）可以查看所有地区的数据
普通用户只能查看自己地区的数据

🔄 混合使用情况

部分模块同时使用了 PostgREST 和后端 API：

模块	PostgREST	后端 API
文档管理	✅ 单个文档查询、更新、删除	✅ 文档列表查询
首页统计	✅ 入口模块查询	✅ 统计数据查询
文件上传	✅ 文档类型、状态查询	✅ 文件上传操作
交叉评查	✅ 文档状态更新	✅ 任务和意见管理

📝 更新记录

日期	说明
2025-11-24	初始版本，整理完整的 PostgREST 使用清单

文档维护: 当添加新的 PostgREST 请求时，请及时更新此文档。

22 KiB Raw Permalink Blame History Unescape Escape

PostgREST 请求模块完整清单

📚 目录

API 模块

1. 首页与统计

使用的 PostgREST 函数

主要功能

2. 认证服务

使用的 PostgREST 函数

主要功能

3. 文档管理

使用的 PostgREST 函数

主要功能

4. 文件上传

使用的 PostgREST 函数

主要功能

5. 评查点管理

使用的 PostgREST 函数

主要功能

6. 评查点分组

使用的 PostgREST 函数

主要功能

7. 评查文件审核

使用的 PostgREST 函数

主要功能

8. 评审结果

使用的 PostgREST 函数

主要功能

9. 文档类型

使用的 PostgREST 函数

主要功能

10. 入口模块

使用的 PostgREST 函数

主要功能

11. 交叉评查

使用的 PostgREST 函数

主要功能

12. 提示词模板

使用的 PostgREST 函数

主要功能

13. 系统配置

使用的 PostgREST 函数

主要功能

14. 合同模板

使用的 PostgREST 函数

主要功能

路由模块

15. 评查点编辑页面

使用的 PostgREST 函数

主要功能

📊 统计信息

模块统计

数据库表统计

PostgREST 操作统计

🔧 PostgREST 使用特性

1. 资源嵌入（Resource Embedding）

2. 过滤查询（Filtering）

3. OR 条件查询

4. 分页与排序

5. RPC 函数调用

⚠️ 注意事项

1. 数据提取

2. JWT 认证

3. 错误处理

4. 用户权限控制

🔄 混合使用情况

📝 更新记录

22 KiB

Raw Permalink Blame History