# 合同起草功能测试指南

## 当前测试配置

系统当前配置为使用测试文档进行占位符提取测试，无需真实的数据库记录。

### 测试文档

- **文件路径**: `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. 实现文件替换和保存功能