# 学员端开发计划 - 后端任务

## 🔧 **技术栈和环境**
- **框架**：PHP ThinkPHP 6.0
- **数据库**：MySQL 8.0
- **缓存**：Redis
- **文件存储**：腾讯云COS
- **支付**：微信支付
- **文档处理**：phpoffice/phpword + dompdf/dompdf

## 📋 **数据库准备工作**

### 1. **数据表字段修改**
**负责人**：后端开发者  
**工期**：0.5天  
**任务内容**：
```sql
-- 1. 消息表添加已读状态字段
ALTER TABLE `school_chat_messages` ADD COLUMN `is_read` tinyint(1) DEFAULT 0 COMMENT '是否已读 0-未读 1-已读';
ALTER TABLE `school_chat_messages` ADD COLUMN `read_time` timestamp NULL DEFAULT NULL COMMENT '已读时间';

-- 2. 课程安排表添加取消原因字段
ALTER TABLE `school_person_course_schedule` ADD COLUMN `cancel_reason` varchar(255) DEFAULT NULL COMMENT '取消预约原因';

-- 3. 订单表修改支付类型枚举
ALTER TABLE `school_order_table` MODIFY COLUMN `payment_type` 
enum('cash','scan_code','subscription','wxpay_online') NOT NULL 
COMMENT '付款类型: cash-现金支付, scan_code-扫码支付, subscription-订阅支付, wxpay_online-微信在线代付';

-- 4. 检查合同签署表字段（如果不存在则添加）
-- ALTER TABLE `school_contract_sign` ADD COLUMN `form_data` text COMMENT '签署时填写的表单数据JSON';
-- ALTER TABLE `school_contract_sign` ADD COLUMN `signature_image` varchar(500) COMMENT '签名图片路径';
-- ALTER TABLE `school_contract_sign` ADD COLUMN `signed_document` varchar(500) COMMENT '已签署文档路径';
```

### 2. **数据字典配置**
**负责人**：后端开发者  
**工期**：0.5天  
**任务内容**：
```sql
-- 插入7个数据字典配置
INSERT INTO `school_sys_dict` (`name`, `key`, `dictionary`) VALUES 
('订单类型', 'order_type', '[{"name":"新订单","value":"1"},{"name":"续费订单","value":"2"},{"name":"内部员工订单","value":"3"},{"name":"转校","value":"4"},{"name":"客户内转课订单","value":"5"}]'),
('订单状态', 'order_status', '[{"name":"待支付","value":"pending"},{"name":"已支付","value":"paid"},{"name":"待签约","value":"signed"},{"name":"已完成","value":"completed"},{"name":"转学","value":"transfer"}]'),
('支付类型', 'payment_type', '[{"name":"现金支付","value":"cash"},{"name":"扫码支付","value":"scan_code"},{"name":"订阅支付","value":"subscription"},{"name":"微信在线代付","value":"wxpay_online"}]'),
('知识库分类', 'knowledge_table_type', '[{"name":"课程教学大纲","value":"1"},{"name":"跳绳教案库","value":"2"},{"name":"增高教案库","value":"3"},{"name":"篮球教案库","value":"4"},{"name":"强化教案库","value":"5"},{"name":"空中忍者教案库","value":"6"},{"name":"少儿安防教案库","value":"7"},{"name":"体能教案库","value":"8"},{"name":"热身动作库","value":"9"},{"name":"体能动作库","value":"10"},{"name":"趣味游戏库","value":"11"},{"name":"放松动作库","value":"12"},{"name":"训练内容","value":"13"},{"name":"训练视频","value":"14"},{"name":"课后作业","value":"15"},{"name":"优秀一堂课","value":"16"}]'),
('消息发送类型', 'message_from_type', '[{"name":"员工","value":"personnel"},{"name":"学生(客户)","value":"customer"},{"name":"系统消息","value":"system"}]'),
('消息内容类型', 'message_type', '[{"name":"文本消息","value":"text"},{"name":"图片消息","value":"img"},{"name":"订单消息","value":"order"},{"name":"学员课程变动消息","value":"student_courses"},{"name":"课程安排消息","value":"person_course_schedule"}]'),
('课程状态', 'course_schedule_status', '[{"name":"待开始","value":"pending"},{"name":"即将开始","value":"upcoming"},{"name":"进行中","value":"ongoing"},{"name":"已结束","value":"completed"}]');
```

**验收标准**：
- ✅ 所有SQL语句执行成功
- ✅ 数据字典配置正确
- ✅ 字段类型和约束正确

---

## 🔌 **API接口开发任务**

### 3. **用户认证模块**
**负责人**：后端开发者  
**工期**：1天  
**任务内容**：
- [ ] 统一登录接口（手机号+密码）
- [ ] 微信登录接口（openid绑定）
- [ ] token生成和验证
- [ ] 登录状态检查中间件

