# 戒烟/抽烟记录小程序：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`：1~5（或 0~5，但 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}`