重构智脑实施方法论：引入FDE模式，八步工作法，适配中国连锁经营企业国情

docs/智脑实施方法论/15-技术参考-指标口径一致性分析.md

@@ -0,0 +1,154 @@
+# 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. 修复并更新文档
+```