# 文档版本管理功能 - 部署指南（使用函数名前缀）

## 📋 方案说明

使用 **函数名前缀 `documents_`** 来区分版本管理函数，无需创建 schema。

**3个新函数**：
- `documents_get_latest_documents_with_version_info` - 获取文档列表
- `documents_count_latest_documents_with_filters` - 统计文档总数
- `documents_get_document_history` - 获取历史版本

---

## 🚀 快速部署（2步）

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

#### 方法A：查询窗口
1. 打开 Navicat，连接到 PostgreSQL 数据库
2. 点击 **"查询"** → **"新建查询"**
3. 打开 `add_document_version_management.sql` 文件
4. 复制所有内容到查询窗口
5. 点击 **"运行"** ▶️ 按钮

#### 方法B：运行 SQL 文件
1. 右键点击数据库
2. 选择 **"运行 SQL 文件"**
3. 选择 `add_document_version_management.sql`
4. 点击 **"开始"**

### 步骤2：重启应用

```bash
npm run build
pm2 restart all
```

**就这么简单！** ✅

---

## 🔍 验证函数是否创建成功

在 Navicat 中执行：

```sql
-- 查看新创建的函数
SELECT proname
FROM pg_proc
WHERE proname LIKE 'documents_%';
```

**应该返回 3 个函数名**：
```
documents_get_latest_documents_with_version_info
documents_count_latest_documents_with_filters
documents_get_document_history
```

### 在 Navicat 中查看函数

```
你的数据库
  └─ public (schema)
       └─ 函数
            ├─ documents_get_latest_documents_with_version_info(...)
            ├─ documents_count_latest_documents_with_filters(...)
            └─ documents_get_document_history(...)
```

---

## 🧪 测试函数

在 Navicat 查询窗口执行：

```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);

-- 测试3：获取历史版本（如果有同名文档）
SELECT * FROM documents_get_document_history('测试文档.pdf', 1, 123);
```

---

## 📁 在 Navicat 中操作函数

### 查看函数定义
1. 在左侧树形结构中找到 `public` → `函数`
2. 找到 `documents_get_latest_documents_with_version_info`
3. 右键 → **"设计函数"** 或 **"查看 SQL"**

### 测试函数（图形界面）
1. 右键点击函数
2. 选择 **"执行函数"**
3. 输入参数值（如 `p_user_id: 1, p_page: 1, p_page_size: 10`）
4. 点击 **"运行"**

### 删除函数（如果需要重建）
```sql
DROP FUNCTION IF EXISTS documents_get_latest_documents_with_version_info;
DROP FUNCTION IF EXISTS documents_count_latest_documents_with_filters;
DROP FUNCTION IF EXISTS documents_get_document_history;

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

---

## ✅ 功能验证

### 1. 访问文档列表页面

打开浏览器：`http://your-domain/documents`

### 2. 检查显示效果

✅ **有历史版本的文档**：
```
[▶️] 📄 合同审查.pdf
        合同审查  v1 (共3个历史版本)
        问题数量：3 🟢 ↓ -2
```

✅ **单版本文档**：
```
📄 新文档.pdf
   合同审查
   问题数量：4
```

### 3. 测试展开功能

点击 [▶️] 图标，应该能看到：
```
[🔽] 📄 合同审查.pdf
        合同审查  v1 (共3个历史版本)
        问题数量：3 🟢 ↓ -2

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

---

## ❌ 故障排查

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

**症状**：查询不到函数

**解决**：
```sql
-- 检查是否有错误
-- 在 Navicat 的"消息"窗口查看错误信息

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

### 问题2：前端报错

**症状**：浏览器控制台显示 `function does not exist`

**解决**：
```bash
# 1. 确认函数已创建
# 在 Navicat 中执行：
SELECT proname FROM pg_proc WHERE proname LIKE 'documents_%';

# 2. 确认前端代码已更新
# 检查 app/api/files/documents.ts 中的函数名

# 3. 重新构建应用
npm run build
pm2 restart all
```

### 问题3：数据不显示

**症状**：页面显示空白或加载失败

**检查清单**：
- ✅ SQL 脚本是否执行成功
- ✅ 函数是否创建在 `public` schema 中
- ✅ 应用是否重启
- ✅ 浏览器控制台是否有错误

**解决方案**：
```bash
# 1. 检查 PostgREST 日志
journalctl -u postgrest -n 50

# 2. 检查应用日志
pm2 logs

# 3. 清除浏览器缓存
# 按 Ctrl + Shift + R (Windows) 或 Cmd + Shift + R (Mac)
```

---

## 📊 性能优化

SQL 脚本自动创建了 4 个索引来优化查询性能：

```sql
-- 1. 用户+名称+时间索引
idx_documents_user_name_created

-- 2. 名称+用户+时间索引
idx_documents_name_user_created

-- 3. 创建时间索引
idx_documents_created_at

-- 4. 文件状态索引
idx_documents_status
```

查看索引：
```sql
SELECT indexname, indexdef
FROM pg_indexes
WHERE tablename = 'documents';
```

---

## 🔐 权限配置（可选）

如果你使用了特定的 PostgREST 用户，需要授权：

```sql
-- 查看你的 PostgREST 用户名
SELECT usename FROM pg_user;

-- 授权函数（替换 'authenticator' 为实际用户名）
GRANT EXECUTE ON FUNCTION documents_get_latest_documents_with_version_info TO authenticator;
GRANT EXECUTE ON FUNCTION documents_count_latest_documents_with_filters TO authenticator;
GRANT EXECUTE ON FUNCTION documents_get_document_history TO authenticator;
```

---

## 📚 相关文档

- **SQL 脚本**：`add_document_version_management.sql`
- **完整技术文档**：`docs/文档版本管理设计方案.md`
- **UI 原型**：`docs/UI设计原型.html`

---

## ✅ 部署检查清单

- [ ] SQL 脚本执行成功
- [ ] 3个函数已创建
- [ ] 应用已重新构建和重启
- [ ] 文档列表页面正常显示
- [ ] 展开/折叠功能正常
- [ ] 问题数量差异正确显示（红色/绿色）

---

## 🎉 完成！

现在你可以：
- ✅ 查看同名文档的版本历史
- ✅ 展开/折叠历史版本
- ✅ 对比问题数量变化
- ✅ 享受高性能的版本管理功能

**部署完成，开始使用吧！** 🚀