# HX-40 统一口径与字段映射文档（第二/三步产出）

> 承接《HX-40-步骤1-体检报告》。本文件是"边写代码前先成文"的映射规则，与 `HX-40-清洗脚本.py` 一一对应（脚本内注释以 R1~R7 + D1~D4 编号回指本文件）。
> 四项口径断点已由发起人 2026-09-18 确认：**D1-A / D2-B / D3-B / D4-C**。

## 一、统一底表字段设计

底表 `HX-40-数据底表.csv` 采用**长表 + 记录类型**：每行是一条"某记录类型、某期间、某维度"的原子事实，避免把口径不同的数据硬塞进同一行。

| 字段 | 含义 | 取值域 |
|---|---|---|
| 记录类型 | 该行属于哪类事实 | 销售明细 / 费用月总 / 库存快照 / 目标 / 区域对账_渠道自报 |
| 期间 | 归一后的年月 `YYYY-MM` | 2026-06 ~ 09（库存另含 04/05） |
| 渠道 | 主口径销售维度 | CH-KA / CH-DIS / CH-WHS / CH-GOV / EC |
| 品类 | 主口径产品维度 | 电视 / 空调 / 冰箱 / 洗衣机 / 厨电 |
| 区域 | 仅渠道自报对账行有值 | 鲁东/鲁中/鲁南/鲁北大区 |
| 层 | 目标行专用 | 大区层 / 城市层 |
| 销售额元 / 不含税额元 / 订单数 / 数量 | 销售 | — |
| 分摊费用元_估算 | D2-B 分摊结果 | 销售行 |
| 费用元_原始 | 台账月度合计 | 费用行 |
| 库存元 / 库存数量 / 在途数量 | 库存 | 库存行 |
| 目标额万元 | 目标 | 目标行 |
| 笔数 | 渠道对账笔数 | 对账行 |

## 二、字段映射规则（哪张表哪个字段、做什么转换）

### R1 金额与单位
- ERP `AMT_TAX`、电商 `实付金额`：单位=元，直接用。
- 渠道 `成交金额（万元）`、库存 `库存金额万元`、目标 `目标额万元`：×10000 化元（目标在计算层再按需还原万元）。
- 含税统一：ERP `TAX_RATE` 恒 13%，底表 `销售额元` 一律视为**含税**；`不含税额元 = 销售额元 ÷ 1.13`。

### R2 区域清洗（仅作用于渠道自报表）
`区域（大区）` 映射：`鲁东→鲁东大区`、`山东鲁东→鲁东大区`、`鲁中→鲁中大区`（命中 5 行，涉 90.50 万，已在异常清单留行号）。其余表无有效区域，区域列留空。

### R3 品类映射（唯一能贯通三张表的维度）
`MAT_CODE/商品编码 → 品类`：M-TV55·M-TV65→电视；M-AC15→空调；M-RF21→冰箱；M-WM10→洗衣机；M-KD07→厨电。库存 `SKU编码` 已自带品类列，直接沿用。

### R4 电商文件级修复
按 `utf-8-sig` + 显式 12 列名读取（原文件带 BOM、表头 11 列但数据 12 字段，默认读法整表右移一列）。补无表头第 12 列为 `收件省份`。

### 记录类型构建
| 记录类型 | 源表 | 转换 |
|---|---|---|
| 销售明细(主口径) | ERP + 电商(D3-B) | 按 期间×渠道×品类 聚合销售额/订单/数量；**渠道自报表不并入主口径**（R6，防与 ERP-KA 双计） |
| 费用月总 | 费用台账 | 按月份对 `金额元` 求和，公司级 |
| 分摊费用元_估算 | 费用台账 | D2-B：某(期间×渠道×品类)费用 = 当月费用总额 × 该组合销售额 ÷ 当月主口径总销售额 |
| 库存快照 | 库存月报 | 按 期间×品类 汇总库存元/数量/在途（同快照×仓库×SKU 双行按 R4 求和保留） |
| 目标 | 目标分解表 | `区域含"大区"→大区层，否则→城市层`；原样落 `目标额万元` |
| 区域对账_渠道自报 | 渠道自报表 | 经 R2 清洗后 按 期间×大区 汇总 `成交元`（对账口径，不进主合计） |

### 跨表连接的边界（成文声明，不隐式合并）
- **单号体系三套独立**（ERP-B / QD-QD / PF2026，交集=0，已验证）：任何跨表匹配不以单号相等为条件。
- **渠道自报表 ↔ ERP 疑似同一业务**：采用"同日 + 同额(万元,两位小数)"弱匹配探查，仅命中 1 对候选；ERP 无客户名无法终验 → **双方都保留、不去重、只披露**（详见异常清单与看板"疑似重复"区）。因主口径本就不含渠道自报表，无论该笔是否重复，主合计均不受影响。
- **费用→渠道/区域**：台账无此维度，分渠道费用纯为 D2-B 估算拆分，不可对账。
- **区域维度**：仅覆盖渠道自报表（约主口径 3.7%），看板以"部分口径"标签呈现。

## 三、交叉计算口径（第四步）
- 目标达成率 = 主口径销售额 ÷ 目标额（分大区层/城市层两套并列，D4-C）。
- 费用率 = 费用总额 ÷ 主口径销售额（公司级口径不受分摊估算影响）。
- 库存周转（估算）= 当月主口径销售额 ÷ 期初期末平均库存金额；**因库存金额量纲存疑（隐含单台≈350元 vs 售价≈6500元），仅作相对值，不推毛利**。
- 渠道结构占比 = 各渠道销售额 ÷ 主口径总销售额。

## 四、主数据缺口记录（供总控知悉，不自行补造）
`00-总控/素材/_主数据/README.md` 约定的 组织架构.csv / 门店清单.csv（CUST_CODE→大区、客户名称）**尚未生成**，ERP 侧仅有 180 个 CUST_CODE 无名称无区域。本案据此选择 D1-A 降级方案而非臆造映射。若后续补齐主数据，可升级为完整区域口径（脚本 `load_channel` / `build_base` 预留了接入点，无需改动其它规则）。
