Token 报告渲染器
概述
读取一个本地 Excel（.xlsx） 文件，按 PCG 公共事务部 7月新版「Token 使用诊断与管理建议」的样式，渲染成单文件 HTML 报告。报告含：头部 + KPI 卡 + 职族拆分 + 各中心柱状图 + 逐人使用强度 + 方案对比 + 推荐方案 + 70% 额度缺口 + 6月预估更新 + 部门沟通话术 + Footer。
整套样式、组件结构封装在 assets/template.html，渲染逻辑在 scripts/render_token_report.py，数据规范在 references/data_schema.md，组件清单在 references/components.md。
何时使用
- 用户说"生成/渲染/出 PCG Token 报告"。
- 用户提供一份 token 用量 .xlsx，要看 HTML 版的诊断报告。
- 用户已有
assets/sample_token_data.xlsx模板，要换一批数据再生成。
不适用：
- 通用数据可视化报告（用别的 skill，如 hr-design-refs）。
- 不在 PCG 公共事务部场景下的报告（本 skill 样式是 PCGPA 的 6 章节版式）。
工作流程
-
检查输入：
- 用户给的是 .xlsx（多 Sheet）→ 走完整流程。
- 用户只贴了一份 Excel 截图 / 一段描述 → 先用python3 scripts/init_sample_data.py生成模板，提示用户在 Excel 里填数，再渲染。
- 用户只给了 CSV → 提示 CSV 只能渲染meta表部分信息，建议改成 .xlsx。 -
确认数据：
- 让用户打开assets/sample_token_data.xlsx对照结构（也可直接说"按模板的 sheet 名和列名填"）。
- 数据量大时，先检查 sheet 是否齐全（缺哪个章节）：必填meta / kpis / byfamily / bycenter / persons，推荐overage / schemes / standard，可选overage_est / scripts。 -
执行渲染：
bash python3 scripts/render_token_report.py <input.xlsx> [output.html]
- 默认output.html= 同目录同名 .html。
- 渲染成功后提示用户用preview_url打开预览。 -
展示结果：
- 在 IDE 内置浏览器中预览 HTML（preview_url工具，url =file:///<绝对路径>）。
- 用户确认后交付；如要改文案/数据，回第 1 步。 -
如果用户改了数据要重新渲染：再次执行第 3 步；模板和数据规范不变。
资源
scripts/
render_token_report.py— 核心渲染脚本（读 xlsx → 拼 HTML）。init_sample_data.py— 生成示例 Excel（脱敏自 PCG 公共事务部 7月版）。
assets/
template.html— 完整 HTML 模板，含所有 CSS 与组件结构。sample_token_data.xlsx— 示例数据（结构与真实 PCG 报告 1:1）。
references/
data_schema.md— Excel 字段规范、Sheet 列表、字段语义、命名提示。components.md— 组件库说明（CSS 变量、class、颜色语义、自定义方法）。
快速开始（给用户的对话模板）
> 我用 token-report-renderer 给你出一份 HTML 报告。
> 1. 先看一下模板文件结构 → assets/sample_token_data.xlsx
> 2. 把数据按 sheet 填好（参考 references/data_schema.md）
> 3. 跑一行命令：python3 scripts/render_token_report.py 你的数据.xlsx
> 4. 浏览器打开同名 .html 即可查看
渲染结果示例
打开 /tmp/test_token_report.html 可看效果：完整 6 章节、4 张 KPI、2 行职族拆分、4 中心柱状图、85 人使用强度表、2 方案对比、推荐卡 + 标准对比卡 + 缺口表 + 6月预估表 + 沟通话术 3 条。
验证（自检）
每次渲染完做这 3 步：
1. 打开 HTML，检查头部 H1 + 4 张 KPI 卡 + 6 章节标题是否齐全。
2. 逐人列表的行数 = persons sheet 的行数。
3. 缺口表缺口数字前不出现 ++（修复了 overage_est 中硬编码 + 的 bug）。
已知限制
- 仅支持 3 个月度（M1/M2/M3），不支持 4+ 月。
- 不做权限控制：拿到 .xlsx 就能渲染。
- 样式绑定 PCG 公共事务部场景；其他部门用需手动改 CSS 变量。
