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.
233 lines
7.1 KiB
Markdown
233 lines
7.1 KiB
Markdown
# 戒烟小程序 - 产品需求文档 (PRD)
|
||
|
||
## 1. 产品概述
|
||
|
||
### 1.1 产品定位
|
||
一款基于 AI 辅助的科学戒烟小程序，通过记录抽烟行为、数据分析、智能递减计划帮助用户逐步减少吸烟量，最终实现戒烟目标。
|
||
|
||
### 1.2 核心价值
|
||
- **记录追踪**：精确记录每次抽烟/忍住行为
|
||
- **数据洞察**：可视化展示吸烟趋势与规律
|
||
- **AI 指导**：个性化递减建议与时间节点规划
|
||
- **正向激励**：省钱计算、健康恢复、成就系统
|
||
|
||
### 1.3 目标用户
|
||
- 有戒烟意愿的吸烟者
|
||
- 想要减少吸烟量的用户
|
||
- 需要科学方法辅助戒烟的人群
|
||
|
||
---
|
||
|
||
## 2. 功能模块
|
||
|
||
### 2.1 首页 (home_dashboard)
|
||
|
||
**核心目标**：快速记录 + 实时激励
|
||
|
||
| 元素 | 说明 | 数据来源 |
|
||
|------|------|----------|
|
||
| 问候语 | 根据时段显示(早上好/下午好等) + 用户昵称 | 本地计算 + profile |
|
||
| AI 提示卡片 | 发现的抽烟规律/建议(可关闭) | `GET /ai/advice` 缓存 |
|
||
| 计时环 | 距上次抽烟时间(时:分:秒) | `GET /next_smoke_time` 的 `last_smoke_at`（前端计时） |
|
||
| 下次建议时间 | 显示建议的下次抽烟时间点 | `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` |
|
||
|
||
**性能要求**：
|
||
- 首屏渲染 < 500ms
|
||
- 关键数据(计时环)优先加载
|
||
- 非关键数据(AI提示)异步延迟加载
|
||
|
||
### 2.2 统计页 (smoking_statistics)
|
||
|
||
**核心目标**：数据可视化 + 趋势分析
|
||
|
||
| 功能 | 说明 | 数据来源 |
|
||
|------|------|----------|
|
||
| 周/月/年切换 | 切换统计时间范围 | `GET /stats?range=week|month|year` |
|
||
| 每周洞察 | AI 分析本周表现 | `GET /ai/advice` |
|
||
| 吸烟趋势图 | 柱状图展示每日吸烟量 | `stats.trend` |
|
||
| 趋势对比 | 较上周期变化 | `stats.change_percent` |
|
||
| 日均吸烟量 | 统计周期内日均值 | `stats.daily_average` |
|
||
| 节省金额 | 后端统一计算 | `stats.money` |
|
||
| 肺部功能恢复 | 后端统一计算 | `stats.health` |
|
||
| 连续记录天数 | 用户活跃天数 | `stats.streak_days` |
|
||
| 已拒绝次数 | 累计忍住次数 | `stats.resisted_total` |
|
||
|
||
### 2.3 AI 助手页 (ai_quit_assistant)
|
||
|
||
**核心目标**：个性化指导 + 阶段管理
|
||
|
||
| 功能 | 说明 | 数据来源 |
|
||
|------|------|----------|
|
||
| 减量计划卡片 | 当前阶段(第X/30天)、阶段名称、进度 | profile + 本地计算 |
|
||
| 每日 AI 分析 | 对话式展示昨日分析与今日建议 | `GET /ai/advice` |
|
||
| 今日目标 | 任务清单(喝水、散步、阅读激励等) | AI 生成 + 本地存储 |
|
||
| 记录按钮 | 快速记录吸烟或烟瘾 | 跳转记录流程 |
|
||
|
||
**阶段划分**：
|
||
1. 阶段1 - 记录期 (Day 1-7)：建立基线数据
|
||
2. 阶段2 - 减量期 (Day 8-21)：逐步减少吸烟量
|
||
3. 阶段3 - 巩固期 (Day 22-30)：维持低量/零吸烟
|
||
|
||
### 2.4 历史记录页 (activity_history)
|
||
|
||
**核心目标**：记录管理 + 行为回顾
|
||
|
||
| 功能 | 说明 | 数据来源 |
|
||
|------|------|----------|
|
||
| 筛选 Tabs | 全部 / 已抽烟 / 已忍住 | 前端筛选 |
|
||
| 时间线 | 按日期分组展示 | `GET /logs` |
|
||
| 记录卡片 | 类型、时间、原因标签、间隔时间 | logs 数据 |
|
||
| 左滑操作 | 编辑 / 删除 | `POST/DELETE /logs/:id` |
|
||
| 新增按钮 | 浮动按钮快速新增 | 跳转记录流程 |
|
||
|
||
### 2.5 个人中心 (profile_&_settings)
|
||
|
||
**核心目标**：用户信息 + 设置管理
|
||
|
||
| 功能 | 说明 | 数据来源 |
|
||
|------|------|----------|
|
||
| 用户信息 | 头像、昵称 | 微信授权 |
|
||
| 目标展示 | 目标戒烟日期、连续天数 | profile |
|
||
| 目标设定 | 调整每日限额与戒烟日期 | `POST /profile` |
|
||
| AI 计划调整 | 个性化辅导风格设置 | profile 扩展 |
|
||
| 通知设置 | 提醒时间、频率 | 本地存储 |
|
||
| 会员解锁 | PRO 功能 / 广告解锁 | 会员系统 |
|
||
| 基础设置 | 作息时间等 | `POST /profile` |
|
||
| 隐私与数据 | 数据导出、账号注销 | 待扩展 |
|
||
|
||
---
|
||
|
||
## 3. 用户流程
|
||
|
||
### 3.1 新用户引导流程
|
||
|
||
```
|
||
启动小程序
|
||
↓
|
||
微信登录 (wx.login)
|
||
↓
|
||
检查 profile (GET /profile)
|
||
↓
|
||
exists=false ? → 进入引导页
|
||
↓
|
||
Step 1: 每日吸烟量 (baseline_cigs_per_day)
|
||
↓
|
||
Step 2: 烟龄 (smoking_years)
|
||
↓
|
||
Step 3: 吸烟动机 (smoke_motivations)
|
||
↓
|
||
Step 4: 戒烟动力 (quit_motivations)
|
||
↓
|
||
Step 5: 作息时间 (wake_up_time, sleep_time)
|
||
↓
|
||
Step 6: 设置目标 (目标日期、每日限额)
|
||
↓
|
||
提交 profile (POST /profile)
|
||
↓
|
||
进入首页
|
||
```
|
||
|
||
### 3.2 日常使用流程
|
||
|
||
```
|
||
打开首页
|
||
↓
|
||
查看计时器 + 下次建议时间
|
||
↓
|
||
[想抽烟时]
|
||
├── 还没到建议时间 → 点击"想抽忍住了"
|
||
└── 到了/忍不住 → 点击"记录抽烟"
|
||
↓
|
||
记录表单 (可选填原因)
|
||
↓
|
||
提交成功 → 更新首页数据
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 数据模型
|
||
|
||
### 4.1 用户档案 (profile)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| baseline_cigs_per_day | int | 基准日吸烟量 |
|
||
| smoking_years | int | 烟龄(年) |
|
||
| pack_price_cent | int | 单包价格(分) |
|
||
| smoke_motivations | []string | 抽烟动机 |
|
||
| quit_motivations | []string | 戒烟动力 |
|
||
| wake_up_time | string | 起床时间 HH:MM |
|
||
| sleep_time | string | 入睡时间 HH:MM |
|
||
| daily_target | int | 每日目标限额(扩展) |
|
||
| quit_date | date | 目标戒烟日期(扩展) |
|
||
|
||
### 4.2 抽烟记录 (log)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| smoke_time | date | 记录日期 |
|
||
| smoke_at | datetime | 实际抽烟时间 |
|
||
| level | int | 烟瘾等级 0-5 (0=忍住) |
|
||
| num | int | 支数 (0=忍住) |
|
||
| remark | string | 原因备注 |
|
||
|
||
---
|
||
|
||
## 5. 性能优化策略
|
||
|
||
### 5.1 首页加载优化
|
||
|
||
**目标**：首屏 < 500ms
|
||
|
||
```
|
||
[并行请求]
|
||
├── GET /profile (用户信息，判断是否需引导)
|
||
├── GET /next_smoke_time (首页汇总 + 下次建议时间)
|
||
└── GET /dashboard (看板数据，可延迟)
|
||
|
||
[延迟加载]
|
||
└── GET /ai/advice (AI提示卡片，非关键)
|
||
```
|
||
|
||
**缓存策略**：
|
||
- profile: 登录后缓存，变更时更新
|
||
- next_smoke_time: 每次进入刷新，下一次记录后刷新
|
||
- dashboard: 进入看板时刷新
|
||
- ai/advice: 按天缓存
|
||
|
||
### 5.2 数据预加载
|
||
|
||
- 首页加载时预取统计页首屏数据
|
||
- TabBar 切换时使用缓存 + 后台刷新
|
||
|
||
---
|
||
|
||
## 6. 权限与会员
|
||
|
||
### 6.1 免费功能
|
||
- 记录抽烟/忍住
|
||
- 基础统计(周视图)
|
||
- 首页计时器
|
||
- 基础递减算法
|
||
|
||
### 6.2 会员/广告解锁功能
|
||
- AI 每日建议
|
||
- AI 时间节点规划
|
||
- 月/年统计视图
|
||
- 数据导出
|
||
|
||
---
|
||
|
||
## 7. 待扩展功能
|
||
|
||
- [ ] 成就系统 (连续X天、累计忍住X次等)
|
||
- [ ] 社交分享 (戒烟打卡海报)
|
||
- [ ] 提醒推送 (到达建议时间提醒)
|
||
- [ ] 健康知识卡片
|
||
- [ ] 紧急求助 (烟瘾强烈时的快速干预)
|