ai-myopia-prevention/docs/api_documentation.md

AI近视防控系统 - API文档

项目概述

AI近视防控系统是一套用于监测、分析和预防青少年近视发展的智能平台。通过眼动追踪、视力检测算法和智能训练内容，帮助学校和家庭及时发现并干预近视发展。

API基础信息

• Base URL: https://api.myopia-prevention.com/v1
• 协议: HTTPS
• 数据格式: JSON
• 字符编码: UTF-8

认证方式

JWT Token认证

所有需要认证的API接口都需要在请求头中添加JWT Token：

Authorization: Bearer {token}

登录接口

POST /api/v1/auth/login

请求参数:

{
  "username": "用户名或手机号",
  "password": "密码",
  "device_id": "设备ID（可选）"
}

响应示例:

{
  "code": 0,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": "2026-03-29T10:00:00Z",
    "user_id": 1,
    "username": "admin",
    "name": "管理员",
    "role": "admin"
  }
}

API接口列表

1. 用户认证相关

1.1 用户注册

POST /api/v1/auth/register

请求参数:

{
  "username": "用户名",
  "password": "密码",
  "name": "姓名",
  "phone": "手机号",
  "role": "角色(student/parent/teacher)"
}

1.2 获取用户资料

GET /api/v1/auth/profile

1.3 更新用户资料

PUT /api/v1/auth/profile

请求参数:

{
  "name": "姓名",
  "phone": "手机号"
}

1.4 修改密码

PUT /api/v1/auth/password

请求参数:

{
  "old_password": "旧密码",
  "new_password": "新密码"
}

2. 检测服务相关

2.1 发起检测

POST /api/v1/detections/start

请求参数:

{
  "class_id": 1,
  "teacher_id": 1,
  "student_count": 30,
  "detection_type": "vision"  // vision/fatigue/training
}

响应示例:

{
  "code": 0,
  "message": "检测任务已创建",
  "data": {
    "task_id": "1",
    "task_no": "task_20260328_123456_001",
    "start_time": "2026-03-28T10:00:00Z"
  }
}

2.2 提交检测结果

POST /api/v1/detections/submit

请求参数:

{
  "student_id": 1,
  "detection_id": "1",
  "vision": {
    "vision_left": 5.0,
    "vision_right": 4.9,
    "confidence": "high"
  },
  "eye_movement": {
    "left_eye": {
      "x": 120.5,
      "y": 85.3,
      "radius": 3.2,
      "confidence": 0.95
    },
    "right_eye": {
      "x": 140.2,
      "y": 84.8,
      "radius": 3.1,
      "confidence": 0.93
    },
    "gaze_point": {
      "x": 1920,
      "y": 540,
      "confidence": 0.9
    },
    "timestamp": 1711612800000
  },
  "response": {
    "accuracy": 0.85,
    "response_time": 2.5,
    "errors": 2
  },
  "timestamp": 1711612800000,
  "device_id": 1
}

2.3 获取检测报告

GET /api/v1/detections/report/:detection_id/student/:student_id

2.4 获取检测历史

GET /api/v1/detections/history

查询参数:

• student_id: 学生ID
• class_id: 班级ID
• start_date: 开始日期
• end_date: 结束日期
• page: 页码，默认1
• page_size: 每页数量，默认20

2.5 获取班级统计

GET /api/v1/detections/class/:class_id/stats

查询参数:

• start_date: 开始日期
• end_date: 结束日期

响应示例:

{
  "code": 0,
  "message": "获取成功",
  "data": {
    "class_id": 1,
    "class_name": "一年级一班",
    "total_students": 30,
    "tested_students": 28,
    "avg_vision_left": 4.9,
    "avg_vision_right": 4.8,
    "vision_decline_count": 2,
    "avg_fatigue_score": 25.5,
    "alert_count": 3,
    "alert_distribution": {
      "green": 20,
      "yellow": 5,
      "orange": 2,
      "red": 1
    },
    "created_at": "2026-03-28T10:00:00Z"
  }
}

3. 预警服务相关

3.1 获取预警列表

GET /api/v1/alerts

查询参数:

• student_id: 学生ID
• class_id: 班级ID
• level: 预警级别
• status: 预警状态
• page: 页码
• page_size: 每页数量

3.2 处理预警

POST /api/v1/alerts/:alert_id/handle

请求参数:

{
  "handle_remark": "处理备注"
}

4. 训练服务相关

4.1 获取训练任务

GET /api/v1/training/tasks

查询参数:

• student_id: 学生ID
• date: 日期

4.2 提交训练记录

POST /api/v1/training/records

请求参数:

{
  "student_id": 1,
  "task_id": 1,
  "score": 95,
  "accuracy": 0.9,
  "duration": 300,
  "performance_metrics": {
    "eye_movement_accuracy": 0.95,
    "focus_time": 280
  }
}

5. 设备服务相关

5.1 设备注册

POST /api/v1/devices/register

请求参数:

{
  "device_no": "设备编号",
  "device_name": "设备名称",
  "device_type": "设备类型",
  "school_id": 1,
  "class_id": 1
}

错误码说明

错误码	说明
0	成功
400	请求参数错误
401	未授权/认证失败
403	禁止访问/权限不足
404	资源不存在
500	服务器内部错误

数据模型

用户模型

• ID: 唯一标识符
• Username: 用户名
• Name: 姓名
• Phone: 手机号
• Role: 角色 (student/parent/teacher/admin)
• Status: 状态 (1:正常, 0:禁用)

学生模型

• ID: 唯一标识符
• StudentNo: 学号
• Name: 姓名
• Gender: 性别 (1:男, 2:女)
• BirthDate: 出生日期
• ClassID: 班级ID
• ParentID: 家长ID

检测模型

• ID: 唯一标识符
• TaskID: 检测任务ID
• StudentID: 学生ID
• DetectionTime: 检测时间
• VisionLeft: 左眼视力
• VisionRight: 右眼视力
• FatigueScore: 疲劳分数
• AlertLevel: 预警级别

预警模型

• ID: 唯一标识符
• StudentID: 学生ID
• DetectionID: 检测ID
• AlertLevel: 预警级别 (1:关注, 2:预警, 3:告警)
• AlertType: 预警类型
• Status: 状态 (0:未处理, 1:已通知, 2:已处理)

限流策略

• 普通用户: 100次/分钟
• 教师用户: 200次/分钟
• 设备接口: 500次/分钟

部署信息

• 环境: 生产环境
• 版本: v1.0.0
• 部署时间: 2026-03-28