zhjwxt/admin/Word模板解析填充功能开发计划.md

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

需求分析与问题识别

📋 核心需求

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

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

1. 技术实现复杂性问题

问题描述：

• Word .doc格式是二进制格式，解析困难
• PHP直接处理Word文档需要复杂的第三方库
• 占位符格式需要统一标准

✅ 确认方案：

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

2. 数据安全风险

问题描述：

• 用户可输入任意表名和字段名存在SQL注入风险
• 函数名直接执行存在代码注入风险

✅ 确认方案：

• 限制可访问的数据表白名单
• 预定义可用函数列表，不允许动态执行
• 添加数据访问权限验证

3. 性能考虑

问题描述：

• 大量模板同时处理可能导致内存溢出
• 文档生成可能耗时较长

✅ 确认方案：

• 实现异步文档生成队列
• 添加文档缓存机制
• 限制并发处理数量

技术架构设计

数据库设计

1. school_contract合同表

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结构示例：

{
  "{{学员姓名}}": {
    "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

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层

// 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层核心方法

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格式和版本

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