# 智慧教务系统 API 接口文档

## 📋 接口概述

### 基础信息
- **API Base URL**: `http://localhost:20080`
- **接口版本**: v1.0
- **数据格式**: JSON
- **字符编码**: UTF-8
- **认证方式**: JWT Token

### 接口前缀
- **管理端接口**: `/adminapi/*`
- **客户端接口**: `/api/*`

### 统一响应格式
```json
{
  "code": 1,           // 状态码：1-成功，0-失败
  "msg": "操作成功",    // 响应消息
  "data": {}          // 响应数据
}
```

### 状态码说明
| 状态码 | 说明 | 描述 |
|--------|------|------|
| 1 | 成功 | 请求处理成功 |
| 0 | 失败 | 请求处理失败 |
| 401 | 未授权 | Token无效或已过期 |
| 403 | 禁止访问 | 权限不足 |
| 404 | 未找到 | 资源不存在 |
| 500 | 服务器错误 | 内部服务器错误 |

## 🔐 认证机制

### JWT Token 认证
所有需要认证的接口都需要在请求头中携带Token：

```http
Authorization: Bearer {token}
```

### Token 获取
通过登录接口获取Token，Token有效期为24小时。

### Token 刷新
当Token即将过期时，可通过刷新接口获取新Token。

## 🔑 管理端接口 (/adminapi)

### 认证相关

#### 1. 管理员登录
**接口地址**: `POST /adminapi/login/login`

**请求参数**:
```json
{
  "username": "admin",     // 用户名
  "password": "123456"     // 密码
}
```

**响应示例**:
```json
{
  "code": 1,
  "msg": "登录成功",
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "expire": 86400,
    "user_info": {
      "uid": 1,
      "username": "admin",
      "nickname": "超级管理员",
      "avatar": "",
      "role_ids": [1],
      "permissions": ["*"]
    }
  }
}
```

**curl 示例**:
```bash
curl -X POST http://localhost:20080/adminapi/login/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"123456"}'
```

#### 2. 获取用户信息
**接口地址**: `GET /adminapi/user/info`

**请求头**:
```http
Authorization: Bearer {token}
```

**响应示例**:
```json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "uid": 1,
    "username": "admin",
    "nickname": "超级管理员",
    "avatar": "",
    "role_ids": [1],
    "permissions": ["*"],
    "campus_ids": [0]  // 0表示所有校区
  }
}
```

#### 3. 退出登录
**接口地址**: `POST /adminapi/login/logout`

**请求头**:
```http
Authorization: Bearer {token}
```

**响应示例**:
```json
{
  "code": 1,
  "msg": "退出成功",
  "data": null
}
```

### 校区管理

#### 1. 校区列表
**接口地址**: `GET /adminapi/campus/list`

**请求参数**:
```
page: 1           // 页码
limit: 20         // 每页数量
keyword: ""       // 搜索关键词
status: ""        // 状态筛选：1-启用，0-禁用
```

**响应示例**:
```json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "campus_name": "总校区",
        "address": "北京市朝阳区xxx路xxx号",
        "phone": "010-12345678",
        "contact_person": "张三",
        "status": 1,
        "created_at": "2025-01-01 10:00:00",
        "updated_at": "2025-01-14 15:30:00"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}
```

#### 2. 新增校区
**接口地址**: `POST /adminapi/campus/add`

**请求参数**:
```json
{
  "campus_name": "新校区",
  "address": "北京市海淀区xxx路xxx号",
  "phone": "010-87654321",
  "contact_person": "李四",
  "status": 1,
  "remark": "备注信息"
}
```

**响应示例**:
```json
{
  "code": 1,
  "msg": "添加成功",
  "data": {
    "id": 2
  }
}
```

#### 3. 编辑校区
**接口地址**: `PUT /adminapi/campus/edit/{id}`

**请求参数**:
```json
{
  "campus_name": "更新后的校区名称",
  "address": "更新后的地址",
  "phone": "010-11111111",
  "contact_person": "王五",
  "status": 1,
  "remark": "更新后的备注"
}
```

#### 4. 删除校区
**接口地址**: `DELETE /adminapi/campus/delete/{id}`

**响应示例**:
```json
{
  "code": 1,
  "msg": "删除成功",
  "data": null
}
```

### 人员管理

#### 1. 员工列表
**接口地址**: `GET /adminapi/personnel/list`

**请求参数**:
```
page: 1
limit: 20
keyword: ""       // 姓名或工号搜索
campus_id: ""     // 校区筛选
dept_id: ""       // 部门筛选
status: ""        // 状态筛选
```

**响应示例**:
```json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 51,
        "name": "花花",
        "employee_id": "EMP001",
        "phone": "13800138000",
        "email": "huahua@example.com",
        "dept_name": "教练部",
        "campus_name": "总校区",
        "role_type": 10,
        "role_name": "校长",
        "status": 1,
        "created_at": "2025-01-01 10:00:00"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}
```

