视力筛查管理系统 API 文档

基本信息

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

接口列表

1. 学校管理

1.1 获取学校信息

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

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

请求参数:

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

响应示例:

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

错误响应:

400: 参数错误

{
"code": 400,
"message": "school_id is required",
"data": null,
"timestamp": "2024-01-01T12:00:00Z"
}

404: 学校不存在

{
"code": 404,
"message": "school not found",
"data": null,
"timestamp": "2024-01-01T12:00:00Z"
}

500: 服务器错误

{
"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

响应示例:

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

错误响应:

400: 参数错误

{
"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	是	年级名称，如：一年级、初一、高一

响应示例:

{
  "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: 参数错误

{
"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	是	操作人手机号

请求示例:

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

响应示例:

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

错误响应:

400: 参数错误

{
"code": 502,
"message": "invalid request parameters",
"data": null,
"timestamp": "2024-01-01T12:00:00Z"
}

409: 学生已存在

{
"code": 409,
"message": "student with this id_card already exists in the class",
"data": null,
"timestamp": "2024-01-01T12:00:00Z"
}

500: 服务器错误

{
"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	否	身份证号（模糊查询）

响应示例:

{
  "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: 参数错误

{
"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

响应示例:

{
  "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: 参数错误

{
"code": 400,
"message": "student_id is required",
"data": null,
"timestamp": "2024-01-01T12:00:00Z"
}

404: 数据不存在

{
"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	是	操作人手机号

请求示例:

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

响应示例:

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

错误响应:

400: 参数错误

{
"code": 502,
"message": "invalid request parameters",
"data": null,
"timestamp": "2024-01-01T12:00:00Z"
}

404: 记录不存在（更新时）

{
"code": 404,
"message": "vision data not found",
"data": null,
"timestamp": "2024-01-01T12:00:00Z"
}

500: 服务器错误

{
"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	是	操作人手机号

请求示例:

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

响应示例:

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

错误响应:

400: 参数错误

{
"code": 502,
"message": "invalid request parameters",
"data": null,
"timestamp": "2024-01-01T12:00:00Z"
}

404: 记录不存在（更新时）

{
"code": 404,
"message": "vision data not found",
"data": null,
"timestamp": "2024-01-01T12:00:00Z"
}

500: 服务器错误

{
"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	是	操作人手机号

请求示例:

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

响应示例:

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

错误响应:

400: 参数错误

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

404: 记录不存在

{
"code": 404,
"message": "vision data not found",
"data": null,
"timestamp": "2024-01-01T12:00:00Z"
}

500: 服务器错误

{
"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	创建时间

统一响应格式说明

响应结构

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

{
  "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	数据验证错误

注意事项

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

API文档.md 16 KB Permalink History Raw

视力筛查管理系统 API 文档

基本信息

接口列表

1. 学校管理

1.1 获取学校信息

2. 年级管理

2.1 获取学校年级列表

2.2 获取年级班级列表

3. 学生管理

3.1 新增学生

4. 视力筛查

4.1 查询学生视力筛查数据

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

4.3 录入视力数据

4.4 录入屈光度数据

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

数据模型

School（学校）

Class（班级）

Student（学生）

VisionData（视力数据）

OperationLog（操作日志）

统一响应格式说明

响应结构

业务状态码说明

注意事项

API文档.md 16 KB

Permalink History Raw