SBrainCO/docs/20260812/20260801_系统升级方案_逐月与时间段分析.md

# 系统升级方案：从"4月单月分析"到"逐月+时间段汇总+同比环比"

> 文档日期：2026-08-01
> 状态：方案设计
> 关联文档：`docs/2026年4月运营分析指标与展现审查及利润提升整改方案.md`

---

## 一、升级目标

| 能力 | 当前状态 | 目标状态 |
|---|---|---|
| 月份选择 | 固定2026年4月 | 任意月份可选，默认最新有数据月份 |
| 时间段汇总 | 不支持 | 季度/半年/全年/自定义区间汇总 |
| 同比（YoY） | 不支持 | 任意月份 vs 去年同月，展示变化率 |
| 环比（MoM） | 不支持 | 任意月份 vs 上月，展示变化率 |
| 趋势分析 | 不支持 | 月度趋势线、移动平均、同比叠加 |
| 前端选择器 | 无 | 全局月份选择器 + 时间范围切换 |
| 数据管道 | 硬编码4月 | 参数化导入，支持多月数据 |

---

## 二、现状诊断

### 1. 硬编码 `_april` 的数据库对象（32个）

这些视图/表的 SQL 内部硬编码了 `WHERE report_month = DATE '2026-04-01'` 或直接从4月数据源取数，**无法切换月份**。

> **核实方法：** `pg_matviews` 查物化视图9个 + `information_schema.tables` 查基表6个和普通视图17个 = 合计32个。

#### 1.1 物化视图（9个，`pg_matviews`）

| 对象名 | 用途 | 依赖月份字段 |
|---|---|---|
| `mv_store_theoretical_actual_cost_april` | 门店理论/实际成本对比 | `report_month` |
| `mv_store_action_priority_deep_april` | 门店行动优先级深度分析 | `report_month` |
| `dish_store_summary_april` | 菜品门店汇总 | `report_month` |
| `dish_store_sku_april` | 菜品门店SKU汇总 | `report_month` |
| `dish_basket_april` | 菜品购物篮分析 | `report_month` |
| `dish_category_summary_april` | 菜品品类汇总 | `report_month` |
| `dish_member_sku_april` | 菜品会员SKU分析 | `report_month` |
| `dish_sales_april` | 菜品销售汇总 | `report_month` |
| `dish_sku_summary_april` | 菜品SKU汇总 | `report_month` |

#### 1.2 普通视图（17个，`information_schema.tables` WHERE table_type='VIEW'）

| 对象名 | 用途 | 依赖月份字段 |
|---|---|---|
| `v_dish_sku_abc_april` | SKU ABC分类分析 | `report_month` |
| `v_inventory_cost_classified_april` | 库存成本分类 | `report_month` |
| `v_inventory_abnormal_items_april` | 库存异常货品 | `report_month` |
| `v_inventory_finance_category_april` | 库存财务分类 | `report_month` |
| `v_c_sku_governance_april` | SKU治理分析 | `report_month` |
| `v_dish_member_repeat_april` | 菜品会员复购 | `report_month` |
| `v_store_action_priority_deep_april` | 门店行动优先级 | `report_month` |
| `v_store_area_efficiency_april` | 门店面积效率 | `report_month` |
| `v_store_deep_diagnosis_april` | 门店深度诊断 | `report_month` |
| `v_store_site_profile_april` | 门店选址画像 | `report_month` |
| `v_store_site_replication_score_april` | 选址复制评分 | `report_month` |
| `v_store_location_overlap_risk_april` | 选址重叠风险 | `report_month` |
| `v_store_nearest_neighbor_april` | 最近邻分析 | `report_month` |
| `v_store_spatial_pairs_april` | 门店空间对分析 | `report_month` |
| `v_store_theoretical_actual_cost_april` | 门店理论/实际成本（视图版） | `report_month` |
| `v_district_site_benchmark_april` | 区域选址基准（视图版） | `report_month` |
| `v_site_segment_benchmark_april` | 分段基准（视图版） | `report_month` |

#### 1.3 基表（6个，`information_schema.tables` WHERE table_type='BASE TABLE'，不含物化视图）

| 对象名 | 用途 |
|---|---|
| `dish_pair_summary_april` | 菜品搭售分析 |
| `mv_district_site_benchmark_april` | 区域选址基准（表） |
| `mv_site_segment_benchmark_april` | 分段基准（表） |
| `mv_store_location_overlap_risk_april` | 选址重叠风险（表） |
| `mv_store_site_profile_april` | 门店选址画像（表） |
| `mv_store_site_replication_score_april` | 选址复制评分（表） |

> **注意：** `v_store_category_cost_benchmark_april` 和 `v_store_inventory_efficiency_april` 在 `data.ts` 中被引用，但数据库中不存在这两个对象（可能已删除或从未创建），需在改造时排查。
> **注意：** 部分对象有同名 `v_`（视图）和 `mv_`（基表）两个版本，如 `v_store_site_profile_april` 和 `mv_store_site_profile_april`，改造时需统一处理。

### 2. 硬编码 `DATE '2026-04-01'` 或 `_april` 表名的 API 接口（45处）

> **核实方法：** `grep -rn "DATE '2026-04-01'\|_april" server/src/routes/*.ts` 逐行统计。

#### 2.1 `server/src/routes/store-expense.ts`（11处 `DATE '2026-04-01'`）

| 行号 | 接口 | 硬编码内容 |
|---|---|---|
| 36 | `/store-expense/overview` | `e.report_month = DATE '2026-04-01'` |
| 88 | `/store-expense/expense-structure` | `report_month = DATE '2026-04-01'` |
| 107 | `/store-expense/store-ranking` | `WHERE report_month = DATE '2026-04-01'` |
| 161 | `/store-expense/store-contribution` | `WHERE report_month = DATE '2026-04-01'` |
| 211 | `/store-expense/rent-risk` | `WHERE report_month = DATE '2026-04-01' AND rent_expense IS NOT NULL` |
| 276 | `/store-expense/delivery-commission` | `WHERE report_month = DATE '2026-04-01' AND delivery_received > 0` |
| 330 | `/store-expense/efficiency` | `WHERE report_month = DATE '2026-04-01' AND received > 0 AND area_sqm IS NOT NULL` |
| 386 | `/store-expense/fixed-variable` | `WHERE report_month = DATE '2026-04-01' AND received > 0` |
| 436 | `/store-expense/break-even` | `WHERE report_month = DATE '2026-04-01' AND received > 0` |
| 499 | `/store-expense/loss-diagnosis` | `WHERE report_month = DATE '2026-04-01' AND actual_store_contribution <= 0 AND received > 0` |
| 725 | `/store-expense/store-evaluation` | `WHERE report_month = DATE '2026-04-01' AND received > 0` |

#### 2.2 `server/src/routes/data.ts`（26处：9处 `DATE '2026-04-01'` + 17处 `_april` 表名）

