Skip to content

api.md

Latest commit

 

History

History
389 lines (308 loc) · 7.41 KB

api.md

File metadata and controls

389 lines (308 loc) · 7.41 KB

API 文档

基础信息

  • Base URL: http://localhost:8080
  • Content-Type: application/json
  • 字符编码: UTF-8

通用响应格式

成功响应

{
  "message": "操作成功",
  "data": {},
  "count": 0
}

错误响应

{
  "error": "错误描述信息"
}

状态码说明

  • 200 OK - 请求成功
  • 400 Bad Request - 请求参数错误
  • 500 Internal Server Error - 服务器内部错误

API 接口列表

1. 提交拉屎记录

提交单条拉屎记录到数据库。

接口地址: POST /shit

请求头:

Content-Type: application/json

请求参数:

{
  "smoothness": "normal"
}

参数说明:

参数 类型 必填 说明
smoothness string 是 拉屎顺畅程度，可选值：blocked(完全拉不出)、hardly(几乎拉不出)、normal(正常拉屎)、diarrhea(一泻千里)

响应示例:

{
  "message": "写入成功",
  "traceID": "550e8400-e29b-41d4-a716-446655440000",
  "smoothness": "normal"
}

2. 生成测试数据

批量生成测试数据，用于开发和测试。

接口地址: POST /api/generate

请求参数:

{
  "start_date": "2024-01-01",
  "end_date": "2025-04-17",
  "count": 0
}

参数说明:

参数 类型 必填 说明
start_date string 是 开始日期，格式：YYYY-MM-DD
end_date string 是 结束日期，格式：YYYY-MM-DD
count int 否 生成天数（当前未使用，按日期范围生成）

生成规则:

  • 以 0-5 天的随机间隔生成数据
  • 每天最多生成 3 条记录
  • 每条记录的时间在当天内随机分布
  • 顺畅程度随机选择

响应示例:

{
  "message": "数据生成成功",
  "total_inserted": 156,
  "start_date": "2024-01-01",
  "end_date": "2025-04-17"
}

3. 获取散点图数据

获取所有拉屎记录，用于绘制散点图。

接口地址: GET /api/scatter

请求参数: 无

响应示例:

{
  "data": [
    {
      "time": "2024-01-01 08:30:00",
      "smoothness": "normal"
    },
    {
      "time": "2024-01-01 14:20:00",
      "smoothness": "diarrhea"
    }
  ],
  "count": 2
}

响应字段说明:

字段 类型 说明
data array 数据点数组
data[].time string 拉屎时间，格式：YYYY-MM-DD HH:mm:ss
data[].smoothness string 顺畅程度
count int 数据点总数

4. 腹泻分析

分析腹泻情况，识别腹泻日期。

接口地址: GET /api/diarrhea

请求参数: 无

判断标准:

  • 一天内拉屎次数 >= 3 次，判定为腹泻
  • 一天内 2 次拉屎的间隔 < 60 分钟，判定为腹泻

响应示例:

{
  "data": [
    {
      "date": "2024-01-15",
      "count": 4,
      "is_diarrhea": true,
      "intervals": [45, 120, 90],
      "has_short_interval": true
    }
  ],
  "count": 1
}

响应字段说明:

字段 类型 说明
data array 腹泻分析结果数组
data[].date string 日期，格式：YYYY-MM-DD
data[].count int 当天拉屎次数
data[].is_diarrhea boolean 是否为腹泻日
data[].intervals array 相邻两次拉屎的间隔（分钟）
data[].has_short_interval boolean 是否存在间隔 < 60 分钟的情况
count int 腹泻日总数

5. 便秘分析

分析便秘情况，识别拉屎困难的时间段。

接口地址: GET /api/constipation

请求参数: 无

判断标准:

  • 相邻两次拉屎的间隔 >= 3 天，判定为便秘

响应示例:

{
  "data": [
    {
      "start_date": "2024-01-10",
      "end_date": "2024-01-15",
      "days": 5,
      "is_constipation": true
    }
  ],
  "count": 1
}

响应字段说明:

字段 类型 说明
data array 便秘分析结果数组
data[].start_date string 开始日期，格式：YYYY-MM-DD
data[].end_date string 结束日期，格式：YYYY-MM-DD
data[].days int 间隔天数
data[].is_constipation boolean 是否为便秘
count int 便秘次数总数

6. 周报

获取每周拉屎统计报告。

接口地址: GET /api/weekly

请求参数: 无

健康状态判断标准:

  • 正常: 4-7 次/周
  • 便秘: <= 3 次/周
  • 腹泻: >= 8 次/周

响应示例:

{
  "data": [
    {
      "week_start": "2024-01-01",
      "week_end": "2024-01-07",
      "total_count": 5,
      "is_normal": true,
      "is_constipation": false,
      "is_diarrhea": false
    }
  ],
  "count": 1
}

响应字段说明:

字段 类型 说明
data array 周报数据数组
data[].week_start string 周开始日期（周一），格式：YYYY-MM-DD
data[].week_end string 周结束日期（周日），格式：YYYY-MM-DD
data[].total_count int 本周拉屎总次数
data[].is_normal boolean 是否正常
data[].is_constipation boolean 是否便秘
data[].is_diarrhea boolean 是否腹泻
count int 周报总数

7. 年报

获取每年拉屎统计报告。

接口地址: GET /api/yearly

请求参数: 无

响应示例:

{
  "data": [
    {
      "year": 2024,
      "total_count": 182,
      "avg_per_week": 3.5,
      "avg_per_month": 15.17,
      "diarrhea_days": 5,
      "constipation_days": 12
    }
  ],
  "count": 1
}

响应字段说明:

字段 类型 说明
data array 年报数据数组
data[].year int 年份
data[].total_count int 全年拉屎总次数
data[].avg_per_week float 平均每周次数
data[].avg_per_month float 平均每月次数
data[].diarrhea_days int 腹泻天数（一天 >= 3 次）
data[].constipation_days int 便秘次数（间隔 >= 3 天）
count int 年报总数

错误处理

常见错误

400 Bad Request - 参数格式错误

{
  "error": "无效的开始日期格式"
}

400 Bad Request - 参数验证失败

{
  "error": "开始日期不能晚于结束日期"
}

500 Internal Server Error - 数据库错误

{
  "error": "写入数据库失败"
}

使用示例

cURL 示例

提交拉屎记录:

curl -X POST http://localhost:8080/shit \
  -H "Content-Type: application/json" \
  -d '{"smoothness": "normal"}'

生成测试数据:

curl -X POST http://localhost:8080/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2024-01-01",
    "end_date": "2024-12-31"
  }'

获取散点图数据:

curl http://localhost:8080/api/scatter

获取腹泻分析:

curl http://localhost:8080/api/diarrhea

获取便秘分析:

curl http://localhost:8080/api/constipation

获取周报:

curl http://localhost:8080/api/weekly

获取年报:

curl http://localhost:8080/api/yearly

注意事项

  1. 所有日期格式统一使用 YYYY-MM-DD
  2. 时间格式统一使用 YYYY-MM-DD HH:mm:ss
  3. 顺畅程度枚举值必须使用小写：blocked、hardly、normal、diarrhea
  4. 周报以周一为周开始日期
  5. 所有接口都会在响应头中包含 TraceID，用于日志追踪