# 数据字典

## 粒度与口径

一条记录代表 `week × store_id × sku_id × channel`。`period` 仅标记本 case 的 `baseline` 或 `current`；金额为人民币、未含增值税。数据是合成数据，不能推断真实门店、供应商或消费者行为。

| 字段 | 含义 | 约束/注意 |
|---|---|---|
| `week` | ISO 周起始日期 | 用于基准期/当前期分组；完整观察周的结束日为 `week + 6 天` |
| `store_id`, `cluster` | 门店与比较簇 | 簇是模拟分组，不等于真实选址模型 |
| `sku_id`, `category`, `role` | 商品、品类与角色 | `role`: core/routine/need_coverage；角色保护阻止机械下架 |
| `channel` | online/offline | 库存按渠道池核算，不能任意相加推断可调拨库存 |
| `sales`, `revenue`, `price` | 销量、收入、单价 | `revenue` 应可与销量和价格近似核对；舍入需披露 |
| `unit_cost`, `gross_margin` | 单位成本、毛利 | `gross_margin = revenue - sales × unit_cost`，未扣损耗与促销费 |
| `inventory_open`, `receipts` | 期初库存、入库 | 实际期末库存跨周结转 |
| `known_shrink_units`, `shrink` | 已知损耗数量、价值 | 已知损耗不是未知盘亏 |
| `inventory_book_close`, `inventory_actual_close` | 账面/实盘期末库存 | 差额是需核查的物理短少；不自动归因偷损 |
| `promotion`, `promo_cost`, `treatment` | 促销、促销成本、实验处理组 | 有促销不等于可识别增量；实验设计由 context 声明 |
| `stockout_hours`, `open_hours` | 缺货时长、营业时长 | 同时检查全局和目标 SKU 比率；ACT 检查试点门店×目标 SKU×渠道最差池。不能证明缺货根因；须满足 0 ≤ stockout_hours ≤ open_hours |
| `budget_revenue`, `budget_gross_margin` | 收入/毛利预算 | 仅用于预算偏差，不构成预算 owner 证明 |

## Case context

每个 case 另有 JSON：`baseline_weeks`、`current_weeks`、`as_of`、`objective`、`requested_action`、`target_skus`、`competitor_signal`、`experiment`、`authority` 与 `data_freshness_days`。`as_of` 是复核截止日；时效检查独立验证 `data_freshness_days` 是否为非布尔、有限的数值且不超过 7 天，并验证当前期最新完整周结束日不晚于 `as_of`、且距其不超过 7 天。`authority` 与实验字段是**模拟声明**，用于测试门禁，不是运行时自行取得的实际授权。运行时 context 不含 scenario 标签、golden 答案或隐藏真相。

## 派生口径与未知值

- 收入变化按“总销量→SKU 组合→SKU 价格”的顺序分解；残差应显式呈现。该会计桥接不是需求因果归因。
- 贡献（contribution）按 SKU“数量→价格→单位成本→已知损耗/促销成本”桥接，以毛利扣**已知**损耗和促销成本的演示口径计算；未知库存差异另列为 exposure，不能和贡献重复扣减。它不是完整 P&L，未包括人工、租金、配送、税费等。
- 促销工具仅在 context 声明随机设计、平行趋势、无外溢与预注册均成立，且数据构成固定 4 个 `baseline_weeks` 加 4 个 `current_weeks` 的完整实验包时，才给出基线调整的 Difference-in-Differences 估计。每个 `store × SKU × channel` 池在基期必须无处理/促销，本期四周内处理和促销必须各自固定且相互一致；同一 `store × SKU` 跨渠道不得交叉分组。任何池不完整或污染即返回 `not_identified`，不做子样本估计。本六店合成样本不提供置信区间或显著性结论。
- `unknown_loss_units = inventory_book_close - inventory_actual_close` 的正值提示账实短少，成因未知；不得直接称为盗损或某部门责任。
- 缺失、负库存、公式不平或超出分析范围的数值，工具应返回 `None` 或质量问题，不能用 0 填充后给出强结论。


## 试点周度复核包

`data/business_challenges/cases/` 的 X01–X03 是补丁后的合成业务复核包，沿用相同行级 POS 字段与 11 字段决策协议；它们不是独立 holdout，也没有真人评测。X01 在指定末周引入 −¥708 的试点池贡献事实；X02 在 `U1 / P1 / online` 指定末周引入 20% 缺货率，同时四周汇总仍为 5%；X03 是稳定参照包。它们描述用于验证门禁的输入事实，并不预先声明任何卡片结果。`pilot_weekly_review` 从同一试点池的四周数据派生末周贡献、前三周平均贡献及末周缺货率，供门禁和卡片读取。它不新增原始数据 schema，也不估计成本、补货、需求或长期效果的因果关系。