智慧教务系统

18 KiB

Raw Blame History

智慧教务系统 API 接口文档

📋 接口概述

基础信息

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

接口前缀

管理端接口: /adminapi/*
客户端接口: /api/*

统一响应格式

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

状态码说明

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

🔐 认证机制

JWT Token 认证

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

Authorization: Bearer {token}

Token 获取

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

Token 刷新

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

🔑 管理端接口 (/adminapi)

认证相关

1. 管理员登录

接口地址: POST /adminapi/login/login

请求参数:

{
  "username": "admin",     // 用户名
  "password": "123456"     // 密码
}

响应示例:

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

curl 示例:

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

2. 获取用户信息

接口地址: GET /adminapi/user/info

请求头:

Authorization: Bearer {token}

响应示例:

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

3. 退出登录

接口地址: POST /adminapi/login/logout

请求头:

Authorization: Bearer {token}

响应示例:

{
  "code": 1,
  "msg": "退出成功",
  "data": null
}

校区管理

1. 校区列表

接口地址: GET /adminapi/campus/list

请求参数:

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

响应示例:

{
  "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

请求参数:

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

响应示例:

{
  "code": 1,
  "msg": "添加成功",
  "data": {
    "id": 2
  }
}

3. 编辑校区

接口地址: PUT /adminapi/campus/edit/{id}

请求参数:

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

4. 删除校区

接口地址: DELETE /adminapi/campus/delete/{id}

响应示例:

{
  "code": 1,
  "msg": "删除成功",
  "data": null
}

人员管理

1. 员工列表

接口地址: GET /adminapi/personnel/list

请求参数:

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

响应示例:

{
  "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

请求参数:

{
  "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: ""        // 状态筛选

响应示例:

{
  "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: ""        // 状态筛选

响应示例:

{
  "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

请求参数:

{
  "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: ""        // 状态筛选

响应示例:

{
  "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

请求参数:

{
  "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: ""              // 场地筛选

响应示例:

{
  "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

请求参数:

{
  "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: ""        // 状态

响应示例:

{
  "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

请求参数:

{
  "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: ""  // 校区筛选，空表示所有校区

响应示例:

{
  "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

响应示例:

{
  "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

请求参数:

{
  "employee_id": "EMP001",  // 工号
  "password": "123456"      // 密码
}

响应示例:

{
  "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

请求头:

Authorization: Bearer {token}

响应示例:

{
  "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"  // 查询日期，默认今天

响应示例:

{
  "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

响应示例:

{
  "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

请求参数:

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

响应示例:

{
  "code": 1,
  "msg": "打卡成功",
  "data": {
    "id": 1,
    "checkin_time": "2025-01-15 08:30:00",
    "type": 1,
    "status": 1
  }
}

学员端功能

1. 学员登录

接口地址: POST /api/student/login

请求参数:

{
  "phone": "13700137000",  // 手机号
  "code": "123456"         // 验证码
}

2. 我的课程

接口地址: GET /api/student/courses

响应示例:

{
  "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

请求参数:

{
  "schedule_id": 1,  // 课程安排ID
  "remark": "正常预约"
}

🔧 开发调试

环境配置

# 启动开发环境
./start.sh

# 查看服务状态
docker ps

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

测试工具

Postman 集合

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

{
  "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 测试脚本

#!/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语句

调试技巧

查看详细错误信息

# 开启调试模式
echo "APP_DEBUG=true" >> niucloud/.env

# 重启PHP服务
docker-compose restart php

查看SQL执行日志

# 进入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';

API响应时间监控

# 使用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
联系方式: [技术支持邮箱]

18 KiB Raw Blame History

智慧教务系统 API 接口文档

📋 接口概述

基础信息

接口前缀

统一响应格式

状态码说明

🔐 认证机制

JWT Token 认证

Token 获取

Token 刷新

🔑 管理端接口 (/adminapi)

认证相关

1. 管理员登录

2. 获取用户信息

3. 退出登录

校区管理

1. 校区列表

2. 新增校区

3. 编辑校区

4. 删除校区

人员管理

1. 员工列表

2. 新增员工

3. 学员列表

课程管理

1. 课程列表

2. 新增课程

班级管理

1. 班级列表

2. 新增班级

排课系统

1. 课程安排列表

2. 新增课程安排

财务管理

1. 收费记录列表

2. 新增收费记录

数据统计

1. 数据看板

2. 收入统计

📱 客户端接口 (/api)

员工端认证

1. 员工登录

2. 获取员工信息

员工端业务功能

1. 我的课程安排

2. 班级学员列表

3. 考勤打卡

学员端功能

1. 学员登录

2. 我的课程

3. 课程预约

🔧 开发调试

环境配置

测试工具

Postman 集合

curl 测试脚本

错误处理

常见错误码

调试技巧

📋 更新日志

v1.0.0 (2025-01-14)

18 KiB

Raw Blame History