# Word合同模板系统开发管理方案

## 项目管理总览

作为项目管理者，我将严格把控开发质量，确保代码规范、功能完整、性能优良。本方案将明确资源需求、开发规范、任务分配和质量控制流程。

## 一、关键资源确认清单

### 🔴 需要您提供的资源支持

#### 1. 数据库相关
- [✅] **数据库访问权限**：开发者是否有数据库读写权限？

- [ ✅] **数据库连接信息**：开发环境的数据库配置
  数据库配置信息如下：
  TYPE = mysql
  HOSTNAME = mysql
  DATABASE = niucloud
  USERNAME = niucloud
  PASSWORD = niucloud123

HOSTPORT = 3306
PREFIX = school_
CHARSET = utf8mb4
DEBUG = false

- [ ✅] **现有表结构**：确认以下表是否已存在及其完整结构
    - `school_contract`
    - `school_contract_sign`
    - `school_document_data_source_config`
    - `school_document_generate_log`
    - `school_personnel`
    - `school_customer_resources`
      数据库字段可能不是很完善例如用户签名的图片现在就没有字段存储需要新增字段。

#### 2. 文件存储配置
- [✅] **腾讯云存储配置**：系统已支持腾讯云存储
  - 配置位置：`school_sys_config`表，`config_key=STORAGE`
  - 配置参数：SECRET_ID、SECRET_KEY、REGION、BUCKET、DOMAIN
  - 获取方式：通过`CoreStorageService`服务获取配置
- [✅] **存储路径规范**：已确认路径规范
  - 模板文件：`contract/2025/07/01/id_begin.docx`
  - 已签署文件：`contract/{1/2}/personnel_id/2025/07/01/id_begin.docx`
  - 其中{1/2}表示内部/外部合同类型
- [✅] **CDN配置**：不使用CDN配置，直接使用腾讯云存储域名

#### 3. 测试资源
- [✅] **测试Word模板**：提供标准的Word模板文件（包含占位符）
  doc/副本（时间卡）体能课学员课程协议.docx外部人员签的合同
  doc/劳 动 合 同.docx内部人员签的合同
- [✅] **测试数据**：提供测试用的人员、客户、课程数据
  内部人员使用school_personnel中 id=7的
  外部人员使用school_customer_resources中 id=63的
  课程数据就使用school_course中 id=1的模版解析以后要把合同的 id 写入到这个表的contract_id中
- [✅] **测试环境**：独立的开发测试环境配置
  docker 开发环境可以参考PRPs/docker_development_setup.md这个文档
#### 4. UniApp主题样式
- [✅] **暗黑主题文件**：已确认暗黑主题规范
  - 背景色：`#181A20`
  - 文字颜色：`#fff`
  - 主题色：`rgb(41, 211, 180)`
  - 页面标题栏：背景`#181A20`，文字`#fff`
- [✅] **UI组件库**：使用firstUI组件库
- [✅] **设计规范**：严格保持现有暗黑主题风格，不随意改变

#### 5. 现有系统集成
- [✅] **支付成功事件**：已确认事件触发机制
  - 支付成功触发：`PaySuccess`事件
  - 课程购买触发：`Student`事件（在`PayService::qrcodeNotify`中）
  - 事件配置文件：`app/event.php`
- [✅] **用户权限系统**：已确认权限控制机制
  - 管理端权限：`AdminCheckRole`中间件
  - API端权限：`ApiCheckToken`中间件
  - 员工端权限：`ApiPersonnelCheckToken`中间件
- [✅] **队列系统配置**：workerman队列系统已配置
  - 队列命令：`php think workerman start`
  - 队列配置：基于Redis，支持延迟处理
  - Job基类：`BaseJob`，支持异步和同步执行

## 二、开发规范和质量标准

### 📋 代码质量标准

#### 后端开发规范（PHP）
```php
// 1. 严格遵循PSR-4自动加载规范
// 2. 所有类必须有完整的注释
// 3. 方法必须有参数和返回值类型声明
// 4. 必须进行异常处理和参数验证

/**
 * 示例：标准的Service类
 */
class DocumentTemplateService extends BaseAdminService
{
    /**
     * 上传Word模板
     * @param array $data 上传数据
     * @return array 返回结果
     * @throws \Exception
     */
    public function uploadTemplate(array $data): array
    {
        // 参数验证
        $this->validateUploadData($data);
        
        try {
            // 业务逻辑
            return $this->processUpload($data);
        } catch (\Exception $e) {
            // 异常处理
            throw new \Exception('模板上传失败：' . $e->getMessage());
        }
    }
}
```

#### 前端开发规范（Vue3）
```javascript
// 1. 使用Composition API
// 2. TypeScript类型声明
// 3. 统一的错误处理
// 4. 组件必须有完整的props和emits声明

<script setup lang="ts">
  interface Props {
  templateId: number
  readonly?: boolean
}

  interface Emits {
  (e: 'update', data: any): void
  (e: 'delete', id: number): void
}

  const props = withDefaults(defineProps<Props>(), {
  readonly: false
})

  const emit = defineEmits<Emits>()
</script>
```