**API接口清单**：
```php
POST /api/login/unified          // 统一登录
POST /api/login/wechat          // 微信登录
POST /api/logout                // 退出登录
GET  /api/auth/check            // 检查登录状态
```

**核心业务逻辑**：
- 手机号+密码验证
- 微信openid绑定到school_customer_resources
- JWT token生成和验证
- 登录失败次数限制

**验收标准**：
- ✅ 登录验证逻辑正确
- ✅ token生成和验证正常
- ✅ 微信登录流程完整
- ✅ 异常处理完善

### 4. **学员信息管理模块**
**负责人**：后端开发者  
**工期**：1.5天  
**任务内容**：
- [ ] 获取学员列表（支持多孩子）
- [ ] 获取学员详情信息
- [ ] 更新学员基本信息
- [ ] 头像上传处理

**API接口清单**：
```php
GET  /api/student/list                    // 获取当前用户的学员列表
GET  /api/student/summary/{id}            // 获取学员概览信息（落地页用）
GET  /api/student/info/{id}               // 获取学员详细信息
PUT  /api/student/update/{id}             // 更新学员信息
POST /api/upload/avatar                   // 头像上传
```

**核心业务逻辑**：
- 通过member_id关联查询学员列表
- 学员信息权限验证（只能查看自己的孩子）
- 头像上传到腾讯云COS
- 信息修改日志记录

**验收标准**：
- ✅ 学员列表查询正确
- ✅ 权限控制严格
- ✅ 头像上传功能正常
- ✅ 数据验证完整

### 5. **体测数据模块**
**负责人**：后端开发者  
**工期**：1.5天  
**任务内容**：
- [ ] 获取体测记录列表
- [ ] 获取体测详情数据
- [ ] PDF转图片分享功能
- [ ] 体测趋势数据计算

**API接口清单**：
```php
GET  /api/physical-test/list/{student_id}     // 获取体测记录列表
GET  /api/physical-test/detail/{id}           // 获取体测详情
POST /api/physical-test/share/{id}            // PDF转图片分享
GET  /api/physical-test/trend/{student_id}    // 获取趋势数据
```

**核心业务逻辑**：
- 按学员ID查询体测记录
- 只返回身高、体重、PDF报告
- 使用imagick将PDF转换为图片
- 计算身高体重趋势数据

**第三方库需求**：
```bash
composer require spatie/pdf-to-image
# 或使用imagick扩展
```

**验收标准**：
- ✅ 体测数据查询正确
- ✅ PDF转图片功能正常
- ✅ 趋势计算准确
- ✅ 权限控制严格

### 6. **课程安排模块**
**负责人**：后端开发者  
**工期**：1天  
**任务内容**：
- [ ] 获取学员课程安排
- [ ] 课程详情查询
- [ ] 课程状态筛选

**API接口清单**：
```php
GET /api/course-schedule/list/{student_id}    // 获取课程安排列表
GET /api/course-schedule/detail/{id}          // 获取课程详情
```

**核心业务逻辑**：
- 查询school_person_course_schedule表
- 关联课程、教练、场地信息
- 支持按日期、状态筛选
- 课程状态枚举处理

**验收标准**：
- ✅ 课程列表查询正确
- ✅ 关联数据完整
- ✅ 筛选功能正常
- ✅ 状态显示准确

### 7. **课程预约模块**
**负责人**：后端开发者  
**工期**：2天  
**任务内容**：
- [ ] 获取可预约课程列表
- [ ] 创建课程预约
- [ ] 获取我的预约列表
- [ ] 取消课程预约
- [ ] 预约冲突检测

**API接口清单**：
```php
GET  /api/course-booking/available/{student_id}  // 获取可预约课程
POST /api/course-booking/create                  // 创建预约
GET  /api/course-booking/my-list/{student_id}    // 我的预约列表
PUT  /api/course-booking/cancel/{id}             // 取消预约
```

**核心业务逻辑**：
- 预约数据存储在school_person_course_schedule表，course_type=3
- 预约冲突检测（同一时间段不能重复预约）
- 取消预约设置deleted_at字段
- 6小时取消限制检查
- 预约成功发送消息通知

**验收标准**：
- ✅ 预约创建逻辑正确
- ✅ 冲突检测准确
- ✅ 取消预约功能正常
- ✅ 时间限制检查正确
- ✅ 消息通知发送成功

### 8. **订单管理模块**
**负责人**：后端开发者
**工期**：2天
**任务内容**：
- [ ] 获取订单列表
- [ ] 获取订单详情
- [ ] 创建支付订单
- [ ] 支付状态查询
- [ ] 订单筛选功能

**API接口清单**：
```php
GET  /api/order/list/{student_id}        // 获取订单列表
GET  /api/order/detail/{id}              // 获取订单详情
POST /api/payment/create                 // 创建支付
GET  /api/payment/status/{order_id}      // 查询支付状态
POST /api/payment/callback               // 支付回调处理
```

**核心业务逻辑**：
- 查询school_order_table表
- 支持按课程类型、时间筛选
- 集成微信支付API
- 支付状态实时更新
- 支付成功后订单状态变更

