|
|
@@ -0,0 +1,732 @@
|
|
|
+# 视力筛查管理系统 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. 年级列表会按照小学、初中、高中的顺序自动排序
|