leaudit-platform-frontend/docs/PostgREST使用情况-后端API替代建议.md

# PostgREST 使用情况及后端 API 替代建议

> **本文档详细列出所有正在使用的 PostgREST 请求**
> **排除"评查点详情"相关的必须保留功能**
> **标注建议改为后端 API 的模块**
>
> **更新时间**: 2025-11-25

---

## 📋 图例说明

| 标记 | 含义 |
|------|------|
| 🔄 | **强烈建议**改为后端 API |
| ⚠️ | **建议评估**是否改为后端 API |
| ✅ | **保留** PostgREST（技术原因或低优先级） |
| 🔒 | **必须保留** PostgREST（评查点详情相关） |

---

## 目录

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. [汇总统计](#汇总统计)

---

## 1. 认证服务

**文件**: `app/api/login/auth.server.ts`

### 1.1 用户信息同步 - `saveUserInfo()`

| 项目 | 内容 |
|------|------|
| **函数** | `saveUserInfo()` |
| **行号** | 551-681 |
| **PostgREST 操作** | `postgrestGet` + `postgrestPut` / `postgrestPost` |
| **表名** | `sso_users` |
| **功能** | OAuth 登录后将用户信息同步到本地数据库 |
| **调用位置** | `app/routes/callback.tsx` - OAuth 回调 |
| **建议** | 🔄 **改为后端 API** |

**详细说明**:
```typescript
// 当前实现：前端直接操作数据库
1. postgrestGet 查询用户是否存在（根据 sub）
2. 如果存在 → postgrestPut 更新用户信息
3. 如果不存在 → postgrestPost 插入新用户
```

**建议后端 API**:
```
POST /api/auth/sync-user
Body: { userInfo, userRole, area }
Response: { success, user_id, ... }
```

**优点**:
- ✅ 统一用户数据管理逻辑
- ✅ 避免前端直接操作用户表
- ✅ 更好的数据一致性保障

---

### 1.2 添加默认角色 - `addDefaultRole()`

| 项目 | 内容 |
|------|------|
| **函数** | `addDefaultRole()` |
| **行号** | 691-738 |
| **PostgREST 操作** | `postgrestGet` + `postgrestPost` |
| **表名** | `user_role` |
| **功能** | 为新用户自动添加默认角色（common） |
| **调用位置** | `saveUserInfo()` 内部调用 |
| **建议** | 🔄 **改为后端 API**（随 `saveUserInfo` 一起） |

**详细说明**:
```typescript
// 当前实现
1. postgrestGet 检查用户是否已有角色
2. 如果没有 → postgrestPost 添加角色
```

**建议**: 合并到 `/api/auth/sync-user` 接口中，后端自动处理

---

## 2. 首页与统计

**文件**: `app/api/home/home.ts`

### 2.1 获取入口模块 - `getEntryModules()`

| 项目 | 内容 |
|------|------|
| **函数** | `getEntryModules()` |
| **行号** | 232-371 |
| **PostgREST 操作** | `postgrestGet` × 2 |
| **表名** | `entry_modules` + `document_types` |
| **功能** | 获取用户可访问的入口模块及关联的文档类型 |
| **调用位置** | `app/routes/home.tsx` - 首页 |
| **建议** | 🔄 **改为后端 API** |

**详细说明**:
```typescript
// 当前实现
1. postgrestGet 查询 entry_modules（根据用户角色和地区过滤）
2. 对每个模块：postgrestGet 查询关联的 document_types
3. 前端进行地区启用状态过滤
```

**建议后端 API**:
```
GET /api/home/entry-modules?userRole={role}&userArea={area}
Response: {
  modules: [
    {
      id, name, description, path, areas,
      documentTypes: [...] // 已关联的文档类型
    }
  ]
}
```

**优点**:
- ✅ 减少多次数据库查询
- ✅ 后端统一处理权限逻辑
- ✅ 支持更复杂的业务规则

---

## 3. 文档管理

**文件**: `app/api/files/documents.ts`

### 3.1 获取单个文档 - `getDocument()`

| 项目 | 内容 |
|------|------|
| **函数** | `getDocument()` |
| **行号** | 286-331 |
| **PostgREST 操作** | `postgrestGet` + 内部调用多个查询 |
| **表名** | `documents` + `evaluation_results` + `document_types` |
| **功能** | 获取单个文档详情及评查结果统计 |
| **调用位置** | `home.tsx`, `documents.list.tsx`, `documents.edit.tsx` |
| **建议** | 🔄 **改为后端 API** |

**详细说明**:
```typescript
// 当前实现
1. postgrestGet 查询文档基本信息（documents 表）
2. 调用 getDocumentTypes() → postgrestGet 查询文档类型
3. 调用 getEvaluationResults() → postgrestGet 查询评查结果
4. 前端计算问题数量（issues）
5. 前端组装 DocumentUI 对象
```

**建议后端 API**:
```
GET /api/documents/{id}?userId={userId}
Response: {
  id, name, documentNumber, type, typeName,
  auditStatus, fileStatus, issues, // 后端计算
  uploadTime, pageCount, ...
}
```

**优点**:
- ✅ 一次请求获取所有数据
- ✅ 后端计算问题数量，提高性能
- ✅ 减少前端数据组装逻辑

---

### 3.2 获取文档（无用户限制） - `getDocumentWithNoUserId()`

| 项目 | 内容 |
|------|------|
| **函数** | `getDocumentWithNoUserId()` |
| **行号** | 339-383 |
| **PostgREST 操作** | `postgrestGet` + 内部调用多个查询 |
| **表名** | `documents` + `evaluation_results` + `document_types` |
| **功能** | 获取文档详情（跨用户查询，用于交叉评查） |
| **调用位置** | 交叉评查模块 |
| **建议** | 🔄 **改为后端 API** |

**建议后端 API**:
```
GET /api/documents/{id}/detail
Response: { ... } // 与 getDocument 类似，但无用户ID限制
```

---

### 3.3 更新文档 - `updateDocument()`

| 项目 | 内容 |
|------|------|
| **函数** | `updateDocument()` |
| **行号** | 393-458 |
| **PostgREST 操作** | `postgrestPut` |
| **表名** | `documents` |
| **功能** | 更新文档信息（文档编号、审核状态、备注等） |
| **调用位置** | `documents.edit.tsx` |
| **建议** | 🔄 **改为后端 API** |

**详细说明**:
```typescript
// 当前实现
postgrestPut('documents', {
  document_number, audit_status, is_test_document, remark
}, { id, user_id })
```

**建议后端 API**:
```
PUT /api/documents/{id}
Body: { documentNumber, auditStatus, isTest, remark }
Response: { success, updatedDocument }
```

**优点**:
- ✅ 后端可以添加业务逻辑（如状态变更日志）
- ✅ 统一权限校验
- ✅ 支持事务处理

---

### 3.4 删除文档 - `deleteDocument()`

| 项目 | 内容 |
|------|------|
| **函数** | `deleteDocument()` |
| **行号** | 242-279 |
| **PostgREST 操作** | `postgrestDelete` |
| **表名** | `documents` |
| **功能** | 删除文档（只能删除自己的文档） |
| **调用位置** | 文档列表操作 |
| **建议** | 🔄 **改为后端 API** |

**建议后端 API**:
```
DELETE /api/documents/{id}?userId={userId}
Response: { success }
```

**优点**:
- ✅ 后端可以执行级联删除（评查结果、文件存储等）
- ✅ 记录删除日志
- ✅ 更安全的权限控制

---

## 4. 文件上传

**文件**: `app/api/files/files-upload.ts`

### 4.1 获取当天文档列表 - `getTodayDocuments()`

| 项目 | 内容 |
|------|------|
| **函数** | `getTodayDocuments()` |
| **行号** | 440-524 |
| **PostgREST 操作** | `postgrestGet` |
| **表名** | `documents` |
| **功能** | 获取当天上传的文档列表（支持按文档类型过滤） |
| **调用位置** | `documents.list.tsx`, `files.upload.tsx`, `ReviewTabs.tsx` |
| **建议** | 🔄 **改为后端 API** |

**详细说明**:
```typescript
// 当前实现
postgrestGet('documents', {
  select: 'id, name, type_id, file_size, status, ...',
  filter: {
    'created_at': `gte.${today}`,
    'user_id': `eq.${userInfo.user_id}`,
    'type_id': `in.(${typeIds})` // 从 sessionStorage 读取
  },
  order: 'created_at.desc'
})
```

**建议后端 API**:
```
GET /api/documents/today?userId={userId}&typeIds={ids}
Response: {
  documents: [...]
}
```

**优点**:
- ✅ 后端可以优化查询性能
- ✅ 支持更复杂的筛选条件
- ✅ 统一日期范围逻辑

---

### 4.2 获取文档类型列表 - `getDocumentTypes()`

| 项目 | 内容 |
|------|------|
| **函数** | `getDocumentTypes()` |
| **行号** | 531-574 |
| **PostgREST 操作** | `postgrestGet` |
| **表名** | `document_types` |
| **功能** | 获取文档类型列表（支持动态过滤） |
| **调用位置** | `documents.list.tsx`, `files.upload.tsx` |
| **建议** | ⚠️ **建议评估** |

**详细说明**:
```typescript
// 当前实现
postgrestGet('document_types', {
  select: 'id, name',
  filter: { 'id': `in.(${typeIds})` } // 从 sessionStorage 读取
})
```

**建议**:
- 如果只是简单查询，可以保留 PostgREST
- 如果需要关联更多数据（如提示词配置），改为后端 API

---

### 4.3 获取文档状态 - `getDocumentsStatus()`

| 项目 | 内容 |
|------|------|
| **函数** | `getDocumentsStatus()` |
| **行号** | 583-658 |
| **PostgREST 操作** | `postgrestGet` × 2 |
| **表名** | `documents` + `contract_structure_comparison` |
| **功能** | 批量查询文档和合同附件的处理状态（用于轮询） |
| **调用位置** | `documents.list.tsx`, `files.upload.tsx`, `ReviewTabs.tsx` |
| **建议** | 🔄 **改为后端 API** |

**详细说明**:
```typescript
// 当前实现
1. postgrestGet('documents', { filter: { id: 'in.(1,2,3)' } })
2. postgrestGet('contract_structure_comparison', { filter: { id: 'in.(4,5)' } })
3. 前端合并结果
```

**建议后端 API**:
```
POST /api/documents/status
Body: { documentIds: [1,2,3], attachmentIds: [4,5] }
Response: {
  documents: [{ id, status }, ...]
}
```

**优点**:
- ✅ 一次请求获取所有状态
- ✅ 减少前端逻辑
- ✅ 支持 WebSocket 推送（未来优化）

---

## 5. 评查点管理

**文件**: `app/api/evaluation_points/rules.ts`

### 5.1 获取评查点列表 - `getRulesList()`

| 项目 | 内容 |
|------|------|
| **函数** | `getRulesList()` |
| **行号** | 182-408 |
| **PostgREST 操作** | `postgrestGet` × 2 |
| **表名** | `evaluation_points` + `evaluation_point_groups` |
| **功能** | 获取评查点列表（支持分页、排序、多条件筛选） |
| **调用位置** | `rules.list.tsx` |
| **建议** | 🔄 **改为后端 API** |

**详细说明**:
```typescript
// 当前实现
1. postgrestGet('evaluation_point_groups', ...) // 查询类型筛选
2. postgrestGet('evaluation_points', {
     select: `id, code, name,
       child_group:evaluation_point_groups!fk_evaluation_points_group(...),
       parent_group:evaluation_point_groups!fk_evaluation_points_parent_group(...)`
   }) // 使用资源嵌入查询父子分组
3. 前端进行地区过滤、编码清洗
```

**建议后端 API**:
```
GET /api/rules/list?page={p}&pageSize={ps}&type={t}&group={g}&status={s}&keyword={k}&area={a}
Response: {
  rules: [...],
  total: 100,
  page: 1,
  pageSize: 10
}
```

**优点**:
- ✅ 简化复杂的资源嵌入查询
- ✅ 后端处理地区过滤和编码清洗
- ✅ 更好的查询性能优化

---

### 5.2 获取单个评查点 - `getRule()`

| 项目 | 内容 |
|------|------|
| **函数** | `getRule()` |
| **行号** | 409-502 |
| **PostgREST 操作** | `postgrestGet` × 2 |
| **表名** | `evaluation_points` + `evaluation_point_groups` |
| **功能** | 获取单个评查点详情 |
| **调用位置** | 评查点编辑页面 |
| **建议** | 🔒 **必须保留**（评查点详情） |

**说明**: 这是评查点详情相关功能，必须使用 PostgREST

---

### 5.3 创建评查点 - `createRule()`

| 项目 | 内容 |
|------|------|
| **函数** | `createRule()` |
| **行号** | 503-563 |
| **PostgREST 操作** | `postgrestPost` |
| **表名** | `evaluation_points` |
| **功能** | 创建新的评查点 |
| **调用位置** | 评查点编辑页面 |
| **建议** | 🔒 **必须保留**（评查点详情） |

---

### 5.4 更新评查点 - `updateRule()`

| 项目 | 内容 |
|------|------|
| **函数** | `updateRule()` |
| **行号** | 564-624 |
| **PostgREST 操作** | `postgrestPut` |
| **表名** | `evaluation_points` |
| **功能** | 更新评查点 |
| **调用位置** | 评查点编辑页面 |
| **建议** | 🔒 **必须保留**（评查点详情） |

---

### 5.5 删除评查点 - `deleteRule()`

| 项目 | 内容 |
|------|------|
| **函数** | `deleteRule()` |
| **行号** | 625-739 |
| **PostgREST 操作** | `postgrestDelete` |
| **表名** | `evaluation_points` |
| **功能** | 删除评查点 |
| **调用位置** | 评查点列表 |
| **建议** | 🔒 **必须保留**（评查点详情） |

---

### 5.6 获取规则类型 - `getRuleTypes()`

| 项目 | 内容 |
|------|------|
| **函数** | `getRuleTypes()` |
| **行号** | 803-945 |
| **PostgREST 操作** | `postgrestGet` × 2 |
| **表名** | `document_types` + `evaluation_point_groups` |
| **功能** | 获取文档类型和评查点类型（用于筛选） |
| **调用位置** | `rules.list.tsx` |
| **建议** | 🔒 **必须保留**（评查点详情） |

---

### 5.7 根据类型获取规则组 - `getRuleGroupsByType()`

| 项目 | 内容 |
|------|------|
| **函数** | `getRuleGroupsByType()` |
| **行号** | 946-1078 |
| **PostgREST 操作** | `postgrestGet` |
| **表名** | `evaluation_point_groups` |
| **功能** | 根据文档类型ID获取规则组 |
| **调用位置** | `rules.list.tsx` |
| **建议** | 🔒 **必须保留**（评查点详情） |

---

### 5.8 获取评查点数据（编辑用） - `getEvaluationPoint()`

| 项目 | 内容 |
|------|------|
| **函数** | `getEvaluationPoint()` |
| **行号** | 1152-1202 |
| **PostgREST 操作** | `postgrestGet` |
| **表名** | `evaluation_points` |
| **功能** | 获取评查点数据（用于编辑页面） |
| **调用位置** | `rules.new.tsx` |
| **建议** | 🔒 **必须保留**（评查点详情） |

---

### 5.9 获取评查点组列表 - `getEvaluationPointGroups()`

| 项目 | 内容 |
|------|------|
| **函数** | `getEvaluationPointGroups()` |
| **行号** | 1203-1327 |
| **PostgREST 操作** | `postgrestGet` |
| **表名** | `evaluation_point_groups` |
| **功能** | 获取所有评查点组（用于下拉选择） |
| **调用位置** | `rules.new.tsx` |
| **建议** | 🔒 **必须保留**（评查点详情） |

---

### 5.10 保存评查点 - `saveEvaluationPoint()`

| 项目 | 内容 |
|------|------|
| **函数** | `saveEvaluationPoint()` |
| **行号** | 1328+ |
| **PostgREST 操作** | `postgrestPut` / `postgrestPost` |
| **表名** | `evaluation_points` |
| **功能** | 保存评查点（新建或更新） |
| **调用位置** | `rules.new.tsx` |
| **建议** | 🔒 **必须保留**（评查点详情） |

---

## 6. 评查点分组

**文件**: `app/api/evaluation_points/rule-groups.ts`

### 6.1 获取顶级分组 - `getRuleGroups()`

| 项目 | 内容 |
|------|------|
| **函数** | `getRuleGroups()` |
| **行号** | 74-145 |
| **PostgREST 操作** | `postgrestGet` |
| **表名** | `evaluation_point_groups` |
| **功能** | 获取顶级评查点分组列表 |
| **调用位置** | `rule-groups._index.tsx` |
| **建议** | 🔒 **必须保留**（评查点详情） |

---

### 6.2 获取子分组 - `getChildGroups()`

| 项目 | 内容 |
|------|------|
| **函数** | `getChildGroups()` |
| **行号** | 146-245 |
| **PostgREST 操作** | `postgrestGet` × 2 |
| **表名** | `evaluation_point_groups` + `evaluation_points` |
| **功能** | 获取子分组列表及评查点数量 |
| **调用位置** | `rule-groups._index.tsx` |
| **建议** | 🔒 **必须保留**（评查点详情） |

---

### 6.3 获取所有分组（树形） - `getAllRuleGroups()`

| 项目 | 内容 |
|------|------|
| **函数** | `getAllRuleGroups()` |
| **行号** | 246-330 |
| **PostgREST 操作** | `postgrestGet` × 多次 |
| **表名** | `evaluation_point_groups` + `evaluation_points` |
| **功能** | 获取所有分组并构建树形结构 |
| **调用位置** | `document-types.new.tsx` |
| **建议** | 🔒 **必须保留**（评查点详情） |

---

### 6.4 获取单个分组 - `getRuleGroup()`

| 项目 | 内容 |
|------|------|
| **函数** | `getRuleGroup()` |
| **行号** | 331-429 |
| **PostgREST 操作** | `postgrestGet` × 2 |
| **表名** | `evaluation_point_groups` + `evaluation_points` |
| **功能** | 获取单个分组详情及评查点数量 |
| **调用位置** | `rule-groups.new.tsx` |
| **建议** | 🔒 **必须保留**（评查点详情） |

---

### 6.5 创建分组 - `createRuleGroup()`

| 项目 | 内容 |
|------|------|
| **函数** | `createRuleGroup()` |
| **行号** | 430-513 |
| **PostgREST 操作** | `postgrestPost` |
| **表名** | `evaluation_point_groups` |
| **功能** | 创建新的评查点分组 |
| **调用位置** | `rule-groups.new.tsx` |
| **建议** | 🔒 **必须保留**（评查点详情） |

---

### 6.6 更新分组 - `updateRuleGroup()`

| 项目 | 内容 |
|------|------|
| **函数** | `updateRuleGroup()` |
| **行号** | 514-576 |
| **PostgREST 操作** | `postgrestPut` |
| **表名** | `evaluation_point_groups` |
| **功能** | 更新评查点分组 |
| **调用位置** | `rule-groups.new.tsx` |
| **建议** | 🔒 **必须保留**（评查点详情） |

---

### 6.7 删除分组 - `deleteRuleGroup()`

| 项目 | 内容 |
|------|------|
| **函数** | `deleteRuleGroup()` |
| **行号** | 577+ |
| **PostgREST 操作** | `postgrestDelete` × 2 |
| **表名** | `evaluation_point_groups` + `evaluation_points` |
| **功能** | 删除分组（级联删除子分组和评查点） |
| **调用位置** | `rule-groups._index.tsx` |
| **建议** | 🔒 **必须保留**（评查点详情） |

---

## 7. 评查文件审核

**文件**: `app/api/evaluation_points/rules-files.ts`

### 7.1 更新文档审核状态 - `updateDocumentAuditStatus()`

| 项目 | 内容 |
|------|------|
| **函数** | `updateDocumentAuditStatus()` |
| **行号** | 118-167 |
| **PostgREST 操作** | `postgrestPut` |
| **表名** | `documents` |
| **功能** | 更新文件的审核状态（通过/不通过/警告） |
| **调用位置** | `documents.list.tsx`, `files.upload.tsx` |
| **建议** | 🔄 **改为后端 API** |

**详细说明**:
```typescript
// 当前实现
postgrestPut('documents',
  { audit_status: auditStatus },
  { id, user_id }
)
```

**建议后端 API**:
```
PUT /api/documents/{id}/audit-status
Body: { auditStatus, userId }
Response: { success }
```

**优点**:
- ✅ 后端可以记录审核日志
- ✅ 触发审核状态变更的业务逻辑
- ✅ 统一权限校验

---

## 8. 评审结果

**文件**: `app/api/evaluation_points/reviews.ts`

### 8.1 获取评查点列表 - `getReviewPoints()`

| 项目 | 内容 |
|------|------|
| **函数** | `getReviewPoints()` |
| **行号** | 132-750 |
| **PostgREST 操作** | `postgrestGet` × 6 |
| **表名** | `contract_structure_comparison`, `evaluation_results`, `evaluation_points`, `evaluation_point_groups`, `audit_status`, `cross_scoring_proposals` |
| **功能** | 获取文档的完整评查结果（关联 6 个表） |
| **调用位置** | `reviews.tsx`, `cross-checking.result.tsx` |
| **建议** | 🔄 **改为后端 API** |

**详细说明**:
```typescript
// 当前实现：复杂的多表关联查询
1. postgrestGet('contract_structure_comparison', ...) // 合同附件
2. postgrestGet('evaluation_results', ...) // 评查结果
3. postgrestGet('evaluation_points', ...) // 评查点
4. postgrestGet('evaluation_point_groups', ...) // 评查点组
5. postgrestGet('audit_status', ...) // 审核状态
6. postgrestGet('cross_scoring_proposals', ...) // 交叉提案
7. 前端复杂的数据组装和分组
```

**建议后端 API**:
```
GET /api/documents/{id}/review-points
Response: {
  reviewPoints: [
    {
      id, evaluationPointId, evaluationPointName,
      groupName, result, score,
      auditStatus, crossProposals, ...
    }
  ],
  groupedByCategory: {...}
}
```

**优点**:
- ✅ 大幅减少数据库查询（从 6 次到 1 次）
- ✅ 后端优化 JOIN 查询性能
- ✅ 简化前端数据处理逻辑
- ✅ 统一数据格式

---

### 8.2 更新评查结果 - `updateReviewResult()`

| 项目 | 内容 |
|------|------|
| **函数** | `updateReviewResult()` |
| **行号** | 751-894 |
| **PostgREST 操作** | `postgrestGet` + `postgrestPut` / `postgrestPost` |
| **表名** | `evaluation_results` + `audit_status` |
| **功能** | 更新评查结果和审核状态 |
| **调用位置** | `reviews.tsx` |
| **建议** | 🔄 **改为后端 API** |

**详细说明**:
```typescript
// 当前实现
1. postgrestGet('evaluation_results', ...) // 获取当前结果
2. postgrestPut('evaluation_results', ...) // 更新结果
3. 根据情况：
   - postgrestPut('audit_status', ...) // 更新审核状态
   - 或 postgrestPost('audit_status', ...) // 创建审核状态
```

**建议后端 API**:
```
PUT /api/review-results/{id}
Body: {
  evaluationResultId,
  evaluatedResult,
  evaluationOpinion,
  userOpinion,
  isReEvaluation
}
Response: { success, updatedResult }
```

**优点**:
- ✅ 事务处理，保证数据一致性
- ✅ 后端处理复杂的状态逻辑
- ✅ 记录修改历史

---

### 8.3 确认评查结果 - `confirmReviewResults()`

| 项目 | 内容 |
|------|------|
| **函数** | `confirmReviewResults()` |
| **行号** | 895+ |
| **PostgREST 操作** | `postgrestPut` |
| **表名** | `documents` |
| **功能** | 确认评查并更新文档状态 |
| **调用位置** | `reviews.tsx` |
| **建议** | 🔄 **改为后端 API** |

**建议后端 API**:
```
POST /api/documents/{id}/confirm-review
Response: { success }
```

**优点**:
- ✅ 后端可以执行确认后的业务逻辑
- ✅ 触发通知或工作流

---

## 9. 文档类型

**文件**: `app/api/document-types/document-types.ts`

### 9.1 获取所有评查点分组 - `getAllEvaluationPointGroups()`

| 项目 | 内容 |
|------|------|
| **函数** | `getAllEvaluationPointGroups()` |
| **行号** | 101-148 |
| **PostgREST 操作** | `postgrestGet` |
| **表名** | `evaluation_point_groups` |
| **功能** | 获取所有评查点分组（用于文档类型关联） |
| **调用位置** | `document-types.new.tsx` |
| **建议** | 🔒 **必须保留**（评查点详情） |

---

### 9.2 获取父级分组 - `getParentEvaluationPointGroups()`

| 项目 | 内容 |
|------|------|
| **函数** | `getParentEvaluationPointGroups()` |
| **行号** | 149-200 |
| **PostgREST 操作** | `postgrestGet` |
| **表名** | `evaluation_point_groups` |
| **功能** | 获取父级评查点分组 |
| **调用位置** | `document-types._index.tsx` |
| **建议** | 🔒 **必须保留**（评查点详情） |

---

### 9.3 获取入口模块 - `getEntryModules()`

| 项目 | 内容 |
|------|------|
| **函数** | `getEntryModules()` |
| **行号** | 201-244 |
| **PostgREST 操作** | `postgrestGet` |
| **表名** | `entry_modules` |
| **功能** | 获取入口模块列表（用于文档类型关联） |
| **调用位置** | `document-types.new.tsx` |
| **建议** | ⚠️ **建议评估** |

**说明**: 如果只是简单查询，可以保留；如果需要复杂业务逻辑，改为后端 API

---

### 9.4 获取文档类型列表 - `getDocumentTypes()`

| 项目 | 内容 |
|------|------|
| **函数** | `getDocumentTypes()` |
| **行号** | 311-465 |
| **PostgREST 操作** | `postgrestGet` |
| **表名** | `document_types` |
| **功能** | 获取文档类型列表（支持分页、筛选） |
| **调用位置** | `documents.list.tsx`, `document-types.new.tsx`, `document-types._index.tsx`, `documents.edit.tsx` |
| **建议** | 🔄 **改为后端 API** |

**详细说明**:
```typescript
// 当前实现
postgrestGet('document_types', {
  select: `id, name, description, ...,
    entry_modules!fk_document_types_entry_module(id,name)`, // 资源嵌入
  filter: { ... },
  order: '...',
  limit: pageSize,
  offset: offset
})
```

**建议后端 API**:
```
GET /api/document-types?page={p}&pageSize={ps}&name={n}&groupId={g}
Response: {
  types: [...],
  total: 100
}
```

**优点**:
- ✅ 简化资源嵌入查询
- ✅ 后端优化查询性能
- ✅ 支持更复杂的业务逻辑

---

### 9.5 删除文档类型 - `deleteDocumentType()`

| 项目 | 内容 |
|------|------|
| **函数** | `deleteDocumentType()` |
| **行号** | 466-559 |
| **PostgREST 操作** | `postgrestDelete` |
| **表名** | `document_types` |
| **功能** | 删除文档类型 |
| **调用位置** | `document-types._index.tsx` |
| **建议** | 🔄 **改为后端 API** |

**建议后端 API**:
```
DELETE /api/document-types/{id}
Response: { success }
```

**优点**:
- ✅ 后端可以检查是否有关联数据
- ✅ 执行级联删除或软删除
- ✅ 记录删除日志

---

### 9.6 获取单个文档类型 - `getDocumentType()`

| 项目 | 内容 |
|------|------|
| **函数** | `getDocumentType()` |
| **行号** | 560-654 |
| **PostgREST 操作** | `postgrestGet` |
| **表名** | `document_types` |
| **功能** | 获取单个文档类型详情 |
| **调用位置** | `document-types.new.tsx` |
| **建议** | ⚠️ **建议评估** |

**说明**: 简单查询，优先级较低

---

### 9.7 创建文档类型 - `createDocumentType()`

| 项目 | 内容 |
|------|------|
| **函数** | `createDocumentType()` |
| **行号** | 655-781 |
| **PostgREST 操作** | `postgrestPost` |
| **表名** | `document_types` |
| **功能** | 创建新的文档类型 |
| **调用位置** | `document-types.new.tsx` |
| **建议** | 🔄 **改为后端 API** |

**建议后端 API**:
```
POST /api/document-types
Body: { name, description, entryModuleId, groupIds, promptConfigs, ... }
Response: { success, id }
```

**优点**:
- ✅ 后端可以验证数据完整性
- ✅ 处理关联关系的创建
- ✅ 事务处理

---

### 9.8 更新文档类型 - `updateDocumentType()`

| 项目 | 内容 |
|------|------|
| **函数** | `updateDocumentType()` |
| **行号** | 782+ |
| **PostgREST 操作** | `postgrestPut` |
| **表名** | `document_types` |
| **功能** | 更新文档类型 |
| **调用位置** | `document-types.new.tsx` |
| **建议** | 🔄 **改为后端 API** |

**建议后端 API**:
```
PUT /api/document-types/{id}
Body: { ... }
Response: { success }
```

---

## 10. 入口模块

**文件**: `app/api/entry-modules/entry-modules.ts`

### 10.1 获取入口模块列表 - `getEntryModules()`

| 项目 | 内容 |
|------|------|
| **函数** | `getEntryModules()` |
| **行号** | 45-118 |
| **PostgREST 操作** | `postgrestGet` |
| **表名** | `entry_modules` |
| **功能** | 获取入口模块列表（支持分页、JSONB 数组查询） |
| **调用位置** | `entry-modules._index.tsx` |
| **建议** | 🔄 **改为后端 API** |

**详细说明**:
```typescript
// 当前实现：使用 JSONB 数组查询
postgrestGet('entry_modules', {
  filter: {
    name: 'ilike.*关键词*',
    areas: 'cs.{"梅州"}' // JSONB contains
  }
})
```

**建议后端 API**:
```
GET /api/entry-modules?page={p}&pageSize={ps}&name={n}&area={a}
Response: {
  modules: [...],
  total: 100
}
```

**优点**:
- ✅ 简化 JSONB 查询逻辑
- ✅ 后端优化查询性能

---

### 10.2 根据 ID 获取入口模块 - `getEntryModuleById()`

| 项目 | 内容 |
|------|------|
| **函数** | `getEntryModuleById()` |
| **行号** | 126-150 |
| **PostgREST 操作** | `postgrestGet` |
| **表名** | `entry_modules` |
| **功能** | 获取单个入口模块详情 |
| **调用位置** | `entry-modules.new.tsx` |
| **建议** | ✅ **保留**（简单查询） |

---

### 10.3 创建入口模块 - `createEntryModule()`

| 项目 | 内容 |
|------|------|
| **函数** | `createEntryModule()` |
| **行号** | 158-179 |
| **PostgREST 操作** | `postgrestPost` |
| **表名** | `entry_modules` |
| **功能** | 创建新的入口模块 |
| **调用位置** | `entry-modules.new.tsx` |
| **建议** | 🔄 **改为后端 API** |

---

### 10.4 更新入口模块 - `updateEntryModule()`

| 项目 | 内容 |
|------|------|
| **函数** | `updateEntryModule()` |
| **行号** | 188-211 |
| **PostgREST 操作** | `postgrestPut` |
| **表名** | `entry_modules` |
| **功能** | 更新入口模块 |
| **调用位置** | `entry-modules.new.tsx` |
| **建议** | 🔄 **改为后端 API** |

---

### 10.5 删除入口模块 - `deleteEntryModule()`

| 项目 | 内容 |
|------|------|
| **函数** | `deleteEntryModule()` |
| **行号** | 219-242 |
| **PostgREST 操作** | `postgrestDelete` |
| **表名** | `entry_modules` |
| **功能** | 删除入口模块 |
| **调用位置** | `entry-modules._index.tsx` |
| **建议** | 🔄 **改为后端 API** |

---

## 11. 交叉评查

**文件**: `app/api/cross-checking/`

### 11.1 更新文档审核状态 - `updateDocumentAuditStatus()`

**文件**: `cross-files.ts`

| 项目 | 内容 |
|------|------|
| **函数** | `updateDocumentAuditStatus()` |
| **行号** | 476-507 |
| **PostgREST 操作** | `postgrestPut` |
| **表名** | `documents` |
| **功能** | 更新文件的审核状态（交叉评查场景） |
| **调用位置** | `cross-checking` 相关页面 |
| **建议** | 🔄 **改为后端 API** |

**说明**: 与 `rules-files.ts` 中的同名函数类似，建议统一改为后端 API

---

### 11.2 查找是否是发起人 - `findIsProposer()`

**文件**: `cross-file-result.ts`

| 项目 | 内容 |
|------|------|
| **函数** | `findIsProposer()` |
| **行号** | 91-112 |
| **PostgREST 操作** | `postgrestGet` |
| **表名** | `cross_examination_tasks` |
| **功能** | 判断当前用户是否是任务发起人 |
| **调用位置** | 交叉评查意见操作 |
| **建议** | 🔄 **改为后端 API** |

**建议后端 API**:
```
GET /api/cross-review/tasks/{taskId}/is-proposer?userId={userId}
Response: { isProposer: true/false }
```

**优点**:
- ✅ 后端统一权限判断逻辑
- ✅ 可以扩展更复杂的权限规则

---

### 11.3 完成评查 - `confirmReviewResults()`

**文件**: `cross-file-result.ts`

| 项目 | 内容 |
|------|------|
| **函数** | `confirmReviewResults()` |
| **行号** | 359-394 |
| **PostgREST 操作** | `postgrestPut` |
| **表名** | `documents` |
| **功能** | 完成评查并更新文档审核状态为通过 |
| **调用位置** | `cross-checking.result.tsx` |
| **建议** | 🔄 **改为后端 API** |

**建议后端 API**:
```
POST /api/cross-review/documents/{id}/confirm
Response: { success }
```

---

## 12. 提示词模板

**文件**: `app/api/prompts/prompts.ts`

### 12.1 获取提示词模板列表 - `getPromptTemplates()`

| 项目 | 内容 |
|------|------|
| **函数** | `getPromptTemplates()` |
| **行号** | 127-232 |
| **PostgREST 操作** | `postgrestGet` |
| **表名** | `prompt_templates` |
| **功能** | 获取提示词模板列表（支持分页、筛选、关联创建者） |
| **调用位置** | `prompts._index.tsx` |
| **建议** | 🔄 **改为后端 API** |

**详细说明**:
```typescript
// 当前实现：使用资源嵌入查询创建者
postgrestGet('prompt_templates', {
  select: `id, template_name, ...,
    sso_users!created_by(username)`, // 资源嵌入
  filter: { ... },
  order: 'created_at.desc'
})
```

**建议后端 API**:
```
GET /api/prompts?page={p}&pageSize={ps}&name={n}&type={t}&status={s}
Response: {
  templates: [
    { id, name, type, status, createdBy, createdAt, ... }
  ],
  total: 100
}
```

**优点**:
- ✅ 简化资源嵌入查询
- ✅ 后端优化查询性能

---

### 12.2 获取单个提示词模板 - `getPromptTemplate()`

| 项目 | 内容 |
|------|------|
| **函数** | `getPromptTemplate()` |
| **行号** | 233-279 |
| **PostgREST 操作** | `postgrestGet` |
| **表名** | `prompt_templates` |
| **功能** | 获取单个提示词模板详情 |
| **调用位置** | `prompts.new.tsx` |
| **建议** | ✅ **保留**（简单查询） |

---

### 12.3 创建提示词模板 - `createPromptTemplate()`

| 项目 | 内容 |
|------|------|
| **函数** | `createPromptTemplate()` |
| **行号** | 280-359 |
| **PostgREST 操作** | `postgrestPost` |
| **表名** | `prompt_templates` |
| **功能** | 创建新的提示词模板 |
| **调用位置** | `prompts.new.tsx` |
| **建议** | 🔄 **改为后端 API** |

---

### 12.4 更新提示词模板 - `updatePromptTemplate()`

| 项目 | 内容 |
|------|------|
| **函数** | `updatePromptTemplate()` |
| **行号** | 360-458 |
| **PostgREST 操作** | `postgrestPut` |
| **表名** | `prompt_templates` |
| **功能** | 更新提示词模板 |
| **调用位置** | `prompts.new.tsx` |
| **建议** | 🔄 **改为后端 API** |

---

### 12.5 删除提示词模板 - `deletePromptTemplate()`

| 项目 | 内容 |
|------|------|
| **函数** | `deletePromptTemplate()` |
| **行号** | 459-499 |
| **PostgREST 操作** | `postgrestDelete` |
| **表名** | `prompt_templates` |
| **功能** | 删除提示词模板 |
| **调用位置** | `prompts._index.tsx` |
| **建议** | 🔄 **改为后端 API** |

---

### 12.6 获取提示词选项列表 - `getPromptTemplateOptions()`

| 项目 | 内容 |
|------|------|
| **函数** | `getPromptTemplateOptions()` |
| **行号** | 500+ |
| **PostgREST 操作** | `postgrestGet` |
| **表名** | `prompt_templates` |
| **功能** | 获取指定类型的模板选项（用于下拉选择） |
| **调用位置** | `document-types.new.tsx`, `rules.new.tsx` |
| **建议** | ✅ **保留**（简单查询，低优先级） |

---

## 13. 合同模板

**文件**: `app/api/contract-template/templates.ts`

### 13.1 获取合同分类 - `getContractCategories()`

| 项目 | 内容 |
|------|------|
| **函数** | `getContractCategories()` |
| **行号** | 76-105 |
| **PostgREST 操作** | `postgrestGet` |
| **表名** | `contract_categories` |
| **功能** | 获取所有合同分类 |
| **调用位置** | 合同模板页面 |
| **建议** | ✅ **保留**（简单查询） |

---

### 13.2 获取分类及模板数量 - `getContractCategoriesWithCount()`

| 项目 | 内容 |
|------|------|
| **函数** | `getContractCategoriesWithCount()` |
| **行号** | 106-169 |
| **PostgREST 操作** | `postgrestGet` × 多次 |
| **表名** | `contract_categories` + `contract_templates` |
| **功能** | 获取分类并统计每个分类的模板数量 |
| **调用位置** | `contract-template.list._index.tsx`, `contract-template.search._index.tsx` |
| **建议** | 🔄 **改为后端 API** |

**详细说明**:
```typescript
// 当前实现：多次查询
1. postgrestGet('contract_categories', ...) // 获取所有分类
2. 对每个分类：postgrestGet('contract_templates', { filter: { category_id } })
3. 前端统计数量
```

**建议后端 API**:
```
GET /api/contract-templates/categories-with-count
Response: {
  categories: [
    { id, name, count: 10 }
  ]
}
```

**优点**:
- ✅ 一次查询获取所有数据（使用 SQL JOIN + COUNT）
- ✅ 大幅提升性能

---

### 13.3 获取合同模板列表 - `getContractTemplates()`

| 项目 | 内容 |
|------|------|
| **函数** | `getContractTemplates()` |
| **行号** | 170-311 |
| **PostgREST 操作** | `postgrestGet` × 2 |
| **表名** | `contract_categories` + `contract_templates` |
| **功能** | 获取合同模板列表（支持分页、筛选、关键词搜索） |
| **调用位置** | `contract-template.list._index.tsx`, `contract-template.search.results.tsx` |
| **建议** | 🔄 **改为后端 API** |

**详细说明**:
```typescript
// 当前实现：复杂的 OR 条件查询
1. 如果有关键词：postgrestGet('contract_categories', { filter: { name: 'ilike.*关键词*' } })
2. postgrestGet('contract_templates', {
     select: `..., contract_categories!fk_contract_templates_category(...)`, // 资源嵌入
     or: `(title.ilike.*关键词*,description.ilike.*关键词*,template_code.ilike.*关键词*)` // OR 查询
   })
```

**建议后端 API**:
```
GET /api/contract-templates?page={p}&pageSize={ps}&category={c}&format={f}&keyword={k}&featured={f}
Response: {
  templates: [...],
  total: 100
}
```

**优点**:
- ✅ 简化复杂的 OR 条件查询
- ✅ 后端优化全文搜索
- ✅ 支持更高级的搜索功能

---

### 13.4 获取单个合同模板 - `getContractTemplate()`

| 项目 | 内容 |
|------|------|
| **函数** | `getContractTemplate()` |
| **行号** | 312-346 |
| **PostgREST 操作** | `postgrestGet` |
| **表名** | `contract_templates` |
| **功能** | 获取单个合同模板详情 |
| **调用位置** | `contract-template.detail.$id.tsx` |
| **建议** | ✅ **保留**（简单查询） |

---

### 13.5 搜索合同模板 - `searchContractTemplates()`

| 项目 | 内容 |
|------|------|
| **函数** | `searchContractTemplates()` |
| **行号** | 380+ |
| **PostgREST 操作** | 内部调用 `getContractTemplates()` |
| **功能** | 搜索合同模板（封装函数） |
| **调用位置** | `contract-template.search.results.tsx` |
| **建议** | 🔄 **改为后端 API**（随 `getContractTemplates` 一起） |

---

## 汇总统计

### 按建议分类

| 建议 | 数量 | 占比 |
|------|------|------|
| 🔄 **强烈建议改为后端 API** | 32 | 53% |
| 🔒 **必须保留**（评查点详情） | 17 | 28% |
| ✅ **保留** PostgREST | 8 | 13% |
| ⚠️ **建议评估** | 3 | 5% |
| **总计** | **60** | **100%** |

---

### 按模块分类

| 模块 | 🔄 改为 API | 🔒 必须保留 | ✅ 保留 | ⚠️ 评估 | 小计 |
|------|-----------|-----------|---------|---------|------|
| 认证服务 | 2 | 0 | 0 | 0 | 2 |
| 首页与统计 | 1 | 0 | 0 | 0 | 1 |
| 文档管理 | 4 | 0 | 0 | 0 | 4 |
| 文件上传 | 2 | 0 | 1 | 1 | 4 |
| 评查点管理 | 1 | 9 | 0 | 0 | 10 |
| 评查点分组 | 0 | 7 | 0 | 0 | 7 |
| 评查文件审核 | 1 | 0 | 0 | 0 | 1 |
| 评审结果 | 3 | 0 | 0 | 0 | 3 |
| 文档类型 | 5 | 2 | 0 | 2 | 9 |
| 入口模块 | 4 | 0 | 1 | 0 | 5 |
| 交叉评查 | 3 | 0 | 0 | 0 | 3 |
| 提示词模板 | 4 | 0 | 2 | 0 | 6 |
| 合同模板 | 3 | 0 | 2 | 0 | 5 |
| **总计** | **32** | **17** | **8** | **3** | **60** |

---

## 优先级建议

### 🔥 高优先级（建议立即改为后端 API）

1. **评审结果模块** - `getReviewPoints()` + `updateReviewResult()`
   - 理由：涉及 6 表关联查询，性能影响大

2. **文档管理模块** - `getDocument()` + `updateDocument()` + `deleteDocument()`
   - 理由：核心业务，使用频繁

3. **文档状态查询** - `getDocumentsStatus()`
   - 理由：轮询操作，频繁调用

4. **合同模板列表** - `getContractCategoriesWithCount()` + `getContractTemplates()`
   - 理由：多次查询，性能优化空间大

5. **认证服务** - `saveUserInfo()` + `addDefaultRole()`
   - 理由：安全性考虑，不应前端直接操作用户表

---

### ⚡ 中优先级

6. **评查点列表** - `getRulesList()`
   - 理由：复杂的资源嵌入查询

7. **文档类型管理** - CRUD 操作
   - 理由：涉及关联数据处理

8. **入口模块管理** - CRUD 操作
   - 理由：涉及 JSONB 查询

9. **提示词模板管理** - CRUD 操作
   - 理由：资源嵌入查询

---

### 🔽 低优先级

10. **简单查询操作**
    - 理由：性能影响小，可后续优化

---

## 建议的实施步骤

1. **Phase 1**: 高优先级模块（1-5）
2. **Phase 2**: 中优先级模块（6-9）
3. **Phase 3**: 低优先级模块（10）

每个 Phase 预计耗时：
- Phase 1: 2-3 周
- Phase 2: 2 周
- Phase 3: 1 周

---

**注意**: 评查点详情相关的 17 个函数必须保留 PostgREST，不应改为后端 API。