all in

2025-12-05 00:09:32 +08:00
parent bb3d22eabf
commit 3d1dbb3f97
214 changed files with 113060 additions and 1232 deletions
@@ -0,0 +1,282 @@
+# 文档版本管理功能 - 部署指南（使用函数名前缀）
+
+## 📋 方案说明
+
+使用 **函数名前缀 `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个函数已创建
+- [ ] 应用已重新构建和重启
+- [ ] 文档列表页面正常显示
+- [ ] 展开/折叠功能正常
+- [ ] 问题数量差异正确显示（红色/绿色）
+
+---
+
+## 🎉 完成！
+
+现在你可以：
+- ✅ 查看同名文档的版本历史
+- ✅ 展开/折叠历史版本
+- ✅ 对比问题数量变化
+- ✅ 享受高性能的版本管理功能
+
+**部署完成，开始使用吧！** 🚀