#### UniApp开发规范
```vue
<!-- 1. 严格遵循暗黑主题样式 -->
<!-- 2. 使用uni-app官方组件 -->
<!-- 3. 响应式设计适配不同屏幕 -->

<template>
  <view class="contract-page">
    <!-- 保持暗黑主题 -->
    <view class="header dark-header">
      <text class="title dark-text">合同详情</text>
    </view>
  </view>
</template>

<style lang="scss">
  .contract-page {
    background-color: #1a1a1a; // 暗黑背景
    min-height: 100vh;
  }

  .dark-header {
    background-color: #2d2d2d;
    color: #ffffff;
  }

  .dark-text {
    color: #e0e0e0;
  }
</style>
```

### 🔍 代码审查标准

#### 必须通过的检查项
1. **功能完整性**：所有功能点必须完整实现
2. **错误处理**：必须有完善的异常处理机制
3. **性能优化**：数据库查询优化、前端渲染优化
4. **安全性**：SQL注入防护、XSS防护、文件上传安全
5. **代码规范**：符合团队编码规范
6. **测试覆盖**：关键功能必须有测试用例

## 三、详细任务分配

### 🔧 后端开发任务（PHP开发者）

#### 阶段一：基础架构搭建（3天）
**任务负责人**：后端开发智能体
**交付标准**：
- [ ] 数据库表结构创建和验证
- [ ] 基础Model类创建（Contract, ContractSign, DocumentDataSourceConfig, DocumentGenerateLog）
- [ ] 基础Service类框架搭建
- [ ] API路由配置

**具体任务**：
1. **数据库设计实现**
   ```sql
   -- 创建所有必需的表
   -- 添加索引优化
   -- 设置外键约束
   ```

2. **模型类开发**
   ```php
   // app/model/contract/Contract.php
   // app/model/contract_sign/ContractSign.php  
   // app/model/document/DocumentDataSourceConfig.php
   // app/model/document/DocumentGenerateLog.php
   ```

3. **基础服务类**
   ```php
   // app/service/admin/document/DocumentTemplateService.php
   // app/service/admin/contract/ContractDistributionService.php
   // app/service/api/contract/ContractService.php
   ```

#### 阶段二：Word模板处理（4天）
**交付标准**：
- [ ] Word文档上传功能
- [ ] 占位符自动解析功能
- [ ] 数据源配置API
- [ ] 模板预览功能

**具体任务**：
1. **Word文档处理**
   ```php
   // 使用phpoffice/phpword
   // 实现占位符提取
   // 支持.docx格式
   ```

2. **文件存储集成**
   ```php
   // 腾讯云存储集成
   // 文件上传安全验证
   // 文件路径管理
   ```

#### 阶段三：合同分发系统（3天）
**交付标准**：
- [ ] 手动分发API
- [ ] 自动分发事件监听器
- [ ] 分发记录管理
- [ ] 与支付系统集成

#### 阶段四：文档生成系统（4天）
**交付标准**：
- [ ] 队列任务处理
- [ ] Word文档生成
- [ ] 生成状态跟踪
- [ ] 文件下载API

### 🎨 前端管理界面任务（Vue3开发者）

#### 阶段一：基础框架（2天）
**任务负责人**：前端开发智能体
**交付标准**：
- [ ] 页面路由配置
- [ ] 基础布局组件
- [ ] API请求封装
- [ ] 错误处理机制

#### 阶段二：模板管理界面（4天）
**交付标准**：
- [ ] 模板列表页面
- [ ] 模板上传组件
- [ ] 占位符配置界面
- [ ] 模板预览功能

#### 阶段三：合同管理界面（3天）
**交付标准**：
- [ ] 合同分发管理
- [ ] 分发记录列表
- [ ] 生成状态监控

### 📱 UniApp小程序任务（UniApp开发者）

#### 阶段一：基础页面（3天）
**任务负责人**：UniApp开发智能体
**交付标准**：
- [ ] 保持现有暗黑主题样式
- [ ] 合同列表页面
- [ ] 合同详情页面
- [ ] 用户身份验证

#### 阶段二：数据收集功能（4天）
**交付标准**：
- [ ] 动态表单生成
- [ ] 数据验证和提交
- [ ] 手写签名组件
- [ ] 离线状态处理

## 四、严格质量控制流程

### 🔥 **零容忍质量标准**

#### 核心原则
- **数据一致性**：页面显示数据必须与数据库完全一致
- **功能完整性**：不允许任何功能缺失或异常
- **用户体验**：每个交互都必须符合预期
- **代码质量**：不合格代码绝不允许合并

### 📊 **严格的验收标准**