#### 2. 新增员工
**接口地址**: `POST /adminapi/personnel/add`

**请求参数**:
```json
{
  "name": "新员工",
  "employee_id": "EMP002",
  "phone": "13900139000",
  "email": "newstaff@example.com",
  "dept_id": 2,
  "campus_ids": [1, 2],
  "role_type": 5,
  "password": "123456",
  "status": 1
}
```

#### 3. 学员列表
**接口地址**: `GET /adminapi/student/list`

**请求参数**:
```
page: 1
limit: 20
keyword: ""       // 姓名或学号搜索
campus_id: ""     // 校区筛选
class_id: ""      // 班级筛选
status: ""        // 状态筛选
```

**响应示例**:
```json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "student_name": "小明",
        "student_no": "STU001",
        "gender": 1,
        "age": 8,
        "phone": "13700137000",
        "parent_name": "明爸爸",
        "parent_phone": "13600136000",
        "campus_name": "总校区",
        "class_name": "跳绳初级班",
        "status": 1,
        "created_at": "2025-01-01 10:00:00"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}
```

### 课程管理

#### 1. 课程列表
**接口地址**: `GET /adminapi/course/list`

**请求参数**:
```
page: 1
limit: 20
keyword: ""       // 课程名称搜索
course_type: ""   // 课程类型筛选
status: ""        // 状态筛选
```

**响应示例**:
```json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "course_name": "跳绳基础课程",
        "course_type": "跳绳",
        "duration": 60,
        "session_count": 12,
        "single_session_count": 1,
        "price": 1200.00,
        "age_range": "6-12岁",
        "description": "适合初学者的跳绳课程",
        "cover_image": "/uploads/course/cover1.jpg",
        "status": 1,
        "created_at": "2025-01-01 10:00:00"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}
```

#### 2. 新增课程
**接口地址**: `POST /adminapi/course/add`

**请求参数**:
```json
{
  "course_name": "新课程",
  "course_type": "篮球",
  "duration": 90,
  "session_count": 16,
  "single_session_count": 1,
  "price": 1600.00,
  "age_range": "8-16岁",
  "description": "篮球基础技能训练",
  "cover_image": "/uploads/course/cover2.jpg",
  "status": 1
}
```

### 班级管理

#### 1. 班级列表
**接口地址**: `GET /adminapi/class/list`

**请求参数**:
```
page: 1
limit: 20
keyword: ""       // 班级名称搜索
campus_id: ""     // 校区筛选
course_id: ""     // 课程筛选
status: ""        // 状态筛选
```

**响应示例**:
```json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "class_name": "跳绳初级班A",
        "campus_name": "总校区",
        "course_name": "跳绳基础课程",
        "head_coach": "张教练",
        "assistant_coach": "李助教",
        "capacity": 15,
        "current_count": 12,
        "status": 1,
        "created_at": "2025-01-01 10:00:00"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}
```

#### 2. 新增班级
**接口地址**: `POST /adminapi/class/add`

**请求参数**:
```json
{
  "class_name": "新班级",
  "campus_id": 1,
  "course_id": 1,
  "head_coach": 51,
  "assistant_coach": 52,
  "capacity": 20,
  "status": 1,
  "remark": "备注信息"
}
```

### 排课系统

#### 1. 课程安排列表
**接口地址**: `GET /adminapi/schedule/list`

**请求参数**:
```
page: 1
limit: 20
date_start: "2025-01-01"  // 开始日期
date_end: "2025-01-31"    // 结束日期
campus_id: ""             // 校区筛选
coach_id: ""              // 教练筛选
venue_id: ""              // 场地筛选
```

**响应示例**:
```json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "course_name": "跳绳基础课程",
        "class_name": "跳绳初级班A",
        "coach_name": "张教练",
        "venue_name": "训练场地A",
        "course_date": "2025-01-15",
        "time_slot": "09:00-10:00",
        "available_capacity": 15,
        "booked_count": 12,
        "status": 1,
        "remarks": "正常上课"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}
```

#### 2. 新增课程安排
**接口地址**: `POST /adminapi/schedule/add`

**请求参数**:
```json
{
  "course_id": 1,
  "class_id": 1,
  "coach_id": 51,
  "venue_id": 1,
  "course_date": "2025-01-15",
  "time_slot": "09:00-10:00",
  "available_capacity": 15,
  "remarks": "正常上课"
}
```

### 财务管理

#### 1. 收费记录列表
**接口地址**: `GET /adminapi/finance/payment/list`

