Update algorithm documentation and API specifications. Enhanced clarity on parameters and calculations in ALGORITHM.md, including default values and boundary conditions. Modified API endpoints from PUT to POST for updating logs and profiles in api.md. Removed outdated DEVELOPMENT.md and related phase documentation files. Added comprehensive health and savings statistics in API responses. Improved user guidance in PHASE3_USER_GUIDE.md.
This commit is contained in:
nepiedg
+177
-2
@@ -155,7 +155,7 @@ curl -X GET 'http://127.0.0.1:8080/api/v1/smoke/logs/5202' \
|
||||
|
||||
## 6) 更新记录
|
||||
|
||||
`PUT /api/v1/smoke/logs/:id`
|
||||
`POST /api/v1/smoke/logs/:id`
|
||||
|
||||
请求体（字段可选，按需传）：
|
||||
|
||||
@@ -302,7 +302,7 @@ curl -X GET 'http://127.0.0.1:8080/api/v1/smoke/logs/5202' \
|
||||
|
||||
## 11) 补全/更新用户基础信息（Upsert）
|
||||
|
||||
`PUT /api/v1/smoke/profile`
|
||||
`POST /api/v1/smoke/profile`
|
||||
|
||||
说明：
|
||||
- 字段按需传；首次进入建议一次性补全。
|
||||
@@ -348,6 +348,7 @@ curl -X GET 'http://127.0.0.1:8080/api/v1/smoke/logs/5202' \
|
||||
|
||||
说明：
|
||||
- 用于首页展示“建议的下次记录时间”。
|
||||
- 已整合首页所需汇总字段（上次抽烟时间/今日抽烟支数/今日克制次数/较昨日减少支数）。
|
||||
- 如果指定日期存在 AI 给出的时间节点（`time_nodes` 不为空），则优先使用 AI 的建议；否则使用默认策略。
|
||||
- 可选参数：
|
||||
- `date`：计划日期（默认今天），支持 `YYYY-MM-DD` 或 `today/tomorrow`。
|
||||
@@ -359,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 生成说明：
|
||||
@@ -374,6 +376,11 @@ AI 生成说明：
|
||||
"source": "default",
|
||||
"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-05T09:30:00+08:00",
|
||||
"next_smoke_at": "2026-01-05T10:18:00+08:00",
|
||||
@@ -398,6 +405,11 @@ AI 生成说明：
|
||||
"source": "ai",
|
||||
"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" },
|
||||
@@ -414,3 +426,166 @@ AI 生成说明：
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
字段说明（新增首页字段）：
|
||||
- `last_smoke_at`：上次“实际抽烟”时间（忽略忍住记录），格式 `RFC3339`（含时区）。
|
||||
- `today_count`：今日抽烟支数（累加 `num`）。
|
||||
- `resisted_count`：今日克制次数（`level=0 && num=0`）。
|
||||
- `reduced_from_yesterday`：较昨日减少的支数（允许为负数；为负时表示“今天超出昨日”）。
|
||||
- `exceeded_yesterday`：是否超出昨日（`true` 表示今天超出昨日，前端可用作单独标识）。
|
||||
|
||||
## 14) 获取健康与储蓄统计（合并接口）
|
||||
|
||||
`GET /api/v1/smoke/health_savings?period=week&start=2026-01-01&end=2026-01-07`
|
||||
|
||||
说明：
|
||||
- 合并了"肺部功能恢复"和"节省金额"两个指标，专用于统计页面展示。
|
||||
- 支持按周/月/年查询，通过 `period` 参数指定时间范围类型。
|
||||
|
||||
参数：
|
||||
- `period`（必填）：时间范围类型，可选值：
|
||||
- `week`：周（默认本周一至本周日）
|
||||
- `month`：月（默认本月1日至本月最后一日）
|
||||
- `year`：年（默认本年1月1日至本年12月31日）
|
||||
- `start`（可选）：起始日期（格式 `YYYY-MM-DD`），不传则根据 `period` 自动计算
|
||||
- `end`（可选）：截止日期（格式 `YYYY-MM-DD`），不传则根据 `period` 自动计算
|
||||
|
||||
**计算逻辑**：
|
||||
|
||||
1. **肺部功能恢复百分比**：
|
||||
- 基于用户最后一次实际抽烟时间（忽略 `level=0 && num=0` 的忍住记录）
|
||||
- 计算无烟时长（分钟）
|
||||
- 根据医学研究恢复时间线计算恢复百分比（详见 `docs/ALGORITHM.md`）
|
||||
- 公式：
|
||||
```
|
||||
无烟天数 = (当前时间 - 最后抽烟时间) / (24 * 60) 分钟
|
||||
|
||||
恢复百分比计算：
|
||||
- < 14天: (天数 / 14) * 15%
|
||||
- 14-30天: 15% + ((天数 - 14) / 16) * 15%
|
||||
- 30-90天: 30% + ((天数 - 30) / 60) * 20%
|
||||
- > 90天: 50% + ((天数 - 90) / 275) * 50%，最高 100%
|
||||
```
|
||||
|
||||
2. **节省金额**：
|
||||
- 基于用户在统计周期内的实际抽烟量与基线对比
|
||||
- 计算公式：
|
||||
```
|
||||
预期总支数 = baseline_cigs_per_day * 周期天数
|
||||
实际总支数 = 周期内所有记录的 num 累加（排除 level=0 && num=0）
|
||||
节省支数 = 预期总支数 - 实际总支数
|
||||
节省包数 = 节省支数 / 20（假设每包20支）
|
||||
节省金额（分）= 节省包数 * pack_price_cent
|
||||
```
|
||||
- 若实际总支数 > 预期总支数，则节省金额为 0（不显示负数）
|
||||
|
||||
3. **目标金额**：
|
||||
- 默认目标：`baseline_cigs_per_day * 周期天数 / 20 * pack_price_cent`（即完全戒烟节省的金额）
|
||||
- 或使用用户设定的目标金额（如有）
|
||||
|
||||
成功响应示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"period": "week",
|
||||
"start": "2026-01-01",
|
||||
"end": "2026-01-07",
|
||||
"days": 7,
|
||||
"health": {
|
||||
"lung_recovery_percent": 40.5,
|
||||
"smoke_free_minutes": 11520,
|
||||
"smoke_free_days": 8,
|
||||
"last_smoke_at": "2025-12-24T14:30:00+08:00",
|
||||
"recovery_stage": "early", // early(0-14天) / mid(14-30天) / late(30-90天) / advanced(>90天)
|
||||
"next_milestone": {
|
||||
"days_until": 6,
|
||||
"milestone": "2周 - 肺功能提升15%",
|
||||
"percent_at_milestone": 15
|
||||
}
|
||||
},
|
||||
"savings": {
|
||||
"saved_amount_cent": 14500, // 已节省金额（分）
|
||||
"saved_amount_yuan": 145.00, // 已节省金额（元，前端展示用）
|
||||
"target_amount_cent": 20000, // 目标金额（分）
|
||||
"target_amount_yuan": 200.00, // 目标金额（元）
|
||||
"saved_cigs": 58, // 节省支数
|
||||
"expected_cigs": 140, // 预期总支数
|
||||
"actual_cigs": 82, // 实际总支数
|
||||
"progress_percent": 72.5, // 完成进度百分比
|
||||
"pack_price_cent": 2500, // 单包价格（分）
|
||||
"cigs_per_pack": 20 // 每包支数
|
||||
},
|
||||
"profile": {
|
||||
"baseline_cigs_per_day": 20,
|
||||
"pack_price_cent": 2500,
|
||||
"smoking_years": 8
|
||||
},
|
||||
"calculated_at": "2026-01-08T10:00:00+08:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
**health（健康数据）**：
|
||||
- `lung_recovery_percent`：肺部功能恢复百分比（0-100）
|
||||
- `smoke_free_minutes`：无烟时长（分钟）
|
||||
- `smoke_free_days`：无烟天数（保留1位小数）
|
||||
- `last_smoke_at`：最后一次实际抽烟时间（RFC3339格式）
|
||||
- `recovery_stage`：恢复阶段标识
|
||||
- `next_milestone`：下一个里程碑信息
|
||||
|
||||
**savings（储蓄数据）**：
|
||||
- `saved_amount_cent`：已节省金额（分，用于计算）
|
||||
- `saved_amount_yuan`：已节省金额（元，用于前端展示）
|
||||
- `target_amount_cent`：目标金额（分）
|
||||
- `target_amount_yuan`：目标金额（元）
|
||||
- `saved_cigs`：节省的支数
|
||||
- `expected_cigs`：预期总支数（基线 × 天数）
|
||||
- `actual_cigs`：实际总支数
|
||||
- `progress_percent`：完成进度百分比（saved_amount / target_amount * 100）
|
||||
- `pack_price_cent`：单包价格（分）
|
||||
- `cigs_per_pack`：每包支数（默认20）
|
||||
|
||||
**period 参数说明**：
|
||||
|
||||
- `period=week`（周）：
|
||||
- 默认：本周一 00:00:00 至 本周日 23:59:59
|
||||
- 若传 `start`，则 `end = start + 6 天`
|
||||
|
||||
- `period=month`（月）：
|
||||
- 默认：本月1日 00:00:00 至 本月最后一日 23:59:59
|
||||
- 若传 `start`，则 `end = start 所在月的最后一日`
|
||||
|
||||
- `period=year`（年）：
|
||||
- 默认：本年1月1日 00:00:00 至 本年12月31日 23:59:59
|
||||
- 若传 `start`，则 `end = start 所在年的12月31日`
|
||||
|
||||
curl 示例：
|
||||
|
||||
```bash
|
||||
# 查询本周数据
|
||||
curl -X GET 'http://127.0.0.1:8080/api/v1/smoke/health_savings?period=week' \
|
||||
-H 'Authorization: Bearer wx-session-key'
|
||||
|
||||
# 查询本月数据
|
||||
curl -X GET 'http://127.0.0.1:8080/api/v1/smoke/health_savings?period=month' \
|
||||
-H 'Authorization: Bearer wx-session-key'
|
||||
|
||||
# 查询本年数据
|
||||
curl -X GET 'http://127.0.0.1:8080/api/v1/smoke/health_savings?period=year' \
|
||||
-H 'Authorization: Bearer wx-session-key'
|
||||
|
||||
# 查询指定日期范围
|
||||
curl -X GET 'http://127.0.0.1:8080/api/v1/smoke/health_savings?period=week&start=2026-01-01&end=2026-01-07' \
|
||||
-H 'Authorization: Bearer wx-session-key'
|
||||
```
|
||||
|
||||
**注意事项**：
|
||||
1. 若用户尚未补全 `profile`（缺少 `baseline_cigs_per_day` 或 `pack_price_cent`），相关计算字段可能为 0 或使用默认值
|
||||
2. 若用户从未抽烟（无历史记录），`last_smoke_at` 可能不存在，肺部恢复百分比按最大恢复计算
|
||||
3. 节省金额计算时，若实际支数 > 预期支数，`saved_amount_cent` 为 0（不显示负数）
|
||||
4. 时间范围计算时，使用用户所在时区（后端需根据用户配置或默认使用 UTC+8）
|
||||
|
||||
Reference in New Issue
Block a user