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 -13
View File
@@ -360,6 +360,7 @@ curl -X GET 'http://127.0.0.1:8080/api/v1/smoke/logs/5202' \
默认策略(不使用 AI):
- 基础间隔:优先使用 `GET /api/v1/smoke/profile` 返回的 `baseline_interval_minutes`;若不存在则默认 `60` 分钟。
- 阶梯式延时:最近 7 天内每累计 `5` 条“忍住记录(level=0,num=0)”,在基础间隔上 `+5` 分钟(最多 `+60` 分钟)。
- 间隔兜底:最终间隔会限制在 `5~240` 分钟之间。
- 若用户已补全作息时间,会自动规避睡眠区间:若计算出的时间落在睡眠区间,顺延到下一次起床时间。
AI 生成说明:
@@ -373,22 +374,23 @@ AI 生成说明:
"message": "success",
"data": {
"source": "default",
"not_before_at": "2026-01-05 10:18:00",
"suggested_at": "2026-01-05 10:18:00",
"last_smoke_at": "2026-01-05 09:30:00",
"not_before_at": "2026-01-05T10:18:00+08:00",
"suggested_at": "2026-01-05T10:18:00+08:00",
"last_smoke_at": "2026-01-05T09:30:00+08:00",
"today_count": 3,
"resisted_count": 1,
"reduced_from_yesterday": 2,
"exceeded_yesterday": false,
"default": {
"last_smoke_at": "2026-01-05 09:30:00",
"next_smoke_at": "2026-01-05 10:18:00",
"last_smoke_at": "2026-01-05T09:30:00+08:00",
"next_smoke_at": "2026-01-05T10:18:00+08:00",
"base_interval_minutes": 48,
"interval_minutes": 48,
"stage": 0,
"resisted_7d": 3,
"sleep_adjusted": false,
"algorithm": "staircase_delay_v1",
"as_of": "2026-01-05 10:00:00"
"as_of": "2026-01-05T10:00:00+08:00"
}
}
}
@@ -401,19 +403,20 @@ AI 生成说明:
"message": "success",
"data": {
"source": "ai",
"not_before_at": "2026-01-05 10:18:00",
"suggested_at": "2026-01-05 10:28:00",
"last_smoke_at": "2026-01-05 09:30:00",
"not_before_at": "2026-01-05T10:18:00+08:00",
"suggested_at": "2026-01-05T10:28:00+08:00",
"last_smoke_at": "2026-01-05T09:30:00+08:00",
"today_count": 3,
"resisted_count": 1,
"reduced_from_yesterday": 2,
"exceeded_yesterday": false,
"time_nodes": ["10:30", "11:10", "14:00", "16:30"],
"advice": "先把这次冲动延后到10:28,期间做一次5分钟快走+喝水,压力场景用深呼吸替代。",
"default": { "algorithm": "staircase_delay_v1" },
"ai": {
"plan_date": "2026-01-05",
"not_before_at": "2026-01-05 10:18:00",
"suggested_at": "2026-01-05 10:28:00",
"not_before_at": "2026-01-05T10:18:00+08:00",
"suggested_at": "2026-01-05T10:28:00+08:00",
"time_nodes": ["10:30", "11:10", "14:00", "16:30"],
"advice": "先把这次冲动延后到10:28,期间做一次5分钟快走+喝水,压力场景用深呼吸替代。",
"prompt_version": "v1",
@@ -425,7 +428,8 @@ AI 生成说明:
```
字段说明(新增首页字段):
- `last_smoke_at`:上次“实际抽烟”时间(忽略忍住记录),格式 `YYYY-MM-DD HH:MM:SS`
- `last_smoke_at`:上次“实际抽烟”时间(忽略忍住记录),格式 `RFC3339`(含时区)
- `today_count`:今日抽烟支数(累加 `num`)。
- `resisted_count`:今日克制次数(`level=0 && num=0`)。
- `reduced_from_yesterday`:较昨日减少的支数(`max(昨日支数 - 今日支数, 0)`)。
- `reduced_from_yesterday`:较昨日减少的支数(允许为负数;为负时表示“今天超出昨日”)。
- `exceeded_yesterday`:是否超出昨日(`true` 表示今天超出昨日,前端可用作单独标识)。