# 15 · 技术参考：指标口径一致性分析

> 从数据溯源审计中提取的跨页面重复指标口径对比，以及已发现和待修复的问题清单。

## 1. 跨页面核心指标口径对比

### 1.1 营业收入（消费金额）

| 页面 | 前端变量 | API | API字段 | 数据源表.字段 |
|------|---------|-----|---------|-------------|
| 总部驾驶舱 | `od?.consumption` | /overview | `consumption` | analytics.bill_fact.consumption |
| 老板驾驶舱 | `od?.consumption` | /overview | `consumption` | 同上 |
| 费用总览Tab | `ov.total_consumption` | /store-expense/overview | `total_consumption` | analytics.bill_fact.consumption |

**口径：一致 ✅**

### 1.2 优惠

| 页面 | 前端变量 | API | API字段 | 数据源表.字段 |
|------|---------|-----|---------|-------------|
| 总部驾驶舱 | `od?.discount` | /overview | `discount` | analytics.bill_fact.discount_total |
| 老板驾驶舱 | `od?.discount` | /overview | `discount` | 同上 |
| 费用总览Tab | `ov.total_discount` | /store-expense/overview | `total_discount` | 同上 |

**口径：一致 ✅**

### 1.3 实收

| 页面 | 前端变量 | API | API字段 | 数据源表.字段 |
|------|---------|-----|---------|-------------|
| 总部驾驶舱 | `od?.received` | /overview | `received` | analytics.bill_fact.received_total |
| 老板驾驶舱 | `od?.received` | /overview | `received` | 同上 |
| 费用总览Tab | `ov.total_received` | /store-expense/overview | `total_received` | analytics.mv_store_risk_rating_monthly.received |
| 利润瀑布 | `wf.received` | /overview/profit-waterfall | `received` | analytics.mv_store_risk_rating_monthly.received |

**口径：一致 ✅** — `bill_fact.received_total` 汇总和物化视图汇总结果相同。

### 1.4 账单数

| 页面 | 前端变量 | API | API字段 | 数据源表.字段 |
|------|---------|-----|---------|-------------|
| 总部驾驶舱 | `od?.bill_count` | /overview | `bill_count` | analytics.bill_fact (count(*)) |
| 老板驾驶舱 | `ex?.total_bills` | /store-expense/overview | `total_bills` | analytics.mv_store_risk_rating_monthly.bill_count |

**口径：一致 ✅**

### 1.5 客单价

| 页面 | 计算方式 | 值 |
|------|---------|-----|
| 总部驾驶舱 | `avg(received_total)` from bill_fact | 38.29 |
| 老板驾驶舱 | `sum(received)/sum(bill_count)` | 38.29 |

**口径：一致 ✅** — 数学结果相同。

### 1.6 门店贡献利润（实际）

| 页面 | API | 计算方式 | 值 |
|------|-----|---------|-----|
| 总部驾驶舱 | /store-expense/overview | `sum(received) FILTER(费用匹配) - food_cost - operating_expense` | 6,982,110.42 |
| 老板驾驶舱(指标卡) | 同上 | 同上 | 同上 |
| 老板驾驶舱(瀑布图) | /overview/profit-waterfall | `sum(received) FILTER(has_expense) - food_cost - operating_expense` | 同上 |

**口径：一致 ✅**（已修复）

### 1.7 食材成本

| 页面 | API | 计算方式 |
|------|-----|---------|
| 总部驾驶舱 | /store-expense/overview | `sum(actual_food_cost)` |
| 老板驾驶舱(瀑布图) | /overview/profit-waterfall | `sum(COALESCE(actual_food_cost,0))` |
| 费用总览Tab | /store-expense/overview | 同总部 |

**口径：一致 ✅** — `sum(NULL)` 忽略 vs `sum(COALESCE(NULL,0))` 加0，结果相同。

### 1.8 费用率

| 页面 | 计算方式 | 值 |
|------|---------|-----|
| 总部驾驶舱 | `sum(operating_expense)/matched_received*100` | 53.77% |
| 老板驾驶舱(瀑布图) | `wf.total_expense/wf.received*100`（matched口径） | 53.77% |
| 费用总览Tab | 同总部 | 53.77% |

