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
parent 7c47b11ec7
commit 3d6305376b
5 changed files with 3640 additions and 0 deletions
@@ -0,0 +1,675 @@
+# PostgREST 请求模块完整清单
+
+> 本文档记录了项目中所有直接使用 PostgREST 客户端发送请求的模块和函数。
+>
+> **更新时间**: 2025-11-24
+> **PostgREST 客户端位置**: `app/api/postgrest-client.ts`
+
+---
+
+## 📚 目录
+
+- [API 模块](#api-模块)
+  - [首页与统计](#1-首页与统计)
+  - [认证服务](#2-认证服务)
+  - [文档管理](#3-文档管理)
+  - [文件上传](#4-文件上传)
+  - [评查点管理](#5-评查点管理)
+  - [评查点分组](#6-评查点分组)
+  - [评查文件审核](#7-评查文件审核)
+  - [评审结果](#8-评审结果)
+  - [文档类型](#9-文档类型)
+  - [入口模块](#10-入口模块)
+  - [交叉评查](#11-交叉评查)
+  - [提示词模板](#12-提示词模板)
+  - [系统配置](#13-系统配置)
+  - [合同模板](#14-合同模板)
+- [路由模块](#路由模块)
+  - [评查点编辑页面](#15-评查点编辑页面)
+
+---
+
+## 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）
+
+**使用示例**:
+```typescript
+// 查询文档类型并关联入口模块
+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）
+
+**使用示例**:
+```typescript
+// 精确匹配
+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 条件查询
+
+**使用示例**:
+```typescript
+// 多字段模糊搜索
+or: [
+  { name: 'ilike.*关键词*' },
+  { code: 'ilike.*关键词*' }
+]
+
+// 或者使用字符串格式
+or: `(title.ilike.*关键词*,description.ilike.*关键词*)`
+```
+
+### 4. 分页与排序
+
+**使用示例**:
+```typescript
+// 分页
+limit: 10,
+offset: (page - 1) * 10,
+
+// 排序
+order: 'created_at.desc',
+order: 'sort_order.asc,name.asc',
+
+// 获取总数
+headers: {
+  'Prefer': 'count=exact'
+}
+```
+
+### 5. RPC 函数调用
+
+**使用示例**:
+```typescript
+// 调用存储过程
+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 响应：
+```typescript
+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 参数：
+```typescript
+const params: PostgrestParams = {
+  // ... 其他参数
+  token: frontendJWT
+};
+```
+
+### 3. 错误处理
+
+统一的错误处理模式：
+```typescript
+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 请求时，请及时更新此文档。