309 lines
8.0 KiB
Markdown
309 lines
8.0 KiB
Markdown
# 合同起草功能测试指南
|
||
|
||
## 当前测试配置
|
||
|
||
系统当前配置为使用测试文档进行占位符提取测试，无需真实的数据库记录。
|
||
|
||
### 测试文档
|
||
|
||
- **文件路径**: `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. 实现文件替换和保存功能
|