**第三方集成**：
```php
// 微信支付SDK
composer require wechatpay/wechatpay-guzzle-middleware
```

**验收标准**：
- ✅ 订单列表查询正确
- ✅ 支付流程完整
- ✅ 支付回调处理正确
- ✅ 状态更新及时
- ✅ 筛选功能正常

### 9. **合同管理模块**
**负责人**：后端开发者
**工期**：2.5天
**任务内容**：
- [ ] 获取合同列表
- [ ] 获取合同详情
- [ ] 合同签署处理
- [ ] 合同文档下载
- [ ] Word转PDF功能

**API接口清单**：
```php
GET  /api/contract/list/{student_id}     // 获取合同列表
GET  /api/contract/detail/{id}           // 获取合同详情
POST /api/contract/sign                  // 提交合同签署
GET  /api/contract/download/{id}         // 下载合同
```

**核心业务逻辑**：
- 查询school_contract和school_contract_sign表
- 合同签署表单数据存储
- 签名图片上传处理
- Word文档转PDF功能
- 已签署合同下载

**第三方库需求**：
```bash
composer require phpoffice/phpword
composer require dompdf/dompdf
# 或者
composer require tecnickcom/tcpdf
```

**验收标准**：
- ✅ 合同列表查询正确
- ✅ 签署流程完整
- ✅ 文档转换功能正常
- ✅ 下载功能正常
- ✅ 数据存储正确

### 10. **知识库模块**
**负责人**：后端开发者
**工期**：1.5天
**任务内容**：
- [ ] 获取知识内容列表
- [ ] 获取内容详情
- [ ] 权限控制处理
- [ ] 分类筛选功能

**API接口清单**：
```php
GET /api/sutdent/knowledge/list/{student_id}     // 获取知识内容列表
GET /api/sutdent/knowledge/detail/{id}           // 获取内容详情
GET /api/sutdent/knowledge/categories            // 获取分类列表
```

**核心业务逻辑**：
- 查询school_lesson_course_teaching表
- 通过student_ids字段控制权限（逗号分割）
- 富文本内容处理
- 按table_type分类筛选

**验收标准**：
- ✅ 内容列表查询正确
- ✅ 权限控制严格
- ✅ 富文本渲染正常
- ✅ 分类筛选功能正常

### 11. **消息管理模块**
**负责人**：后端开发者
**工期**：2天
**任务内容**：
- [ ] 获取消息列表
- [ ] 获取消息详情
- [ ] 标记消息已读
- [ ] 5种消息类型处理
- [ ] 消息推送功能

**API接口清单**：
```php
GET /api/message/list/{student_id}       // 获取消息列表
GET /api/message/detail/{id}             // 获取消息详情
PUT /api/message/read/{id}               // 标记已读
POST /api/message/send                   // 发送消息（系统用）
```

**核心业务逻辑**：
- 查询school_chat_messages表
- 5种消息类型的不同处理逻辑
- 已读状态更新
- 消息推送到微信小程序
- 消息内容JSON格式处理

**验收标准**：
- ✅ 消息列表查询正确
- ✅ 5种类型处理正确
- ✅ 已读状态更新正常
- ✅ 推送功能正常
- ✅ JSON数据格式正确

---

## 📊 **后端开发进度计划**

### 第1周（5天）
- 天1：数据库准备工作（0.5天）+ 用户认证模块（0.5天）
- 天2：用户认证模块完成 + 学员信息管理模块（0.5天）
- 天3：学员信息管理模块完成 + 体测数据模块（0.5天）
- 天4：体测数据模块完成 + 课程安排模块
- 天5：课程预约模块（第1天）

### 第2周（5天）
- 天1：课程预约模块完成
- 天2-3：订单管理模块
- 天4-5：合同管理模块（第1-2天）

### 第3周（3.5天）
- 天1：合同管理模块完成（第3天）
- 天2：知识库模块
- 天3-4：消息管理模块

**总工期：13.5天**

---

## 🔍 **质量控制和验收标准**

### 代码质量要求
- [ ] 代码规范符合PSR-12标准
- [ ] 数据库操作使用ORM
- [ ] 异常处理完善
- [ ] 日志记录完整
- [ ] 安全防护到位

### API接口要求
- [ ] 统一的响应格式
- [ ] 完整的参数验证
- [ ] 权限控制严格
- [ ] 错误码规范
- [ ] 接口文档完整

### 性能要求
- [ ] 数据库查询优化
- [ ] 缓存策略合理
- [ ] 文件处理高效
- [ ] 并发处理能力

### 安全要求
- [ ] SQL注入防护
- [ ] XSS攻击防护
- [ ] 权限验证严格
- [ ] 敏感数据加密
- [ ] 接口访问限制

### 测试要求
- [ ] 单元测试覆盖率>80%
- [ ] 接口测试通过
- [ ] 压力测试达标
- [ ] 安全测试通过