nepiedg
f80c3e8f45
- Enhanced the algorithm documentation to clarify the calculation of smoking intervals, including default values and edge cases. - Updated API documentation to reflect changes in response formats, including the addition of `exceeded_yesterday` and adjustments to time formatting to RFC3339. - Improved descriptions of user profile management and AI suggestions in the product documentation, ensuring consistency across all related files. - Removed outdated sequence diagram and UI documentation files to streamline project resources.
110 lines
5.7 KiB
Markdown
110 lines
5.7 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）、时间节点列表、快速入口（抽烟/忍住）。
|
||
- 记录页：快速添加抽烟、快速忍住、补录真实时间 `smoke_at`。
|
||
- 列表页：按日期筛选、分页、区分“抽烟/忍住”标签、支持编辑/删除。
|
||
- 看板页：周视图/区间视图，展示每日支数与 `minutes_since_last`。
|
||
- 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 付费/广告：解锁按钮曝光 -> 广告完成 -> 生成成功率。
|