更新进度文档

docs/交接说明_2026-08-28.md

@@ -0,0 +1,138 @@
+# 财报图表项目交接说明（2026-08-28）
+
+## 1. 当前状态
+
+项目已迁移到 **Vite + Vanilla JavaScript + ECharts**，本地开发地址为 `http://localhost:8899`。页面支持模块/CSS 热更新；修改 `manifest.json` 或 CSV 后会整页刷新。当前泡泡玛特已配置 **22 张图表**，另有 **5 张示例图表**；完整回归与生产构建均已通过。
+
+当前页面结构：公司选择 → 分析分类 Tab → 当前分类图表卡片 → 右侧图表锚点导航。泡泡玛特的“成长性”已经并入“盈利能力”，不再单独保留该分类。
+
+## 2. 启动与验证
+
+```bash
+cd /Users/joey-xd/sites/vest-tools/smart-fin-chart
+pnpm install        # 仅首次或依赖变化后执行
+pnpm dev            # 打开 http://localhost:8899
+pnpm test           # 27 张图表的 ECharts SSR 回归
+pnpm build          # 生产构建
+```
+
+项目根目录另有可双击执行的 [`start.command`](../start.command)，会启动 Vite 并打开本地地址。
+
+截至本次交接，`pnpm test` 的结果是 **27 张成功 / 0 张失败**。其中 `ppmt-ip-share` 与 `ppmt-ip-share-history` 会提示 `legend.top=middle`，这是两张右侧纵向图例的预期配置，不是故障。
+
+## 3. 架构与单一数据源
+
+### 图表声明
+
+[`manifest.json`](../manifest.json) 是公司、分类、图表与 CSV 的唯一声明源：
+
+- `company.chartCatalog`：每个图表只声明一次（图表 key、CSV、画布高度、导出文件名）。
+- `company.tabs[].chartRefs`：分类只引用图表 ID；概览与详细分类可以引用同一个 ID，不复制图表代码或数据配置。
+- `js/main.js`：读取 manifest、把 `chartRefs` 解析为视图实例；同一图在概览和详细分类中使用同一 chart builder。
+- `js/charts/index.js`：chart key 与图表构建函数的注册表。
+
+这项设计已经用于“概览”：概览展示的营收利润增速、盈利能力、IP 占比、区域渠道分布，在原分类中仍保留，且复用同一组件和同一 CSV。
+
+### 新增图表的标准步骤
+
+1. 在 `data/<company>/` 新增或更新运行时 CSV。
+2. 在 `js/charts/` 新建 chart builder，并从 `js/theme.js` 导入公共主题与系列构造器。
+3. 在 `js/charts/index.js` 注册 key。
+4. 在 `manifest.json` 的 `chartCatalog` 中声明一次，再在所需 Tab 的 `chartRefs` 中引用。
+5. 普通图表运行 `node test/regress.mjs <chart-id>`；若改了 `theme.js`、`csv.js`、manifest 等公共部分，运行 `pnpm test`，然后 `pnpm build`。
+
+详细开发约定见 [`CLAUDE.md`](../CLAUDE.md)，方案背景见 [`方案设计.md`](方案设计.md)。
+
+## 4. 泡泡玛特当前分类与图表
+
+| 分类 | 图表 |
+| --- | --- |
+| 概览 | 营收到利润的增速对比、盈利能力、主要 IP 收入占比、区域渠道分布 |
+| 盈利能力 | 营收到利润的增速对比、核心利润及同比增速、核心利润率、净利率同比拆解、利润流向、经营现金流与净利润、三大现金流与现金净增加 |
+| 费用率 | 利润率与费用率拆解、费用结构与费用率 |
+| 资产负债 | 资产结构演变、现金/负债/净营运资本、营运资本效率 |
+| IP 与品类 | 主要 IP 收入趋势、主要 IP 收入占比、各 IP 半年收入占比、除 THE MONSTERS 外 IP 收入及同比、品类收入结构 |
+| 区域渠道 | 区域渠道分布、区域渠道同比增速、区域渠道同比增速趋势、渠道收入结构与增速 |
+
+## 5. 数据状态与口径
+
+### 原始数据
+
+用户提供的 8 份 2026-08-28 原始 CSV 已原样保存到 [`data/ppmt/raw/`](../data/ppmt/raw/)：资产负债表、利润表、现金流量表、财务指标、营收构成、员工、股本变动、分红分析。目录中也保留了早期 `ppmt.xlsx` 与 `2026H1.pdf`。
+
+运行时图表 CSV 位于 [`data/ppmt/`](../data/ppmt/)；原始文件不直接被浏览器读取。归一化脚本为 [`scripts/normalize_ppmt_financials.mjs`](../scripts/normalize_ppmt_financials.mjs)，可由原始合并报表和财务指标生成以下衍生数据：
+
+- `ppmt_cash_conversion.csv`
+- `ppmt_liquidity_working_capital.csv`
+- `ppmt_cashflow_composition.csv`
+- `ppmt_working_capital_days.csv`
+- `ppmt_expense_structure.csv`
+- `ppmt_channel_revenue.csv`
+
+### 必须注意的口径
+
+- CSV 内的 `202xH2` 在利润表/部分财务表中代表**全年累计**，显示层会写成 `xx全年`；不可当作单独的下半年。
+- `ppmt_ip_share_history.csv` 的 H2 则是**单半年**，所以该图使用自定义横轴格式，不能套 `periodAxis` 的“全年”转换。
+- 非 GAAP 净利率是派生指标：非 GAAP 净利 ÷ 营业收入；2020H1/H2 缺失时暂用归母净利替代，脚注已标注。
+- 净利率同比拆解为税盾换算后的百分点贡献；改动后应验证首尾闭合误差小于 0.05pct。
+
+## 6. 近期完成的修改
+
+### 页面与交互
+
+- 使用 Vite 的 vanilla 模式，取代静态服务器，支持热更新。
+- 页面通过 `localhost` 访问，避免 `file://` 读取 CSV 的 CORS 问题。
+- 移除了宽而无信息价值的“财报图表”标题栏；“重新加载数据”改为固定位置的刷新图标按钮。
+- 左侧菜单断点调整为 `880px`。
+- 区域渠道同比增速趋势热力图：绘图区底部留白调整为 `155px`；控制器与横轴不重叠；高/低增长颜色的语义已调整为“红色更代表高增长”。
+
+### 图表组织与数据
+
+- 概览改为复用重要图表，不搬走原分类里的图表，避免两份图表代码逐渐不一致。
+- “成长性”内容并入“盈利能力”，分类导航和方案文档已同步。
+- 基于最新原始数据新增 6 张高优先级图表：经营现金流与净利润、现金/负债/净营运资本、三大现金流与现金净增加、营运资本效率、费用结构与费用率、渠道收入结构与增速。
+
+### 图例与标签
+
+- 图例图标统一交由 ECharts 按系列类型渲染：柱状图为矩形，折线图为“短线 + 空心圆”；统一图例图标宽度为 `20px`。
+- `barSeries()` 默认强制展示柱状标签，避免小柱标签被自动隐藏。
+- `lineDataWithSafeLabels()` 会根据折线值与柱值的接近程度调整标签距离；本次增加 `closePosition` 参数，可把接近柱顶的折线标签切到柱体另一侧。
+- “营运资本效率”四条折线已全部显示数值，并按同期间相邻数值的间隔决定朝上/朝下，降低遮挡。
+- “现金、负债与净营运资本”两组柱和净营运资本折线均显示数值。
+
+### 配色：已确认方向为「轻快消费」
+
+主题文件 [`js/theme.js`](../js/theme.js) 中的正式色板：
+
+- `FINANCIAL_COLORS`：青绿经营现金流、蓝色投资/现金、琥珀融资/负债、珊瑚红净现金增加或关键压力项、暖橙净利润、紫色转化率/同比强调。
+- `CHANNEL_COLORS`：渠道收入和增速的固定语义色。
+- `BRIDGE_COLORS`：瀑布图固定为蓝色基准、青绿色正向贡献、珊瑚红负向拖累。
+
+最近已按该方向调整：
+
+- 净利率同比拆解：蓝色基准、青绿色正向、珊瑚红负向。
+- 核心利润及同比增速：暖橙利润柱、紫色同比线。
+- 经营现金流与净利润、三大现金流、渠道收入结构与增速已采用该色系。
+- 现金/负债/净营运资本：蓝、琥珀、青绿。
+- 营运资本效率：琥珀、蓝、紫、珊瑚红。
+
+后续新增图表必须优先复用主题语义色，不要在单个图表文件里重复手写同语义的十六进制颜色。具体规则见 [`CLAUDE.md`](../CLAUDE.md) 的“配色”部分。
+
+## 7. 下一步建议（尚未开始）
+
+按开发优先级建议：
+
+1. **人工视觉巡检**：重点确认资产负债页新增加的全量标签在桌面和窄屏下是否仍有重叠；当前已通过 SVG 回归，仍应以真实浏览器视觉为准。
+2. **补齐数据链路**：当前员工、股本变动、分红分析原始数据已归档，但尚未生成对应运行时 CSV 或图表。可优先评估“人均营收/人均利润”“分红与派息率”“股本/期权稀释”等图表。
+3. **更新对外 README**：README 的图表清单仍停在较早阶段，未完整列出新增的 6 张 PPMT 图，也仍写有“raw 仅 PDF/XLSX”的旧描述；这不影响运行，但应在对外使用前更新。
+4. **通用财务模板后置**：只有至少两家公司需要同一图型、字段映射和口径都稳定时，再抽取 `template(rows, meta, { width, height }) => option`；当前保持“一图一文件”更稳妥。
+
+## 8. 给下一位 AI 的工作约束
+
+- 不要用 npm；使用 pnpm。
+- 不要把概览图复制出第二套 chart 配置；复用 `manifest.json` 的同一 `chartRef`。
+- 主题、图例、字体、轴和脚注均从 `js/theme.js` 复用；优先 `standardLegend()`、`lineSeries()`、`barSeries()`。
+- 不要手工设置 `legend.icon`，否则会破坏柱/折线图例的统一样式。
+- 修改公共模块（特别是 `theme.js`、`csv.js`、manifest）必须跑 `pnpm test` 与 `pnpm build`。
+- 保留已有用户修改；不要使用 `git reset --hard` 或覆盖无关文件。
+