销售成本因素分析（全月加权平均法 · 连环替代）

〇、功能亮点（为什么装这个技能）

• 🔢 两因素 + 三因素连环替代，一次算清：自动把销售成本总差异拆成「①销量因素」「②加权单价因素」，再把 ② 进一步拆成「②a 量结构权重 / ②b 期初成本水平 / ②c 本期入库成本」三个其中项，每一步都带算式与通俗大白话解读，数字绝不上手算、闭合校验不过不交付。
• 📦 单品单基准 → 多项单品 × 多个基准，自由扩展：既支持传统"一个产品比一个区间"，也支持"上传 N 个产品、每个产品比 M 个区间（同比/环比/预算混搭）"，一键跑出所有案例，告别反复手动改数据。
• 📊 每个产品一份完整报告（多周期分章节）：上传多个产品、每个产品多个周期（同比/环比/预算），每个产品自动产出一份 HTML/Word/PPT 报告，报告内按周期分章节——例如 A产品「实际 vs 上期」「实际 vs 同期」同文件、分两部分，每部分都是带阶梯表 / 连环替代推演 / 立体图表的完整详报；不同产品各自独立成文件，互不干扰。另有可选的「跨产品横向汇总」(--report summary) 供总览。
• 🗂 三格式默认齐出（HTML / Word / PPT）：不用纠结交付形态——网页可交互看最全图表、Word 可编辑进汇报材料、PPT 可直接路演，同一份数据三种成品一次拿到手。
• 🧱 立体化图表 + 强对比配色：基期→各因素累加→报告期的立体瀑布图、因素影响额占比图、跨案例热力图，增量因素高对比着色，重点项重点表述，领导一眼看懂主因。
• 💡 通俗含义标注框（管理者友好）：每个因素配一个"大白话解读框"——这是什么、为什么影响成本、可控性如何，财务不用再给老板做二次翻译。
• 📐 口径零歧义：凡出现"入库"必带期间定语（本期/同期/上期/计划），预算简化口径自动标注三因素不适用，报告严谨可直接对外。
• 🔒 范围边界清晰：纯做成本差异归因与折算，不做料工费标准成本下钻，避免越界误用。

> 一句话：把"成本到底为什么涨了/降了"这件最让老板追问的事，做成一份打开就能用的三格式、多维度、带解读的正式报告。

一、目的

对制造业单品（或多个单品）的主营业务成本（销售成本）差异做规范化归因：把本期销售成本相对基准（同比 / 环比 / 预算）的总差异，完整分解为「销量因素」与「加权单位成本因素」，再将加权单位成本因素进一步拆为「量结构权重」「期初成本水平」「本期入库成本」三个子因素，输出可直接呈报管理层的正式分析报告。

• 单品单基准模式：一个产品 + 一个基准区间，产出该产品的 COGS 报告与单价深化报告（单章节）。
• 多项单品 × 多个基准模式：上传多个产品，每个产品可带多个基准区间（同比/环比/预算任意组合），脚本自动展开为多个分析案例，每个产品产出一份报告、报告内按周期分章节（每章节 = 一份完整详报）。

默认每个产品产出两份配套报告（COGS + 单价深化），每份按"一产品一文件、多周期分章节"组织：

1. 《销售成本差异分析报告》（COGS 口径）——各因素影响额 = 单价增量 × 本期销量，回答"成本总额为什么变了"；
2. 《销售成本单价变化分析报告》（单价深化篇，元/件口径，不乘销量）——聚焦加权单价 ΔP 本身的变动分解，回答"每一件产品的单位成本为什么变了"。

范围边界（重要）：本技能只做上述分解与折算，不做料、工、费的标准成本下钻分析。若用户提出下钻需求，明确告知超出本技能范围，可另行分析。

措辞规范（硬性）：报告中凡出现"入库"一词，必须带期间定语，让报告使用者明确其所属区间——
- 实际口径一侧：一律写 "本期入库"；
- 基准口径一侧：按基准类型写 "同期入库"（同比）/ "上期入库"（环比）/ "计划入库"（预算），由脚本按 baseline_type 自动注入（数据表另有入库口径说明脚注）。

二、输入数据规范

每个单品需要两套指标（实际一套、基准一套），共 6 项 × 2：

同时确认三件事：
1. 基准类型：同比（去年同期）/ 环比（上期）/ 预算（标准成本）；
2. 单品名称、本期期间、基准期间标签；
3. 计价方法须为全月加权平均法（本技能公式仅适用此法）。

数据来源兼容：对话中直接口述的数字、Excel/CSV 文件、JSON 文件。Excel/CSV 先解析为下述 JSON 再运行脚本；字段缺失时先向用户补问，不得臆造数字。

输入 JSON 格式（向后兼容，两种写法都支持）：

写法 A · 单品单基准（传统写法，旧格式直接用）

