# 服务记录分发功能说明

## 功能概述

服务记录分发功能是一个定时任务系统，用于自动将已完成的服务记录分发给教务人员和教练，确保相关人员能够及时了解服务情况。

## 功能特性

### 1. 自动分发
- 定时检查最近24小时内完成的服务记录
- 自动识别教务人员和教练
- 根据人员角色发送相应的通知

### 2. 分发规则
- **教务人员**：接收所有已完成的服务记录通知
- **教练**：只接收自己负责的服务记录通知

### 3. 通知方式
- 支持短信通知
- 支持微信通知
- 支持小程序通知

## 文件结构

```
app/
├── job/schedule/
│   └── ServiceLogsDistribution.php          # 定时任务类
├── service/admin/service_logs/
│   └── ServiceLogsDistributionService.php   # 分发管理服务
├── adminapi/controller/service_logs/
│   └── ServiceLogsDistribution.php          # 分发管理控制器
├── dict/notice/
│   └── service_logs_notice.php              # 通知模板配置
└── upgrade/v151/
    ├── upgrade.php                          # 升级脚本
    └── upgrade.sql                          # 数据库升级SQL
```

## 数据库变更

### 服务记录表 (service_logs)
新增字段：
- `is_distributed_to_academic` (tinyint): 是否已分发给教务
- `is_distributed_to_coach` (tinyint): 是否已分发给教练
- `distribution_time` (int): 分发时间

### 人员表 (personnel)
新增字段：
- `position` (varchar): 职位信息

## API接口

### 1. 手动执行分发任务
```
POST /adminapi/service_logs/distribution/execute
```

### 2. 获取分发统计信息
```
GET /adminapi/service_logs/distribution/stats
```

### 3. 获取待分发的服务记录列表
```
GET /adminapi/service_logs/distribution/pending
参数：
- distribution_status: 分发状态筛选
- date_range: 日期范围筛选
```

### 4. 重置分发状态
```
POST /adminapi/service_logs/distribution/reset
参数：
- ids: 服务记录ID数组
- type: 重置类型 (academic|coach|both)
```

### 5. 获取教务和教练人员列表
```
GET /adminapi/service_logs/distribution/staff
```

## 使用方法

### 1. 安装升级
执行数据库升级脚本：
```sql
-- 执行 app/upgrade/v151/upgrade.sql 中的SQL语句
```

### 2. 配置定时任务
在系统定时任务中添加：
```php
// 任务类
app\job\schedule\ServiceLogsDistribution

// 执行频率：每小时执行一次
0 * * * *
```

### 3. 配置通知模板
在后台管理系统中配置通知模板：
- 服务记录教务通知 (service_log_academic_notice)
- 服务记录教练通知 (service_log_coach_notice)

### 4. 设置人员职位
确保人员表中的职位字段正确设置：
- 教务人员：职位包含"教务"
- 教练：职位包含"教练"

## 通知模板变量

### 教务通知模板变量
- `{staff_name}`: 教务人员姓名
- `{service_name}`: 服务名称
- `{score}`: 评分
- `{created_at}`: 创建时间

### 教练通知模板变量
- `{staff_name}`: 教练姓名
- `{service_name}`: 服务名称
- `{score}`: 学员评分
- `{feedback}`: 学员反馈
- `{created_at}`: 创建时间

## 日志记录

系统会自动记录以下日志：
- 分发任务开始和完成时间
- 分发成功的记录数量
- 发送通知的成功和失败情况
- 异常错误信息

## 注意事项

1. **数据库升级**：首次使用前必须执行数据库升级脚本
2. **人员配置**：确保人员表中的职位信息正确设置
3. **通知配置**：需要在后台配置相应的通知模板
4. **定时任务**：建议设置为每小时执行一次
5. **权限控制**：API接口需要相应的权限才能访问

## 故障排除

### 常见问题

1. **没有找到教务/教练人员**
   - 检查人员表中的职位字段是否正确设置
   - 确认人员状态是否为正常状态

2. **通知发送失败**
   - 检查通知模板配置
   - 确认短信/微信配置是否正确

3. **分发状态不更新**
   - 检查数据库字段是否存在
   - 确认数据库权限是否正确

### 调试方法

1. 查看系统日志文件
2. 使用手动执行接口测试
3. 检查数据库中的分发状态字段
4. 验证通知模板配置