wx_service/docs/smoke/API.md

# 戒烟/抽烟记录 API

所有接口前缀：`/api/v1/smoke`  
除登录外都需要：`Authorization: Bearer <session_key>`（见：`docs/common/auth.md`）

## 1) 新增记录

`POST /api/v1/smoke/logs`

请求体：

```json
{
  "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 示例：

```bash
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}'
```

成功响应示例（字段以实际为准）：

```json
{
  "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 示例：

```bash
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`）

成功响应示例：

```json
{
  "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 天`。

成功响应示例：

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

成功响应示例：

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

请求体（字段可选，按需传）：

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

成功响应：

```json
{
  "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`）。

未满足权限时的建议响应（示例）：
```json
{
  "code": 403,
  "message": "需要会员或观看广告解锁后才可生成建议",
  "data": {
    "date": "2026-01-02",
    "need": "vip_or_ad"
  }
}
```

成功响应（示例）：
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "date": "2026-01-02",
    "advice": "..."
  }
}
```

## 9) 看广告解锁（用于非会员）

`POST /api/v1/smoke/ai/advice_unlocks`

请求体：
```json
{
  "date": "2026-01-02",
  "ad_watched_at": "2026-01-03 09:00:00"
}
```

说明：
- 该接口用于记录“已完成观看广告”，落库到 `fa_smoke_ai_advice_unlocks`（`uid + unlock_date` 唯一）。
- `ad_watched_at` 可由后端取当前时间；如需审计/对账可保留前端上报并做校验。