# 视力筛查管理系统 API 文档

## 基本信息

- **Base URL**: `http://localhost:8080`
- **版本**: 1.0.0
- **描述**: 学校视力筛查数据管理系统API文档

---

## 接口列表

### 1. 学校管理

#### 1.1 获取学校信息

**接口地址**: `GET /schools/{school_id}`

**接口描述**: 根据学校ID获取学校详细信息

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| school_id | string | path | 是 | 学校ID |

**响应示例**:

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "school_001",
    "name": "XX小学",
    "created_at": "2024-01-01T00:00:00Z"
  },
  "timestamp": "2024-01-01T12:00:00Z"
}
```

**错误响应**:

- `400`: 参数错误
  ```json
  {
    "code": 400,
    "message": "school_id is required",
    "data": null,
    "timestamp": "2024-01-01T12:00:00Z"
  }
  ```

- `404`: 学校不存在
  ```json
  {
    "code": 404,
    "message": "school not found",
    "data": null,
    "timestamp": "2024-01-01T12:00:00Z"
  }
  ```

- `500`: 服务器错误
  ```json
  {
    "code": 501,
    "message": "failed to query school",
    "data": {
      "details": "具体错误信息"
    },
    "timestamp": "2024-01-01T12:00:00Z"
  }
  ```

---

### 2. 年级管理

#### 2.1 获取学校年级列表

**接口地址**: `GET /schools/{school_id}/grades`

**接口描述**: 根据学校ID获取该学校下所有年级，按小学、初中、高中顺序排序

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| school_id | string | path | 是 | 学校ID |

**响应示例**:

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "school_id": "school_001",
    "grades": [
      "一年级",
      "二年级",
      "三年级",
      "初一",
      "初二",
      "高一"
    ]
  },
  "timestamp": "2024-01-01T12:00:00Z"
}
```

**错误响应**:

- `400`: 参数错误
  ```json
  {
    "code": 400,
    "message": "school_id is required",
    "data": null,
    "timestamp": "2024-01-01T12:00:00Z"
  }
  ```

---

#### 2.2 获取年级班级列表

**接口地址**: `GET /schools/{school_id}/grades-with-classes`

**接口描述**: 根据学校ID和年级名称获取该年级下的所有班级

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| school_id | string | path | 是 | 学校ID |
| grade | string | query | 是 | 年级名称，如：一年级、初一、高一 |

**响应示例**:

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "id": "class_001",
        "school_id": "school_001",
        "grade": "一年级",
        "class_name": "1班",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 1
  },
  "timestamp": "2024-01-01T12:00:00Z"
}
```

**错误响应**:

- `400`: 参数错误
  ```json
  {
    "code": 400,
    "message": "grade parameter is required",
    "data": null,
    "timestamp": "2024-01-01T12:00:00Z"
  }
  ```

---

### 3. 学生管理

#### 3.1 新增学生

**接口地址**: `POST /students`

**接口描述**: 新增学生信息，会检查身份证号在班级中是否重复

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| class_id | string | body | 是 | 班级ID |
| name | string | body | 是 | 学生姓名 |
| gender | string | body | 是 | 性别 |
| id_card | string | body | 是 | 身份证号 |
| created_user | string | body | 是 | 创建人 |
| operator_phone | string | body | 是 | 操作人手机号 |

**请求示例**:

```json
{
  "class_id": "class_001",
  "name": "张三",
  "gender": "男",
  "id_card": "110101200001011234",
  "created_user": "管理员",
  "operator_phone": "13800138000"
}
```

**响应示例**:

```json
{
  "code": 200,
  "message": "student created successfully",
  "data": {
    "student_id": 123
  },
  "timestamp": "2024-01-01T12:00:00Z"
}
```

**错误响应**:

- `400`: 参数错误
  ```json
  {
    "code": 502,
    "message": "invalid request parameters",
    "data": null,
    "timestamp": "2024-01-01T12:00:00Z"
  }
  ```

- `409`: 学生已存在
  ```json
  {
    "code": 409,
    "message": "student with this id_card already exists in the class",
    "data": null,
    "timestamp": "2024-01-01T12:00:00Z"
  }
  ```

- `500`: 服务器错误
  ```json
  {
    "code": 501,
    "message": "failed to create student",
    "data": {
      "details": "具体错误信息"
    },
    "timestamp": "2024-01-01T12:00:00Z"
  }
  ```

---

### 4. 视力筛查

#### 4.1 查询学生视力筛查数据

**接口地址**: `GET /classes/{class_id}/incomplete-vision-students`

**接口描述**: 根据班级ID查询学生视力筛查数据，支持按姓名和身份证号模糊查询，可查询全部、未完成或已完成的学生

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| class_id | string | path | 是 | 班级ID |
| status | string | query | 否 | 查询状态：all-全部数据，incomplete-未录入数据（默认），complete-已录入数据 |
| name | string | query | 否 | 学生姓名（模糊查询） |
| id_card | string | query | 否 | 身份证号（模糊查询） |

**响应示例**:

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "class_id": "class_001",
        "name": "张三",
        "gender": "男",
        "id_card": "110101200001011234",
        "created_at": "2024-01-01T00:00:00Z",
        "vision_data_id": "vision_001",
        "vision_input_status": 1,
        "refraction_input_status": 0,
        "has_vision_data": true,
        "input_status": "已录入视力"
      }
    ],
    "total": 2
  },
  "timestamp": "2024-01-01T12:00:00Z"
}
```

