幼儿园体质测评报告生成器
一个给幼儿园教研场景用的单文件 HTML 应用：导入 Excel 体测数据 → 自动生成个人 / 年级 / 全园三层次报告 → 导出 A4 分页打印。
三套文件，别搞混
| 路径 | 角色 | 说明 |
|---|---|---|
体能监测生成器/fitness-report-generator.html |
开发源 | 唯一可改的地方。263 KB |
幼儿园体质测评报告生成器1.0/幼儿园体质报告生成器.html |
发布副本 | 由开发源 cp 过去，内容与源一致 |
幼儿园体质测评报告生成器1.0/幼儿园体质报告生成器-单文件版.html |
对外分发 | 内联了 xlsx 库，1.09 MB，断网可用 |
幼儿园体质报告生成器-在线版/index.html |
线上部署 | 单文件版改名，供部署工具用 |
任何改动都在开发源上做，然后按「改完怎么办」的顺序同步出去。 直接改发布副本会被下次 cp 覆盖掉。
六屏结构
1 数据管理 导入三次体测 Excel / 导出数据 / 导入模板下载 / 清空
2 班级名单 按班级分组，可折叠；显示每人各测次的数据完整度
3 个人数据 左「基本信息」+ 右「测评数据」（测次可滚动切换）
4 个人报告预览 单次测评报告 / 对比测评报告 → #report
5 年级报告预览 小班/中班/大班滚动选择，单次 / 对比 → #reportGrade
6 全园报告预览 年级横向对比 + 全园纵向对比 → #reportSum
三套报告用三个独立容器，互不覆盖。第 5、6 屏是"预览屏"（不是表单），进屏时自动补渲染。
改完怎么办（严格按序）
cd 体能监测生成器
PY="C:/Users/Administrator/.workbuddy/binaries/python/versions/3.13.12/python.exe"
NODE="C:/Users/Administrator/.workbuddy/binaries/node/versions/22.22.2/node.exe"
SK="C:/Users/Administrator/.workbuddy/skills/kindergarten-fitness-report/scripts"
"$PY" "$SK/syntax_check.py" fitness-report-generator.html _tests/_tmp_main.js # ①
"$NODE" --check _tests/_tmp_main.js
bash "$SK/run_regression.sh" # ② 11 套回归（需 Edge 9337 端口）
cp fitness-report-generator.html ../幼儿园体质测评报告生成器1.0/幼儿园体质报告生成器.html
"$PY" _tests/_inline.py # ③ 重新生成单文件版
cp ../幼儿园体质测评报告生成器1.0/幼儿园体质报告生成器-单文件版.html ../幼儿园体质报告生成器-在线版/index.html
# ④ 部署 → ⑤ 跑 _v_online.js 验线上
> 路径写全。Git Bash 里的 ~ 传给 Windows 原生 Python 会被拼成 C:\c\Users\... 直接报找不到文件（踩过，见 pitfalls 第 14 条）。
>
> 上面几条是开发机的绝对路径。换电脑不要改脚本本体，用环境变量覆盖即可：
> KG_BASE="<发布目录>"（inline_xlsx.py）、NODE / NODE_MODULES / DBG_PORT（run_regression.sh）。
>
> scripts/inline_xlsx.py 与项目内 _tests/_inline.py 等价（实测产出 md5 相同）；发布流程里沿用 _tests/_inline.py。
① 是硬门槛。 这个文件 4000+ 行、几千个字符串拼接，引号漏一个转义就是整页白屏，node --check 是唯一快速把关手段。
常见任务入口
| 要改什么 | 动哪里 |
|---|---|
| 报告章节增删 / 顺序 | gradeReportBlocks（年级单次）、gradeCmpBlocks（年级对比）、schoolReportBlocks（全园） |
| 体能发展建议文案 | METRIC_COACH（15 个指标的训练方案库）+ gradeAdviceParts（章节编排） |
| 指标标准值 | METRIC_SETS（按年级分组的 std:{min,effort,pass,good,ex}） |
| 颜色 / 图例 | LEVEL_COLORS、heatColor、classDeltaHeat、图例三件套（swatchLegendHtml / levelLegendHtml / heatLegendHtml） |
| 班级列表 | groupByClass / renderClassList / CLS_FOLD |
| 测次切换 | refreshSessionOpts / onStuSessPick / captureForm(opts) |
| 导入导出 | importExcel / exportExcel / BASE_COLS（导入列名） |
详细函数索引见 references/architecture.md；改之前先读 references/pitfalls.md，里面有 14 个会浪费你一小时的真坑。
易错的三条铁律
- 长内容必须先切小块再分页。
paginateSummary只能按 block 粒度分页，一个 block 超过一页就会溢出 A4。写建议/分析这类长文本，用gradeAdviceParts()返回小块数组逐块 push，别返回一整块大 HTML。 - 改文案别凭记忆写锚点。 先
Read真实行或 grep 一个别处不会出现的短串，再Edit。连续NOT FOUND就是锚点编错了。 - 截图前必须真实触发生成。 预览容器靠用户操作才有内容，只
goStep(n)会截到空容器。
两条"代码验不了"的事（状态跟踪）
- 指标标准值 ✅ 已确认：
METRIC_SETS各年级std五档阈值 + BMI 阈值，华老师 2026-09-21 确认无误。之后若课题标准换版、或谁改过阈值，都要重新请他核对一遍——自动化只能证明「算得对」，证明不了「阈值对」。 - localStorage 数据易失 ⚠️ 2026-09-21 决策：暂不上云，靠导出 Excel 留档（华老师同时希望手机能看，两者冲突与可行解见
references/cloud-sync.md顶部"决策记录"）。注意：手机上只能看导出的 PDF 报告，不能录数据、不能看实时数据 —— 别承诺做不到的事。
已做的兜底加固（_v_backup.js 10 项守护）：
- 导出文件名带日期时分：幼儿园体能测评数据-2026-09-21-1136.xlsx（原先是固定名，多次导出在下载目录堆成 (1)(2)(3)，没法归档）
- 打开时提醒：从未导出过 → 提示；距上次导出 ≥7 天 → 提示并报天数；7 天内不打扰；名单为空不提醒
- 相关常量：LS_EXPORT='kg-fit-lastexport-v1'、BACKUP_DAYS=7、fileStamp()、backupHintHtml()、markExported()
项目背景（影响交付口径）
- 使用人是华老师，苏州，做幼儿园健康课题、动作发展方向的研究；助手自称「健健」。
- 最终用户是一线老师（非技术人员） → 分发一律给单文件版；面向他们的文档写通俗中文，不要出现代码、路径、命令行。
- 老师反馈问题常附截图 → 优先从截图推断现象，再回代码定位。
参考资源
references/architecture.md— 数据结构、函数索引、分页引擎、配色常量、测试套件清单references/pitfalls.md— 踩坑清单（编辑、事件、分页、截图、打印断言）references/release.md— 发布与资产库上传全流程scripts/inline_xlsx.py— 生成单文件版（把 xlsx 库内联进 HTML）scripts/syntax_check.py— 抽取内联 JS 做语法检查scripts/run_regression.sh— 跑 11 套本地回归并汇总（含_v_stress真实规模压测、_v_quota配额与持久化）assets/templates/— 小/中/大班导入模板（表头即导入口径，改模板前先解包读真实表头）