**请求参数**:
```
page: 1
limit: 20
date_start: "2025-01-01"
date_end: "2025-01-31"
campus_id: ""
student_id: ""
payment_type: ""  // 支付方式
status: ""        // 状态
```

**响应示例**:
```json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "student_name": "小明",
        "course_name": "跳绳基础课程",
        "amount": 1200.00,
        "payment_type": "微信支付",
        "payment_time": "2025-01-15 10:30:00",
        "operator": "收费员",
        "status": 1,
        "remark": "学费"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20,
    "summary": {
      "total_amount": 1200.00,
      "count": 1
    }
  }
}
```

#### 2. 新增收费记录
**接口地址**: `POST /adminapi/finance/payment/add`

**请求参数**:
```json
{
  "student_id": 1,
  "course_id": 1,
  "amount": 1200.00,
  "payment_type": "微信支付",
  "payment_time": "2025-01-15 10:30:00",
  "remark": "学费"
}
```

### 数据统计

#### 1. 数据看板
**接口地址**: `GET /adminapi/statistics/dashboard`

**请求参数**:
```
date_start: "2025-01-01"
date_end: "2025-01-31"
campus_id: ""  // 校区筛选，空表示所有校区
```

**响应示例**:
```json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "today": {
      "income": 5600.00,
      "new_students": 3,
      "classes": 12,
      "attendance_rate": 95.5
    },
    "month": {
      "income": 156000.00,
      "new_students": 45,
      "total_students": 320,
      "total_classes": 280
    },
    "trends": {
      "income_trend": [1200, 1500, 1800, 2100, 1900, 2200, 2400],
      "student_trend": [2, 3, 1, 4, 2, 3, 5],
      "attendance_trend": [92.5, 94.2, 96.1, 93.8, 95.5, 97.2, 95.8]
    }
  }
}
```

#### 2. 收入统计
**接口地址**: `GET /adminapi/statistics/income`

**请求参数**:
```
date_start: "2025-01-01"
date_end: "2025-01-31"
campus_id: ""
group_by: "day"  // 分组方式：day/week/month
```

**响应示例**:
```json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "total_amount": 156000.00,
    "chart_data": [
      {
        "date": "2025-01-01",
        "amount": 5200.00,
        "count": 4
      },
      {
        "date": "2025-01-02",
        "amount": 6800.00,
        "count": 5
      }
    ],
    "summary": {
      "avg_daily": 5200.00,
      "max_daily": 8900.00,
      "min_daily": 2100.00
    }
  }
}
```

## 📱 客户端接口 (/api)

### 员工端认证

#### 1. 员工登录
**接口地址**: `POST /api/staff/login`

**请求参数**:
```json
{
  "employee_id": "EMP001",  // 工号
  "password": "123456"      // 密码
}
```

**响应示例**:
```json
{
  "code": 1,
  "msg": "登录成功",
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "expire": 86400,
    "user_info": {
      "user_id": 51,
      "name": "花花",
      "employee_id": "EMP001",
      "role_type": 10,
      "role_name": "校长",
      "campus_ids": [1, 2],
      "avatar": "/uploads/avatar/51.jpg"
    }
  }
}
```

#### 2. 获取员工信息
**接口地址**: `GET /api/staff/info`

**请求头**:
```http
Authorization: Bearer {token}
```

**响应示例**:
```json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "user_id": 51,
    "name": "花花",
    "employee_id": "EMP001",
    "phone": "13800138000",
    "email": "huahua@example.com",
    "role_type": 10,
    "role_name": "校长",
    "dept_name": "管理部",
    "campus_ids": [1, 2],
    "campus_names": ["总校区", "分校区A"],
    "avatar": "/uploads/avatar/51.jpg"
  }
}
```

### 员工端业务功能

#### 1. 我的课程安排
**接口地址**: `GET /api/staff/schedule`

**请求参数**:
```
date: "2025-01-15"  // 查询日期，默认今天
```

**响应示例**:
```json
{
  "code": 1,
  "msg": "获取成功",
  "data": [
    {
      "id": 1,
      "course_name": "跳绳基础课程",
      "class_name": "跳绳初级班A",
      "venue_name": "训练场地A",
      "time_slot": "09:00-10:00",
      "student_count": 12,
      "status": 1,
      "remarks": "正常上课"
    }
  ]
}
```

#### 2. 班级学员列表
**接口地址**: `GET /api/staff/class/{class_id}/students`

**响应示例**:
```json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "class_info": {
      "id": 1,
      "class_name": "跳绳初级班A",
      "course_name": "跳绳基础课程",
      "capacity": 15,
      "current_count": 12
    },
    "students": [
      {
        "id": 1,
        "student_name": "小明",
        "student_no": "STU001",
        "gender": 1,
        "age": 8,
        "parent_name": "明爸爸",
        "parent_phone": "13600136000",
        "avatar": "/uploads/student/1.jpg",
        "status": 1
      }
    ]
  }
}
```

