# 文档版本管理 - 使用 documents Schema 部署指南

## 📋 文件说明

本次使用 **`documents` schema** 来组织所有文档版本管理相关的 RPC 函数。

**SQL 脚本位置**：`add_document_version_management_with_schema.sql`

---

## 🚀 快速部署（3步）

### 步骤1：在 Navicat 中执行 SQL 脚本

#### 方法A：通过查询窗口
1. 打开 Navicat，连接到你的 PostgreSQL 数据库
2. 点击 **"查询"** → **"新建查询"**
3. 打开 `add_document_version_management_with_schema.sql` 文件
4. 复制所有内容到查询窗口
5. **⚠️ 重要：将所有的 `authenticator` 替换为你的实际 PostgREST 用户名**
6. 点击 **"运行"** 按钮

#### 方法B：通过文件导入
1. 在 Navicat 中右键点击数据库
2. 选择 **"运行 SQL 文件"**
3. 选择 `add_document_version_management_with_schema.sql`
4. 点击 **"开始"**

### 步骤2：验证函数是否创建成功

在 Navicat 查询窗口执行：

```sql
-- 查看 documents schema 中的所有函数
SELECT proname, proargnames
FROM pg_proc p
JOIN pg_namespace n ON p.pronamespace = n.oid
WHERE n.nspname = 'documents';
```

**应该看到 3 个函数**：
- `get_latest_documents_with_version_info`
- `count_latest_documents_with_filters`
- `get_document_history`

### 步骤3：测试函数（可选）

```sql
-- 测试1：获取文档列表（假设用户ID为1）
SELECT * FROM documents.get_latest_documents_with_version_info(1, 1, 10);

-- 测试2：统计文档数量
SELECT documents.count_latest_documents_with_filters(1);
```

---

## 📁 Navicat 中查看函数

执行成功后，在 Navicat 左侧树形结构中：

```
你的数据库
  └─ 模式 (Schemas)
       ├─ public
       └─ documents ← 新创建的 schema
            ├─ 表
            └─ 函数 ← 3个新函数在这里
                 ├─ get_latest_documents_with_version_info
                 ├─ count_latest_documents_with_filters
                 └─ get_document_history
```

---

## ⚙️ PostgREST 配置

确保你的 PostgREST 配置文件包含 `documents` schema：

```conf
# /etc/postgrest/config (或其他配置文件路径)

# 添加 documents 到 db-schemas
db-schemas = "public, documents"

# 或者，如果之前没有配置，添加这一行
db-schemas = "public, documents"
```

修改配置后重启 PostgREST：
```bash
sudo systemctl restart postgrest
```

---

## 🔐 权限配置

### 查找你的 PostgREST 用户名

```sql
-- 方法1：查看所有数据库用户
SELECT usename FROM pg_user;

-- 方法2：查看当前连接用户
SELECT current_user;
```

**常见的 PostgREST 用户名**：
- `authenticator`
- `web_anon`
- `postgres`
- `api_user`

### 授权函数给用户

将下面的 `YOUR_POSTGREST_USER` 替换为你的实际用户名：

```sql
-- 授权 schema 使用权限
GRANT USAGE ON SCHEMA documents TO YOUR_POSTGREST_USER;

-- 授权函数执行权限
GRANT EXECUTE ON FUNCTION documents.get_latest_documents_with_version_info TO YOUR_POSTGREST_USER;
GRANT EXECUTE ON FUNCTION documents.count_latest_documents_with_filters TO YOUR_POSTGREST_USER;
GRANT EXECUTE ON FUNCTION documents.get_document_history TO YOUR_POSTGREST_USER;
```

---

## 🎯 前端代码已自动适配

前端代码已经修改为使用 `documents` schema：

```typescript
// app/api/files/documents.ts

// ✅ 已修改为：
postgrestPost('rpc/documents.get_latest_documents_with_version_info', ...)
postgrestPost('rpc/documents.count_latest_documents_with_filters', ...)
postgrestPost('rpc/documents.get_document_history', ...)
```

**无需手动修改前端代码！**

---

## 🧪 完整测试流程

### 1. 在 Navicat 中测试 SQL

```sql
-- 测试获取文档列表
SELECT * FROM documents.get_latest_documents_with_version_info(
  p_user_id := 1,
  p_page := 1,
  p_page_size := 10
);

-- 测试搜索功能
SELECT * FROM documents.get_latest_documents_with_version_info(
  p_user_id := 1,
  p_page := 1,
  p_page_size := 10,
  p_search_name := '合同'
);

-- 测试历史版本查询
SELECT * FROM documents.get_document_history('测试文档.pdf', 1, 123);
```

