Update algorithm and API documentation for smoking tracking app

- Enhanced the algorithm documentation to clarify the calculation of smoking intervals, including default values and edge cases.
- Updated API documentation to reflect changes in response formats, including the addition of `exceeded_yesterday` and adjustments to time formatting to RFC3339.
- Improved descriptions of user profile management and AI suggestions in the product documentation, ensuring consistency across all related files.
- Removed outdated sequence diagram and UI documentation files to streamline project resources.
This commit is contained in:
nepiedg
2026-01-25 08:51:25 +00:00
parent b67dc32369
commit f80c3e8f45
9 changed files with 62 additions and 402 deletions
+17 -17
View File
@@ -21,7 +21,7 @@
| 参数 | 来源 | 默认值 | 说明 |
|------|------|--------|------|
| base_interval | profile.baseline_interval_minutes | 60 分钟 | 用户初始平均抽烟间隔 |
| base_interval | profile.baseline_interval_minutes | 60 分钟 | 用户初始平均抽烟间隔(为空/0 时默认 60 |
| resisted_7d | 近7天忍住次数 | 0 | level=0,num=0 的记录数 |
| bonus_interval | 计算得出 | 0 | 奖励延长时间 |
@@ -31,7 +31,7 @@
```
bonus_interval = min(floor(resisted_7d / 5) * 5, 60)
final_interval = base_interval + bonus_interval
final_interval = clamp(base_interval + bonus_interval, 5, 240)
```
**示例**
@@ -41,17 +41,22 @@ final_interval = base_interval + bonus_interval
### 2.4 睡眠规避
若计算出的时间落在睡眠区间,顺延到次日起床时间
若计算出的时间落在睡眠区间,顺延到**下一次**起床时间(可能是当天也可能是次日)
```
if suggested_time in [sleep_time, wake_up_time]:
suggested_time = next_day_wake_up_time
```
### 2.5 算法流程图
### 2.5 边界与兜底
- 若没有历史记录,则以“当前时间”作为 `last_smoke_at` 参与计算。
- 若生成未来日期计划(如明天),默认建议不早于该日起床时间;未配置作息时按 `07:00` 处理。
### 2.6 算法流程图
```
获取上次抽烟时间 (last_smoke_at)
获取上次抽烟时间 (last_smoke_at, 若无记录则取当前时间)
获取用户基础间隔 (base_interval_minutes)
@@ -59,7 +64,7 @@ if suggested_time in [sleep_time, wake_up_time]:
计算奖励间隔: bonus = min(floor(resisted_7d / 5) * 5, 60)
计算建议时间: suggested = last_smoke_at + base + bonus
计算建议时间: suggested = last_smoke_at + base + bonus (并限制在 5~240 分钟区间)
检查是否在睡眠时间?
├── 是 → 顺延到起床时间
@@ -91,20 +96,14 @@ if suggested_time in [sleep_time, wake_up_time]:
### 3.2 AI 建议内容
AI 会生成以下内容:
AI 会生成以下内容(实际接口格式)
```json
{
"advice": "昨天你的吸烟量比限额少了2支,这是一个巨大的胜利!数据显示你的烟瘾在下午2点左右达到顶峰——今天试着那个时候去散散步。",
"time_nodes": [
{ "time": "09:30", "type": "suggested", "note": "第一支,早餐后" },
{ "time": "12:30", "type": "suggested", "note": "午餐后" },
{ "time": "15:30", "type": "suggested", "note": "下午茶时间" },
{ "time": "19:00", "type": "suggested", "note": "晚餐后" },
{ "time": "22:00", "type": "suggested", "note": "睡前最后一支" }
],
"daily_target": 5,
"tips": ["2点是你的高峰期,准备一颗薄荷糖", "试着用深呼吸替代"]
"not_before_at": "2026-01-05T10:18:00+08:00",
"suggested_at": "2026-01-05T10:28:00+08:00",
"time_nodes": ["09:30", "12:30", "15:30", "19:00", "22:00"],
"advice": "昨天你的吸烟量比限额少了2支,这是一个巨大的胜利!数据显示你的烟瘾在下午2点左右达到顶峰——今天试着那个时候去散散步。"
}
```
@@ -299,6 +298,7 @@ function getMotivationMessage(context) {
| 忍住成功率 | 忍住次数 / (忍住+抽烟次数) | 意志力评估 |
| 平均间隔 | 总时长 / 抽烟次数 | 递减效果 |
| 最长无烟时长 | 最大间隔记录 | 成就激励 |
| 较昨日减少 | 昨日支数 - 今日支数(可为负) | 若为负,表示今天超出昨日 |
### 8.2 周报数据结构