#### 3. 考勤打卡
**接口地址**: `POST /api/staff/attendance/checkin`

**请求参数**:
```json
{
  "type": 1,           // 打卡类型：1-上班，2-下班
  "latitude": 39.9042,  // 纬度
  "longitude": 116.4074, // 经度
  "address": "北京市朝阳区xxx路xxx号",
  "remark": "正常打卡"
}
```

**响应示例**:
```json
{
  "code": 1,
  "msg": "打卡成功",
  "data": {
    "id": 1,
    "checkin_time": "2025-01-15 08:30:00",
    "type": 1,
    "status": 1
  }
}
```

### 学员端功能

#### 1. 学员登录
**接口地址**: `POST /api/student/login`

**请求参数**:
```json
{
  "phone": "13700137000",  // 手机号
  "code": "123456"         // 验证码
}
```

#### 2. 我的课程
**接口地址**: `GET /api/student/courses`

**响应示例**:
```json
{
  "code": 1,
  "msg": "获取成功",
  "data": [
    {
      "id": 1,
      "course_name": "跳绳基础课程",
      "class_name": "跳绳初级班A",
      "coach_name": "张教练",
      "total_sessions": 12,
      "completed_sessions": 8,
      "remaining_sessions": 4,
      "next_class_time": "2025-01-16 09:00:00",
      "venue_name": "训练场地A"
    }
  ]
}
```

#### 3. 课程预约
**接口地址**: `POST /api/student/booking`

**请求参数**:
```json
{
  "schedule_id": 1,  // 课程安排ID
  "remark": "正常预约"
}
```

## 🔧 开发调试

### 环境配置
```bash
# 启动开发环境
./start.sh

# 查看服务状态
docker ps

# 查看API日志
docker-compose logs -f php
```

### 测试工具

#### Postman 集合
可以导入以下Postman集合进行接口测试：

```json
{
  "info": {
    "name": "智慧教务系统API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "base_url",
      "value": "http://localhost:20080"
    },
    {
      "key": "admin_token",
      "value": ""
    },
    {
      "key": "staff_token",
      "value": ""
    }
  ]
}
```

#### curl 测试脚本
```bash
#!/bin/bash

# 设置基础URL
BASE_URL="http://localhost:20080"

# 管理员登录
echo "=== 管理员登录 ==="
ADMIN_TOKEN=$(curl -s -X POST $BASE_URL/adminapi/login/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"123456"}' | \
  jq -r '.data.token')

echo "Admin Token: $ADMIN_TOKEN"

# 获取校区列表
echo "=== 获取校区列表 ==="
curl -s -H "Authorization: Bearer $ADMIN_TOKEN" \
  "$BASE_URL/adminapi/campus/list" | jq

# 获取员工列表
echo "=== 获取员工列表 ==="
curl -s -H "Authorization: Bearer $ADMIN_TOKEN" \
  "$BASE_URL/adminapi/personnel/list" | jq
```

### 错误处理

#### 常见错误码
| 错误码 | 错误信息 | 解决方案 |
|--------|----------|----------|
| 10001 | 参数错误 | 检查请求参数格式和必填字段 |
| 10002 | Token无效 | 重新登录获取新Token |
| 10003 | 权限不足 | 检查用户角色权限 |
| 10004 | 数据不存在 | 确认请求的资源ID是否正确 |
| 10005 | 数据库错误 | 检查数据库连接和SQL语句 |

#### 调试技巧
1. **查看详细错误信息**
   ```bash
   # 开启调试模式
   echo "APP_DEBUG=true" >> niucloud/.env
   
   # 重启PHP服务
   docker-compose restart php
   ```

2. **查看SQL执行日志**
   ```bash
   # 进入MySQL容器
   docker exec -it niucloud_mysql mysql -u niucloud -pniucloud123
   
   # 开启查询日志
   SET GLOBAL general_log = 'ON';
   SET GLOBAL general_log_file = '/var/log/mysql/query.log';
   ```

3. **API响应时间监控**
   ```bash
   # 使用curl测试响应时间
   curl -w "@curl-format.txt" -o /dev/null -s "http://localhost:20080/adminapi/user/info"
   ```

## 📋 更新日志

### v1.0.0 (2025-01-14)
- 初始版本发布
- 完成基础认证功能
- 实现校区管理接口
- 实现人员管理接口
- 实现课程管理接口
- 实现班级管理接口
- 实现排课系统接口
- 实现财务管理接口
- 实现数据统计接口
- 完成员工端基础功能
- 完成学员端基础功能

---

**文档维护**: 开发团队  
**最后更新**: 2025-01-14  
**文档版本**: v1.0  
**联系方式**: [技术支持邮箱]