| 行号 | 接口 | 硬编码内容 |
|---|---|---|
| 530 | `/overview/profit-waterfall` | `e.report_month = DATE '2026-04-01'` |
| 568 | `/overview/store-profit-ranking` | `e.report_month = DATE '2026-04-01'` |
| 589 | `/overview/profit-opportunity` | `e.report_month = DATE '2026-04-01'` |
| 661 | `/overview/profit-opportunity` | `report_month = DATE '2026-04-01'`（platform CTE） |
| 668 | `/overview/profit-opportunity` | `e.report_month = DATE '2026-04-01'`（platform_stores CTE） |
| 890 | `/bank/report` | `month = DATE '2026-04-01'`（overview） |
| 891 | `/bank/report` | `month = DATE '2026-04-01'`（daily） |
| 898 | `/bank/report` | `e.report_month = DATE '2026-04-01'`（waterfall） |
| 909 | `/bank/report` | `business_date >= DATE '2026-04-01' AND < DATE '2026-05-01'`（channel） |
| 117 | `/stores/:code` | `mv_store_action_priority_deep_april`（表名硬编码） |
| 176 | `/cost/comparison` | `mv_store_theoretical_actual_cost_april`（表名硬编码） |
| 185 | `/cost/category-benchmark` | `v_store_category_cost_benchmark_april`（表名硬编码） |
| 194 | `/cost/inventory` | `v_store_inventory_efficiency_april`（表名硬编码） |
| 230 | `/sku/abc` | `v_dish_sku_abc_april`（表名硬编码） |
| 248 | `/sku/attach` | `dish_pair_summary_april`（表名硬编码） |
| 364 | `/data-quality` | `v_inventory_cost_classified_april`（表名硬编码） |
| 406 | `/stores/:code/cost` | `mv_store_theoretical_actual_cost_april`（表名硬编码） |
| 412 | `/stores/:code/cost` | `v_inventory_cost_classified_april`（表名硬编码） |
| 420 | `/stores/:code/cost` | `v_inventory_cost_classified_april`（表名硬编码） |
| 474 | `/site-selection/profile` | `mv_store_site_profile_april`（表名硬编码） |
| 482 | `/site-selection/segment-benchmark` | `mv_site_segment_benchmark_april`（表名硬编码） |
| 490 | `/site-selection/replication` | `mv_store_site_replication_score_april`（表名硬编码） |
| 498 | `/site-selection/overlap-risk` | `mv_store_location_overlap_risk_april`（表名硬编码） |
| 506 | `/site-selection/district-benchmark` | `mv_district_site_benchmark_april`（表名硬编码） |
| 676 | `/overview/profit-opportunity` | `v_dish_sku_abc_april`（表名硬编码，sku CTE） |
| 680 | `/overview/profit-opportunity` | `v_dish_sku_abc_april`（表名硬编码，sku_samples CTE） |

#### 2.3 `server/src/routes/cost-analysis.ts`（4处）

| 行号 | 接口 | 硬编码内容 |
|---|---|---|
| 736 | `/cost-analysis/store-overview` | `mv_store_theoretical_actual_cost_april`（表名硬编码） |
| 753 | `/cost-analysis/store-map` | `mv_store_theoretical_actual_cost_april`（表名硬编码） |
| 780 | `/cost-analysis/store-ranking` | `mv_store_theoretical_actual_cost_april`（表名硬编码） |
| 791 | `/cost-analysis/store-ranking` | `mv_store_theoretical_actual_cost_april`（表名硬编码） |

#### 2.4 `server/src/routes/situational-awareness.ts`（2处）

| 行号 | 接口 | 硬编码内容 |
|---|---|---|
| 23 | `/situational-awareness/health-score` | `mv_store_theoretical_actual_cost_april`（表名硬编码） |
| 296 | `/situational-awareness/correlation` | `mv_store_theoretical_actual_cost_april`（表名硬编码） |

#### 2.5 `server/src/routes/tasks.ts`（2处）

| 行号 | 接口 | 硬编码内容 |
|---|---|---|
| 622 | `/tasks/monthly-review/sku-governance` | `v_dish_sku_abc_april`（表名硬编码） |
| 629 | `/tasks/monthly-review/sku-governance` | `v_dish_sku_abc_april`（表名硬编码） |

### 3. 已支持月度参数的接口（少数，可作参考模式）

| 接口 | 文件 | 参数化方式 |
|---|---|---|
| `/overview` | `data.ts:9-17` | `parseMonth(req)` → `mv_overview_monthly WHERE month = $1` |
| `/overview/daily` | `data.ts:19-27` | `parseMonth(req)` → `mv_overview_daily WHERE month = $1` |
| `/revenue/channel` | `data.ts:789-813` | `parseMonth(req)` → `business_date >= $1 AND < $1 + INTERVAL '1 month'` |
| `/revenue/meal-period` | `data.ts:816-834` | `parseMonth(req)` → 同上 |
| `/revenue/store-ranking` | `data.ts:837-860` | `parseMonth(req)` → 同上 |
| `/revenue/daily-summary` | `data.ts:863-884` | `parseMonth(req)` → 同上 |

### 4. 底层数据结构

| 数据对象 | 类型 | 日期字段 | 支持多月 | 说明 |
|---|---|---|:---:|---|
| `bill_fact` | 物化视图 | `closed_at`（timestamptz） | ✅ | 账单事实表，通过 `closed_at::date` 派生 `business_date` |
| `v_store_daily` | 视图 | `business_date`（派生） | ✅ | 从 `bill_fact.closed_at::date` 派生 |
| `v_channel_daily` | 视图 | `business_date` | ✅ | 渠道日度数据 |
| `mv_overview_monthly` | 物化视图 | `month` | ✅ | 月度总览，已有 `month` 字段 |
| `mv_overview_daily` | 物化视图 | `month` + `business_date` | ✅ | 日度总览 |
| `mv_store_operating_expense_monthly` | 物化视图 | `report_month` | ✅ | 门店费用月度，已有 `report_month` 字段 |
| `mv_store_risk_rating` | 物化视图 | 无显式月份 | ❌ | 门店风险评级，当前只反映4月 |
| `v_operating_expense_account_monthly` | 视图 | `report_month` | ✅ | 费用科目月度 |
| 32个 `_april` 对象 | 混合 | 硬编码4月 | ❌ | 需改造（9物化视图 + 17普通视图 + 6基表） |

### 5. 数据导入脚本硬编码

| 文件 | 硬编码内容 |
|---|---|
| `db/import_salary_attendance.py:57` | `report_month = '2026-04-01'` |
| `db/import_salary_attendance.py:159` | `report_month = '2026-04-01'` |
| `sql/etl_fact_inventory.sql:32` | `WHERE i.report_month = DATE '2026-04-01'` |
| `db/ontology_standard.sql:758-772` | 15处 `'2026-04-01'::date` 作为指标 `effective_date`（元数据，非查询过滤器） |

### 6. 前端硬编码月份参数（10处）

> **核实方法：** `grep -rn "2026-0[3-5]" client/src/pages/*.tsx` 逐行统计。

