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,308 @@
+# 合同起草功能测试指南
+
+## 当前测试配置
+
+系统当前配置为使用测试文档进行占位符提取测试，无需真实的数据库记录。
+
+### 测试文档
+
+- **文件路径**: `public/testWork/买卖合同 (1).docx`
+- **包含占位符**: 18个
+- **占位符格式**: `{{占位符名称}}`
+
+### 提取的占位符列表
+
+| 序号 | 占位符 | 类型 | 分组 | 必填 |
+|------|--------|------|------|------|
+| 1 | 地市名称 | text | 基本信息 | 是 |
+| 2 | 合同名称 | text | 基本信息 | 是 |
+| 3 | 合同编号 | text | 基本信息 | 是 |
+| 4 | 项目编号 | text | 基本信息 | 是 |
+| 5 | 市名 | text | 基本信息 | 是 |
+| 6 | 区名 | text | 基本信息 | 是 |
+| 7 | 年 | text | 基本信息 | 是 |
+| 8 | 月 | text | 基本信息 | 是 |
+| 9 | 日 | text | 基本信息 | 是 |
+| 10 | 有效期限 | text | 基本信息 | 是 |
+| 11 | 甲方名称 | text | 甲方信息 | 是 |
+| 12 | 甲方注册地址 | textarea | 甲方信息 | 是 |
+| 13 | 甲方法定代表人 | text | 甲方信息 | 是 |
+| 14 | 甲方联系电话 | text | 甲方信息 | 是 |
+| 15 | 乙方名称 | text | 乙方信息 | 是 |
+| 16 | 乙方注册地址 | textarea | 乙方信息 | 是 |
+| 17 | 乙方法定代表人 | text | 乙方信息 | 是 |
+| 18 | 乙方联系电话 | text | 乙方信息 | 是 |
+
+## 测试步骤
+
+### 1. 启动开发服务器
+
+```bash
+npm run dev
+```
+
+访问地址：`http://localhost:5173`
+
+### 2. 访问草稿页面
+
+由于使用的是临时测试数据，可以直接访问任意草稿ID：
+
+```
+http://localhost:5173/contract-draft/1
+http://localhost:5173/contract-draft/999
+http://localhost:5173/contract-draft/test
+```
+
+任意ID都会加载测试文档。
+
+### 3. 验证占位符提取
+
+#### 查看控制台日志
+
+打开浏览器开发者工具（F12），查看 Console 标签，应该能看到：
+
+```
+[Loader] 使用测试文档: D:\remix_project\docreview\public\testWork\买卖合同 (1).docx
+[DOCX Parser] 开始读取文件: ...
+[DOCX Parser] 文档 XML 长度: 33378
+[DOCX Parser] 提取到的占位符: ["地市名称", "合同名称", ...]
+[Loader] 提取到的占位符: [...]
+[Loader] 生成的 schema: {...}
+```
+
+#### 验证表单渲染
+
+右侧应该显示占位符表单，包含以下分组：
+
+- **基本信息** (10个字段)
+- **甲方信息** (4个字段)
+- **乙方信息** (4个字段)
+
+### 4. 测试填写表单
+
+在右侧表单中填写测试数据，例如：
+
+**基本信息**：
+- 地市名称：广州市
+- 合同名称：设备采购合同
+- 合同编号：HT-2025-001
+- ...
+
+**甲方信息**：
+- 甲方名称：XX烟草公司
+- 甲方注册地址：广州市天河区...
+- 甲方法定代表人：张三
+- 甲方联系电话：020-12345678
+
+**乙方信息**：
+- 乙方名称：XX供应商
+- ...
+
+### 5. 测试一键替换功能
+
+#### ⚠️ 前置条件
+
+一键替换功能需要 **CollaboraViewer** 组件加载完成。当前系统中：
+
+- 如果文件是 **PDF**：使用 react-pdf 预览（不支持替换）
+- 如果文件是 **DOCX**：需要 Collabora Online 集成（尚未实现）
+
+**临时测试方法**：
+
+1. 点击"一键替换占位符"按钮
+2. 查看控制台输出，应该显示：
+
+```
+[Draft] 开始批量替换占位符: {...}
+[Draft] 替换: {{地市名称}} -> 广州市
+[Draft] 替换: {{合同名称}} -> 设备采购合同
+...
+```
+
+3. 如果 Collabora 未集成，会显示警告：
+   - "文档尚未加载完成，请稍候..."
+   - 或 "unoCommands.replaceAll 方法不可用"
+
+### 6. 测试导出文档
+
+点击"导出文档"按钮，应该：
+
+1. 显示"正在下载文件..."提示
+2. 浏览器触发文件下载
+3. 下载的文件名为：`买卖合同-测试草稿.docx`
+
+**注意**：当前导出的是原始模板文档，不包含替换后的内容（需要 Collabora 集成后才能保存修改）
+
+### 7. 测试完成起草
+
+点击"完成起草"按钮，应该：
+
+1. 先下载文件
+2. 延迟500ms后显示"草稿已删除"
+3. 自动跳转到 `/contract-template` 页面
+
+### 8. 测试返回按钮
+
+点击"返回"按钮，应该：
+
+1. 弹出确认对话框："确定要返回吗？草稿将被删除。"
+2. 点击确定后删除草稿
+3. 跳转到模板列表页
+
+## 测试要点
+
+### ✅ 应该正常工作的功能
+
+1. **占位符提取**
+   - 从测试文档中正确提取18个占位符
+   - 自动推测字段类型（text/textarea）
+   - 自动分组（基本信息/甲方信息/乙方信息）
+
+2. **表单渲染**
+   - 右侧显示分组表单
+   - 字段按组展示
+   - 输入框正常工作
+
+3. **文档预览**
+   - 左侧显示文档预览（需要 Collabora/react-pdf）
+   - 60% 宽度布局
+
+4. **导出功能**
+   - 可以下载原始文档
+
+5. **自动清理**
+   - 关闭页面时删除草稿记录（sendBeacon）
+   - 路由跳转时删除草稿记录（fetch keepalive）
+
+### ⚠️ 待实现的功能
+
+1. **文件替换**
+   - 需要集成 Collabora Online
+   - 参考 `docs/docxtemplater-placeholder-extraction.md` 中的集成计划
+
+2. **真实数据库操作**
+   - 当前使用临时模拟数据
+   - 后续需要连接真实的 `drafted_contracts` 表
+
+3. **MinIO 文件复制**
+   - `draft-service.server.ts` 中的 `copyMinioFile()` 待实现
+   - 参考 `docs/minio-file-copy-implementation.md`
+
+## 调试技巧
+
+### 查看提取的 Schema
+
+在浏览器控制台执行：
+
+```javascript
+// 获取 loader 数据
+const loaderData = window.__remixContext.state.loaderData;
+console.log('Placeholder Schema:', loaderData['routes/contract-draft.$draftId'].template.placeholder_schema);
+```
+
+### 查看占位符值
+
+```javascript
+// 在 React DevTools 中查找 ContractDraftPage 组件
+// 查看 placeholderValues state
+```
+
+### 测试占位符提取逻辑
+
+运行测试脚本：
+
+```bash
+node scripts/test-docx-parser.cjs
+```
+
+应该输出：
+
+```
+============================================================
+测试从 DOCX 文件提取占位符功能
+============================================================
+
+✅ 文件存在
+✅ 文件读取成功, 大小: 18.95 KB
+✅ PizZip 解压成功
+✅ document.xml 读取成功
+✅ XML 内容长度: 33378
+✅ 提取纯文本成功
+文本长度: 5047
+
+找到 18 个占位符:
+1. {{地市名称}}
+2. {{合同名称}}
+...
+```
+
+## 切换到真实数据
+
+当需要切换到真实数据库操作时，修改 `contract-draft.$draftId.tsx`:
+
+1. 取消注释第55-72行（获取草稿和模板）
+2. 删除第54-102行（临时测试代码）
+3. 从数据库中读取模板的 `file_path`
+4. 使用真实的 `file_path` 提取占位符
+
+```typescript
+// 恢复真实数据库查询
+const draft = await getDraftById(draftId, parseInt(userInfo.sub), jwt);
+const { postgrestGet } = await import('~/api/postgrest-client');
+const templateResult = await postgrestGet('contract_templates', {
+  select: '*',
+  filter: { id: `eq.${draft.template_id}` },
+  token: jwt
+});
+const template = templateResult.data[0];
+
+// 使用模板的真实文件路径
+const placeholders = await extractPlaceholdersFromDocx(template.file_path);
+```
+
+## 常见问题
+
+### Q1: 页面显示"草稿不存在"
+
+**原因**：真实数据库查询被注释了，但错误处理没更新
+
+**解决**：使用临时测试模式，任意ID都可以访问
+
+### Q2: 控制台报错"template is not defined"
+
+**原因**：修改后的代码中 template 变量已定义，不应该出现此错误
+
+**解决**：清除浏览器缓存，重新加载页面
+
+### Q3: "一键替换"点击无反应
+
+**原因**：Collabora Online 尚未集成
+
+**解决**：这是正常现象，查看控制台日志确认替换逻辑正常执行即可
+
+### Q4: 下载的文件没有替换内容
+
+**原因**：当前导出的是原始模板，Collabora 修改保存功能待实现
+
+**解决**：需要集成 Collabora Online 的保存功能
+
+## 总结
+
+✅ **已完成功能**：
+- 占位符自动提取
+- 智能类型推断
+- 表单动态渲染
+- 文档导出
+- 草稿自动清理
+
+⏳ **待完成功能**：
+- Collabora Online 集成
+- 文件内容替换保存
+- MinIO 文件复制
+- 真实数据库CRUD
+
+🎯 **下一步**：
+1. 测试占位符提取功能
+2. 验证表单渲染正确性
+3. 集成 Collabora Online（参考 `collabora-test` 项目）
+4. 实现文件替换和保存功能