# 健康数据模块API接口规范 ## 概述 本文档详细定义了健康数据模块的API接口规范，包括4个子模块的完整接口定义。所有接口遵循RESTful设计理念，采用统一的请求/响应格式。 ## 公共规范 ### 请求格式 - **Content-Type**: `application/json` - **认证方式**: Bearer Token (`Authorization: Bearer `) - **参数校验**: 使用Bean Validation注解 ### 响应格式 ```json { "code": "SUCCESS", "message": "操作成功", "data": {} } ``` ### 分页响应格式 ```json { "code": "SUCCESS", "message": "查询成功", "data": { "records": [], "current": 1, "size": 10, "total": 100 } } ``` ### 错误响应格式 ```json { "code": "PARAM_ERROR", "message": "参数校验失败", "data": null } ``` ## 体格数据模块API ### 1. 添加体格数据 - **接口路径**: `POST /physical-data/add` - **功能描述**: 添加用户的体格数据（身高、体重） - **请求参数**: ```json { "height": 170.5, "weight": 65.2, "measureTime": "2024-01-15T10:30:00" } ``` - **参数说明**: - `height`: 身高(cm)，范围100-250，必填 - `weight`: 体重(kg)，范围20-300，必填 - `measureTime`: 测量时间，必填 - **响应示例**: ```json { "code": "SUCCESS", "message": "添加成功", "data": null } ``` ### 2. 查询体格数据列表 - **接口路径**: `POST /physical-data/list` - **功能描述**: 分页查询用户的体格数据历史记录 - **请求参数**: ```json { "pageNum": 1, "pageSize": 10, "startTime": "2024-01-01T00:00:00", "endTime": "2024-01-31T23:59:59" } ``` - **参数说明**: - `pageNum`: 页码，默认1 - `pageSize`: 每页大小，默认10，最大100 - `startTime`: 开始时间，可选 - `endTime`: 结束时间，可选 - **响应示例**: ```json { "code": "SUCCESS", "message": "查询成功", "data": { "records": [ { "id": 1, "height": 170.5, "weight": 65.2, "bmi": 22.45, "measureTime": "2024-01-15T10:30:00", "createTime": "2024-01-15T10:35:00" } ], "current": 1, "size": 10, "total": 1 } } ``` ### 3. 计算BMI - **接口路径**: `GET /physical-data/bmi` - **功能描述**: 根据身高体重计算BMI值 - **请求参数**: Query参数 - `height`: 身高(cm)，范围100-250，必填 - `weight`: 体重(kg)，范围20-300，必填 - **请求示例**: `GET /physical-data/bmi?height=170.5&weight=65.2` - **响应示例**: ```json { "code": "SUCCESS", "message": "计算成功", "data": 22.45 } ``` ## 血压数据模块API ### 1. 添加血压数据 - **接口路径**: `POST /blood-pressure-data/add` - **功能描述**: 添加用户的血压数据 - **请求参数**: ```json { "systolicPressure": 120, "diastolicPressure": 80, "measureTime": "2024-01-15T10:30:00" } ``` - **参数说明**: - `systolicPressure`: 收缩压(mmHg)，范围60-250，必填 - `diastolicPressure`: 舒张压(mmHg)，范围40-150，必填 - `measureTime`: 测量时间，必填 - **响应示例**: ```json { "code": "SUCCESS", "message": "添加成功", "data": null } ``` ### 2. 查询血压数据列表 - **接口路径**: `POST /blood-pressure-data/list` - **功能描述**: 分页查询用户的血压数据历史记录 - **请求参数**: ```json { "pageNum": 1, "pageSize": 10, "startTime": "2024-01-01T00:00:00", "endTime": "2024-01-31T23:59:59" } ``` - **响应示例**: ```json { "code": "SUCCESS", "message": "查询成功", "data": { "records": [ { "id": 1, "systolicPressure": 120, "diastolicPressure": 80, "measureTime": "2024-01-15T10:30:00", "createTime": "2024-01-15T10:35:00" } ], "current": 1, "size": 10, "total": 1 } } ``` ## 血糖数据模块API ### 1. 添加血糖数据 - **接口路径**: `POST /blood-glucose-data/add` - **功能描述**: 添加用户的血糖数据 - **请求参数**: ```json { "type": "FASTING", "value": 5.2, "measureTime": "2024-01-15T10:30:00" } ``` - **参数说明**: - `type`: 血糖测量类型，枚举值（如`FASTING`、`AFTER_BREAKFAST`等），必填 - `value`: 血糖值(mmol/L)，范围1.0-30.0，必填 - `measureTime`: 测量时间，必填 - **响应示例**: ```json { "code": "SUCCESS", "message": "添加成功", "data": null } ``` ### 2. 查询血糖数据列表 - **接口路径**: `POST /blood-glucose-data/list` - **功能描述**: 分页查询用户的血糖数据历史记录 - **请求参数**: ```json { "pageNum": 1, "pageSize": 10, "startTime": "2024-01-01T00:00:00", "endTime": "2024-01-31T23:59:59" } ``` - **响应示例**: ```json { "code": "SUCCESS", "message": "查询成功", "data": { "records": [ { "id": 1, "fastingBloodGlucose": 5.2, "afterBreakfastBloodGlucose": 8.5, "beforeLunchBloodGlucose": 6.1, "afterLunchBloodGlucose": 9.2, "beforeDinnerBloodGlucose": 5.8, "afterDinnerBloodGlucose": 8.9, "beforeBedBloodGlucose": 7.3, "measureTime": "2024-01-15T10:30:00", "createTime": "2024-01-15T10:35:00" } ], "current": 1, "size": 10, "total": 1 } } ``` ## 心率数据模块API ### 1. 添加心率数据 - **接口路径**: `POST /heart-rate-data/add` - **功能描述**: 添加用户的心率数据 - **请求参数**: ```json { "heartRate": 75, "measureTime": "2024-01-15T10:30:00" } ``` - **参数说明**: - `heartRate`: 心率(次/分钟)，范围30-200，必填 - `measureTime`: 测量时间，必填 - **响应示例**: ```json { "code": "SUCCESS", "message": "添加成功", "data": null } ``` ### 2. 查询心率数据列表 - **接口路径**: `POST /heart-rate-data/list` - **功能描述**: 分页查询用户的心率数据历史记录 - **请求参数**: ```json { "pageNum": 1, "pageSize": 10, "startTime": "2024-01-01T00:00:00", "endTime": "2024-01-31T23:59:59" } ``` - **响应示例**: ```json { "code": "SUCCESS", "message": "查询成功", "data": { "records": [ { "id": 1, "heartRate": 75, "measureTime": "2024-01-15T10:30:00", "createTime": "2024-01-15T10:35:00" } ], "current": 1, "size": 10, "total": 1 } } ``` ## 错误码定义 ### 通用错误码 - `SUCCESS`: 操作成功 - `PARAM_ERROR`: 参数校验失败 - `SYSTEM_ERROR`: 系统内部错误 - `UNAUTHORIZED`: 未授权访问 - `FORBIDDEN`: 权限不足 ### 业务错误码 - `DATA_NOT_FOUND`: 数据不存在 - `DATA_ALREADY_EXISTS`: 数据已存在 - `INVALID_MEASURE_TIME`: 无效的测量时间 - `INVALID_DATA_RANGE`: 数据超出有效范围 ## 接口调用示例 ### 添加体格数据 ```bash curl -X POST "http://localhost:8080/physical-data/add" \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \ -H "Content-Type: application/json" \ -d '{ "height": 170.5, "weight": 65.2, "measureTime": "2024-01-15T10:30:00" }' ``` ### 查询体格数据 ```bash curl -X POST "http://localhost:8080/physical-data/list" \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \ -H "Content-Type: application/json" \ -d '{ "pageNum": 1, "pageSize": 10 }' ``` ### 计算BMI ```bash curl -X GET "http://localhost:8080/physical-data/bmi?height=170.5&weight=65.2" \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." ``` ## 注意事项 1. **数据单位**: 严格按照接口文档中定义的单位进行数据录入 2. **时间格式**: 所有时间字段使用ISO 8601格式 3. **分页参数**: 页码从1开始，每页大小不超过100 4. **权限控制**: 所有接口都需要有效的用户认证 5. **数据校验**: 前端应进行初步校验，后端会进行二次校验 6. **并发控制**: 高频数据录入时注意避免重复提交 ## 版本信息 - **API版本**: v1.0 - **文档版本**: 1.0 - **更新日期**: 2024-01-15