| 文件 | 行号 | 硬编码内容 |
|---|---|---|
| `BomPenetrationPage.tsx` | 23 | `useState('2026-04')` |
| `CentralKitchenPage.tsx` | 25 | `useState('2026-04')` |
| `DistributionReconciliationPage.tsx` | 28 | `useState('2026-04')` |
| `MonthlyReviewPage.tsx` | 27 | `useState('2026-05')` |
| `ProductionPlanPage.tsx` | 26 | `useState('2026-04')` |
| `RegionalPage.tsx` | 32 | `month: '2026-05'`（API调用参数） |
| `StoreDetailPage.tsx` | 45 | `month: '2026-05'`（API调用参数） |
| `StorePage.tsx` | 33 | `month: '2026-05'`（API调用参数） |
| `StorePage.tsx` | 38 | `month: '2026-04'`（API调用参数） |
| `TasksPage.tsx` | 14 | `useState('2026-05')` |

> **注意：** 这些前端硬编码月份需要替换为全局 `MonthPicker` 组件的选择值，通过 React Query 的 `queryKey` 联动。

### 7. `parseMonth` 函数现状

```typescript
// server/src/middleware/error.ts:33-36
export function parseMonth(req: Request): string {
  const month = (req.query.month as string) || '2026-04'  // 默认4月
  return month.length === 7 ? `${month}-01` : month
}
```

已有参数解析基础设施，但默认值硬编码为4月，且大部分接口未使用。

---

## 三、改造方案

### 第1层：数据库 — 去硬编码，参数化视图

#### 方案选择：参数化函数 + 通用视图

将32个 `_april` 视图/表改为接受 `p_month DATE` 参数的函数，同时创建同名通用视图供过渡期使用。

#### 1.1 核心利润链改造（第1批，9个对象）

**示例：`mv_store_theoretical_actual_cost_april` → 函数**

```sql
-- 创建参数化函数
CREATE OR REPLACE FUNCTION analytics.fn_store_cost_comparison(
  p_month DATE DEFAULT '2026-04-01'
) RETURNS TABLE (
  store_code TEXT,
  store_name TEXT,
  theoretical_cost NUMERIC,
  actual_food_cost NUMERIC,
  food_cost_variance NUMERIC,
  theoretical_cost_rate_pct NUMERIC,
  actual_food_cost_rate_pct NUMERIC,
  variance_to_theoretical_pct NUMERIC,
  comparison_status TEXT,
  variance_level TEXT,
  negative_item_lines INT,
  estimated_inventory_days NUMERIC,
  ending_inventory_amount NUMERIC,
  abnormal_item_lines INT
) AS $$
  SELECT ...
  FROM analytics.v_inventory_cost_classified(p_month)  -- 下游视图也需参数化
  WHERE report_month = p_month
  GROUP BY store_code, store_name
$$ LANGUAGE SQL STABLE;

-- 创建通用视图（过渡期兼容）
CREATE OR REPLACE VIEW analytics.v_store_cost_comparison AS
  SELECT * FROM analytics.fn_store_cost_comparison('2026-04-01');
```

**需改造的第1批对象：**

| 原始对象名 | 新函数名 | 新通用视图名 | 依赖链 |
|---|---|---|---|
| `mv_store_theoretical_actual_cost_april` | `fn_store_cost_comparison(p_month)` | `v_store_cost_comparison` | 依赖 `v_inventory_cost_classified` |
| `v_inventory_cost_classified_april` | `fn_inventory_cost_classified(p_month)` | `v_inventory_cost_classified` | 依赖 `v_inventory_finance_category` |
| `v_inventory_finance_category_april` | `fn_inventory_finance_category(p_month)` | `v_inventory_finance_category` | 依赖 `inventory_cost_records` |
| `v_inventory_abnormal_items_april` | `fn_inventory_abnormal_items(p_month)` | `v_inventory_abnormal_items` | 依赖 `inventory_cost_records` |
| `v_store_action_priority_deep_april` | `fn_store_action_priority(p_month)` | `v_store_action_priority` | 依赖 `mv_store_risk_rating` |
| `mv_store_action_priority_deep_april` | 与 `v_` 版本统一为 `fn_store_action_priority` | 同上 | 物化视图，与v_版本共享函数 |
| `v_store_area_efficiency_april` | `fn_store_area_efficiency(p_month)` | `v_store_area_efficiency` | 依赖 `mv_store_operating_expense_monthly` |
| `v_store_deep_diagnosis_april` | `fn_store_deep_diagnosis(p_month)` | `v_store_deep_diagnosis` | 依赖多个视图 |
| `v_c_sku_governance_april` | `fn_sku_governance(p_month)` | `v_sku_governance` | 依赖 `v_dish_sku_abc` |

#### 1.2 SKU/菜品分析改造（第2批，9个对象）

| 原始对象名 | 新函数名 | 新通用视图名 |
|---|---|---|
| `v_dish_sku_abc_april` | `fn_dish_sku_abc(p_month)` | `v_dish_sku_abc` |
| `dish_store_summary_april` | `fn_dish_store_summary(p_month)` | `v_dish_store_summary` |
| `dish_basket_april` | `fn_dish_basket(p_month)` | `v_dish_basket` |
| `dish_category_summary_april` | `fn_dish_category_summary(p_month)` | `v_dish_category_summary` |
| `dish_member_sku_april` | `fn_dish_member_sku(p_month)` | `v_dish_member_sku` |
| `dish_pair_summary_april` | `fn_dish_pair_summary(p_month)` | `v_dish_pair_summary` |
| `dish_store_sku_april` | `fn_dish_store_sku(p_month)` | `v_dish_store_sku` |
| `dish_sales_april` | `fn_dish_sales(p_month)` | `v_dish_sales` |
| `dish_sku_summary_april` | `fn_dish_sku_summary(p_month)` | `v_dish_sku_summary` |

#### 1.3 选址/空间分析改造（第3批，14个对象，含v_/mv_双版本）

| 原始对象名 | 新函数名 | 新通用视图名 |
|---|---|---|
| `v_store_site_profile_april` | `fn_store_site_profile(p_month)` | `v_store_site_profile` |
| `mv_store_site_profile_april` | 物化视图按月刷新 | `v_store_site_profile` |
| `v_store_site_replication_score_april` | `fn_store_site_replication(p_month)` | `v_store_site_replication` |
| `mv_store_site_replication_score_april` | 物化视图按月刷新 | 同上 |
| `v_store_location_overlap_risk_april` | `fn_store_overlap_risk(p_month)` | `v_store_overlap_risk` |
| `mv_store_location_overlap_risk_april` | 物化视图按月刷新 | 同上 |
| `v_store_nearest_neighbor_april` | `fn_store_nearest_neighbor(p_month)` | `v_store_nearest_neighbor` |
| `v_store_spatial_pairs_april` | `fn_store_spatial_pairs(p_month)` | `v_store_spatial_pairs` |
| `v_dish_member_repeat_april` | `fn_dish_member_repeat(p_month)` | `v_dish_member_repeat` |
| `v_store_theoretical_actual_cost_april` | 与 `mv_` 版本统一为 `fn_store_cost_comparison` | 同上 |
| `v_district_site_benchmark_april` | `fn_district_site_benchmark(p_month)` | `v_district_site_benchmark` |
| `v_site_segment_benchmark_april` | `fn_site_segment_benchmark(p_month)` | `v_site_segment_benchmark` |
| `mv_site_segment_benchmark_april` | 与 `v_` 版本统一 | 同上 |
| `mv_district_site_benchmark_april` | 与 `v_` 版本统一为 `fn_district_site_benchmark` | 同上 |