### 2. 测试 PostgREST API

```bash
# 测试获取文档列表
curl -X POST http://your-api-url/rpc/documents.get_latest_documents_with_version_info \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "p_user_id": 1,
    "p_page": 1,
    "p_page_size": 10
  }'
```

### 3. 测试前端页面

1. 重启应用：
   ```bash
   npm run build
   pm2 restart all
   ```

2. 访问文档列表页面：`http://your-domain/documents`

3. 检查功能：
   - ✅ 文档列表正常显示
   - ✅ 有历史版本的文档显示展开图标
   - ✅ 点击展开图标能看到历史版本
   - ✅ 问题数量差异正确显示（红色/绿色）

---

## ❌ 故障排查

### 问题1：函数未创建成功

**症状**：执行查询时提示 `function does not exist`

**解决方案**：
```sql
-- 检查 documents schema 是否存在
SELECT schema_name FROM information_schema.schemata WHERE schema_name = 'documents';

-- 如果不存在，手动创建
CREATE SCHEMA IF NOT EXISTS documents;

-- 重新执行 SQL 脚本
```

### 问题2：权限不足

**症状**：前端报错 `permission denied`

**解决方案**：
```sql
-- 检查当前用户权限
SELECT grantee, privilege_type
FROM information_schema.role_usage_grants
WHERE object_schema = 'documents';

-- 重新授权（替换 YOUR_USER 为实际用户）
GRANT USAGE ON SCHEMA documents TO YOUR_USER;
GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA documents TO YOUR_USER;
```

### 问题3：前端调用失败

**症状**：浏览器控制台报错 `404 Not Found`

**检查清单**：
1. PostgREST 配置是否包含 `documents` schema
2. PostgREST 是否已重启
3. 前端代码是否已更新并重新构建

**解决方案**：
```bash
# 1. 检查 PostgREST 配置
cat /etc/postgrest/config

# 2. 确保包含：
# db-schemas = "public, documents"

# 3. 重启 PostgREST
sudo systemctl restart postgrest

# 4. 重新构建前端
npm run build
pm2 restart all
```

---

## 📊 性能优化

SQL 脚本已自动创建以下索引：

```sql
-- 1. 用户+名称+时间索引
CREATE INDEX idx_documents_user_name_created
ON documents(user_id, name, created_at DESC);

-- 2. 名称+用户+时间索引
CREATE INDEX idx_documents_name_user_created
ON documents(name, user_id, created_at DESC);

-- 3. 创建时间索引
CREATE INDEX idx_documents_created_at
ON documents(created_at DESC);

-- 4. 文件状态索引
CREATE INDEX idx_documents_status
ON documents(status);
```

查看索引是否创建成功：
```sql
SELECT indexname, indexdef
FROM pg_indexes
WHERE tablename = 'documents'
AND schemaname = 'public';
```

---

## ✅ 部署检查清单

- [ ] SQL 脚本执行成功
- [ ] 3个函数都已创建在 `documents` schema 中
- [ ] 已授权给 PostgREST 用户
- [ ] PostgREST 配置已更新
- [ ] PostgREST 已重启
- [ ] 前端应用已重新构建
- [ ] 文档列表页面正常显示
- [ ] 展开/折叠功能正常工作
- [ ] 问题数量差异正确显示

---

## 🎉 完成！

部署完成后，你应该能看到：

```
文档列表页面
  ├─ [▶️] 📄 合同审查.pdf
  │         合同审查  v1 (共3个历史版本)
  │         问题数量：3 🟢 ↓ -2
  │
  ├─ [▶️] 📄 许可证申请.docx
  │         许可证审查  v1 (共2个历史版本)
  │         问题数量：5 🔴 ↑ +1
  │
  └─ 📄 新文档.pdf
            合同审查
            问题数量：4
```

点击展开图标后：
```
  [🔽] 📄 合同审查.pdf
          合同审查  v1 (共3个历史版本)
          问题数量：3 🟢 ↓ -2

    ├─ 🕒 v2 版本  (问题：5 🔴 ↑ +2)
    ├─ 🕒 v3 版本  (问题：3 🟢 ↓ -1)
    └─ 🕒 v4 版本 (最早)  (问题：4)
```

**功能完美运行！** 🚀