From be6d579d411cec923c51d3ff2efe3c3e83ae0503 Mon Sep 17 00:00:00 2001
From: nepiedg <806669289@qq.com.com>
Date: Tue, 20 Jan 2026 07:34:25 +0000
Subject: [PATCH] Update README.md to include product and UI documentation
 references

- Added new sections in README.md for product documentation (PRD) and UI/UX design documentation, linking to `docs/smoke/PRODUCT.md` and `docs/smoke/UI.md` respectively, to enhance the overall documentation for the project.
---
 docs/smoke/PRODUCT.md | 109 +++++++++++++++++++++++
 docs/smoke/README.md  |   5 ++
 docs/smoke/UI.md      | 201 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 315 insertions(+)
 create mode 100644 docs/smoke/PRODUCT.md
 create mode 100644 docs/smoke/UI.md

diff --git a/docs/smoke/PRODUCT.md b/docs/smoke/PRODUCT.md
new file mode 100644
index 0000000..66a4201
--- /dev/null
+++ b/docs/smoke/PRODUCT.md
@@ -0,0 +1,109 @@
+# 戒烟/抽烟记录小程序：产品说明（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 “最后一次抽烟”
+- 定义为“最后一次实际抽烟事件”（忽略忍住记录）。
+- 后端看板 `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) 若未补全：进入补全页，提交：`PUT /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`
+- 编辑/删除：`PUT /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`
+
+### 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. 页面能力清单（对应 UI 文档）
+- 首页：今日累计、距上次实际抽烟、下次建议时间（默认/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`
+- 时序图：`docs/smoke/SEQUENCE.md`
+
+## 7. 权限与错误处理（产品口径）
+- 未登录：统一提示“请先登录”，引导重新登录。
+- AI 未解锁（403）：弹窗/页内提示“观看广告解锁当天生成”，提供“去观看”按钮。
+- AI 服务不可用（503）：提示“稍后再试”，不阻断默认策略展示。
+- 没有记录：列表/看板显示空态；首页 `minutes_since_last` 不显示或显示“暂无数据”。
+
+## 8. 埋点与指标（建议）
+- D1/D7 留存：进入首页、完成补全、记录次数（抽烟/忍住）、打开看板、生成 AI 建议。
+- “忍住记录”转化：忍住按钮点击 -> 成功落库。
+- AI 付费/广告：解锁按钮曝光 -> 广告完成 -> 生成成功率。
+
diff --git a/docs/smoke/README.md b/docs/smoke/README.md
index 9fa1847..6cb4a00 100644
--- a/docs/smoke/README.md
+++ b/docs/smoke/README.md
@@ -6,6 +6,11 @@
 
 见：`docs/smoke/SEQUENCE.md`
 
+## 产品与 UI 文档
+
+- 产品说明（PRD）：`docs/smoke/PRODUCT.md`
+- UI/UX 设计说明：`docs/smoke/UI.md`
+
 ## 依赖
 
 - 公共登录与认证：`docs/common/auth.md`
diff --git a/docs/smoke/UI.md b/docs/smoke/UI.md
new file mode 100644
index 0000000..6f6853a
--- /dev/null
+++ b/docs/smoke/UI.md
@@ -0,0 +1,201 @@
+# 戒烟/抽烟记录小程序：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}`
+