#### 每日强制检查项
- [x] **代码提交质量**：每行代码都要有注释和类型声明
- [x] **数据库一致性**：页面数据与数据库数据100%匹配
- [x] **功能完整性测试**：每个功能点都要有完整的测试用例
- [x] **API响应验证**：所有API返回数据格式和内容验证
- [x] **前端渲染验证**：页面显示内容与API数据完全一致
- [x] **错误处理测试**：异常情况处理必须完善
- [x] **性能指标监控**：API响应<1秒，页面加载<3秒

#### 阶段性验收标准（必须100%通过）
1. **功能完整性**：每个功能点都要有详细测试报告
2. **数据一致性**：前后端数据流转完全正确
3. **代码质量**：通过静态分析+人工审查
4. **性能标准**：API响应<1秒，复杂查询<2秒
5. **安全标准**：SQL注入、XSS、文件上传安全测试
6. **兼容性**：多浏览器、多设备测试通过

### 🔍 **详细的代码审查流程**

#### 后端代码审查清单
- [x] **数据库操作**：每个查询都要验证返回数据的正确性
- [x] **API接口**：返回数据格式、字段完整性、错误处理
- [x] **业务逻辑**：每个业务流程都要有完整的测试用例
- [x] **安全验证**：参数验证、权限检查、SQL注入防护
- [x] **异常处理**：所有可能的异常情况都要有处理机制

#### 前端代码审查清单
- [x] **数据渲染**：页面显示数据与API返回数据完全一致
- [x] **用户交互**：每个按钮、表单、弹窗都要测试
- [x] **状态管理**：数据状态变化要正确反映到页面
- [x] **错误提示**：用户操作错误要有明确提示
- [x] **加载状态**：异步操作要有加载提示

#### UniApp代码审查清单
- [x] **主题一致性**：严格保持暗黑主题，不允许颜色偏差
- [x] **数据同步**：小程序数据与后端数据实时同步
- [x] **用户体验**：每个页面跳转、数据加载都要流畅
- [x] **离线处理**：网络异常时的用户提示和数据保存

### 🚨 **零容忍的质量控制措施**

#### 代码合并标准
- **功能测试**：必须通过完整的功能测试
- **数据验证**：页面数据与数据库数据100%一致
- **性能测试**：API响应时间和页面加载速度达标
- **安全测试**：通过安全漏洞扫描
- **代码审查**：至少2人审查通过

#### 不合格代码处理
- **立即回退**：发现问题立即回退代码
- **重新开发**：不允许修修补补，要求重新开发
- **详细报告**：问题分析和改进措施报告
- **再次审查**：修复后必须重新走完整审查流程

## 五、开发环境和工具

### 必需的开发工具
- **后端**：PHP 7.4+, Composer, phpoffice/phpword, ThinkPHP框架
- **前端**：Node.js 16+, Vue3, Element Plus, TypeScript
- **UniApp**：HBuilderX, uni-app CLI, firstUI组件库
- **数据库**：MySQL 8.0+（已配置：niucloud数据库）
- **队列系统**：workerman + Redis
- **文件存储**：腾讯云COS（已配置）
- **版本控制**：Git
- **代码质量**：ESLint, PHPStan

## 六、资源确认完成情况

### ✅ 已确认的资源
- **数据库配置**：MySQL连接信息已确认
- **现有表结构**：Contract、ContractSign模型已存在
- **腾讯云存储**：配置方式和存储路径已确认
- **UniApp主题**：暗黑主题规范已明确
- **系统集成**：支付事件、权限系统、队列系统已确认

### 🔄 需要开发的数据库表
基于现有模型分析，需要创建以下表：
- `school_document_data_source_config`（数据源配置表）
- `school_document_generate_log`（文档生成记录表）
- 为现有表添加签名图片字段等

## 七、开发任务分配确认

所有关键资源已确认完毕，系统架构清晰，可以开始分发开发任务。

### 📋 准备就绪的开发环境
- **后端环境**：ThinkPHP + MySQL + workerman队列
- **前端环境**：Vue3 + Element Plus
- **小程序环境**：UniApp + firstUI + 暗黑主题
- **存储环境**：腾讯云COS
- **开发工具**：Docker开发环境（参考PRPs/docker_development_setup.md）

---

## 🎯 **项目管理者质量承诺**

### **严格把控标准**
1. **数据一致性**：页面显示的每一个数据都必须与数据库完全一致
2. **功能完整性**：不允许任何功能缺失、异常或不符合预期
3. **用户体验**：每个交互流程都要完整、流畅、符合预期
4. **代码质量**：不合格代码绝对不允许合并到主分支

### **质量控制措施**
- **每日代码审查**：每天检查代码质量和功能实现
- **数据验证测试**：确保前后端数据流转100%正确
- **完整功能测试**：每个功能都要有详细的测试用例
- **性能监控**：API响应和页面加载性能持续监控

### **不合格处理**
- 发现任何质量问题立即要求重新开发
- 不允许"先上线后修复"的做法
- 每个功能必须达到生产环境标准才能通过

**✅ 在严格质量标准下，确认可以开始分发开发任务**