init

2026-01-25 11:45:16 +08:00
commit c883ae7b17
44 changed files with 5945 additions and 0 deletions
@@ -0,0 +1,231 @@
+# 戒烟小程序 - 产品需求文档 (PRD)
+
+## 1. 产品概述
+
+### 1.1 产品定位
+一款基于 AI 辅助的科学戒烟小程序，通过记录抽烟行为、数据分析、智能递减计划帮助用户逐步减少吸烟量，最终实现戒烟目标。
+
+### 1.2 核心价值
+- **记录追踪**：精确记录每次抽烟/忍住行为
+- **数据洞察**：可视化展示吸烟趋势与规律
+- **AI 指导**：个性化递减建议与时间节点规划
+- **正向激励**：省钱计算、健康恢复、成就系统
+
+### 1.3 目标用户
+- 有戒烟意愿的吸烟者
+- 想要减少吸烟量的用户
+- 需要科学方法辅助戒烟的人群
+
+---
+
+## 2. 功能模块
+
+### 2.1 首页 (home_dashboard)
+
+**核心目标**：快速记录 + 实时激励
+
+| 元素 | 说明 | 数据来源 |
+|------|------|----------|
+| 问候语 | 根据时段显示(早上好/下午好等) + 用户昵称 | 本地计算 + profile |
+| AI 提示卡片 | 发现的抽烟规律/建议(可关闭) | `GET /ai/advice` 缓存 |
+| 计时环 | 距上次抽烟时间(时:分:秒) | `dashboard.minutes_since_last` |
+| 下次建议时间 | 显示建议的下次抽烟时间点 | `GET /next_smoke_time` |
+| 今日已抽 | X / 目标数，较昨日 ±N | `dashboard.today_count` |
+| 烟瘾发作已抵抗 | 忍住次数统计 | 筛选 `level=0,num=0` 记录 |
+| 记录抽烟按钮 | 快速记录一次抽烟 | `POST /logs` |
+| 想抽忍住了按钮 | 记录成功抵抗 | `POST /logs/resisted` |
+
+**性能要求**：
+- 首屏渲染 < 500ms
+- 关键数据(计时环)优先加载
+- 非关键数据(AI提示)异步延迟加载
+
+### 2.2 统计页 (smoking_statistics)
+
+**核心目标**：数据可视化 + 趋势分析
+
+| 功能 | 说明 | 数据来源 |
+|------|------|----------|
+| 周/月/年切换 | 切换统计时间范围 | `GET /dashboard?start=&end=` |
+| 每周洞察 | AI 分析本周表现 | `GET /ai/advice` |
+| 吸烟趋势图 | 柱状图展示每日吸烟量 | `dashboard.weekly` |
+| 趋势对比 | 较上周减少 X% | 本地计算 |
+| 日均吸烟量 | 统计周期内日均值 | 本地计算 |
+| 节省金额 | 基于减少量 × 单价计算 | profile + logs |
+| 肺部功能恢复 | 根据戒烟天数估算 | 固定公式 |
+| 连续记录天数 | 用户活跃天数 | logs 统计 |
+| 已拒绝次数 | 累计忍住次数 | `level=0,num=0` 统计 |
+
+### 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 数据 |
+| 左滑操作 | 编辑 / 删除 | `PUT/DELETE /logs/:id` |
+| 新增按钮 | 浮动按钮快速新增 | 跳转记录流程 |
+
+### 2.5 个人中心 (profile_&_settings)
+
+**核心目标**：用户信息 + 设置管理
+
+| 功能 | 说明 | 数据来源 |
+|------|------|----------|
+| 用户信息 | 头像、昵称 | 微信授权 |
+| 目标展示 | 目标戒烟日期、连续天数 | profile |
+| 目标设定 | 调整每日限额与戒烟日期 | `PUT /profile` |
+| AI 计划调整 | 个性化辅导风格设置 | profile 扩展 |
+| 通知设置 | 提醒时间、频率 | 本地存储 |
+| 会员解锁 | PRO 功能 / 广告解锁 | 会员系统 |
+| 基础设置 | 作息时间等 | `PUT /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 (PUT /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 /dashboard (今日统计，计时器数据)
+└── GET /next_smoke_time (下次建议时间)
+
+[延迟加载]
+└── GET /ai/advice (AI提示卡片，非关键)
+```
+
+**缓存策略**：
+- profile: 登录后缓存，变更时更新
+- dashboard: 每次进入刷新，后台定时更新
+- next_smoke_time: 缓存至下次记录
+- ai/advice: 按天缓存
+
+### 5.2 数据预加载
+
+- 首页加载时预取统计页首屏数据
+- TabBar 切换时使用缓存 + 后台刷新
+
+---
+
+## 6. 权限与会员
+
+### 6.1 免费功能
+- 记录抽烟/忍住
+- 基础统计(周视图)
+- 首页计时器
+- 基础递减算法
+
+### 6.2 会员/广告解锁功能
+- AI 每日建议
+- AI 时间节点规划
+- 月/年统计视图
+- 数据导出
+
+---
+
+## 7. 待扩展功能
+
+- [ ] 成就系统 (连续X天、累计忍住X次等)
+- [ ] 社交分享 (戒烟打卡海报)
+- [ ] 提醒推送 (到达建议时间提醒)
+- [ ] 健康知识卡片
+- [ ] 紧急求助 (烟瘾强烈时的快速干预)