docs: 补全 README(算法、公式表、示例结果、交叉验证、局限与免责)

This commit is contained in:
2026-09-24 03:42:58 +00:00
parent e5b43b48dd
commit 93a6626de7
+158 -1
View File
@@ -1,3 +1,160 @@
# teen-calorie-calculator
青少年 & 成人每日热量需求计算器:输入性别/年龄/身高/体重/每日步数 → 输出 BMI(含年龄别判定)、BMR、PAL、TDEE、目标摄入与蛋白质/钙目标(Python CLI + 网页版)
青少年 & 成人的**每日热量需求**计算器:输入性别 / 年龄 / 身高 / 体重 / 每日步数,输出
**BMI(含年龄别判定)、BMR、PAL、TDEE、目标摄入量**,以及蛋白质 / 钙目标。
| 文件 | 说明 |
| --- | --- |
| `calculator.py` | 命令行版,无第三方依赖(Python 3.8+) |
| `index.html` | 网页版,单文件,浏览器直接打开即可 |
| `cutoffs.json` | 年龄别 BMI 界值表(7–18 岁,男 / 女) |
---
## 快速开始
```bash
# 默认示例参数(男 / 15 岁 / 173 cm / 55 kg / 每天 5000 步)
python calculator.py
# 自定义参数
python calculator.py --sex 男 --age 15 --height 173 --weight 55 --steps 5000
python calculator.py --sex 女 --age 30 --height 160 --weight 48 --steps 8000
python calculator.py --sex male --age 15 --height 173 --weight 55 --steps 5000 --json
```
网页版:双击 `index.html`,默认值已按示例预填,改数字后点「计算」。
输出示例:
```text
==================================================
每日热量需求估算报告
==================================================
输入:男 / 15 岁 / 173 cm / 55 kg / 每天约 5000 步
1) BMI = 18.38 → 正常
年龄别界值:消瘦 <16.6;超重 >=23.1;肥胖 >=26.9
2) BMR(基础代谢)= 1631 kcal/天 [Schofield(青少年)]
对照:成人 Mifflin 公式 = 1561 kcal/天
3) PAL(身体活动水平)= 1.450 (每天约 5000 步)
4) TDEE(维持当前体重的热量)= 2390 kcal/天 区间 2308 - 2472
已含生长发育额外耗能 +25 kcal/天
5) 建议每日摄入 = 2390 - 2629 kcal
蛋白质 66 - 83 g/天,钙 >= 1000 mg/天
```
---
## 算法(5 步)
### 第 1 步:算 BMI,并**用年龄别标准**判定
```
BMI = 体重(kg) / 身高(m)^2
```
**7 ≤ 年龄 < 18 岁必须用年龄别、性别别界值**,不能套成人 18.5 / 24 / 28 那条线:
| 年龄 | 男:消瘦 / 超重 / 肥胖 | 女:消瘦 / 超重 / 肥胖 |
| --- | --- | --- |
| 10 | 14.9 / 19.6 / 22.5 | 14.6 / 18.9 / 21.5 |
| 13 | 16.0 / 21.9 / 25.7 | 16.1 / 21.9 / 25.2 |
| 15 | 16.6 / 23.1 / 26.9 | 17.0 / 23.0 / 26.8 |
| 17 | 17.2 / 23.7 / 27.6 | 17.5 / 23.4 / 27.6 |
| 18(成人) | 18.5 / 24.0 / 28.0 | 18.5 / 24.0 / 28.0 |
界值之间按年龄线性插值(支持 15.5 这类半岁),完整表见 `cutoffs.json`。
### 第 2 步:算 BMR(基础代谢)
- **< 18 岁** 用 **Schofield 青少年公式**(体重公式,MJ/天,再 ×239.006 换成 kcal):
| 年龄 | 男 | 女 |
| --- | --- | --- |
| 10–18 | `0.074×W + 2.754` | `0.056×W + 2.898` |
| 18–30 | `0.063×W + 2.896` | `0.062×W + 2.036` |
| 30–60 | `0.048×W + 3.653` | `0.034×W + 3.538` |
- **≥ 18 岁** 用 **Mifflin-St Jeor**:
`男:10W + 6.25H − 5A + 5`;`女:10W + 6.25H − 5A − 161`(W=kg,H=cm,A=岁)
> 为什么不全用 Mifflin?Mifflin 是成人公式,对青少年会低估。示例中两者差约 70 kcal,程序同时把 Mifflin 结果打出来做对照。
### 第 3 步:用每日步数确定 PAL(身体活动水平)
```
TDEE = BMR × PAL
```
| 每日步数 | 活动水平 | PAL |
| --- | --- | --- |
| < 2500 | 久坐 | 1.20 – 1.30 |
| ≈ 5000 | 轻度 | **1.45** |
| ≈ 7500 | 中等偏低 | 1.525 |
| ≈ 10000 | 中等 | **1.60** |
| ≈ 12500 | 较高 | 1.70 |
| ≈ 15000 | 高 | 1.80 |
| ≥ 20000 | 很高 | 1.95 |
锚点之间线性插值(`PAL_ANCHORS` 可自行调整)。
### 第 4 步:加生长耗能
未成年人在长身体,额外 **+20 kcal/天(<10 岁)或 +25 kcal/天(10–17 岁)**。
### 第 5 步:给出建议摄入区间
- BMI 落在**正常范围偏下段**(BMI < 20,含"贴近偏瘦边缘"):`维持量 ~ 维持量×1.1`
- 其他情况:`维持量 ~ 维持量×1.05`
再附蛋白质 **1.2 – 1.5 g/kg 体重/天**、钙按年龄对应的 RNI。
---
## 示例结果解读(男 / 15 岁 / 173 cm / 55 kg / 每天 5000 步)
| 项目 | 结果 | 说明 |
| --- | --- | --- |
| BMI | **18.38** | 按**成人**标准贴着 18.5 的边(差约 0.4 kg);按**15 岁男生年龄别**界值(消瘦 <16.6)属**正常**,不属消瘦 |
| BMR | **≈ 1631 kcal/天** | Schofield 青少年公式 |
| PAL | **1.45** | 每天 5000 步 = 轻度活动 |
| **TDEE(维持)** | **≈ 2390 kcal/天** | 区间 2308 – 2472 |
| **建议摄入** | **≈ 2390 – 2630 kcal/天** | 正常偏下段留 10% 余量 |
| 蛋白质 / 钙 | 66 – 83 g / ≥ 1000 mg | 青春期骨量积累关键期 |
### 交叉验证
《中国居民膳食营养素参考摄入量》对 **14–17 岁男性、轻身体活动** 给出的能量需要量约 **2500 kcal/天**
(对应参考体重约 56 kg、身高约 172 cm,与示例几乎一致)。
用 PAL 1.5 反推:`1631 × 1.5 ≈ 2450 kcal` —— 与本工具结果吻合,说明取值可靠。
> 注:手算时若把 BMR 取整为 1600,得 `1600×1.45+25 ≈ 2350 kcal`,与程序的 2390 只差约 40 kcal,都在 ±10% 误差内。
---
## 数据来源与已知局限
1. **年龄别 BMI 界值**:消瘦参考《学龄儿童青少年营养不良筛查》WS/T 456-2014,
超重 / 肥胖参考《学龄儿童青少年超重与肥胖筛查》WS/T 586-2018。
`cutoffs.json` 中是**按标准整理的近似值**(各版表格在小数位上略有差异),
仅供学习与粗略估算;**正式判定请核对标准原文**,或做医院生长发育评估。
2. **BMR 公式**:Schofield / Mifflin-St Jeor 都是群体回归公式,对个体误差约 ±10%。
3. **PAL 只由步数推断**,无法区分"散步 5000 步"和"跑步 5000 步",
也没考虑力量训练、球类运动等;有系统训练时应手动上调 PAL。
4. **未考虑体成分**:肌肉量大者 BMI 可能偏高但体脂正常;公式只按体重计算。
5. 青春期发育早晚个体差异很大,一次 BMI 偏低往往只是发育偏晚,
**看身高增长速度曲线比看单次 BMI 更有意义**。
---
## 免责声明
本项目为学习 / 估算工具,**不构成医学建议或诊断**。
未成年人(尤其 18 岁以下)不建议自行实施严格的增重或减重饮食计划,
如需调整请咨询儿科 / 儿保科医生或注册营养师。
若出现持续疲劳、食欲明显下降、体重半年内不增或下降等情况,请及时就医。