wx_service/docs/smoke/UI.md

戒烟/抽烟记录小程序：UI/UX 设计说明

本文档面向前端实现，包含信息架构、页面结构、组件与交互细节，以及与后端 API 的映射。

1. 信息架构（IA）

推荐 4 个 Tab：

1. 首页
2. 记录
3. 看板
4. 我的

页面路由（建议）：

• 首页：NextTimeCard + QuickActions + TodaySummary + RecentList
• 记录：新增抽烟、忍住、历史列表入口
• 看板：周视图/区间视图
• 我的：基础信息、AI/解锁入口、帮助与隐私

2. 视觉与组件规范（简版）

2.1 视觉风格

• 主色：清爽、偏健康（绿色/蓝绿）+ 强对比强调色（橙/红用于“抽烟”风险提示，但避免羞辱语气）。
• 卡片化布局：关键指标卡片（下次时间/今日累计/间隔）。

2.2 通用组件

• AppHeader：标题 + 日期切换（today/tomorrow）
• MetricCard：标题/主数值/辅助说明/状态标识（AI/默认）
• PrimaryButton / SecondaryButton
• Tag：抽烟/忍住/动机标签
• Timeline：时间节点列表（AI time_nodes）
• EmptyState / ErrorState / Skeleton
• ModalPaywall：广告解锁提示（403）

2.3 文案口径

• 避免指责：使用“建议/可以尝试/你已经在进步”。
• 忍住记录：用“忍住了”/“成功延后”作为正反馈。

3. 页面详设

3.1 首页（核心）

目标

• 让用户一眼看到：下一次建议时间、今天累计、距离上次实际抽烟的间隔、快速记录入口。

布局（从上到下）

1. 顶部：日期选择（默认 today，可切 tomorrow）
2. NextTimeCard
3. QuickActions（两按钮：抽烟/忍住）
4. TodaySummary（今日累计、minutes_since_last）
5. AITipsCard（可选：每日 AI 建议入口）
6. RecentList（最近记录 10~20 条）

NextTimeCard（关键）

数据来源：

• GET /api/v1/smoke/next_smoke_time?date=today|tomorrow&mode=auto 展示字段：
• source：
  • ai：展示 not_before_at、suggested_at、time_nodes（Timeline），并展示一句 advice
  • default：展示 default.next_smoke_at（同时映射为 not_before_at/suggested_at） 交互：
• “生成AI计划”按钮：调用同接口但 mode=ai
  • 403：弹 ModalPaywall，引导先看广告解锁
  • 503：提示 AI 暂不可用，仍保留默认卡片

解锁流程（按天）：

1. 前端看广告完成
2. POST /api/v1/smoke/ai/advice_unlocks {date: 计划日期}
3. 再调 GET /api/v1/smoke/next_smoke_time?date=...&mode=ai

QuickActions（抽烟/忍住）

• 抽烟：进入“新增抽烟”轻表单（默认 num=1, level=2）
• 忍住：一键记录（可选弹小输入框写 remark），调用 POST /api/v1/smoke/logs/resisted

TodaySummary

数据来源：

• GET /api/v1/smoke/dashboard（默认本周）+ 也可在首页只展示 today_count 与 minutes_since_last 展示：
• 今日支数（sum num）
• 距上次实际抽烟分钟（后端已忽略忍住记录）

RecentList

数据来源：

• GET /api/v1/smoke/logs/latest?limit=20 展示规则：
• num==0 && level==0：标记为“忍住了”，颜色更积极（如绿色），不展示“支数”
• 其它：展示 num + level + remark + smoke_at（优先）/创建时间 交互：
• 点击进入详情（编辑/删除）

3.2 记录页（新增/补录）

页面目标

• 让记录成本极低（3 秒内完成一条）。

模块

1. 快速新增抽烟（表单）
2. 快速忍住（按钮 + 可选 remark）
3. 历史记录入口（跳列表）

新增抽烟表单

字段：

• smoke_at：默认当前时间，可手动改
• num：Stepper（1~10）
• level：15（或 05，但 0 仅用于忍住）
• remark：常用标签（压力/无聊/社交/提神）+ 自定义输入 API：
• POST /api/v1/smoke/logs

3.3 历史列表页

目标

• 可回溯、可筛选、可编辑。

UI：

• 顶部筛选：日期范围（start/end）、分页加载
• 列表项：时间、类型（抽烟/忍住）、num/level、remark API：
• GET /api/v1/smoke/logs?page=&page_size=&start=&end=

空态：

• “还没有记录，先从右下角按钮开始”

3.4 记录详情页（编辑/删除）

展示：

• smoke_time、smoke_at、remark、level、num 编辑：
• PUT /api/v1/smoke/logs/:id（支持清空 smoke_at/smoke_time 传空字符串） 删除：
• DELETE /api/v1/smoke/logs/:id

3.5 看板页

目标

• 展示趋势：周视图/区间视图，给用户反馈与成就感。

UI：

• 顶部：日期范围选择（默认本周）
• 柱状图：weekly.count
• 指标：today_count、minutes_since_last API：
• GET /api/v1/smoke/dashboard?start=&end=

3.6 AI 建议页（每日）

入口：

• 首页卡片/我的页面

展示：

• Markdown 渲染（建议内容可能包含列表） API：
• GET /api/v1/smoke/ai/advice?date=YYYY-MM-DD（默认昨天） 解锁：
• 若 403，弹引导看广告 -> POST /api/v1/smoke/ai/advice_unlocks {date}

3.7 基础信息（Profile）页

目标：

• 获取默认策略与 AI 个性化所需信息；尽量简短可跳过但提示价值。

字段建议（分组）

1. 基础烟量：日均支数 baseline_cigs_per_day
2. 烟龄/价格：smoking_years、pack_price_cent
3. 抽烟动机（多选）：压力/无聊/社交/提神 + 自定义
4. 戒烟动力（多选）：健康/家人/省钱 + 自定义
5. 作息：起床/入睡（HH:MM）

API：

• GET /api/v1/smoke/profile
• PUT /api/v1/smoke/profile

4. 关键交互与状态

4.1 AI 生成（按天一次）

推荐状态机：

• idle -> generating -> success/locked(403)/failed(5xx)

403（未解锁）：

• 弹窗：说明“观看一次广告解锁当天生成”
• 按钮：去观看（前端完成广告后调用 unlock 接口）

4.2 日期选择（today/tomorrow）

• 首页切 tomorrow 时：
  • GET /api/v1/smoke/next_smoke_time?date=tomorrow&mode=auto
  • 仅在用户主动点“生成AI计划”时才 mode=ai（且 unlock date=tomorrow）

4.3 忍住记录的视觉反馈

• 提交成功 toast：已记录：忍住了
• 列表项显示“忍住”Tag，并用绿色/正向文案。

5. API 映射速查表

• 登录：POST /api/v1/auth/login（返回 session_key）
• Profile：GET/PUT /api/v1/smoke/profile
• 新增抽烟：POST /api/v1/smoke/logs
• 忍住：POST /api/v1/smoke/logs/resisted
• 列表：GET /api/v1/smoke/logs、GET /api/v1/smoke/logs/latest
• 看板：GET /api/v1/smoke/dashboard
• 下次时间：GET /api/v1/smoke/next_smoke_time?date=&mode=
• 每日 AI 建议：GET /api/v1/smoke/ai/advice?date=
• 广告解锁：POST /api/v1/smoke/ai/advice_unlocks {date}