# Word模板解析填充功能开发计划

## 需求分析与问题识别

### 📋 核心需求
- 解析Word模板中的占位符（如：`{{学员姓名}}`、`{{签约日期}}`等）
- 提供可视化配置界面，让用户选择字段数据源
- 支持数据库字段映射和自定义函数处理
- 生成填充后的Word文档

### ⚠️ 需求存在的潜在问题及建议

#### 1. 技术实现复杂性问题
**问题描述：**
- Word .doc格式是二进制格式，解析困难
- PHP直接处理Word文档需要复杂的第三方库
- 占位符格式需要统一标准

**✅ 确认方案：**
- 统一使用 `.docx` 格式（基于XML，更易解析）
- 采用 `phpoffice/phpword` 库处理文档  
- 制定标准占位符格式：`{{字段名}}`

#### 2. 数据安全风险
**问题描述：**
- 用户可输入任意表名和字段名存在SQL注入风险
- 函数名直接执行存在代码注入风险

**✅ 确认方案：**
- 限制可访问的数据表白名单
- 预定义可用函数列表，不允许动态执行
- 添加数据访问权限验证

#### 3. 性能考虑
**问题描述：**
- 大量模板同时处理可能导致内存溢出
- 文档生成可能耗时较长

**✅ 确认方案：**
- 实现异步文档生成队列
- 添加文档缓存机制
- 限制并发处理数量

## 技术架构设计

### 数据库设计

#### 1. school_contract合同表
```sql
CREATE TABLE `school_contract` (
  `id` int NOT NULL AUTO_INCREMENT COMMENT '合同编号',
  `contract_name` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL COMMENT '合同名称',
  `contract_template` text CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL COMMENT '合同模板',
  `contract_status` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL COMMENT '合同状态',
  `contract_type` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL COMMENT '合同类型',
  `remarks` text CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci COMMENT '合同备注',
  `created_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '修改时间',
  `deleted_at` int NOT NULL DEFAULT '0' COMMENT '逻辑删除时间',
  `placeholder` text CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci COMMENT '占位符配置用 json 数据来存储',
  PRIMARY KEY (`id`) USING BTREE
) 
```

**placeholder字段JSON结构示例：**
```json
{
  "{{学员姓名}}": {
    "name": "学员姓名",
    "data_source": "database",
    "table_name": "school_student", 
    "field_name": "student_name",
    "process_function": null,
    "default_value": "",
    "is_required": true
  },
  "{{签约日期}}": {
    "name": "签约日期", 
    "data_source": "manual",
    "table_name": null,
    "field_name": null,
    "process_function": "formatDate",
    "default_value": "",
    "is_required": true
  }
}
```
#### 2. 合同和人员关系表 `school_document_generate_log`
```sql
CREATE TABLE `school_document_generate_log` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `site_id` int(11) NOT NULL DEFAULT '0',
  `template_id` int(11) NOT NULL COMMENT '模板ID',
  `user_id` int(11) NOT NULL COMMENT '操作用户',
  `fill_data` text COMMENT '填充数据JSON',
  `generated_file` varchar(500) DEFAULT NULL COMMENT '生成文件路径',
  `status` enum('pending','processing','completed','failed') NOT NULL DEFAULT 'pending',
  `error_msg` text COMMENT '错误信息',
  `created_at` int(11) NOT NULL DEFAULT '0',
  `completed_at` int(11) DEFAULT '0',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='文档生成记录表';
```

### 前端页面架构

#### 页面结构
```
admin/src/app/views/document-template/
├── index.vue           # 模板列表页
├── add.vue            # 新增/编辑模板页
├── config.vue         # 占位符配置页
├── generate.vue       # 文档生成页
└── components/
    ├── PlaceholderConfig.vue    # 占位符配置组件
    ├── DataSourceSelector.vue   # 数据源选择组件
    └── DocumentPreview.vue      # 文档预览组件
