wx_service/docs/smoke/API.md

戒烟/抽烟记录 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：页码，默认 1
• page_size：每页数量，默认 20，最大 200
• start/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 可由后端取当前时间；如需审计/对账可保留前端上报并做校验。

10) 获取用户基础信息（首次进入：判断是否需要补全）

GET /api/v1/smoke/profile

说明：

• 首次进入小程序建议先调用该接口：若 exists=false 或 is_completed=false，前端进入“信息补全”流程。
• baseline_interval_minutes 用于建立初始基准：在用户清醒时段内的“平均间隔（分钟）”。计算：awake_minutes / baseline_cigs_per_day。
• 若未提供作息时间（起床/入睡），后端会用默认清醒时长 16*60=960 分钟参与计算。

成功响应（示例）：

{
  "code": 200,
  "message": "success",
  "data": {
    "exists": true,
    "profile": {
      "id": 1,
      "created_at": "2026-01-05T10:00:00+08:00",
      "updated_at": "2026-01-05T10:00:00+08:00",
      "baseline_cigs_per_day": 20,
      "smoking_years": 8,
      "pack_price_cent": 2500,
      "smoke_motivations": ["压力大", "社交"],
      "quit_motivations": ["身体健康", "省钱"],
      "wake_up_time": "07:30",
      "sleep_time": "23:30",
      "onboarding_completed_at": "2026-01-05T10:00:00+08:00"
    },
    "is_completed": true,
    "awake_minutes": 960,
    "baseline_interval_minutes": 48
  }
}

当 exists=false（尚未补全）时，响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "exists": false,
    "is_completed": false,
    "awake_minutes": 960,
    "baseline_interval_minutes": 0
  }
}

字段用途（补全页面可参考）：

• baseline_cigs_per_day（基础烟量/日均抽烟支数）：建立初始基准，计算初始建议间隔时长。
• smoking_years（烟龄/年）+ pack_price_cent（单包价格/分）：用于看板计算“已省金额”和“恢复时长”等指标（公式可在看板端实现）。
• smoke_motivations（抽烟动机）：如 压力大/无聊/社交/提神，用于 AI 在分析 remark 时更有针对性。
• quit_motivations（戒烟动力）：如 身体健康/家人孩子/省钱，当用户产生动摇时 AI 可用这些信息做“情感阻断/自我提醒”。
• wake_up_time + sleep_time（作息时间）：用于自动规避睡眠时间，防止在用户睡觉时提醒其“坚持”。

11) 补全/更新用户基础信息（Upsert）

PUT /api/v1/smoke/profile

说明：

• 字段按需传；首次进入建议一次性补全。
• 作息时间格式：HH:MM（24 小时制），例如 07:30、23:10。
• pack_price_cent 为“分”；若前端用“元”，请乘以 100。

请求体（示例）：

{
  "baseline_cigs_per_day": 20,
  "smoking_years": 8,
  "pack_price_cent": 2500,
  "smoke_motivations": ["压力大", "社交"],
  "quit_motivations": ["身体健康", "省钱"],
  "wake_up_time": "07:30",
  "sleep_time": "23:30"
}

成功响应：同 GET /api/v1/smoke/profile（返回最新 profile + is_completed + baseline_interval_minutes）。