nepiedg
f1f77a4d3d
- Introduced a new API endpoint `GET /api/v1/smoke/dashboard` to retrieve a summary of smoking statistics over a specified date range, including today's count and weekly breakdown. - Added `GET /api/v1/smoke/logs/latest` endpoint to fetch the most recent smoking logs with a configurable limit. - Updated the smoke handler and service to support the new functionality, including error handling for date parsing and limit validation. - Enhanced documentation to reflect the new API endpoints and their usage.
5.5 KiB
5.5 KiB
戒烟/抽烟记录 API
所有接口前缀：/api/v1/smoke
除登录外都需要：Authorization: Bearer <session_key>（见：docs/common/auth.md）
1) 新增记录
POST /api/v1/smoke/logs
请求体：
{
"smoke_time": "2025-12-31",
"smoke_at": "2025-12-31 08:30:00",
"remark": "压力大",
"level": 2,
"num": 3
}
说明：
smoke_time可选；不传则默认“当天”。smoke_at可选；真实抽烟时间（格式YYYY-MM-DD HH:MM:SS）。用于“按时间节点分析/AI 建议”；不传则可用createtime近似。level/num可选；不传或传<=0时会按1处理。
curl 示例：
curl -X POST 'http://127.0.0.1:8080/api/v1/smoke/logs' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer wx-session-key' \
-d '{"smoke_time":"2025-12-31","smoke_at":"2025-12-31 08:30:00","remark":"压力大","level":2,"num":3}'
成功响应示例（字段以实际为准）：
{
"code": 200,
"message": "success",
"data": {
"id": 5202,
"smoke_time": "2025-12-31T00:00:00+08:00",
"smoke_at": "2025-12-31T08:30:00+08:00",
"remark": "压力大",
"createtime": 1735600000,
"updatetime": 1735600000,
"deletetime": null,
"level": 2,
"num": 3
}
}
2) 获取单条记录
GET /api/v1/smoke/logs/:id
curl 示例：
curl -X GET 'http://127.0.0.1:8080/api/v1/smoke/logs/5202' \
-H 'Authorization: Bearer wx-session-key'
3) 列表查询（分页）
GET /api/v1/smoke/logs?page=1&page_size=20&start=2025-12-01&end=2025-12-31
参数：
page：页码，默认1page_size：每页数量，默认20，最大200start/end：可选，按smoke_time过滤（格式YYYY-MM-DD）
成功响应示例：
{
"code": 200,
"message": "success",
"data": {
"items": [],
"total": 0,
"page": 1,
"page_size": 20
}
}
4) 获取看板概览
GET /api/v1/smoke/dashboard?start=2026-01-01&end=2026-01-07
参数：
start：起始日期（含，格式YYYY-MM-DD），默认“本周一”end：截止日期（含，格式YYYY-MM-DD），默认“本周日”。若只传start，end默认为start + 6 天。
成功响应示例：
{
"code": 200,
"message": "success",
"data": {
"today_count": 6,
"minutes_since_last": 42,
"weekly": [
{ "date": "2026-01-01", "count": 2, "is_today": false },
{ "date": "2026-01-02", "count": 1, "is_today": false },
{ "date": "2026-01-03", "count": 0, "is_today": false },
{ "date": "2026-01-04", "count": 0, "is_today": false },
{ "date": "2026-01-05", "count": 3, "is_today": true },
{ "date": "2026-01-06", "count": 0, "is_today": false },
{ "date": "2026-01-07", "count": 0, "is_today": false }
]
}
}
字段说明：
today_count：当天吸烟总支数（累加num）minutes_since_last：距最后一次抽烟的分钟数，通过最近一条smoke_at/smoke_time/createtime计算；若历史为空则字段不存在weekly：起止日期内每日汇总，count为当日总支数，is_today标记当前日期（即便不在start/end范围内也会标记为false）
5) 最近记录列表（轻量版）
GET /api/v1/smoke/logs/latest?limit=20
参数：
limit：返回条数，默认20，最大100
成功响应示例：
{
"code": 200,
"message": "success",
"data": {
"items": [
{
"id": 123,
"smoke_time": "2026-01-05T00:00:00+08:00",
"smoke_at": "2026-01-05T09:12:00+08:00",
"remark": "压力大",
"level": 3,
"num": 2,
"createtime": 1736049120
}
]
}
}
6) 更新记录
PUT /api/v1/smoke/logs/:id
请求体（字段可选，按需传）：
{
"smoke_time": "2026-01-01",
"smoke_at": "2026-01-01 21:10:00",
"remark": "聚会",
"level": 3,
"num": 1
}
注意：
- 如果你想“清空 smoke_time”，请传空字符串：
{"smoke_time":""}。 - 如果你想“清空 smoke_at”，请传空字符串：
{"smoke_at":""}。 - 如果传
null或者不传smoke_time，后端会认为你没有修改该字段。
7) 删除记录（软删除）
DELETE /api/v1/smoke/logs/:id
成功响应：
{
"code": 200,
"message": "success",
"data": {
"deleted": true
}
}
8) 获取 AI 戒烟建议（会员 + 广告解锁并行）
GET /api/v1/smoke/ai/advice?date=2026-01-02
说明：
date可选，默认“昨天”（建议针对哪一天的数据）。- 权限：会员用户直接可用；非会员需要先对该
date完成“看广告解锁”（见下一个接口）。 - 建议结果会按
uid + date + prompt_version缓存（表：fa_smoke_ai_advice）。
未满足权限时的建议响应（示例）：
{
"code": 403,
"message": "需要会员或观看广告解锁后才可生成建议",
"data": {
"date": "2026-01-02",
"need": "vip_or_ad"
}
}
成功响应（示例）：
{
"code": 200,
"message": "success",
"data": {
"date": "2026-01-02",
"advice": "..."
}
}
9) 看广告解锁（用于非会员）
POST /api/v1/smoke/ai/advice_unlocks
请求体：
{
"date": "2026-01-02",
"ad_watched_at": "2026-01-03 09:00:00"
}
说明：
- 该接口用于记录“已完成观看广告”，落库到
fa_smoke_ai_advice_unlocks（uid + unlock_date唯一）。 ad_watched_at可由后端取当前时间；如需审计/对账可保留前端上报并做校验。