docs(汇报): 解决方案汇报稿 —— 九张业务示意图 + 26 张界面截图 + PPT 讲稿

[hotlong]

为什么加这份文档

现有交付文档缺一环:《设计方案》是需求基准(逐条口径、待确认事项),《操作手册》是分角色操作指引(点哪个按钮),两者都不回答「这套系统整体怎么转、为什么这么设计」。而考核流程跨六个岗位、四个审核节点、四种计分方式、四个汇总维度,纯文字讲不清 —— 所以这份汇报稿以图为主、截图为证。

九张示意图

每张只回答一个用文字讲不清的点:

图	回答的问题
1 角色动线泳道图	谁在什么阶段做什么;系统在发布、保存、提交、审批通过、归档五处自动接手了什么
2 状态机与闸门	每一次流转的前置条件是什么;驳回退回到哪一节点
3 发布即冻结	八项完整性检查;明细行上的目标/权重/规则为何是副本而不是引用
4 计分链路	实际值到最终得分的五步,四种计分方式只在中段分岔
5 计分方式曲线	同一个完成率下线性 / 区间插值 / 阶梯三种方式的得分率差异
6 重算传播	源数据调整、结果调整、加减分三条通道如何汇入总分并触发四维重算
7 四维汇总口径	一个最终得分如何落到部门 / 分公司 / 到人 / 分管领导四个问题上
8 数据范围模型	可见范围由方案发布生成,组织调整与换分管领导为何不需要改元数据
9 对象模型总图	17 个自建对象分四组,缩进表示主从

改了什么

第一次提交 —— 汇报稿

• docs/汇报/KPI考核管理系统-解决方案汇报.html —— 汇报稿源稿(Artifact 片段格式,无 html/head/body 外壳)。截图引用操作手册已归档的 26 张,走相对路径,不重复入库(遵 CLAUDE.md E2 中「截图不进代码树」的手册配图例外)。
• scripts/inline-assets.cjs —— 把 img 标签的相对路径改写成 data URI,产出可独立发布的单文件。找不到的文件报错退出,不静默漏图。
• package.json —— 新增 pnpm docs:report。
• .gitignore —— 生成的自包含副本 6MB+ 且可从源稿重建,不入库。

第二次提交 —— PPT 讲稿

• scripts/build-report-deck.mjs —— 从同一批素材生成 19 页汇报 PPT,每页一个论点、一句结论、一张图,并带讲稿备注。版式分四类(整图页、双截图页、卡片页、数据页),不是同一个「标题 + 项目符号」模板套 19 遍。配色取应用自身的品牌色(src/apps/index.ts 的 primaryColor #1D4ED8)与汇报稿同一套语义色,三份交付物看起来是一家的。
• 依赖 pptxgenjs,刻意不进 package.json —— 一次性成稿工具,不值得让元数据项目的依赖图为它变长;装法写在脚本头注里。示意图同理不入库:它们是汇报稿 HTML 里内联 SVG 的渲染产物,可随时按 figure 重新截取,入库就多一份会与源稿走散的副本。
• README.md —— 文档表补两行。

数据核对

文中每个数字都对照代码与 issue 列表核实过:

• 139 条单元测试(pnpm test 实测,7 个测试文件)
• 17 个自建业务对象(src/objects/*.ts)
• 8 项发布前完整性检查(src/hooks/plan.hook.ts,含 发布前完整性检查缺「每个参与主体须配分管领导」,未配置的主体流程死在领导审批节点 #29 补的「每个主体已配分管领导」;设计方案表 4 列的是补充前的 7 项)
• 20 个工作项中 15 项 status:PM验收中、3 项 status:待细化、2 项已关闭
• 表 3 计分示例与设计方案第 7 章表 5 逐位一致

验证

• pnpm verify 通过(validate + typecheck + 139 tests + i18n 同步检查),CI verify 在 head 3a96646 上 success。
• 九张图在 Chromium 中逐张渲染检查过版式:无溢出、无文字重叠,浅色与深色两套主题的 token 都已定义。
• PPT:结构校验通过;逐页几何检查(出界 / 文字溢出 / 文字框重叠)0 条问题,过程中修掉三处真实缺陷(40pt 统计数字撑破文本框、计分曲线页脚注压住页码、交付状态页状态标签与行内文字重叠 1.29")。
• 已知局限:本会话环境的 LibreOffice 不可用(连纯文本都转换不了),PPT 的目视 QA 走的是从 pptx 真实几何回放的近似预览,不是 PowerPoint 原生渲染 —— 位置、层叠、图片缩放是准的,字体为替代字体。

备注

本 PR 只动 docs/、scripts/、package.json、.gitignore 与 README.md,不涉及任何元数据或运行时代码。

🤖 Generated with Claude Code

https://claude.ai/code/session_01QhMsYoDpoMGeQLf24eTawP