# Word合同模板系统任务规划文档

## 项目概述

### 需求总结
基于现有的学校管理系统，开发一个完整的Word合同模板系统，实现：
1. **模板管理**：上传Word文档作为合同模板，解析占位符并配置数据源
2. **合同分发**：支持内部员工分发和业务用户购买课程签约两种方式
3. **数据收集**：在微信小程序上完成签订数据收集
4. **文档生成**：通过队列异步生成填充数据后的完整Word文档

### 技术栈
- **后端**：PHP ThinkPHP框架
- **前端管理**：Vue3 + Element Plus
- **小程序**：UniApp
- **数据库**：MySQL
- **文档处理**：phpoffice/phpword
- **队列**：基于现有的workerman队列系统

## 系统架构分析

### 现有架构基础
根据代码分析，系统已具备：
- 基础的合同管理模块（ContractSign模型）
- 文档数据源配置模块（DocumentDataSourceConfig模型）
- 文档生成记录模块（DocumentGenerateLog模型）
- 队列处理系统（workerman）

### 核心数据流
```
Word模板上传 → 占位符解析 → 数据源配置 → 合同分发 → 小程序数据收集 → 队列生成文档
```

## 数据库设计确认

### 核心表结构（需要确认）

#### 1. school_contract（合同模板表）
```sql
CREATE TABLE `school_contract` (
  `id` int NOT NULL AUTO_INCREMENT COMMENT '合同编号',
  `contract_name` varchar(255) NOT NULL COMMENT '合同名称',
  `contract_template` text NOT NULL COMMENT '合同模板文件路径',
  `contract_status` varchar(50) NOT NULL COMMENT '合同状态',
  `contract_type` varchar(50) NOT NULL COMMENT '合同类型',
  `placeholder_config` text COMMENT '占位符配置JSON',
  `remarks` text COMMENT '合同备注',
  `created_at` timestamp DEFAULT CURRENT_TIMESTAMP,
  `updated_at` timestamp DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  `deleted_at` int NOT NULL DEFAULT '0',
  PRIMARY KEY (`id`)
);
```

#### 2. school_contract_sign（合同签署关系表）
```sql
CREATE TABLE `school_contract_sign` (
  `id` int NOT NULL AUTO_INCREMENT,
  `contract_id` int NOT NULL COMMENT '合同ID',
  `personnel_id` int NOT NULL COMMENT '人员ID',
  `type` tinyint NOT NULL DEFAULT '1' COMMENT '类型：1内部员工 2外部用户',
  `status` varchar(50) NOT NULL DEFAULT 'pending' COMMENT '签署状态',
  `sign_time` int DEFAULT NULL COMMENT '签署时间',
  `created_at` timestamp DEFAULT CURRENT_TIMESTAMP,
  `deleted_at` int NOT NULL DEFAULT '0',
  PRIMARY KEY (`id`)
);
```