{
  "product": "CX-208 减速机铸件",
  "period": "2026年8月",
  "baseline_type": "同比",
  "baseline_label": "2025年8月",
  "actual":  {"opening_qty":1000,"opening_amt":50000,"in_qty":4000,"in_amt":220000,"sold_qty":3500},
  "baseline":{"opening_qty":800, "opening_amt":36000,"in_qty":2400,"in_amt":122400,"sold_qty":2500}
}

写法 B · 多项单品 × 多个基准（多案例批量模式，推荐用于横向对比）

{
  "products": [
    {
      "name": "CX-208 减速机铸件",
      "period": "2026年8月",
      "actual": {"opening_qty":1000,"opening_amt":50000,"in_qty":4000,"in_amt":220000,"sold_qty":3500},
      "baselines": [
        {"type":"同比", "label":"2025年8月",
         "data":{"opening_qty":800,"opening_amt":36000,"in_qty":2400,"in_amt":122400,"sold_qty":2500}},
        {"type":"环比", "label":"2026年7月",
         "data":{"opening_qty":900,"opening_amt":45000,"in_qty":3200,"in_amt":168000,"sold_qty":3000}},
        {"type":"预算", "label":"2026年预算",
         "data":{"sold_qty":3800,"unit_cost":52.0}}
      ]
    },
    {
      "name": "CX-315 电机轴",
      "period": "2026年8月",
      "actual": {"opening_qty":600,"opening_amt":30000,"in_qty":2000,"in_amt":110000,"sold_qty":2100},
      "baselines": [
        {"type":"同比", "label":"2025年8月",
         "data":{"opening_qty":500,"opening_amt":24000,"in_qty":1600,"in_amt":88000,"sold_qty":1700}},
        {"type":"预算", "label":"2026年预算",
         "data":{"sold_qty":2300,"unit_cost":60.0}}
      ]
    }
  ]
}

脚本会自动把写法 B 展开为多个分析案例（上例 = 5 个案例），逐一计算后，每个单品产出一份报告（COGS + 单价两份），每份报告内按周期分章节——例如单品 A 的报告里第一章节是「实际 vs 上期」、第二章节是「实际 vs 同期」，每章都是带阶梯表 / 连环替代 / 图表的完整详报；不同单品各自独立成文件。预算简化口径（data 仅含 sold_qty + unit_cost）自动按两因素处理并标注说明（仅出现在 COGS 报告，单价深化篇跳过该案例）。

预算模式允许两种基准写法：
- 完整口径（预算同样编了期初/入库计划）：与上同结构；
- 简化口径："baseline": {"sold_qty":3200, "unit_cost":52.0} —— 此时只做两因素分解，"加权单价因素"改称"单位成本差异"，不拆三因素，并在报告中说明原因。

三、计算原理（必读）

完整推导见 references/method.md，核心链条：

第一步  COGS = Q × P
第二步  P = (期初金额+入库金额)/(期初数量+入库数量) = w_a·a₀ + w_b·b
第三步  连环替代（顺序固定：先权重w → 再期初价a₀ → 最后入库价b）：
        P₀ → P(1)=w_a₁·a₀₀+w_b₁·b₀ → P(2)=w_a₁·a₀₁+w_b₁·b₀ → P₁
        ②a量结构=P(1)−P₀   ②b期初水平=P(2)−P(1)   ②c入库成本=P₁−P(2)
第四步  各因素对COGS的影响额 = Q₁ × 对应的P增量；① 销量=(Q₁−Q₀)×P₀

闭合校验强制执行：① + ②a + ②b + ②c 必须精确等于总差异（允许 ±0.5 元浮点误差），不平则停止输出并检查输入。

四、执行流程

1. 解析输入：从对话 / 文件提取两套六项指标与基准类型，整理成 JSON。缺项先问，不臆造。
2. 运行脚本：

# 依赖（首次使用先安装到隔离环境）
# pip install python-docx python-pptx matplotlib

# 单品单基准：默认同时出 html+docx+pptx 三格式、COGS+单价两份报告（单章节）
python scripts/cogs_report.py --input data.json --outdir ./out

# 多品多基准（推荐写法 B）：每个产品一份报告、报告内按周期分章节，三格式齐出
python scripts/cogs_report.py --input data.json --format html,docx,pptx --outdir ./out

# 想再附一份"跨产品横向汇总"总览（默认不生成，避免把不同产品压成一张薄表）
python scripts/cogs_report.py --input data.json --report summary --outdir ./out

# --format  可选 html | docx | pptx，可同时传多个（默认 "html,docx,pptx" 三格式齐出）
# --report  both（默认：每个产品一份 COGS+单价报告，多周期分章节）| cogs | price | summary（在逐产品报告基础上附赠跨产品横向汇总）
# 输出文件名自动生成（每个产品一个文件）：
#   <产品名>-销售成本差异分析报告-分基准.<ext>        （内含该产品的所有周期对比章节）
#   <产品名>-销售成本单价变化分析报告-分基准.<ext>
#   （仅 --report summary 时）跨单品跨基准-销售成本差异对比汇总.<ext> / 跨单品跨基准-销售成本单价变化对比汇总.<ext>