```

#### 核心交互流程
1. **模板上传** → 自动解析占位符 → 显示配置界面
2. **占位符配置** → 选择数据源 → 设置处理函数 → 保存配置
3. **文档生成** → 选择模板 → 填写/选择数据 → 生成文档 → 下载

### 后端API设计

#### Controller层
```php
// app/adminapi/controller/document/DocumentTemplate.php
class DocumentTemplate extends BaseAdminController 
{
    public function getPage()        // 获取模板列表
    public function add()           // 新增模板
    public function edit()          // 编辑模板  
    public function delete()        // 删除模板
    public function uploadTemplate() // 上传模板文件
    public function parsePlaceholder() // 解析占位符
    public function configPlaceholder() // 配置占位符
    public function generateDocument() // 生成文档
    public function getGenerateLog()   // 获取生成记录
}
```

#### Service层核心方法
```php
class DocumentTemplateService 
{
    public function parseWordTemplate($filePath)     // 解析Word模板
    public function extractPlaceholders($content)    // 提取占位符
    public function validateDataSource($config)      // 验证数据源配置
    public function fillTemplate($templateId, $data) // 填充模板数据
    public function generateDocument($config)        // 生成最终文档
}
```

## 开发任务分解

### 阶段一：基础架构搭建（2天）
- [✅] 数据库表设计和创建
- [ ] 后端基础Controller和Service创建
- [ ] 前端页面路由和基础组件搭建
- [ ] 文件上传功能集成

### 阶段二：Word解析功能（3天）
- [ ] 集成phpoffice/phpword库
- [ ] 实现Word文档读取和占位符提取
- [ ] 开发占位符正则匹配算法
- [ ] 实现模板预览功能

### 阶段三：配置管理功能（2天）
- [ ] 占位符配置界面开发
- [ ] 数据源选择组件开发
- [ ] 数据表和字段动态获取API
- [ ] 处理函数管理功能

### 阶段四：文档生成功能（3天）
- [ ] 数据填充逻辑实现
- [ ] Word文档生成功能
- [ ] 文件下载和预览功能
- [ ] 异步生成队列实现

### 阶段五：测试和优化（1天）
- [ ] 功能测试和Bug修复
- [ ] 性能优化
- [ ] 安全性检查
- [ ] 用户体验优化

## 技术选型

### 后端依赖
- `phpoffice/phpword`: Word文档处理
- `phpoffice/common`: 公共组件
- PHP 7.4+ (项目要求)

### 前端依赖
- Vue 3 + Composition API
- Element Plus UI组件库
- Axios HTTP客户端
- 文件上传组件

## 风险评估与应对

### 高风险项
1. **Word格式兼容性** 
   - 风险：不同版本Word文档解析失败
   - 应对：支持多种格式，提供格式转换工具

2. **性能问题**
   - 风险：大文档处理缓慢
   - 应对：异步处理+进度条+缓存机制

3. **安全风险**
   - 风险：SQL注入、代码注入
   - 应对：严格的输入验证和白名单机制

### 中风险项
1. **用户体验复杂度**
   - 风险：配置过程过于复杂
   - 应对：提供模板和向导式配置

2. **数据一致性**
   - 风险：配置与实际数据不匹配
   - 应对：实时验证和错误提示

## 测试策略

### 单元测试
- 占位符解析算法测试
- 数据填充逻辑测试
- 文档生成功能测试

### 集成测试
- 完整流程端到端测试
- 不同格式文档兼容性测试
- 并发处理压力测试

### 安全测试
- SQL注入防护测试
- 文件上传安全测试
- 权限控制测试

## 上线计划

### 灰度发布
1. 内部测试环境验证
2. 小范围用户试用
3. 收集反馈优化
4. 全量发布

### 监控指标
- 文档生成成功率
- 处理时间监控
- 错误日志分析
- 用户使用频率统计

---

## 总结

这个功能具有一定复杂性，建议分阶段实施。核心关注点：
1. **安全性**：严格的输入验证和权限控制
2. **性能**：异步处理和缓存优化  
3. **易用性**：简化配置流程，提供良好的用户体验
4. **兼容性**：支持多种Word格式和版本

请确认以上计划是否符合您的期望，如有调整需求请告知。确认后我们开始具体的开发实施。