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
```

**请求参数**:
```json
{
  "username": "用户名或手机号",
  "password": "密码",
  "device_id": "设备ID（可选）"
}
```

**响应示例**:
```json
{
  "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
```

**请求参数**:
```json
{
  "username": "用户名",
  "password": "密码",
  "name": "姓名",
  "phone": "手机号",
  "role": "角色(student/parent/teacher)"
}
```

#### 1.2 获取用户资料
```
GET /api/v1/auth/profile
```

#### 1.3 更新用户资料
```
PUT /api/v1/auth/profile
```

**请求参数**:
```json
{
  "name": "姓名",
  "phone": "手机号"
}
```

#### 1.4 修改密码
```
PUT /api/v1/auth/password
```

**请求参数**:
```json
{
  "old_password": "旧密码",
  "new_password": "新密码"
}
```

### 2. 检测服务相关

#### 2.1 发起检测
```
POST /api/v1/detections/start
```

**请求参数**:
```json
{
  "class_id": 1,
  "teacher_id": 1,
  "student_count": 30,
  "detection_type": "vision"  // vision/fatigue/training
}
```

**响应示例**:
```json
{
  "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
```

**请求参数**:
```json
{
  "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`: 结束日期

**响应示例**:
```json
{
  "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
```

**请求参数**:
```json
{
  "handle_remark": "处理备注"
}
```

### 4. 训练服务相关

#### 4.1 获取训练任务
```
GET /api/v1/training/tasks
```

**查询参数**:
- `student_id`: 学生ID
- `date`: 日期

#### 4.2 提交训练记录
```
POST /api/v1/training/records
```

**请求参数**:
```json
{
  "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
```

**请求参数**:
```json
{
  "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