TanWenyan/leaudit-platform-frontend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
leaudit-platform-frontend/docs/contract-drafting-implementation-summary.md
T
LiangShiyong 3d1dbb3f97 all in
2025-12-05 00:09:32 +08:00

13 KiB
Raw Permalink Blame History

合同起草功能实施总结

实施概览

实施时间：2025-01-04 方案：方案B - CollaboraViewer 实时替换 状态：✅ 基础功能已完成

已完成工作

✅ 阶段一：数据库设计

文件：database/migrations/001_create_drafted_contracts.sql

  1. ✅ 创建 drafted_contracts 表

    • 字段完整，包含草稿ID、模板ID、文件路径、标题、占位符值等
    • 添加索引优化查询性能
    • 创建更新时间触发器

  2. ✅ 扩展 contract_templates 表

    • 添加 placeholder_schema 字段（JSONB类型）
    • 用于存储占位符配置

SQL 示例：

CREATE TABLE drafted_contracts (
  id SERIAL PRIMARY KEY,
  template_id INTEGER NOT NULL,
  file_path TEXT NOT NULL,
  title TEXT NOT NULL,
  placeholder_values JSONB DEFAULT '{}'::jsonb,
  status TEXT DEFAULT 'draft' CHECK (status IN ('draft', 'completed', 'archived')),
  created_by INTEGER,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

✅ 阶段二：类型定义和后端服务

1. 类型定义

文件：app/types/contract-draft.ts

定义了完整的 TypeScript 类型：

  • PlaceholderField - 占位符字段配置
  • PlaceholderSchema - 占位符Schema
  • DraftedContract - 草稿记录
  • CreateDraftRequest/Response - API 请求响应类型

2. 后端服务

文件：app/api/contracts/draft-service.server.ts

实现了核心业务逻辑：

  • ✅ copyTemplateFile - 复制模板文件（当前为临时实现，需要后续完善 MinIO 集成）
  • ✅ createDraftContract - 创建草稿记录
  • ✅ updatePlaceholders - 更新占位符值
  • ✅ completeDraft - 完成起草
  • ✅ getDraftById - 获取草稿详情
  • ✅ getDraftsByUser - 获取用户草稿列表

3. API 路由

创建了 3 个 API 端点：

a. 创建草稿 API

  • 文件：app/routes/api.contracts.draft.tsx
  • 方法：POST
  • 路径：/api/contracts/draft

b. 更新占位符 API

  • 文件：app/routes/api.contracts.draft.$id.placeholders.tsx
  • 方法：PUT
  • 路径：/api/contracts/draft/:id/placeholders

c. 完成起草 API

  • 文件：app/routes/api.contracts.draft.$id.complete.tsx
  • 方法：POST
  • 路径：/api/contracts/draft/:id/complete

✅ 阶段三：前端组件开发

1. 占位符表单组件

文件：app/components/contracts/PlaceholderForm.tsx

功能：

  • ✅ 动态渲染表单字段（根据 placeholder_schema）
  • ✅ 按分组显示字段（甲方信息、乙方信息、合同条款等）
  • ✅ 支持多种字段类型（text, number, date, tel, textarea）
  • ✅ 必填字段验证
  • ✅ 操作按钮：
    • 一键替换占位符
    • 保存草稿
    • 完成起草

关键特性：

  • 实时同步表单值
  • 加载状态提示
  • 必填字段校验
  • 美观的UI设计

2. 起草页面

文件：app/routes/contract-draft.$draftId.tsx

布局：

  • 左侧（60%）：FilePreview 组件 - 实时预览文档
  • 右侧（40%）：PlaceholderForm 组件 - 填写表单

功能：

  • ✅ 加载草稿和模板数据
  • ✅ 批量替换占位符
    • 调用 CollaboraViewer 的 replaceAll 方法
    • 逐个替换占位符（带延迟避免冲突）
    • 显示替换进度
  • ✅ 保存草稿到数据库
  • ✅ 完成起草（必填字段校验）
  • ✅ 返回按钮（带确认）

关键代码：

const handleBatchReplace = async () => {
  const collaboraRef = filePreviewRef.current?.collaboraViewerRef?.current;

  for (const [key, value] of Object.entries(placeholderValues)) {
    if (value) {
      const placeholder = `{{${key}}}`;
      await collaboraRef.unoCommands.replaceAll(placeholder, value);
      await new Promise(resolve => setTimeout(resolve, 100));
    }
  }
};

3. 模板详情页增强

文件：app/routes/contract-template.detail.$id.tsx

修改内容：

  • ✅ 添加 useState 管理起草状态
  • ✅ 实现 handleStartDraft 函数
    • 提示用户输入标题
    • 调用创建草稿 API
    • 跳转到起草页面
  • ✅ 添加"起草合同"按钮（主要操作按钮）
  • ✅ 添加加载状态和错误处理

按钮布局：

[起草合同] [下载模板] [在线预览]
   主按钮      次要按钮    次要按钮

✅ 阶段四：CollaboraViewer 功能完善

文件：app/components/collabora/hooks.ts

增强内容：

  • ✅ 添加 replaceAll 方法到 useCollaboraUnoCommands hook
  • ✅ 导入 unoReplaceAll 函数
  • ✅ 实现异步替换逻辑
  • ✅ 添加延迟避免 Collabora 响应冲突

导出的 API：

{
  scrollToTop: () => Promise<void>;
  replaceAll: (searchText: string, replaceText: string) => Promise<void>;
}

技术架构总结

数据流

1. 用户点击"起草合同"
   ↓
2. 创建草稿 API（POST /api/contracts/draft）
   - 复制模板文件
   - 创建 drafted_contracts 记录
   ↓
3. 跳转到起草页面（/contract-draft/:id）
   - 加载草稿和模板数据
   ↓
4. 用户填写表单
   ↓
5. 点击"一键替换"
   - 调用 CollaboraViewer.replaceAll
   - 批量替换占位符
   ↓
6. 点击"保存草稿"（PUT /api/contracts/draft/:id/placeholders）
   - 保存占位符值到数据库
   ↓
7. 点击"完成起草"（POST /api/contracts/draft/:id/complete）
   - 验证必填字段
   - 更新状态为 completed
   - 跳转回模板列表

文件结构

docreview/
├── database/
│   └── migrations/
│       └── 001_create_drafted_contracts.sql       # 数据库迁移脚本
├── app/
│   ├── types/
│   │   └── contract-draft.ts                       # 类型定义
│   ├── api/
│   │   └── contracts/
│   │       └── draft-service.server.ts             # 后端服务
│   ├── routes/
│   │   ├── api.contracts.draft.tsx                 # 创建草稿 API
│   │   ├── api.contracts.draft.$id.placeholders.tsx # 更新占位符 API
│   │   ├── api.contracts.draft.$id.complete.tsx    # 完成起草 API
│   │   ├── contract-draft.$draftId.tsx             # 起草页面
│   │   └── contract-template.detail.$id.tsx        # 模板详情页（已修改）
│   ├── components/
│   │   ├── contracts/
│   │   │   └── PlaceholderForm.tsx                 # 占位符表单组件
│   │   ├── collabora/
│   │   │   └── hooks.ts                            # Collabora hooks（已增强）
│   │   └── reviews/
│   │       └── FilePreview.tsx                      # 文件预览组件
└── docs/
    ├── contract-drafting-solution.md               # 方案对比
    ├── contract-drafting-implementation-checklist.md # 实施清单
    ├── contract-drafting-usage-guide.md            # 使用指南
    └── contract-drafting-implementation-summary.md # 实施总结（本文档）

待完成工作

🔲 高优先级

  1. MinIO 文件复制实现

    • 当前 copyTemplateFile 只是临时返回路径
    • 需要实现真正的文件复制逻辑
    • 使用 MinIO SDK 进行文件操作

  2. 数据库迁移执行

    • 执行 001_create_drafted_contracts.sql
    • 为测试模板配置 placeholder_schema

  3. 错误处理完善

    • 网络错误提示
    • 文件加载失败处理
    • 替换失败回滚

🔲 中优先级

  1. 草稿列表页面

    • 路由：/contracts/drafts
    • 显示用户的所有草稿
    • 支持筛选和搜索

  2. 样式优化

    • 占位符表单样式
    • 起草页面布局优化
    • 响应式设计

  3. 测试

    • 功能测试
    • 边界情况测试
    • 性能测试

🔲 低优先级

  1. 增强功能
    • 草稿历史版本
    • 导出为 PDF
    • 审批流程集成
    • 电子签名集成

测试检查清单

功能测试

  • 创建草稿流程

    • 点击"起草合同"按钮
    • 输入标题
    • 成功创建并跳转

  • 占位符替换

    • 填写表单字段
    • 点击"一键替换"
    • 验证文档中的占位符已替换

  • 保存草稿

    • 填写部分字段
    • 点击"保存草稿"
    • 刷新页面，验证数据已保存

  • 完成起草

    • 未填必填字段时提示错误
    • 填写完整后成功完成
    • 状态更新为 completed

  • 手动编辑

    • 使用 Collabora 编辑器修改文档
    • 验证编辑功能正常

部署步骤

1. 数据库迁移

# 连接到PostgreSQL数据库
psql -U postgres -d docreview

# 执行迁移脚本
\i database/migrations/001_create_drafted_contracts.sql

2. 配置测试模板

-- 为测试模板添加占位符配置
UPDATE contract_templates
SET placeholder_schema = '{
  "fields": [
    {"key": "甲方名称", "label": "甲方名称", "type": "text", "required": true, "group": "甲方信息"},
    {"key": "甲方地址", "label": "甲方地址", "type": "text", "required": true, "group": "甲方信息"},
    {"key": "甲方法定代表人", "label": "法定代表人", "type": "text", "required": true, "group": "甲方信息"},
    {"key": "甲方联系电话", "label": "联系电话", "type": "tel", "required": true, "group": "甲方信息"},
    {"key": "乙方名称", "label": "乙方名称", "type": "text", "required": true, "group": "乙方信息"},
    {"key": "乙方地址", "label": "乙方地址", "type": "text", "required": true, "group": "乙方信息"},
    {"key": "乙方法定代表人", "label": "法定代表人", "type": "text", "required": true, "group": "乙方信息"},
    {"key": "乙方联系电话", "label": "联系电话", "type": "tel", "required": true, "group": "乙方信息"},
    {"key": "合同金额", "label": "合同金额（元）", "type": "number", "required": true, "group": "合同条款"},
    {"key": "签订日期", "label": "签订日期", "type": "date", "required": true, "group": "合同条款"}
  ]
}'::jsonb
WHERE id = 1;  -- 根据实际模板ID调整