#### 1.4 `mv_store_risk_rating` 改造

当前 `mv_store_risk_rating` 无月份字段，只反映4月数据。需改为按月生成：

```sql
-- 方案：改为参数化函数
CREATE OR REPLACE FUNCTION analytics.fn_store_risk_rating(
  p_month DATE DEFAULT '2026-04-01'
) RETURNS TABLE (...) AS $$
  SELECT s.store_code, s.store_name, ...
  FROM analytics.v_store_daily s
  WHERE s.business_date >= p_month AND s.business_date < (p_month + INTERVAL '1 month')
  GROUP BY s.store_code, s.store_name
$$ LANGUAGE SQL STABLE;

-- 保留物化视图用于4月（兼容期）
-- 新建通用视图
CREATE OR REPLACE VIEW analytics.v_store_risk_rating AS
  SELECT * FROM analytics.fn_store_risk_rating('2026-04-01');
```

### 第2层：后端 API — 统一月度参数

#### 2.1 改造 `parseMonth` 函数

```typescript
// server/src/middleware/error.ts
export function parseMonth(req: Request): string {
  const month = (req.query.month as string) || '2026-04'
  return month.length === 7 ? `${month}-01` : month
}

// 新增：解析日期范围
export interface DateRange {
  start: string        // ISO date 'YYYY-MM-DD'
  end: string          // ISO date 'YYYY-MM-DD'（半开区间，不含end）
  mode: 'month' | 'quarter' | 'halfyear' | 'year' | 'custom'
  label: string        // 显示用标签
}

export function parseDateRange(req: Request): DateRange {
  const mode = (req.query.range_mode as string) || 'month'
  const month = parseMonth(req)
  const startDate = new Date(month)
  
  const addMonths = (d: Date, n: number): string => {
    const r = new Date(d)
    r.setMonth(r.getMonth() + n)
    return r.toISOString().slice(0, 10)
  }
  
  switch (mode) {
    case 'quarter':
      return { start: month, end: addMonths(startDate, 3), mode, label: '季度' }
    case 'halfyear':
      return { start: month, end: addMonths(startDate, 6), mode, label: '半年' }
    case 'year':
      return { start: month, end: addMonths(startDate, 12), mode, label: '全年' }
    case 'custom': {
      const start = (req.query.start_date as string) || month
      const end = (req.query.end_date as string) || addMonths(new Date(start), 1)
      return { start, end, mode, label: '自定义' }
    }
    default:
      return { start: month, end: addMonths(startDate, 1), mode, label: '月度' }
  }
}

// 新增：计算同比月份
export function prevYearMonth(month: string): string {
  const d = new Date(month)
  d.setFullYear(d.getFullYear() - 1)
  return d.toISOString().slice(0, 10)
}

// 新增：计算环比月份
export function prevMonth(month: string): string {
  const d = new Date(month)
  d.setMonth(d.getMonth() - 1)
  return d.toISOString().slice(0, 10)
}
```

#### 2.2 改造现有接口（去硬编码 `DATE '2026-04-01'`）

**模式：将所有 `DATE '2026-04-01'` 替换为 `$N::date` 参数**

```typescript
// Before
router.get('/overview/profit-waterfall', async (req: AuthRequest, res) => {
  const result = await query(`
    ...WHERE e.report_month = DATE '2026-04-01'
  `)
})

// After
router.get('/overview/profit-waterfall', async (req: AuthRequest, res) => {
  const month = parseMonth(req)
  const result = await query(`
    ...WHERE e.report_month = $1::date
  `, [month])
})
```

**改造清单（45处）：**

| 文件 | 接口 | 改造方式 |
|---|---|---|
| `store-expense.ts:36` | `/store-expense/overview` | `e.report_month = $1::date` |
| `store-expense.ts:88` | `/store-expense/expense-structure` | `report_month = $1::date` |
| `store-expense.ts:107` | `/store-expense/store-ranking` | `WHERE report_month = $1::date` |
| `store-expense.ts:161` | `/store-expense/store-contribution` | `WHERE report_month = $1::date` |
| `store-expense.ts:211` | `/store-expense/rent-risk` | `WHERE report_month = $1::date` |
| `store-expense.ts:276` | `/store-expense/delivery-commission` | `WHERE report_month = $1::date` |
| `store-expense.ts:330` | `/store-expense/efficiency` | `WHERE report_month = $1::date` |
| `store-expense.ts:386` | `/store-expense/fixed-variable` | `WHERE report_month = $1::date` |
| `store-expense.ts:436` | `/store-expense/break-even` | `WHERE report_month = $1::date` |
| `store-expense.ts:499` | `/store-expense/loss-diagnosis` | `WHERE report_month = $1::date` |
| `store-expense.ts:725` | `/store-expense/store-evaluation` | `WHERE report_month = $1::date` |
| `data.ts:530` | `/overview/profit-waterfall` | `e.report_month = $1::date` |
| `data.ts:568` | `/overview/store-profit-ranking` | `e.report_month = $1::date` |
| `data.ts:589` | `/overview/profit-opportunity` | `e.report_month = $1::date`（3处 DATE） + 2处 `v_dish_sku_abc_april` 表名 |
| `data.ts:890-909` | `/bank/report` | 4处 `DATE '2026-04-01'` + 1处 `DATE '2026-05-01'` → `$N::date` |
| `data.ts:117` | `/stores/:code` | 表名 → `fn_store_action_priority($1)` |
| `data.ts:176` | `/cost/comparison` | 表名 → `fn_store_cost_comparison($1)` |
| `data.ts:185` | `/cost/category-benchmark` | 表名 → `fn_store_category_cost_benchmark($1)` |
| `data.ts:194` | `/cost/inventory` | 表名 → `fn_store_inventory_efficiency($1)` |
| `data.ts:230` | `/sku/abc` | 表名 → `fn_dish_sku_abc($1)` |
| `data.ts:248` | `/sku/attach` | 表名 → `fn_dish_pair_summary($1)` |
| `data.ts:364` | `/data-quality` | 表名 → `fn_inventory_cost_classified($1)` |
| `data.ts:406-420` | `/stores/:code/cost` | 表名 → `fn_store_cost_comparison($1)` + `fn_inventory_cost_classified($1)`（3处） |
| `data.ts:474-506` | `/site-selection/*` | 5个表名 → 对应函数（含 `district-benchmark`） |
| `cost-analysis.ts:736-791` | `/cost-analysis/store-*` | 4处表名 → `fn_store_cost_comparison($1)` |
| `situational-awareness.ts:23,296` | `/situational-awareness/health-score`, `/correlation` | 2处表名 → `fn_store_cost_comparison($1)` |
| `tasks.ts:622,629` | `/tasks/monthly-review/sku-governance` | 2处表名 → `fn_dish_sku_abc($1)` |

