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.

docs/smoke/ALGORITHM.md

@@ -202,7 +202,9 @@ function calculateDailyTarget(baseline, stage, dayInStage) {
 
 ---
 
-## 5. 健康恢复计算
+## 5. 健康恢复计算（后端统一）
+
+接口：`GET /api/v1/smoke/stats?range=week|month|year`（详见 `docs/smoke/API.md`）
 
 基于医学研究的恢复时间线：
 
@@ -236,7 +238,9 @@ function calculateLungRecovery(smokeFreeMinutes) {
 
 ---
 
-## 6. 省钱计算
+## 6. 省钱计算（后端统一）
+
+接口：`GET /api/v1/smoke/stats?range=week|month|year`（详见 `docs/smoke/API.md`）
 
 ```javascript
 // utils/money.js
@@ -250,7 +254,9 @@ function calculateMoneySaved(packPriceCent, cigsPerPack, baselineCigsPerDay, act
 
 ---
 
-## 7. 激励语生成
+## 7. 激励语生成（后端统一）
+
+接口：`GET /api/v1/smoke/motivation`（详见 `docs/smoke/API.md`）
 
 根据用户状态生成不同的激励语：
 

docs/smoke/API.md

@@ -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"
+  }
+}
+```

docs/smoke/PRD.md

@@ -32,6 +32,7 @@
 | 下次建议时间 | 显示建议的下次抽烟时间点 | `GET /next_smoke_time` |
 | 今日已抽 | X / 目标数，较昨日 ±N | `next_smoke_time.today_count` + `next_smoke_time.reduced_from_yesterday`（可为负） + `next_smoke_time.exceeded_yesterday`（标识“超出昨日”） |
 | 烟瘾发作已抵抗 | 忍住次数统计 | `next_smoke_time.resisted_count` |
+| 激励语 | 当天一句话鼓励 | `GET /motivation` |
 | 记录抽烟按钮 | 快速记录一次抽烟 | `POST /logs` |
 | 想抽忍住了按钮 | 记录成功抵抗 | `POST /logs/resisted` |
 
@@ -46,15 +47,15 @@
 
 | 功能 | 说明 | 数据来源 |
 |------|------|----------|
-| 周/月/年切换 | 切换统计时间范围 | `GET /dashboard?start=&end=` |
+| 周/月/年切换 | 切换统计时间范围 | `GET /stats?range=week|month|year` |
 | 每周洞察 | AI 分析本周表现 | `GET /ai/advice` |
-| 吸烟趋势图 | 柱状图展示每日吸烟量 | `dashboard.weekly` |
-| 趋势对比 | 较上周减少 X% | 本地计算 |
-| 日均吸烟量 | 统计周期内日均值 | 本地计算 |
-| 节省金额 | 基于减少量 × 单价计算 | profile + logs |
-| 肺部功能恢复 | 根据戒烟天数估算 | 固定公式 |
-| 连续记录天数 | 用户活跃天数 | logs 统计 |
-| 已拒绝次数 | 累计忍住次数 | `level=0,num=0` 统计 |
+| 吸烟趋势图 | 柱状图展示每日吸烟量 | `stats.trend` |
+| 趋势对比 | 较上周期变化 | `stats.change_percent` |
+| 日均吸烟量 | 统计周期内日均值 | `stats.daily_average` |
+| 节省金额 | 后端统一计算 | `stats.money` |
+| 肺部功能恢复 | 后端统一计算 | `stats.health` |
+| 连续记录天数 | 用户活跃天数 | `stats.streak_days` |
+| 已拒绝次数 | 累计忍住次数 | `stats.resisted_total` |
 
 ### 2.3 AI 助手页 (ai_quit_assistant)
 

docs/smoke/PRODUCT.md

@@ -82,9 +82,10 @@
 
 ## 5. 页面能力清单
 - 首页：上次实际抽烟时间（用于计时）、今日累计、今日克制、较昨日增减（可为负并标识“超出昨日”）、下次建议时间（默认/AI）、时间节点列表、快速入口（抽烟/忍住）。
+- 首页激励语：`GET /api/v1/smoke/motivation`
 - 记录页：快速添加抽烟、快速忍住、补录真实时间 `smoke_at`。
 - 列表页：按日期筛选、分页、区分“抽烟/忍住”标签、支持编辑/删除。
-- 看板页：周视图/区间视图，展示每日支数与 `minutes_since_last`。
+- 看板/统计页：使用 `GET /api/v1/smoke/stats?range=week|month|year` 获取趋势、均值、环比、健康与省钱等数据。
 - AI 建议页：每日建议展示（解锁后生成）。
 - 基础信息页：补全/编辑基础烟量、动机/动力、作息。