3. 准备测试模板文档

在 Word 中创建测试模板，包含以下占位符：

合同编号：______________

甲方（以下简称甲方）：{{甲方名称}}
地址：{{甲方地址}}
法定代表人：{{甲方法定代表人}}
联系电话：{{甲方联系电话}}

乙方（以下简称乙方）：{{乙方名称}}
地址：{{乙方地址}}
法定代表人：{{乙方法定代表人}}
联系电话：{{乙方联系电话}}

根据《中华人民共和国合同法》及有关法律、法规的规定，甲乙双方在平等、自愿的基础上，就以下事项达成一致，签订本合同。

一、合同标的
合同金额：人民币{{合同金额}}元（大写：________）

二、签订日期
本合同于{{签订日期}}签订。

4. 启动服务

npm run dev

5. 测试流程

  1. 访问 http://localhost:5173/contract-template
  2. 点击测试模板进入详情页
  3. 点击"起草合同"
  4. 填写表单并测试替换功能

关键技术点

1. CollaboraViewer 替换机制

使用 LibreOffice UNO 命令 .uno:ExecuteSearch 实现替换：

sendUnoCommand(iframeWindow, '.uno:ExecuteSearch', {
  'SearchItem.SearchString': { type: 'string', value: searchText },
  'SearchItem.ReplaceString': { type: 'string', value: replaceText },
  'SearchItem.Command': { type: 'long', value: SearchCommand.ReplaceAll },
  'SearchItem.SearchAll': { type: 'boolean', value: true },
  // ...
});

