leaudit-platform-frontend/docs/PostgREST实际使用清单.md

# PostgREST 实际使用清单

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

---

## 📋 目录

- [实际使用的模块](#实际使用的模块)
  - [1. 认证服务](#1-认证服务)
  - [2. 首页与统计](#2-首页与统计)
  - [3. 文档管理](#3-文档管理)
  - [4. 文件上传](#4-文件上传)
  - [5. 评查点管理](#5-评查点管理)
  - [6. 评查点分组](#6-评查点分组)
  - [7. 评查文件审核](#7-评查文件审核)
  - [8. 评审结果](#8-评审结果)
  - [9. 文档类型](#9-文档类型)
  - [10. 入口模块](#10-入口模块)
  - [11. 交叉评查](#11-交叉评查)
  - [12. 提示词模板](#12-提示词模板)
  - [13. 合同模板](#13-合同模板)
  - [14. 评查点编辑页面](#14-评查点编辑页面)
- [排除列表](#排除列表)
- [统计数据](#统计数据)

---

## 实际使用的模块

### 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` 字段）
  ```typescript
  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` | 获取模板选项列表 |

#### 资源嵌入查询

```typescript
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 条件查询（多字段模糊搜索）
  ```typescript
  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 请求，删除数据 |

---

## ⚠️ 重要说明

### 权限控制差异

1. **严格用户权限控制**（通过 `user_id` 过滤）：
   - `documents.ts` 中的 CRUD 操作
   - `rules-files.ts` 中的审核状态更新

2. **跨用户访问**（无 `user_id` 过滤）：
   - `cross-checking` 模块（交叉评查需要）
   - `getDocumentWithNoUserId()` 函数

### 数据提取统一方式

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

```typescript
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 参数：

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

---

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