nepiedg
c9ebfd5873
- 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.
111 lines
5.8 KiB
Markdown
111 lines
5.8 KiB
Markdown
# 戒烟/抽烟记录小程序：产品说明（PRD）
|
||
|
||
本文档面向前端/产品/测试，描述小程序的目标、核心流程、页面能力与后端接口对接方式。
|
||
|
||
## 1. 产品目标
|
||
|
||
### 1.1 核心目标
|
||
- 帮用户“更直观地记录抽烟与忍住”，形成可回顾的数据。
|
||
- 在不使用 AI 的情况下提供默认策略：给出“下次建议记录时间”（阶梯式延时）。
|
||
- 在用户解锁（看广告/会员）后，提供更个性化的 AI：每日建议 + 当天/明天的时间节点计划。
|
||
|
||
### 1.2 非目标（暂不做）
|
||
- 医疗诊断、处方建议、健康风险评估。
|
||
- 强绑定设备（如穿戴）或复杂提醒系统（可后续扩展）。
|
||
|
||
## 2. 用户与场景
|
||
|
||
### 2.1 目标用户
|
||
- 有戒烟/控烟意愿的烟民。
|
||
- 想要“看到进步”（忍住次数、间隔变长）的人。
|
||
|
||
### 2.2 典型场景
|
||
- 抽完烟立刻记一笔（含时间/原因/数量）。
|
||
- 想抽但忍住：快速一键记录（`level=0,num=0`）。
|
||
- 首页查看：下次建议时间、上次实际抽烟时间、今日累计、今日克制、较昨日增减。
|
||
- 每天晚上/第二天查看 AI 总结与行动建议（解锁后）。
|
||
- 生成“今天/明天时间节点计划”（解锁后），帮助前端展示时间线/日程。
|
||
|
||
## 3. 业务定义与数据口径
|
||
|
||
### 3.1 抽烟记录
|
||
- 实际抽烟：`num>0`（支数），`level>=1`（烟瘾程度）。
|
||
- 想抽但忍住：`level=0 && num=0`（仍写入 `fa_smoke_log`，用于列表可见与算法输入）。
|
||
|
||
### 3.2 “最后一次抽烟”
|
||
- 定义为“最后一次实际抽烟事件”（忽略忍住记录）。
|
||
- 首页口径使用 `next_smoke_time` 返回的 `last_smoke_at` 作为计时起点（前端可自行计算间隔）。
|
||
- 看板的 `minutes_since_last` 仍按该口径计算。
|
||
|
||
### 3.3 默认“下次建议时间”（不使用 AI）
|
||
- 基础间隔来自 `GET /api/v1/smoke/profile` 的 `baseline_interval_minutes`（若无则默认 60 分钟）。
|
||
- 阶梯式延时：最近 7 天每累计 5 条忍住记录，在基础间隔上 +5 分钟（上限 +60 分钟）。
|
||
- 作息规避：如落在睡眠区间，顺延到起床时间。
|
||
- 支持生成某日计划：`GET /api/v1/smoke/next_smoke_time?date=today|tomorrow|YYYY-MM-DD`。
|
||
|
||
### 3.4 AI “时间节点计划”
|
||
- 仅在用户“已解锁当天（或指定 date）”时生成（看广告/会员）。
|
||
- 输入包含：最近 3 天抽烟与忍住数据 + 作息/动机/动力 + 默认策略。
|
||
- 输出包含：
|
||
- `not_before_at`：不早于时间（后端会强制不早于默认策略的最小不早于时间）
|
||
- `suggested_at`：建议的下次时间（>= not_before_at）
|
||
- `time_nodes`：3~6 个关键节点（HH:MM）
|
||
- `advice`：一句话策略
|
||
- 缓存策略：同一天生成一次即可复用（按 `date`）。
|
||
|
||
## 4. 核心用户流程
|
||
|
||
### 4.1 首次进入（Onboarding）
|
||
1) 登录：`POST /api/v1/auth/login` 获取 `session_key`（Bearer）。
|
||
2) 拉取基础信息：`GET /api/v1/smoke/profile`
|
||
3) 若未补全：进入补全页，提交：`POST /api/v1/smoke/profile`
|
||
4) 进入首页：展示下次时间/今日累计/最近记录。
|
||
|
||
### 4.2 日常记录
|
||
- 实际抽烟：`POST /api/v1/smoke/logs`
|
||
- 忍住：`POST /api/v1/smoke/logs/resisted`
|
||
- 列表：`GET /api/v1/smoke/logs`、`GET /api/v1/smoke/logs/latest`
|
||
- 编辑/删除：`POST /api/v1/smoke/logs/:id`、`DELETE /api/v1/smoke/logs/:id`
|
||
|
||
### 4.3 首页“下次时间”
|
||
- 默认展示：`GET /api/v1/smoke/next_smoke_time?date=today&mode=auto`
|
||
- 若已存在 AI 时间节点：返回 `source=ai`
|
||
- 否则：返回 `source=default`
|
||
- 生成 AI 节点（需要解锁）：`GET /api/v1/smoke/next_smoke_time?date=today&mode=ai`
|
||
- 接口会同时返回首页汇总字段：`last_smoke_at`、`today_count`、`resisted_count`、`reduced_from_yesterday`（可为负，负数代表“超出昨日”）、`exceeded_yesterday`（前端用于标识“超出昨日”）。
|
||
|
||
### 4.4 AI 解锁（按天）
|
||
- 看广告完成后回调：`POST /api/v1/smoke/ai/advice_unlocks {date}`
|
||
- 解锁后可生成：
|
||
- 每日 AI 建议：`GET /api/v1/smoke/ai/advice?date=...`
|
||
- AI 时间节点计划：`GET /api/v1/smoke/next_smoke_time?date=...&mode=ai`
|
||
|
||
## 5. 页面能力清单
|
||
- 首页：上次实际抽烟时间（用于计时）、今日累计、今日克制、较昨日增减（可为负并标识“超出昨日”）、下次建议时间（默认/AI）、时间节点列表、快速入口（抽烟/忍住）。
|
||
- 首页激励语：`GET /api/v1/smoke/motivation`
|
||
- 记录页：快速添加抽烟、快速忍住、补录真实时间 `smoke_at`。
|
||
- 列表页：按日期筛选、分页、区分“抽烟/忍住”标签、支持编辑/删除。
|
||
- 看板/统计页：使用 `GET /api/v1/smoke/stats?range=week|month|year` 获取趋势、均值、环比、健康与省钱等数据。
|
||
- AI 建议页：每日建议展示（解锁后生成）。
|
||
- 基础信息页：补全/编辑基础烟量、动机/动力、作息。
|
||
|
||
## 6. 接口对接约定（摘要）
|
||
|
||
### 6.1 认证
|
||
- Header：`Authorization: Bearer <session_key>`
|
||
- 登录文档：`docs/common/auth.md`
|
||
|
||
### 6.2 Smoke 模块 API
|
||
- 详见：`docs/smoke/API.md`
|
||
|
||
## 7. 权限与错误处理（产品口径）
|
||
- 未登录：统一提示“请先登录”，引导重新登录。
|
||
- AI 未解锁（403）：弹窗/页内提示“观看广告解锁当天生成”，提供“去观看”按钮。
|
||
- AI 服务不可用（503）：提示“稍后再试”，不阻断默认策略展示。
|
||
- 没有记录：列表/看板显示空态；首页 `last_smoke_at` 不显示或展示“暂无数据”。
|
||
|
||
## 8. 埋点与指标（建议）
|
||
- D1/D7 留存：进入首页、完成补全、记录次数（抽烟/忍住）、打开看板、生成 AI 建议。
|
||
- “忍住记录”转化：忍住按钮点击 -> 成功落库。
|
||
- AI 付费/广告：解锁按钮曝光 -> 广告完成 -> 生成成功率。
|