2. 异步批量替换

for (const [key, value] of Object.entries(placeholderValues)) {
  if (value) {
    await collaboraRef.unoCommands.replaceAll(`{{${key}}}`, value);
    await new Promise(resolve => setTimeout(resolve, 100)); // 延迟避免冲突
  }
}

3. JSONB 占位符配置

使用 PostgreSQL JSONB 类型存储灵活的配置：

{
  "fields": [
    {
      "key": "甲方名称",
      "label": "甲方名称",
      "type": "text",
      "required": true,
      "group": "甲方信息"
    }
  ]
}

成果展示

✅ 已实现的核心功能：

  1. ✅ 从模板创建草稿
  2. ✅ 动态表单渲染
  3. ✅ 批量替换占位符
  4. ✅ 实时文档预览
  5. ✅ 草稿保存
  6. ✅ 完成起草

预计开发时间：1天（实际已完成基础功能）

代码质量：

  • 类型安全（TypeScript）
  • 组件化设计
  • 错误处理
  • 代码注释完整

总结

合同起草功能的基础架构已经完成，核心功能可用。通过 CollaboraViewer 的实时替换机制，用户可以快速、便捷地基于模板创建新合同。

后续主要工作集中在完善 MinIO 文件复制、草稿管理列表页面以及各类边界情况的处理上。

整体架构清晰，代码质量良好，为后续功能扩展打下了坚实基础。

Reference in New Issue View Git Blame Copy Permalink