教练财务数据API文档

教练财务数据API

接口信息

GET/gym/trainer/my_data

认证: 需要认证，使用access_token
描述: 获取教练的销售金额和消课金额数据，按月、季度、年三个维度统计

请求参数

参数名	类型	必填	描述
period	String	否	统计周期，可选值：month(月)、quarter(季度)、year(年)，默认为month
year	Integer	否	统计年份，如果不提供则使用当前年份
access_token	String	是	访问令牌

响应数据

成功响应(200):

{
  "year": 2024,
  "period": "month",
  "data": [
    {
      "月份": "1月",
      "销售金额": 39000,
      "消课金额": 36890
    },
    {
      "月份": "2月",
      "销售金额": 36800,
      "消课金额": 25000
    },
    {
      "月份": "3月",
      "销售金额": 44700,
      "消课金额": 30000
    },
    // ... 其他月份的数据
  ],
  "chart_data": {
    "labels": ["1月", "2月", "3月", ...],
    "sales_amounts": [39000, 36800, 44700, ...],
    "course_amounts": [36890, 25000, 30000, ...]
  },
  "trainer": {
    "name": "刘尚武",
    "image_1920": "base64编码的图片数据",
    "total_members": 28
  }
}

错误响应:

400: 用户不存在

{
  "error": "User not found",
  "error_descrip": "未找到用户信息"
}

400: 教练不存在

{
  "error": "Trainer not found",
  "error_descrip": "未找到教练信息"
}

400: 学员不存在

{
  "error": "No students found",
  "error_descrip": "未找到学员信息"
}

400: 年份格式无效

{
  "error": "Invalid year",
  "error_descrip": "年份格式无效"
}

400: 无效的统计周期

{
  "error": "Invalid period",
  "error_descrip": "无效的统计周期"
}

数据字段说明

year (年份)

统计数据的年份

period (统计周期)

统计数据的周期，可能的值：month(月)、quarter(季度)、year(年)

data (数据列表)

按照指定周期统计的数据列表
当period=month时，包含12个月的数据
当period=quarter时，包含4个季度的数据
当period=year时，包含1个年度的数据

chart_data (图表数据)

labels: 图表标签数组，对应各个周期（月份/季度/年份）
sales_amounts: 销售金额数组，与labels一一对应
course_amounts: 消课金额数组，与labels一一对应

trainer (教练信息)

name: 教练姓名
image_1920: 教练头像(base64编码)
total_members: 教练名下的学员总数

数据计算逻辑

销售金额计算逻辑:

销售金额基于课程登记记录(course.registration)计算:

筛选教练名下所有学员的课程登记记录
按照课程登记日期(registration_date)归类到对应的月份
累加每个月份的课程总价(total_price)

消课金额计算逻辑:

消课金额基于会员训练记录(member.workout.detail)计算:

筛选教练名下所有学员的训练记录
按照训练日期(date_from)归类到对应的月份
只计算已签课(member_checkout=True)的记录
查找对应的课程登记记录，获取课时单价(price_per_hour)
计算训练时长(小时) = (date_to - date_from) / 3600
消课金额 = 训练时长 × 课时单价

使用示例

请求示例

按月统计(默认):

GET /gym/trainer/my_data?access_token=abc123

按季度统计:

GET /gym/trainer/my_data?period=quarter&access_token=abc123

按年统计:

GET /gym/trainer/my_data?period=year&access_token=abc123

指定年份统计:

GET /gym/trainer/my_data?year=2023&access_token=abc123

前端展示示例

该API返回的数据可用于生成类似以下的展示效果:

教练信息卡片:
- 显示教练姓名、头像
- 显示教练名下的学员总数
销售金额和消课金额柱状图:
- 使用柱状图展示销售金额和消课金额的对比
- X轴为时间周期（月份/季度/年份）
- Y轴为金额
- 两种颜色的柱状图分别表示销售金额和消课金额
数据详情表格:
- 表格形式展示每个周期的销售金额和消课金额
- 包含月份/季度/年份、销售金额、消课金额三列
周期切换按钮:
- 提供月、季、年三个按钮，用于切换统计周期