Update algorithm and API documentation for smoking recovery and motivation features

- Added unified backend calculations for health recovery, savings, and motivation generation in the algorithm documentation. - Updated API documentation to include new endpoints for retrieving statistics and motivation messages, enhancing clarity on data retrieval processes. - Revised product documentation to reflect changes in API usage for health recovery and savings calculations, ensuring consistency across all related files.
2026-01-25 09:33:10 +00:00
parent f80c3e8f45
commit c9ebfd5873
7 changed files with 595 additions and 12 deletions
@@ -433,3 +433,83 @@ AI 生成说明：
 - `resisted_count`：今日克制次数（`level=0 && num=0`）。
 - `reduced_from_yesterday`：较昨日减少的支数（允许为负数；为负时表示“今天超出昨日”）。
 - `exceeded_yesterday`：是否超出昨日（`true` 表示今天超出昨日，前端可用作单独标识）。
+
+## 14) 数据统计分析（趋势 + 健康 + 省钱）
+
+`GET /api/v1/smoke/stats?range=week|month|year&date=2026-01-07`
+
+参数：
+- `range`：`week|month|year`，默认 `week`
+- `date`：锚点日期（`YYYY-MM-DD`），默认今天
+
+说明：
+- 用于“统计页”一屏数据整合（趋势、均值、环比、健康恢复、省钱、连续记录、已拒绝次数）。
+- `trend_unit`：`day` 或 `month`，用于前端图表横轴显示。
+
+成功响应（示例）：
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "range": "week",
+    "start": "2026-01-01",
+    "end": "2026-01-07",
+    "trend_unit": "day",
+    "trend": [
+      { "label": "2026-01-01", "count": 2 },
+      { "label": "2026-01-02", "count": 1 },
+      { "label": "2026-01-03", "count": 0 },
+      { "label": "2026-01-04", "count": 0 },
+      { "label": "2026-01-05", "count": 3 },
+      { "label": "2026-01-06", "count": 0 },
+      { "label": "2026-01-07", "count": 0 }
+    ],
+    "daily_average": 4,
+    "change_percent": -20,
+    "money": {
+      "available": true,
+      "pack_price_cent": 2500,
+      "cigs_per_pack": 20,
+      "expected_total": 140,
+      "actual_total": 92,
+      "saved_cent": 6000
+    },
+    "health": {
+      "available": true,
+      "smoke_free_minutes": 420,
+      "lung_recovery_percent": 12,
+      "milestones": [
+        { "name": "心率血压恢复正常", "minutes": 20, "reached": true },
+        { "name": "血氧水平恢复", "minutes": 480, "reached": false }
+      ]
+    },
+    "streak_days": 12,
+    "resisted_total": 24
+  }
+}
+```
+
+字段说明：
+- `change_percent`：与上一个同周期对比的变化比例（可为负）。
+- `money.available=false`：表示缺少 `baseline_cigs_per_day` 或 `pack_price_cent`。
+- `health.available=false`：表示无历史记录。
+
+## 15) 激励语（后端统一生成）
+
+`GET /api/v1/smoke/motivation`
+
+说明：
+- 基于当日数据（如 `today_count`、`resisted_count`、`last_smoke_at`）与 `quit_motivations` 生成一句激励语。
+
+成功响应（示例）：
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "message": "今天的表现很稳，继续保持！记住你的目标：身体健康。",
+    "type": "encourage"
+  }
+}
+```