#### 3. school_document_data_source_config（数据源配置表）
```sql
CREATE TABLE `school_document_data_source_config` (
  `id` int NOT NULL AUTO_INCREMENT,
  `contract_id` int NOT NULL COMMENT '合同ID',
  `placeholder` varchar(255) NOT NULL COMMENT '占位符',
  `table_name` varchar(100) COMMENT '数据表名',
  `field_name` varchar(100) COMMENT '字段名',
  `field_type` varchar(50) COMMENT '字段类型',
  `is_required` tinyint DEFAULT '0' COMMENT '是否必填',
  `default_value` text COMMENT '默认值',
  `created_at` timestamp DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`)
);
```

#### 4. school_document_generate_log（文档生成记录表）
```sql
CREATE TABLE `school_document_generate_log` (
  `id` int NOT NULL AUTO_INCREMENT,
  `user_type` int NOT NULL DEFAULT '0' COMMENT '人员类型1内部 2外部',
  `template_id` int NOT NULL COMMENT '模板ID',
  `user_id` int NOT NULL COMMENT '操作用户',
  `fill_data` text COMMENT '填充数据JSON',
  `generated_file` varchar(500) DEFAULT NULL COMMENT '生成文件路径',
  `status` enum('pending','processing','completed','failed') DEFAULT 'pending',
  `error_msg` text COMMENT '错误信息',
  `created_at` int NOT NULL DEFAULT '0',
  `completed_at` int DEFAULT '0',
  PRIMARY KEY (`id`)
);
```

## 功能模块设计

### 1. 模板管理模块
**功能**：
- Word模板上传
- 占位符自动解析
- 数据源配置界面
- 模板预览

**涉及页面**：
- 模板列表页
- 模板上传页
- 占位符配置页

### 2. 合同分发模块
**功能**：
- 内部员工分发
- 外部用户分发（购买课程支付成功后触发）
- 分发记录管理

**涉及页面**：
- 合同分发管理页
- 分发记录列表页

### 3. 数据收集模块（小程序端）
**功能**：
- 合同信息展示
- 表单数据收集
- 电子签名
- 数据提交

**涉及页面**：
- 合同详情页
- 数据填写页
- 签名页

### 4. 文档生成模块
**功能**：
- 队列任务处理
- Word文档生成
- 文件存储管理
- 生成状态跟踪

## 关键问题确认

### 🔴 数据库相关问题
1. **表名前缀**：现有代码中有些表是`school_`前缀，有些不是，请确认统一的命名规范？
这个问题school_就是前缀，我文档中的表名称有些是去掉前缀的。所以你在记录表名的时候需要忽略掉 shcool 这个前缀
2. **表结构完整性**：上述表结构是否完整？是否有遗漏的字段？
具体的你可以再详细查看数据库中的表结构，并确认是否完整。
3. **人员表关联**：`personnel_id`关联的是哪个表？表结构是什么？
   personnel_id来自两个表根据type和user_type来区分 1 是内部人员查询school_personnel表，2是外部人员查询school_customer_resources这个表

### 🔴 业务流程问题
1. **分发触发时机**：
   - 内部员工分发：是手动分发还是自动分发？
   手动触发
   - 外部用户分发：购买课程后如何自动触发合同分发？
   在用户支付成功以后进行合同分发现在php 后端在支付成功后会触发student 的事件。目前这里面只会分发合同。
2. **签名流程**：电子签名是手写签名还是电子印章？签名数据如何存储？
签名是前端端进行手写签名，签名图片的 url 应该存在数据库中，生成签名前要将签名上传至服务器。
3. **数据收集范围**：除了占位符数据，还需要收集哪些额外信息？
占位符的数据的来源分两种类型，一种是从数据库中获取，另一种是用户填写。在管理后台的是可以对这个占位符
的字段进行配置，比如这个占位符的数据来源是数据库中获取从哪个表获取数据哪个字段数据

### 🔴 技术实现问题
1. **文件存储**：Word模板和生成的文档存储在哪里？本地还是云存储？
云存储（腾讯云）
2. **队列处理**：使用现有的workerman队列还是需要其他队列系统？
使用现有的workerman队列
3. **权限控制**：不同角色的权限如何划分？
暂时默认所有用户都可以操作，后续完善权限控制

### 🔴 小程序交互问题
1. **访问方式**：用户如何访问小程序合同页面？扫码还是链接？
两种情况都有。小程序端是有我的合同这个页面的。获取自己的合同列表点击查看合同详情进入合同详情页。根据状态
未签的就可以签署，已签的就是预览 word。
2. **身份验证**：如何确保用户身份的准确性？
只要用户登录才能签署合同，自己签署自己的合同。而且有自己的手写签名做备份。
3. **离线处理**：网络不好时如何处理数据收集？
离线时所有功能不可用提示用户网络有问题所有功能停用。

## 前后端任务分工

### 后端任务（PHP）
1. **模板管理API**
   - 模板上传接口
   - 占位符解析服务
   - 数据源配置API
   
2. **合同分发API**
   - 分发创建接口
   - 分发记录查询API
   
3. **数据收集API**
   - 合同信息获取API
   - 数据提交接口
   - 签名上传API
   
4. **文档生成服务**
   - 队列任务处理
   - Word文档生成
   - 文件下载接口

### 前端管理界面任务（Vue3）
1. **模板管理页面**
   - 模板列表组件
   - 模板上传组件
   - 占位符配置组件
   
2. **合同管理页面**
   - 合同分发组件
   - 分发记录组件
   
3. **生成记录页面**
   - 生成状态监控
   - 文件下载功能

### 小程序端任务（UniApp）
1. **合同展示页面**
   - 合同信息展示
   - 占位符数据收集表单
   
2. **签名功能页面**
   - 手写签名组件
   - 签名确认功能
   
3. **提交确认页面**
   - 数据确认展示
   - 最终提交功能

## 开发时间估算

### 第一阶段：基础架构（5天）
- 数据库表设计和创建
- 基础API框架搭建
- 前端页面框架搭建

### 第二阶段：模板管理（7天）
- Word解析功能开发
- 占位符配置功能
- 模板管理界面

### 第三阶段：合同分发（5天）
- 分发逻辑开发
- 分发管理界面
- 与业务系统集成

### 第四阶段：小程序端（8天）
- 数据收集页面
- 签名功能开发
- 数据提交逻辑

### 第五阶段：文档生成（6天）
- 队列处理开发
- Word生成功能
- 文件管理功能

### 第六阶段：测试优化（4天）
- 功能测试
- 性能优化
- Bug修复

**总计：35天**

## 补充问题确认

基于您的回答和代码分析，我发现还有几个关键问题需要确认：

### 🔴 支付成功事件集成问题
1. **现有支付流程**：我看到代码中支付成功后会触发`Student`事件，但在`Student.php`监听器中的`studentAdd`方法里，合同分发逻辑似乎不完整。您希望在哪个环节触发合同分发？
   - 在`studentAdd`方法中直接添加合同分发逻辑？
   - 还是创建新的事件监听器专门处理合同分发？

2. **合同分发条件**：外部用户购买课程后，是否所有课程都需要分发合同，还是只有特定课程？如何判断哪些课程需要分发合同？

### 🔴 数据库表结构问题
3. **表名前缀统一**：您确认使用`school_`前缀，但我需要确认以下表的完整表名：
   - `school_contract`（合同模板表）
   - `school_contract_sign`（合同签署关系表）
   - `school_document_data_source_config`（数据源配置表）
   - `school_document_generate_log`（文档生成记录表）

4. **现有表结构检查**：我需要查看现有数据库中是否已经存在这些表，以及它们的具体结构是否与我设计的一致。

### 🔴 小程序页面集成问题
5. **现有小程序结构**：您提到小程序有"我的合同"页面，这个页面是否已经存在？如果存在，我需要了解现有的页面结构和路由配置。

6. **用户身份关联**：小程序用户登录后，如何关联到`school_customer_resources`表中的用户？是通过`member_id`字段吗？

### 🔴 文件处理问题
7. **Word模板格式**：您提到测试文档是`doc/副本（时间卡）体能课学员课程协议.docx`，我需要确认：
   - 模板中的占位符格式是什么？（如`{{学员姓名}}`、`{学员姓名}`还是其他格式？）
   - 是否有现成的模板可以参考？

8. **腾讯云存储配置**：现有系统是否已经配置了腾讯云存储？我需要了解存储的配置信息以便集成。

## 建议的架构优化

### 1. 事件监听器优化
建议创建专门的合同分发事件监听器，而不是在现有的`Student`监听器中添加逻辑：

```php
// 新建 app/listener/contract/ContractDistributionListener.php
class ContractDistributionListener
{
    public function handle(array $params)
    {
        // 处理合同分发逻辑
        if ($params['event_type'] === 'course_purchase') {
            $this->distributeCourseContract($params['data']);
        }
    }
}
```

### 2. 数据库设计优化
建议在`school_contract_sign`表中添加一些字段：

```sql
ALTER TABLE `school_contract_sign` ADD COLUMN `source_type` varchar(50) DEFAULT 'manual' COMMENT '分发来源：manual手动分发，auto_course自动课程分发';
ALTER TABLE `school_contract_sign` ADD COLUMN `source_id` int DEFAULT NULL COMMENT '来源ID（如课程ID、订单ID等）';
```

### 3. API接口设计建议
基于您的需求，我建议以下API结构：

**管理端API：**
- `/admin/contract/template` - 模板管理
- `/admin/contract/distribution` - 合同分发管理
- `/admin/contract/generate-log` - 生成记录管理

**小程序端API：**
- `/api/contract/my-contracts` - 我的合同列表
- `/api/contract/detail/{id}` - 合同详情
- `/api/contract/submit-data` - 提交填写数据
- `/api/contract/upload-signature` - 上传签名

## 下一步行动

请您确认上述补充问题后，我将：

1. 检查现有数据库表结构
2. 完善数据库设计方案
3. 制定详细的API接口文档
4. 创建具体的开发任务分配
5. 建立项目开发时间表

---

**注意**：这些补充问题的确认对于系统的正确实现非常重要，请务必详细回答。