**口径：一致 ✅**（已修复）

### 1.9 门店风险分布 / P0+P1门店 / 盈利亏损数

| 指标 | 页面 | API | 数据源 |
|------|------|-----|--------|
| 风险分布 | 总部/老板 | /stores/risk | mv_store_risk_rating_monthly.risk_level |
| P0/P1 | 总部/老板 | /stores/priority | mv_store_action_priority_deep_monthly |
| 盈利/亏损 | 总部/老板 | /store-expense/overview | count FILTER(actual_store_contribution > 0) |

**口径：一致 ✅**

## 2. 口径一致性保障原则

1. **同一指标多页面展示时，必须使用同一数据源**（物化视图或原始表，不能混用）
2. **分母口径必须一致**：如"费用率"分母必须统一为 matched_received（仅含费用匹配门店）
3. **FILTER vs COALESCE**：`sum(x) FILTER(WHERE has_expense)` 与 `sum(COALESCE(x,0))` 在无NULL行时结果相同，但语义不同——FILTER排除整行，COALESCE只替换NULL值
4. **物化视图 vs 原始表**：优先用物化视图，避免直接查原始表（性能差 + 可能stale不一致）
5. **新增页面时**：如果复用已有指标，必须检查数据源是否一致，避免口径分裂

## 3. 已发现问题清单

### 已修复 ✅

| # | 问题 | 位置 | 修复方式 |
|---|------|------|---------|
| 1 | 利润瀑布 store_contribution 口径不一致 | /overview/profit-waterfall | received等改为 `FILTER(WHERE has_expense)` |
| 2 | 瀑布图费率分母不一致 | 前端除法 | received改为matched口径后分母一致 |
| 3 | mv_overview_monthly 刷新缺失 | 刷新脚本 | 加入DELETE+INSERT步骤 |
| 4 | 优惠率/毛利率/会员占比硬编码为0 | /overview API | 修正SQL计算 |
| 5 | Schema前缀错误 | /channel API | 移除analytics.前缀 |
| 6 | 列名不存在 | /stores/risk等 | SELECT * 或0 AS替代 |
| 7 | 日期格式不匹配 | 考勤相关API | to_char改中文格式 |
| 8 | 客流-人力匹配在岗人数不合理 | /situational-awareness/correlation | 改用打卡数据解析 |
| 9 | 客流月度汇总vs日均未对齐 | 同上 | 客流除以30天 |

### 待确认 ⚠️

| # | 问题 | 位置 | 影响 | 建议 |
|---|------|------|------|------|
| 1 | KPI达成率利润口径不一致 | /analytics-enhanced/kpi | 利润率偏低~0.7pp | 分母改为matched_received |
| 2 | store-profit-ranking COALESCE导致无费用门店排名异常 | /overview/store-profit-ranking | 利润TOP5可能含无费用门店 | 加FILTER(has_expense) |
| 3 | StorePage公司均值硬编码 | StorePage.tsx:188 | 不随数据更新 | 改为API动态获取 |
| 4 | StorePage scorecard直接查bill_records | /stores/:code | 可能与物化视图不一致 | 改用物化视图 |

## 4. 口径检查方法论

### 4.1 新增指标时的检查流程

```
1. 该指标是否在其他页面已存在？
   → 是：检查数据源是否一致（表、字段、过滤条件）
   → 否：记录到溯源文档
2. 分子分母的过滤条件是否一致？
   → 如：费用率分母是否都用了matched_received
3. 是否用了物化视图？
   → 优先用物化视图，避免直接查原始表
4. 是否有NULL处理差异？
   → sum(x) vs sum(COALESCE(x,0)) 在有NULL行时结果不同
5. curl + psql 双向验证
   → API返回值与直查数据库一致
```

### 4.2 定期口径审计

```
1. 运行溯源文档中的"跨页面对比"部分
2. 对每个指标，在所有出现的页面验证值是否一致
3. 不一致的，定位差异原因（数据源、过滤条件、计算方式）
4. 修复并更新文档
```