**字段说明**:

- `vision_input_status`: 视力录入状态（0-未录入，1-已录入）
- `refraction_input_status`: 屈光度录入状态（0-未录入，1-已录入）
- `has_vision_data`: 是否有视力数据记录
- `input_status`: 录入状态描述（未录入、已录入视力、已录入屈光度、已完成）

**错误响应**:

- `400`: 参数错误
  ```json
  {
    "code": 400,
    "message": "class_id is required",
    "data": null,
    "timestamp": "2024-01-01T12:00:00Z"
  }
  ```

---

#### 4.2 根据学生ID查询视力数据

**接口地址**: `GET /students/{student_id}/vision-data`

**接口描述**: 根据学生ID查询该学生的视力数据详情，包含学生基本信息

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| student_id | integer | path | 是 | 学生ID |

**响应示例**:

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "vision_001",
    "student_id": "123",
    "student_name": "张三",
    "gender": "男",
    "id_card": "110101200001011234",
    "class_id": "class_001",
    "left_eye_vision": 5.0,
    "right_eye_vision": 4.8,
    "left_eye_refraction": -2.5,
    "right_eye_refraction": -3.0,
    "vision_input_status": 1,
    "refraction_input_status": 1,
    "vision_input_user": "张医生",
    "vision_input_time": "2024-01-01T10:00:00Z",
    "refraction_input_user": "李医生",
    "refraction_input_time": "2024-01-01T11:00:00Z",
    "created_at": "2024-01-01T09:00:00Z",
    "updated_at": "2024-01-01T11:00:00Z"
  },
  "timestamp": "2024-01-01T12:00:00Z"
}
```

**错误响应**:

- `400`: 参数错误
  ```json
  {
    "code": 400,
    "message": "student_id is required",
    "data": null,
    "timestamp": "2024-01-01T12:00:00Z"
  }
  ```

- `404`: 数据不存在
  ```json
  {
    "code": 404,
    "message": "vision data not found",
    "data": null,
    "timestamp": "2024-01-01T12:00:00Z"
  }
  ```

---

#### 4.3 录入视力数据

**接口地址**: `POST /vision/input-vision`

**接口描述**: 录入学生的左右眼视力数据，支持 0 值，自动记录录入人和录入时间，并记录操作日志

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| vision_data_id | string | body | 否 | 视力数据ID，不传则新增记录，传则更新记录 |
| student_id | integer | body | 是 | 学生ID |
| left_eye_vision | number | body | 是 | 左眼视力（0-10），如：5.0，支持 0 值 |
| right_eye_vision | number | body | 是 | 右眼视力（0-10），如：4.8，支持 0 值 |
| input_user | string | body | 是 | 录入人姓名 |
| operator_phone | string | body | 是 | 操作人手机号 |

**请求示例**:

```json
{
  "student_id": 123,
  "left_eye_vision": 5.0,
  "right_eye_vision": 0,
  "input_user": "张医生",
  "operator_phone": "13900139000"
}
```

**响应示例**:

```json
{
  "code": 200,
  "message": "vision data created successfully",
  "data": {
    "vision_data_id": "550e8400e29b41d4a716446655440000"
  },
  "timestamp": "2024-01-01T12:00:00Z"
}
```

**错误响应**:

- `400`: 参数错误
  ```json
  {
    "code": 502,
    "message": "invalid request parameters",
    "data": null,
    "timestamp": "2024-01-01T12:00:00Z"
  }
  ```

- `404`: 记录不存在（更新时）
  ```json
  {
    "code": 404,
    "message": "vision data not found",
    "data": null,
    "timestamp": "2024-01-01T12:00:00Z"
  }
  ```

- `500`: 服务器错误
  ```json
  {
    "code": 501,
    "message": "failed to insert vision data",
    "data": {
      "details": "具体错误信息"
    },
    "timestamp": "2024-01-01T12:00:00Z"
  }
  ```

---

#### 4.4 录入屈光度数据

**接口地址**: `POST /vision/input-refraction`

**接口描述**: 录入学生的左右眼屈光度数据，支持 0 值，自动记录录入人和录入时间，并记录操作日志

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| vision_data_id | string | body | 否 | 视力数据ID，不传则新增记录，传则更新记录 |
| student_id | integer | body | 是 | 学生ID |
| left_eye_refraction | number | body | 是 | 左眼屈光度，如：-2.50，支持 0 值 |
| right_eye_refraction | number | body | 是 | 右眼屈光度，如：-3.00，支持 0 值 |
| input_user | string | body | 是 | 录入人姓名 |
| operator_phone | string | body | 是 | 操作人手机号 |

**请求示例**:

```json
{
  "student_id": 123,
  "left_eye_refraction": 0,
  "right_eye_refraction": -3.0,
  "input_user": "李医生",
  "operator_phone": "13700137000"
}
```

**响应示例**:

```json
{
  "code": 200,
  "message": "refraction data created successfully",
  "data": {
    "vision_data_id": "550e8400e29b41d4a716446655440000"
  },
  "timestamp": "2024-01-01T12:00:00Z"
}
```

**错误响应**:

- `400`: 参数错误
  ```json
  {
    "code": 502,
    "message": "invalid request parameters",
    "data": null,
    "timestamp": "2024-01-01T12:00:00Z"
  }
  ```

- `404`: 记录不存在（更新时）
  ```json
  {
    "code": 404,
    "message": "vision data not found",
    "data": null,
    "timestamp": "2024-01-01T12:00:00Z"
  }
  ```

- `500`: 服务器错误
  ```json
  {
    "code": 501,
    "message": "failed to insert refraction data",
    "data": {
      "details": "具体错误信息"
    },
    "timestamp": "2024-01-01T12:00:00Z"
  }
  ```

---

#### 4.5 根据视力数据ID修改数据

**接口地址**: `PUT /vision-data/{vision_data_id}`

**接口描述**: 根据视力数据ID修改视力或屈光度数据，支持部分字段更新，自动更新对应的录入状态和录入人信息

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| vision_data_id | string | path | 是 | 视力数据ID |
| left_eye_vision | number | body | 否 | 左眼视力（0-10） |
| right_eye_vision | number | body | 否 | 右眼视力（0-10） |
| left_eye_refraction | number | body | 否 | 左眼屈光度 |
| right_eye_refraction | number | body | 否 | 右眼屈光度 |
| input_user | string | body | 是 | 操作人姓名 |
| operator_phone | string | body | 是 | 操作人手机号 |

**请求示例**:

```json
{
  "left_eye_vision": 5.1,
  "right_eye_vision": 4.9,
  "input_user": "张医生",
  "operator_phone": "13600136000"
}
```

**响应示例**:

```json
{
  "code": 200,
  "message": "vision data updated successfully",
  "data": {
    "vision_data_id": "550e8400e29b41d4a716446655440000"
  },
  "timestamp": "2024-01-01T12:00:00Z"
}
```

**错误响应**:

- `400`: 参数错误
  ```json
  {
    "code": 400,
    "message": "at least one field must be provided for update",
    "data": null,
    "timestamp": "2024-01-01T12:00:00Z"
  }
  ```

- `404`: 记录不存在
  ```json
  {
    "code": 404,
    "message": "vision data not found",
    "data": null,
    "timestamp": "2024-01-01T12:00:00Z"
  }
  ```

- `500`: 服务器错误
  ```json
  {
    "code": 501,
    "message": "failed to update vision data",
    "data": {
      "details": "具体错误信息"
    },
    "timestamp": "2024-01-01T12:00:00Z"
  }
  ```

---

## 数据模型

### School（学校）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | 学校ID |
| name | string | 学校名称 |
| created_at | datetime | 创建时间 |

### Class（班级）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | 班级ID |
| school_id | string | 学校ID |
| grade | string | 年级名称 |
| class_name | string | 班级名称 |
| created_at | datetime | 创建时间 |

### Student（学生）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | integer | 学生ID |
| class_id | string | 班级ID |
| name | string | 学生姓名 |
| gender | string | 性别 |
| id_card | string | 身份证号 |
| created_at | datetime | 创建时间 |

### VisionData（视力数据）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | 视力数据ID |
| student_id | integer | 学生ID |
| left_eye_vision | number | 左眼视力 |
| right_eye_vision | number | 右眼视力 |
| left_eye_refraction | number | 左眼屈光度 |
| right_eye_refraction | number | 右眼屈光度 |
| vision_input_status | integer | 视力录入状态（0-未录入，1-已录入） |
| refraction_input_status | integer | 屈光度录入状态（0-未录入，1-已录入） |
| vision_input_user | string | 视力录入人 |
| vision_input_time | datetime | 视力录入时间 |
| refraction_input_user | string | 屈光度录入人 |
| refraction_input_time | datetime | 屈光度录入时间 |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

### OperationLog（操作日志）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | 日志ID |
| api_path | string | 接口地址 |
| parameters | string | 传入的参数（JSON格式） |
| operator | string | 操作人 |
| operator_phone | string | 操作人手机号 |
| created_at | datetime | 创建时间 |

---

## 统一响应格式说明

### 响应结构

所有接口均返回以下统一格式：

```json
{
  "code": 200,
  "message": "success",
  "data": {},
  "timestamp": "2024-01-01T12:00:00Z"
}
```

**字段说明：**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| code | int | 是 | 业务状态码（200=成功，其他=失败） |
| message | string | 是 | 响应消息（成功提示或错误信息） |
| data | any | 否 | 业务数据（成功时返回，失败时可为null） |
| timestamp | string | 是 | 服务器响应时间（ISO 8601格式） |

### 业务状态码说明

| 状态码 | HTTP状态码 | 说明 |
|--------|-----------|------|
| 200 | 200 | 请求成功 |
| 400 | 400 | 请求参数错误 |
| 401 | 401 | 未授权 |
| 403 | 403 | 禁止访问 |
| 404 | 404 | 资源不存在 |
| 409 | 409 | 资源冲突（如重复创建） |
| 500 | 500 | 服务器内部错误 |
| 501 | 500 | 数据库错误 |
| 502 | 400 | 数据验证错误 |

---

## 注意事项

1. 所有时间字段均为 ISO 8601 格式
2. 视力数据ID为32位不带连字符的UUID
3. 新增和更新操作会自动记录操作日志
4. 身份证号在同一班级内不能重复
5. 年级列表会按照小学、初中、高中的顺序自动排序