#### 2.3 新增同比/环比接口

```typescript
// 同比：当前月 vs 去年同月
router.get('/overview/yoy', async (req: AuthRequest, res) => {
  try {
    const month = parseMonth(req)
    const prevYear = prevYearMonth(month)
    const [current, previous] = await Promise.all([
      query(`SELECT bill_count, received, avg_bill_value, discount_rate_pct, theoretical_margin_pct, member_bills, member_share_pct FROM analytics.mv_overview_monthly WHERE month = $1::date`, [month]),
      query(`SELECT bill_count, received, avg_bill_value, discount_rate_pct, theoretical_margin_pct, member_bills, member_share_pct FROM analytics.mv_overview_monthly WHERE month = $1::date`, [prevYear])
    ])
    const c = current.rows[0] as any
    const p = previous.rows[0] as any
    if (!c) { sendSuccess(res, null); return }
    const calcChange = (cur: number, prev: number | null) => {
      if (prev === null || prev === 0) return null
      return round(((cur - prev) / Math.abs(prev)) * 100, 2)
    }
    sendSuccess(res, {
      current: c,
      previous: p,
      yoy: p ? {
        received_change_pct: calcChange(parseFloat(c.received), parseFloat(p.received)),
        bill_count_change_pct: calcChange(parseInt(c.bill_count), parseInt(p.bill_count)),
        avg_bill_value_change_pct: calcChange(parseFloat(c.avg_bill_value), parseFloat(p.avg_bill_value)),
        discount_rate_change: p ? round(parseFloat(c.discount_rate_pct) - parseFloat(p.discount_rate_pct), 2) : null,
      } : null
    })
  } catch (err: any) { sendError(res, err.message) }
})

// 环比：当前月 vs 上月
router.get('/overview/mom', async (req: AuthRequest, res) => {
  try {
    const month = parseMonth(req)
    const prevMo = prevMonth(month)
    // 同上结构，prevYear → prevMo
  } catch (err: any) { sendError(res, err.message) }
})

// 月度趋势
router.get('/overview/trend', async (req: AuthRequest, res) => {
  try {
    const endMonth = parseMonth(req)
    const months = parseInt(req.query.months as string) || 12
    const startDate = new Date(endMonth)
    startDate.setMonth(startDate.getMonth() - months + 1)
    const startMonth = startDate.toISOString().slice(0, 10)
    
    const result = await query(`
      SELECT month, bill_count, received, avg_bill_value, discount_rate_pct, theoretical_margin_pct, member_bills, member_share_pct
      FROM analytics.mv_overview_monthly
      WHERE month >= $1::date AND month <= $2::date
      ORDER BY month
    `, [startMonth, endMonth])
    sendSuccess(res, result.rows)
  } catch (err: any) { sendError(res, err.message) }
})

// 利润趋势（多月瀑布汇总）
router.get('/overview/profit-trend', async (req: AuthRequest, res) => {
  try {
    const endMonth = parseMonth(req)
    const months = parseInt(req.query.months as string) || 6
    const startDate = new Date(endMonth)
    startDate.setMonth(startDate.getMonth() - months + 1)
    const startMonth = startDate.toISOString().slice(0, 10)
    
    // 逐月查询利润瀑布数据
    const result = await query(`
      WITH monthly AS (
        SELECT e.report_month,
          round(sum(r.received)::numeric, 2) AS received,
          round(sum(e.actual_food_cost)::numeric, 2) AS food_cost,
          round(sum(e.wage_expense)::numeric, 2) AS wage,
          round(sum(e.rent_expense)::numeric, 2) AS rent,
          round(sum(e.utility_expense)::numeric, 2) AS utility,
          round(sum(e.operating_expense)::numeric, 2) AS total_expense,
          round(sum(r.received) - sum(e.actual_food_cost) - sum(e.operating_expense), 2) AS store_contribution
        FROM analytics.mv_store_risk_rating r
        JOIN analytics.mv_store_operating_expense_monthly e 
          ON r.store_code = e.sales_store_code
        WHERE e.report_month >= $1::date AND e.report_month <= $2::date
          AND e.operating_expense IS NOT NULL AND r.received > 0
        GROUP BY e.report_month
        ORDER BY e.report_month
      )
      SELECT *,
        round(store_contribution / nullif(received, 0) * 100, 2) AS contribution_margin_pct
      FROM monthly
    `, [startMonth, endMonth])
    sendSuccess(res, result.rows)
  } catch (err: any) { sendError(res, err.message) }
})

// 时间段汇总
router.get('/overview/period', async (req: AuthRequest, res) => {
  try {
    const { start, end, mode, label } = parseDateRange(req)
    const result = await query(`
      SELECT
        sum(bill_count)::bigint AS bill_count,
        round(sum(received)::numeric, 2) AS received,
        round(sum(discounts)::numeric, 2) AS discounts,
        round(sum(discounts) / nullif(sum(received) + sum(discounts), 0) * 100, 2) AS discount_rate_pct,
        round(sum(received) / nullif(sum(bill_count), 0), 2) AS avg_bill_value,
        round(sum(guests)::numeric, 0) AS guests
      FROM analytics.v_store_daily
      WHERE business_date >= $1::date AND business_date < $2::date
    `, [start, end])
    sendSuccess(res, { ...result.rows[0], range_mode: mode, range_label: label, start_date: start, end_date: end })
  } catch (err: any) { sendError(res, err.message) }
})
```

#### 2.4 利润瀑布/利润机会池支持时间段汇总

```typescript
// 利润瀑布 — 支持月度和时间段两种模式
router.get('/overview/profit-waterfall', async (req: AuthRequest, res) => {
  try {
    const rangeMode = (req.query.range_mode as string) || 'month'
    if (rangeMode === 'month') {
      // 原有逻辑，参数化
      const month = parseMonth(req)
      const result = await query(`
        WITH full_scope AS (
          SELECT r.received, e.actual_food_cost AS food_cost, ...
          FROM analytics.fn_store_risk_rating($1::date) r
          LEFT JOIN analytics.mv_store_operating_expense_monthly e 
            ON r.store_code = e.sales_store_code AND e.report_month = $1::date
          WHERE r.received IS NOT NULL AND e.operating_expense IS NOT NULL
        )
        SELECT round(sum(received)::numeric,2) AS received, ...
        FROM full_scope
      `, [month])
      sendSuccess(res, result.rows[0])
    } else {
      // 时间段汇总：多月费用累加
      const { start, end } = parseDateRange(req)
      const result = await query(`
        WITH full_scope AS (
          SELECT e.report_month, r.received, e.actual_food_cost AS food_cost, ...
          FROM analytics.v_store_daily r
          JOIN analytics.mv_store_operating_expense_monthly e 
            ON r.store_code = e.sales_store_code
          WHERE e.report_month >= $1::date AND e.report_month < $2::date
            AND e.operating_expense IS NOT NULL
          GROUP BY e.report_month, r.store_code
        )
        SELECT round(sum(received)::numeric,2) AS received, ...
        FROM full_scope
      `, [start, end])
      sendSuccess(res, result.rows[0])
    }
  } catch (err: any) { sendError(res, err.message) }
})
```

