283 lines
6.1 KiB
Markdown
283 lines
6.1 KiB
Markdown
# 文档版本管理功能 - 部署指南（使用函数名前缀）
|
||
|
||
## 📋 方案说明
|
||
|
||
使用 **函数名前缀 `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个函数已创建
|
||
- [ ] 应用已重新构建和重启
|
||
- [ ] 文档列表页面正常显示
|
||
- [ ] 展开/折叠功能正常
|
||
- [ ] 问题数量差异正确显示（红色/绿色）
|
||
|
||
---
|
||
|
||
## 🎉 完成！
|
||
|
||
现在你可以：
|
||
- ✅ 查看同名文档的版本历史
|
||
- ✅ 展开/折叠历史版本
|
||
- ✅ 对比问题数量变化
|
||
- ✅ 享受高性能的版本管理功能
|
||
|
||
**部署完成，开始使用吧！** 🚀
|