3. 核对闭合：脚本会打印各因素影响额与闭合校验结果；校验失败必须先解决再交付。多案例模式下会汇总案例数与各案例闭合状态。
4. 交付：用 present_files 展示报告文件，并附各因素影响额的一句话结论（哪个是主因、占多少百分比）。多产品时每个产品一个文件，文件内按周期分章节，可直接发给对应产品负责人。
5. 用户未指定格式时，默认 HTML + Word + PPT 三格式齐出（满足"自由选择"诉求），并提示可减配为单一格式。

五、报告结构（硬性要求，脚本已内置）

生成的报告必须且按以下顺序组织（三种格式一致）：

1. 概论——分析口径（单品、期间、计价方法、基准类型）、方法说明（两因素+三因素连环替代）、结论先行摘要（总差异、主因及占比）。
2. 数据基础表——两套指标原始数据及派生指标（期初单价 a₀、入库单价 b、加权单价 P、销售成本 COGS）。
3. 两因素分解——① 销量因素、② 加权单价因素，附算式。
4. 三因素阶梯汇总表——阶梯式呈现：基期 P₀ → +换权重 → +换期初价 → +换入库价 → 报告期 P₁，每级显示本步增量及其归属因素。预算简化口径下此节替换为"单位成本差异说明"。
5. 各因素明细表述——先呈现 ② 加权单价因素（合计）影响额，随后 ②a / ②b / ②c 三张卡片必须标注 "（其中项）"，明确它们是 ② 合计的组成部分：每项一小节，算式 + 通俗含义标注框（用管理者听得懂的大白话解释该因素是什么、为什么会影响成本、可控性如何），标注框不可省略。
6. 连环替代过程推演——把第三步的四行替换算式逐步完整呈现（过程与明细分离，不得混写）；随后呈现第四步折算（P 增量 × Q₁ = COGS 影响额），合计必须与总差异闭合。
7. 分析图表——立体效果瀑布图（基期 → 各因素累加 → 报告期）+ 因素影响额占比图；配色对比度必须强烈（增量因素各用高对比色、不利用暖色系突出），图下只对重点项（影响额最大的因素）做重点表述，明细不在图下赘述。
8. 总结——归因结论、可控性提示、给管理层的一句话行动建议（不含料工费下钻）。

《销售成本单价变化分析报告》（单价深化篇）结构：概论（ΔP 结论先行）→ 数据基础（a₀、b、w_a、w_b、P 两期对比表，含入库口径说明）→ 单价差异阶梯表（元/件，末行为 ② 合计 = ΔP 验算）→ 各因素明细（② 合计 + 三个其中项，单位元/件，提示折算见主报告）→ 连环替代过程推演 → 单价瀑布图 + 重点项表述 → 总结。三格式（HTML/Word/PPT）结构一致。预算简化口径下单价报告不适用（无库存结构计划），脚本自动跳过并提示。

《跨单品跨基准对比汇总报告》（可选横向总览，仅 --report summary 时产出，默认不生成）结构：
> 说明：默认每个产品已有一份「多周期分章节」完整报告，足以覆盖"逐品深挖"。此汇总报告仅在你额外想做"跨产品横向对标"时附赠，避免把不同产品压成一张薄对比表。

1. 概论——覆盖单品数 × 基准类数 × 案例数总览、合计 COGS 差异 / 合计 ΔP。
2. 各案例因素影响对比表——所有案例横向铺开，COGS 版列出「总差异 / ①销量 / ②单价 / ②a / ②b / ②c」，单价版列出「ΔP / ②a / ②b / ②c」，一眼看清谁偏离最大。
3. 因素热力图——跨案例横向对比，颜色深浅直观定位异常单品 / 异常基准，优先纳入成本管控会议。
4. 总结——横向结论、可控性提示（②c 本期入库成本是唯一的本期管理动作因素，跨单品对比应重点盯各单品 ②c 差异）、下钻指引（点同目录单品分基准详细报告看逐项阶梯表与连环替代推演）。

> 三种报告均支持 HTML / Word / PPT 三格式；默认输出"每个产品一份（多周期分章节）"的完整报告，覆盖逐品深挖；需要横向对标时加 --report summary 即可额外得到跨产品汇总。

六、质量红线

• 数字一律由脚本计算，禁止心算代入报告；闭合不平禁止交付。
• 每个因素必须有通俗含义标注，禁止只给数字不给解读。
• 过程（第 6 节）与明细（第 5 节）分开呈现，图表下不重复明细。
• 报告金额保留 2 位小数，千分位分隔；单价保留 2~4 位小数。
• 基准类型为"预算+简化口径"时，报告须注明"三因素分解因预算未编库存结构计划而不适用"。

Resources

• scripts/cogs_report.py —— 计算与三格式报告生成主脚本，直接运行，无需读入全文。
• references/method.md —— 公式完整推导（两因素、三因素连环替代、闭合校验），解读与排查数字问题时加载。