### 第3层：前端 — 月份选择器 + 时间范围切换

#### 3.1 全局月份选择器组件

```tsx
// client/src/components/MonthPicker.tsx
import { useState, useMemo } from 'react'
import { ChevronLeft, ChevronRight, Calendar } from 'lucide-react'

interface MonthPickerProps {
  value: string           // 'YYYY-MM' 格式
  onChange: (month: string) => void
  minMonth?: string       // 数据最早月份 'YYYY-MM'
  maxMonth?: string       // 数据最晚月份 'YYYY-MM'
}

export function MonthPicker({ value, onChange, minMonth = '2026-04', maxMonth }: MonthPickerProps) {
  const [open, setOpen] = useState(false)
  const [year, setYear] = useState(parseInt(value.slice(0, 4)))
  
  const max = maxMonth || new Date().toISOString().slice(0, 7)
  const months = useMemo(() => {
    const arr: { label: string; value: string; disabled: boolean }[] = []
    for (let m = 1; m <= 12; m++) {
      const v = `${year}-${String(m).padStart(2, '0')}`
      arr.push({
        label: `${m}月`,
        value: v,
        disabled: v < minMonth || v > max
      })
    }
    return arr
  }, [year, minMonth, max])
  
  return (
    <div className="relative">
      <button
        onClick={() => setOpen(!open)}
        className="flex items-center gap-2 rounded-lg border px-3 py-1.5 text-sm"
      >
        <Calendar className="h-4 w-4" />
        <span>{value.slice(0, 4)}年{parseInt(value.slice(5, 7))}月</span>
        <ChevronRight className="h-3 w-3" />
      </button>
      {open && (
        <div className="absolute z-50 mt-1 rounded-lg border bg-background p-3 shadow-lg">
          <div className="mb-2 flex items-center justify-between">
            <button onClick={() => setYear(year - 1)}><ChevronLeft className="h-4 w-4" /></button>
            <span className="font-medium">{year}年</span>
            <button onClick={() => setYear(year + 1)}><ChevronRight className="h-4 w-4" /></button>
          </div>
          <div className="grid grid-cols-4 gap-1">
            {months.map(m => (
              <button
                key={m.value}
                disabled={m.disabled}
                onClick={() => { onChange(m.value); setOpen(false) }}
                className={`rounded px-2 py-1 text-sm ${
                  m.value === value ? 'bg-primary text-primary-foreground' :
                  m.disabled ? 'text-muted-foreground/50 cursor-not-allowed' :
                  'hover:bg-accent'
                }`}
              >
                {m.label}
              </button>
            ))}
          </div>
        </div>
      )}
    </div>
  )
}
```

#### 3.2 时间范围切换器

```tsx
// client/src/components/RangeModeSwitch.tsx
type RangeMode = 'month' | 'quarter' | 'halfyear' | 'year' | 'custom'

interface RangeModeSwitchProps {
  value: RangeMode
  onChange: (mode: RangeMode) => void
}

export function RangeModeSwitch({ value, onChange }: RangeModeSwitchProps) {
  const modes: { key: RangeMode; label: string }[] = [
    { key: 'month', label: '月度' },
    { key: 'quarter', label: '季度' },
    { key: 'halfyear', label: '半年' },
    { key: 'year', label: '全年' },
  ]
  return (
    <div className="flex rounded-lg border p-0.5">
      {modes.map(m => (
        <button
          key={m.key}
          onClick={() => onChange(m.key)}
          className={`rounded px-3 py-1 text-xs font-medium ${
            value === m.key ? 'bg-primary text-primary-foreground' : 'text-muted-foreground'
          }`}
        >
          {m.label}
        </button>
      ))}
    </div>
  )
}
```

#### 3.3 同比/环比展示组件

```tsx
// client/src/components/ComparisonBadge.tsx
interface ComparisonBadgeProps {
  changePct: number | null
  label: string          // '同比' or '环比'
  invertColors?: boolean // true: 下降为好（如成本率）
}

export function ComparisonBadge({ changePct, label, invertColors = false }: ComparisonBadgeProps) {
  if (changePct === null) return <span className="text-xs text-muted-foreground">{label}: —</span>
  const isUp = changePct > 0
  const isGood = invertColors ? !isUp : isUp
  return (
    <span className={`text-xs ${isGood ? 'text-green-600' : 'text-red-600'}`}>
      {label} {isUp ? '↑' : '↓'} {Math.abs(changePct).toFixed(1)}%
    </span>
  )
}
```

#### 3.4 指标卡集成同比环比

```tsx
// 在 MetricCard 中增加 yoy/mom 展示
interface MetricCardProps {
  title: string
  value: number | string
  ...
  yoyChange?: number | null    // 同比变化率
  momChange?: number | null    // 环比变化率
  invertColors?: boolean
}

// 渲染时在值下方显示
{yoyChange !== undefined && <ComparisonBadge changePct={yoyChange} label="同比" invertColors={invertColors} />}
{momChange !== undefined && <ComparisonBadge changePct={momChange} label="环比" invertColors={invertColors} />}
```

#### 3.5 趋势图组件

```tsx
// client/src/components/MonthlyTrendChart.tsx
import { LineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer, Legend } from 'recharts'

interface MonthlyTrendChartProps {
  data: Array<{ month: string; received: number; store_contribution: number; contribution_margin_pct: number }>
}

export function MonthlyTrendChart({ data }: MonthlyTrendChartProps) {
  return (
    <ResponsiveContainer width="100%" height={300}>
      <LineChart data={data}>
        <CartesianGrid strokeDasharray="3 3" />
        <XAxis dataKey="month" tickFormatter={m => m.slice(5, 7) + '月'} />
        <YAxis yAxisId="left" />
        <YAxis yAxisId="right" orientation="right" unit="%" />
        <Tooltip labelFormatter={m => m} />
        <Legend />
        <Line yAxisId="left" dataKey="received" name="实收" stroke="#3b82f6" />
        <Line yAxisId="left" dataKey="store_contribution" name="门店贡献利润" stroke="#22c55e" />
        <Line yAxisId="right" dataKey="contribution_margin_pct" name="贡献率" stroke="#a855f7" unit="%" />
      </LineChart>
    </ResponsiveContainer>
  )
}
```

#### 3.6 React Query 参数联动

```tsx
// 在每个页面中，将 month 和 rangeMode 加入 queryKey
const { data } = useQuery({
  queryKey: ['overview', month, rangeMode],
  queryFn: () => api.get('/overview', { params: { month, range_mode: rangeMode } }),
  enabled: !!month,
})

// 利润瀑布
const { data: waterfall } = useQuery({
  queryKey: ['profit-waterfall', month, rangeMode],
  queryFn: () => api.get('/overview/profit-waterfall', { params: { month, range_mode: rangeMode } }),
})

// 同比环比
const { data: yoy } = useQuery({
  queryKey: ['overview-yoy', month],
  queryFn: () => api.get('/overview/yoy', { params: { month } }),
})

// 趋势
const { data: trend } = useQuery({
  queryKey: ['overview-trend', month, trendMonths],
  queryFn: () => api.get('/overview/trend', { params: { month, months: trendMonths } }),
})
```

#### 3.7 页面布局调整

在以下页面顶部统一添加：

| 页面 | 调用的硬编码API |
|---|---|
| BossPage | `/overview/profit-waterfall`, `/overview/profit-opportunity`, `/store-expense/overview`, `/cost/comparison` |
| RevenuePage | `/revenue/*`（已参数化，需加选择器统一体验） |
| CostPage | `/cost/comparison`（`mv_store_theoretical_actual_cost_april`） |
| StoreExpensePage | `/store-expense/*`（11处 `DATE '2026-04-01'`，含 `/overview`, `/expense-structure`, `/store-ranking`, `/store-contribution`, `/rent-risk`, `/delivery-commission`, `/efficiency`, `/fixed-variable`, `/break-even`, `/loss-diagnosis`, `/store-evaluation`） |
| DataQualityPage | `/data-quality`（`v_inventory_cost_classified_april`） |
| CostAnalysisPage | `/cost-analysis/store-overview`, `/cost-analysis/store-ranking`（`mv_store_theoretical_actual_cost_april`） |
| SiteSelectionPage | `/site-selection/*`（5个 `_april` 表名） |
| SituationalAwarenessPage | `/situational-awareness/health-score`, `/correlation`（`mv_store_theoretical_actual_cost_april`） |
| BankPage | `/bank/report`（5处 `DATE '2026-04-01'`） |
| DashboardPage | `/store-expense/overview`（`DATE '2026-04-01'`） |
| SKUPage | `/sku/abc`（`v_dish_sku_abc_april`） |
| StoreDetailPage | `/stores/:code`, `/stores/:code/cost`（多个 `_april` 表名）+ 前端硬编码 `month: '2026-05'` |
| StorePage | `/stores/:code/daily`（前端硬编码 `month: '2026-04'`）+ `/tasks`（前端硬编码 `month: '2026-05'`） |
| MonthlyReviewPage | `/tasks/monthly-review/sku-governance`（`v_dish_sku_abc_april`）+ 前端硬编码 `month: '2026-05'` |
| RegionalPage | `/stores/risk`（`mv_store_risk_rating` 无月份字段）+ 前端硬编码 `month: '2026-05'` |
| TasksPage | 前端硬编码 `month: '2026-05'` |
| BomPenetrationPage | 前端硬编码 `month: '2026-04'` |
| CentralKitchenPage | 前端硬编码 `month: '2026-04'` |
| DistributionReconciliationPage | 前端硬编码 `month: '2026-04'` |
| ProductionPlanPage | 前端硬编码 `month: '2026-04'` |

```tsx
// 页面顶部控制栏
<div className="flex items-center justify-between">
  <h2 className="text-xl font-bold">总部驾驶舱</h2>
  <div className="flex items-center gap-3">
    <MonthPicker value={month} onChange={setMonth} maxMonth={maxMonth} />
    <RangeModeSwitch value={rangeMode} onChange={setRangeMode} />
  </div>
</div>
```

### 第4层：数据管道 — 多月数据导入

#### 4.1 数据导入脚本参数化

```python
# db/import_salary_attendance.py
# Before
report_month = '2026-04-01'

# After
import sys
report_month = sys.argv[1] if len(sys.argv) > 1 else '2026-04-01'
# 或从文件名自动提取月份
```

```sql
-- sql/etl_fact_inventory.sql
-- Before
WHERE i.report_month = DATE '2026-04-01'

-- After（使用 psql 变量）
WHERE i.report_month = :'report_month'::date
-- 执行：psql -v report_month='2026-04-01' -f etl_fact_inventory.sql
```

#### 4.2 物化视图按月刷新策略

```sql
-- 刷新指定月份的物化视图
-- 方案1：物化视图不按月分区，REFRESH 全量刷新
REFRESH MATERIALIZED VIEW CONCURRENTLY analytics.mv_store_operating_expense_monthly;

-- 方案2（推荐）：将物化视图改为按月分区表
-- 每月导入后只刷新该月分区
```

#### 4.3 可用月份查询接口

```typescript
// 新增：返回系统中有数据的月份列表
router.get('/meta/available-months', async (req: AuthRequest, res) => {
  try {
    const result = await query(`
      SELECT DISTINCT report_month AS month
      FROM analytics.mv_store_operating_expense_monthly
      WHERE operating_expense IS NOT NULL
      UNION
      SELECT DISTINCT date_trunc('month', closed_at)::date
      FROM analytics.bill_fact
      WHERE closed_at IS NOT NULL
      ORDER BY month DESC
    `)
    sendSuccess(res, result.rows.map(r => r.month))
  } catch (err: any) { sendError(res, err.message) }
})
```

---

## 四、实施路线图

| 阶段 | 时间 | 内容 | 优先级 | 涉及文件 |
|---|---|---|:---:|---|
| **Phase 1** | 1-2天 | 后端 API 去硬编码 `DATE '2026-04-01'`，统一用 `parseMonth()` | P0 | `store-expense.ts`, `data.ts`, `cost-analysis.ts`, `situational-awareness.ts`, `tasks.ts` |
| **Phase 2** | 2-3天 | 数据库视图去 `_april` 后缀，改为参数化函数（第1批：核心利润链9个） | P0 | 新建 SQL 迁移脚本 |
| **Phase 3** | 1-2天 | 新增同比/环比/趋势/时间段汇总接口 | P1 | `data.ts` 新增接口 |
| **Phase 4** | 2-3天 | 前端月份选择器 + 范围切换 + 同比环比展示 + 趋势图 | P1 | 新建组件 + 改造各页面 |
| **Phase 5** | 1-2天 | 数据库视图参数化（第2批：SKU/菜品9个） | P2 | 新建 SQL 迁移脚本 |
| **Phase 6** | 1-2天 | 数据库视图参数化（第3批：选址/空间14个） | P2 | 新建 SQL 迁移脚本 |
| **Phase 7** | 1天 | 数据导入脚本参数化 + 多月数据导入测试 | P2 | `import_salary_attendance.py`, `etl_fact_inventory.sql` |
| **Phase 8** | 1天 | `mv_store_risk_rating` 改为参数化函数 | P2 | SQL 迁移脚本 + 相关 API |

**总工期：约 10-16 天**

---

## 五、风险评估与注意事项

### 1. 数据覆盖

- 当前只有2026年4月数据，同比/环比功能需要至少2个月数据才能展示
- 需先导入多月数据（至少5月数据）才能验证环比功能
- 同比需要2025年数据，当前完全没有

### 2. 物化视图刷新

- 参数化后物化视图无法直接带参数，需改为函数或按月刷新策略
- `REFRESH MATERIALIZED VIEW` 是全量刷新，数据量大时耗时较长
- 建议采用 `CONCURRENTLY` 选项避免锁表

### 3. 性能

- 时间段汇总查询（如全年）可能较慢，需考虑：
  - 预聚合表：按月汇总后再按时间段聚合
  - 查询缓存：Redis 或前端 React Query 缓存
  - 分页加载：趋势图先加载近6月，可展开查看更多

### 4. 前端兼容

- 改造期间需保持4月数据正常展示
- `MonthPicker` 默认值为 `2026-04`
- API 参数 `month` 默认值保持 `2026-04`，确保旧请求不报错

### 5. API 向后兼容

- 所有改造接口保持向后兼容：不传 `month` 参数时默认返回4月数据
- 新增接口（同比/环比/趋势）为独立路径，不影响现有接口
- 表名替换为函数调用时，保留旧视图作为别名（过渡期）

### 6. 测试策略

- 每个 Phase 完成后需验证：
  - 不传 `month` 参数时，4月数据与改造前完全一致
  - 传 `month=2026-04` 时，结果与不传参数一致
  - 传 `month=2026-05` 时（如有数据），返回5月数据
- 回归测试：所有页面的4月数据展示不受影响

---

## 六、完整性检查清单

### 数据库层

- [ ] 32个 `_april` 视图/表全部改为参数化函数或通用视图（9物化视图 + 17普通视图 + 6基表）
- [ ] `mv_store_risk_rating` 改为支持月份参数
- [ ] 新建 `fn_store_cost_comparison(p_month)` 函数
- [ ] 新建 `fn_inventory_cost_classified(p_month)` 函数
- [ ] 新建 `fn_dish_sku_abc(p_month)` 函数
- [ ] 新建 `fn_store_action_priority(p_month)` 函数
- [ ] 新建 `fn_store_site_profile(p_month)` 函数
- [ ] 新建 `fn_store_overlap_risk(p_month)` 函数
- [ ] 其余19个函数按3批计划完成（总计25个唯一函数，6个已显式列出）
- [ ] 保留旧视图作为别名（过渡期兼容）

### 后端 API 层

- [ ] `parseMonth()` 函数保留默认值 `2026-04`
- [ ] 新增 `parseDateRange()` 函数
- [ ] 新增 `prevYearMonth()` 函数
- [ ] 新增 `prevMonth()` 函数
- [ ] `store-expense.ts` 11处硬编码改为参数化
- [ ] `data.ts` 26处硬编码改为参数化（9处 DATE + 17处 _april表名）
- [ ] `cost-analysis.ts` 4处硬编码改为参数化
- [ ] `situational-awareness.ts` 2处硬编码改为参数化
- [ ] `tasks.ts` 2处硬编码改为参数化
- [ ] 新增 `/overview/yoy` 接口
- [ ] 新增 `/overview/mom` 接口
- [ ] 新增 `/overview/trend` 接口
- [ ] 新增 `/overview/period` 接口
- [ ] 新增 `/overview/profit-trend` 接口
- [ ] 新增 `/meta/available-months` 接口
- [ ] 利润瀑布接口支持 `range_mode` 参数
- [ ] 利润机会池接口支持 `month` 参数
- [ ] 银行报告接口支持 `month` 参数

### 前端层

- [ ] 新建 `MonthPicker` 组件
- [ ] 新建 `RangeModeSwitch` 组件
- [ ] 新建 `ComparisonBadge` 组件
- [ ] 新建 `MonthlyTrendChart` 组件
- [ ] `MetricCard` 增加同比/环比展示
- [ ] BossPage 集成月份选择器和范围切换
- [ ] RevenuePage 集成月份选择器
- [ ] CostPage 集成月份选择器
- [ ] StoreExpensePage 集成月份选择器
- [ ] DataQualityPage 集成月份选择器
- [ ] CostAnalysisPage 集成月份选择器
- [ ] SiteSelectionPage 集成月份选择器
- [ ] SituationalAwarenessPage 集成月份选择器
- [ ] BankPage 集成月份选择器
- [ ] DashboardPage 集成月份选择器
- [ ] SKUPage 集成月份选择器
- [ ] StoreDetailPage 集成月份选择器（含去除前端硬编码 `month: '2026-05'`）
- [ ] StorePage 集成月份选择器（含去除前端硬编码 `month: '2026-04'` 和 `'2026-05'`）
- [ ] MonthlyReviewPage 集成月份选择器（含去除前端硬编码 `month: '2026-05'`）
- [ ] RegionalPage 集成月份选择器（含去除前端硬编码 `month: '2026-05'`）
- [ ] TasksPage 集成月份选择器（含去除前端硬编码 `month: '2026-05'`）
- [ ] BomPenetrationPage 集成月份选择器（含去除前端硬编码 `month: '2026-04'`）
- [ ] CentralKitchenPage 集成月份选择器（含去除前端硬编码 `month: '2026-04'`）
- [ ] DistributionReconciliationPage 集成月份选择器（含去除前端硬编码 `month: '2026-04'`）
- [ ] ProductionPlanPage 集成月份选择器（含去除前端硬编码 `month: '2026-04'`）
- [ ] 所有 `useQuery` 的 `queryKey` 加入 `month` 和 `rangeMode`
- [ ] 趋势图在 BossPage 展示

### 数据管道层

- [ ] `import_salary_attendance.py` 参数化 `report_month`
- [ ] `etl_fact_inventory.sql` 参数化 `report_month`
- [ ] `ontology_standard.sql` 指标 `effective_date` 评估是否需参数化（元数据，优先级低）
- [ ] 其他导入脚本参数化（如有）
- [ ] 物化视图按月刷新策略文档

### 测试验证

- [ ] 不传 `month` 参数时4月数据与改造前一致
- [ ] 传 `month=2026-04` 时结果与不传参数一致
- [ ] 所有页面4月数据展示不受影响（回归测试）
- [ ] TypeScript 编译无错误（`npx tsc --noEmit`）
- [ ] 生产环境部署后验证

---

## 七、预期成果

改造完成后系统将具备：

1. **任意月份分析**：用户可选择任意有数据的月份进行分析，不再局限于4月
2. **时间段汇总**：支持季度/半年/全年/自定义区间的汇总分析
3. **同比环比**：每个核心指标都展示同比和环比变化率，一眼看出趋势
4. **月度趋势图**：可视化展示多月趋势，支持移动平均和同比叠加
5. **数据管道参数化**：导入脚本支持任意月份，不再需要修改代码
6. **向后兼容**：不传参数时默认返回4月数据，现有功能不受影响