# 系统本体结构描述

## 一、数据库架构

- **数据库引擎**: PostgreSQL 15 (Homebrew)
- **数据库名**: bill_query
- **Schema 分布**: `public`（原始数据）、`analytics`（分析层）

---

## 二、原始数据表（public schema）

### 2.1 账单数据

| 表名 | 列数 | 说明 |
|------|------|------|
| `bill_records` | 199 | 账单明细原始表，每行一笔账单，字段以 c001~c199 编码 |
| `bill_columns` | 4 | 账单字段元数据（列号→含义映射） |

**关键字段映射**:
- `c002` = 门店名称，`c003` = 门店名称（冗余），`c009` = 消费金额，`c068` = 优惠金额
- `c175` = 下单时间，`c176` = 结账时间，`c178` = 就餐人数
- `c181` = 会员卡号，`c185` = 会员标识
- `c114` = 理论成本额，`c009` = 消费额（用于理论毛利率计算）

### 2.2 费用数据

| 表名 | 列数 | 说明 |
|------|------|------|
| `operating_expense_records` | 17 | 经营费用原始记录（工资/房租/水电/佣金等） |
| `operating_expense_store_mapping` | 10 | 费用单位→销售门店编码映射，含 `include_in_operating_analysis` 标志 |
| `operating_expense_import_log` | 8 | 费用导入日志 |

### 2.3 库存成本数据

| 表名 | 列数 | 说明 |
|------|------|------|
| `inventory_cost_records` | 42 | 库存盘点成本原始记录 |
| `inventory_store_mapping` | 10 | 库存单位→销售门店编码映射，含 `include_in_operating_cost` 标志 |
| `inventory_cost_import_log` | 7 | 库存成本导入日志 |

### 2.4 菜品成本分析

| 表名 | 列数 | 说明 |
|------|------|------|
| `dish_cost_analysis_summary` | 18 | 菜品成本分析汇总（理论 vs 实际毛利率） |
| `dish_cost_analysis_material_detail` | 19 | 菜品原料明细 |
| `dish_cost_analysis_import_log` | 17 | 菜品成本分析导入日志 |

### 2.5 考勤薪资数据

| 表名 | 列数 | 说明 |
|------|------|------|
| `attendance_records` | 38 | 考勤打卡记录 |
| `attendance_import_log` | 7 | 考勤导入日志 |
| `salary_detail_records` | 102 | 薪资明细记录 |
| `salary_import_log` | 7 | 薪资导入日志 |

### 2.6 门店位置数据

| 表名 | 列数 | 说明 |
|------|------|------|
| `store_location_master` | 34 | 门店位置主数据（地址/经纬度/面积/租约等） |
| `store_location_source_rows` | 13 | 门店位置原始行 |
| `store_location_import_log` | 10 | 位置导入日志 |
| `sales_store_location_mapping` | 8 | 销售门店→位置映射 |
| `store_name_mapping` | 2 | 门店名称映射表 |

### 2.7 中央厨房数据

| 表名 | 列数 | 说明 |
|------|------|------|
| `central_kitchen_finished_receipt` | 34 | 成品入库记录 |
| `central_kitchen_manufacturing_cost_pool` | 14 | 制造费用池 |
| `central_kitchen_material_daily` | 36 | 原料日耗明细 |
| `central_kitchen_processing_cost` | 29 | 加工成本 |
| `central_kitchen_recipe_consumption` | 39 | 配方消耗 |
| `central_kitchen_import_log` | 13 | 中央厨房导入日志 |

### 2.8 配送数据

| 表名 | 列数 | 说明 |
|------|------|------|
| `distribution_detail_records` | 85 | 配送明细记录 |
| `distribution_import_log` | 17 | 配送导入日志 |

### 2.9 菜品调整

| 表名 | 列数 | 说明 |
|------|------|------|
| `dish_adjustment_log` | 20 | 菜品调整日志 |
| `dish_adjustment_result` | 15 | 菜品调整结果 |
| `dish_diagnosis_snapshot` | 19 | 菜品诊断快照 |
| `dish_sales_details` | 24 | 菜品销售明细 |
| `dish_sales_import_log` | 6 | 菜品销售导入日志 |

---

## 三、分析层维度表（analytics schema）

| 表名 | 列数 | 说明 |
|------|------|------|
| `dim_store` | 14 | 门店维度（编码/名称/类型/区域） |
| `dim_calendar` | 14 | 日历维度 |
| `dim_channel` | 10 | 渠道维度 |
| `dim_daily_target` | 12 | 日度目标 |
| `dim_employee` | 9 | 员工维度 |
| `dim_material` | 12 | 原料维度 |
| `dim_member` | 13 | 会员维度 |
| `dim_product_lifecycle` | 16 | 产品生命周期 |
| `dim_promotion` | 15 | 促销维度 |
| `dim_sku` | 21 | SKU维度 |
| `dim_store_target` | 11 | 门店目标 |
| `dim_supplier` | 9 | 供应商维度 |

---

## 四、分析层事实表（analytics schema）

| 表名 | 列数 | 说明 |
|------|------|------|
| `fact_bill` | 52 | 账单事实表（标准化） |
| `fact_bill_item` | 25 | 账单明细事实 |
| `fact_payment` | 9 | 支付事实 |
| `fact_customer_contact` | 13 | 客户联系事实 |
| `fact_employee_shift` | 13 | 员工排班事实 |
| `fact_inspection` | 17 | 巡检事实 |
| `fact_inventory_snapshot` | 19 | 库存快照事实 |
| `fact_iot_reading` | 11 | IoT读数事实 |
| `fact_platform_order` | 16 | 平台订单事实 |
| `fact_promotion_usage` | 12 | 促销使用事实 |
| `fact_purchase_receipt` | 16 | 采购入库事实 |
| `fact_recipe_bom` | 14 | BOM配方事实 |
| `fact_review` | 14 | 评价事实 |
| `fact_scan_confirm` | 13 | 扫描确认事实 |
| `fact_store_task` | 22 | 门店任务事实 |
| `fact_transfer` | 12 | 调拨事实 |
| `fact_waste` | 11 | 报损事实 |

---

## 五、枚举表（analytics schema）

| 表名 | 说明 |
|------|------|
| `enum_business_type` | 业务类型 |
| `enum_channel_group` | 渠道分组 |
| `enum_management_quadrant` | 管理象限 |
| `enum_member_status` | 会员状态 |
| `enum_metric_direction` | 指标方向 |
| `enum_priority` | 优先级 |
| `enum_risk_level` | 风险等级 |
| `enum_sku_status` | SKU状态 |
| `enum_sku_type` | SKU类型 |
| `enum_task_status` | 任务状态 |
| `enum_verification_result` | 验证结果 |
| `enum_waste_reason` | 报损原因 |

---

## 六、物化视图列表（analytics schema）

### 6.1 核心账单物化视图

| 物化视图 | 说明 | 依赖原始表 |
|----------|------|------------|
| `bill_fact` | 账单事实物化视图，从 bill_records 标准化 | `bill_records` |
| `mv_daily_revenue` | 日度营收汇总 | `bill_records` |

### 6.2 门店评估物化视图

| 物化视图 | 说明 | 依赖 |
|----------|------|------|
| `mv_store_risk_rating_monthly` | 门店风险评级（月度） | `bill_fact` |
| `mv_store_operating_expense_monthly` | 门店经营费用（月度，物化表） | `operating_expense_records` + mapping |
| `mv_store_theoretical_actual_cost_monthly` | 门店理论 vs 实际成本（月度） | `bill_fact` + `inventory_cost_records` |
| `mv_store_action_priority_deep_monthly` | 门店行动优先级深度分析 | `bill_fact` |
| `mv_store_deep_diagnosis_monthly` | 门店深度诊断 | `bill_fact` |
| `mv_store_scorecard` | 门店记分卡 | `bill_fact` |

### 6.3 门店基准与效率物化视图

| 物化视图 | 说明 | 依赖 |
|----------|------|------|
| `mv_store_benchmark_composite_monthly` | 门店综合基准 | `bill_fact` |
| `mv_store_area_efficiency_monthly` | 门店坪效分析 | `bill_fact` |
| `mv_store_platform_economics_monthly` | 门店平台经济分析 | `bill_fact` |
| `mv_store_category_mix_monthly` | 门店品类结构 | `bill_fact` |
| `mv_store_member_opportunity_monthly` | 门店会员机会 | `bill_fact` |
| `mv_store_overlap_risk_monthly` | 门店重叠风险 | `bill_fact` |
| `mv_store_site_profile_monthly` | 门店选址画像 | `bill_fact` |
| `mv_store_site_replication_monthly` | 门店选址复制 | `bill_fact` |
| `mv_store_repeat_summary_monthly` | 门店复购汇总 | `bill_fact` |

### 6.4 菜品分析物化视图

| 物化视图 | 说明 | 依赖 |
|----------|------|------|
| `mv_dish_sku_abc_monthly` | 菜品SKU ABC分类 | `bill_fact` |
| `mv_dish_sku_summary_monthly` | 菜品SKU汇总 | `bill_fact` |
| `mv_dish_store_summary_monthly` | 门店菜品汇总 | `bill_fact` |
| `mv_dish_basket_monthly` | 菜品购物篮分析 | `bill_fact` |
| `mv_dish_pair_summary_monthly` | 菜品搭配分析 | `bill_fact` |

### 6.5 选址与区域物化视图

| 物化视图 | 说明 | 依赖 |
|----------|------|------|
| `mv_district_site_benchmark_monthly` | 区域选址基准 | `bill_fact` |
| `mv_site_segment_benchmark_monthly` | 分段选址基准 | `bill_fact` |

### 6.6 库存成本物化视图

| 物化视图 | 说明 | 依赖 |
|----------|------|------|
| `mv_inventory_cost_classified_monthly` | 库存成本分类汇总 | `inventory_cost_records` + mapping |

### 6.7 固定月份物化视图（2026年4月专用）

| 物化视图 | 说明 |
|----------|------|
| `mv_store_theoretical_actual_cost_april` | 4月理论 vs 实际成本 |
| `mv_store_site_profile_april` | 4月门店选址画像 |
| `mv_store_action_priority_deep_april` | 4月行动优先级 |
| `dish_sales_april` | 4月菜品销售 |
| `dish_sku_summary_april` | 4月SKU汇总 |
| `dish_store_summary_april` | 4月门店菜品汇总 |
| `dish_basket_april` | 4月购物篮 |
| `dish_category_summary_april` | 4月品类汇总 |
| `dish_member_sku_april` | 4月会员SKU |
| `dish_store_sku_april` | 4月门店SKU |

---

## 七、普通视图列表（analytics schema）

### 7.1 费用相关视图

| 视图 | 说明 | 依赖 |
|------|------|------|
| `v_operating_expense_unit_monthly` | 费用单位月度汇总 | `operating_expense_records` + mapping |
| `v_store_operating_expense_monthly` | 门店费用月度汇总（按 sales_store_code 聚合） | `v_operating_expense_unit_monthly` |
| `v_operating_expense_account_monthly` | 费用科目月度汇总 | `operating_expense_records` |
| `v_operating_expense_data_quality` | 费用数据质量 | `operating_expense_records` + mapping |

### 7.2 门店分析视图

| 视图 | 说明 |
|------|------|
| `v_store_location_operating` | 门店位置经营信息 |
| `v_store_location_data_quality` | 门店位置数据质量 |
| `v_store_daily` | 门店日度数据 |
| `v_store_daily_card` | 门店日度卡片 |
| `v_store_meal_opportunity` | 门店餐段机会 |
| `v_store_member_monthly_activity` | 门店会员月度活动 |
| `v_store_monthly_followup` | 门店月度跟进 |
| `v_store_nearest_neighbor_april` | 门店最近邻 |
| `v_store_spatial_pairs_april` | 门店空间配对 |

### 7.3 营收分析视图

| 视图 | 说明 |
|------|------|
| `v_overview_daily` | 日度总览 |
| `v_hourly_summary` | 小时汇总 |
| `v_weekday_summary` | 星期汇总 |
| `v_meal_period_daily` | 餐段日度 |
| `v_channel_daily` | 渠道日度 |
| `v_region_summary` | 区域汇总 |

### 7.4 风险与异常视图

| 视图 | 说明 |
|------|------|
| `v_anomaly_bills` | 异常账单 |
| `v_anomaly_summary` | 异常汇总 |
| `v_cashier_risk` | 收银风险 |
| `v_zero_received_store_summary` | 零实收门店汇总 |
| `v_zero_received_detail` | 零实收明细 |

### 7.5 成本相关视图

| 视图 | 说明 |
|------|------|
| `v_inventory_cost_operating` | 库存成本经营 |
| `v_inventory_cost_unit_summary` | 库存成本单位汇总 |
| `v_inventory_finance_category_april` | 库存财务分类 |
| `v_inventory_abnormal_items_april` | 库存异常项 |
| `v_cost_linkage_*` | 成本联动系列视图 |

### 7.6 中央厨房视图

| 视图 | 说明 |
|------|------|
| `v_central_kitchen_*` | 中央厨房系列视图（6个） |
| `v_distribution_*` | 配送系列视图（4个） |

### 7.7 任务与指标视图

| 视图 | 说明 |
|------|------|
| `v_task_monthly_review` | 任务月度复盘 |
| `v_task_weekly_check` | 任务周度检查 |
| `v_loop_health` | 闭环健康度 |
| `v_marketing_plan_summary` | 营销计划汇总 |
| `v_member_comparison` | 会员对比 |
| `v_member_level_mapping` | 会员等级映射 |
| `v_member_monthly_activity` | 会员月度活动 |
| `v_member_repeat_summary_monthly` | 会员复购汇总 |
| `v_position_mapping` | 岗位映射 |
| `v_data_quality_check` | 数据质量检查 |

---

## 八、V3.0 业务管理表（analytics schema）

| 表名 | 说明 |
|------|------|
| `v3_annual_target` | 年度目标 |
| `v3_regional_target` | 区域目标 |
| `v3_store_monthly_target` | 门店月度目标 |
| `v3_daily_target` | 日度目标 |
| `v3_store_grade` | 门店分级 |
| `v3_store_roi` | 门店ROI |
| `v3_alert_rule` / `v3_alert_log` | 预警规则/日志 |
| `v3_approval_*` | 审批流（3表） |
| `v3_budget` / `v3_budget_lock` | 预算/预算锁 |
| `v3_coupon` | 优惠券 |
| `v3_marketing_campaign` | 营销活动 |
| `v3_forecast` | 预测 |
| `v3_monthly_report` | 月报 |
| `v3_notification` | 通知 |
| `v3_purchase_order` / `v3_purchase_order_item` | 采购订单 |
| `v3_supplier_master` | 供应商主数据 |
| `v3_inventory_snapshot` | 库存快照 |
| `v3_iot_device` / `v3_iot_temperature` | IoT设备/温度 |
| `v3_loop_verification` | 闭环验证 |
| `v3_learning_record` / `v3_training_course` | 培训学习 |
| `v3_product_lifecycle` | 产品生命周期 |
| `v3_scheduled_task` / `v3_personal_task` | 计划任务/个人任务 |
| `v3_store_grade` | 门店分级 |
| `v3_target_variance` | 目标偏差 |
| `v3_ai_target_adjustment` | AI目标调整 |
| `v3_audit_log` | 审计日志 |
| `v3_brand_asset` | 品牌资产 |
| `v3_customer_review` | 客户评价 |
| `v3_data_import_log` / `v3_data_quality_rule` | 数据导入/质量规则 |

---

## 九、数据流架构

```
原始数据导入                    分析层构建                     API serving
┌─────────────┐            ┌──────────────┐            ┌──────────────┐
│ bill_records │──REFRESH──▶│  bill_fact   │◀──QUERY───│  Express API │
│ (199 cols)   │            │  (52 cols)   │            │  (18 routes) │
└─────────────┘            └──────────────┘            └──────────────┘
      │                          │
      │                    REFRESH ▼
      │              ┌──────────────────────┐
      │              │ mv_store_risk_rating │
      │              │ _monthly             │
      │              └──────────────────────┘
      │                    │
      │              REFRESH ▼
      │     ┌────────────────────────────────┐
      │     │ mv_store_theoretical_actual_   │
      │     │ cost_monthly                   │
      │     └────────────────────────────────┘
      │
┌──────────────────────┐     ┌──────────────────────────┐
│ operating_expense_   │────▶│ v_operating_expense_     │
│ records + mapping    │     │ unit_monthly (view)      │
└──────────────────────┘     └──────────────────────────┘
                                        │
                                 VIEW   ▼
                             ┌──────────────────────────┐
                             │ v_store_operating_       │
                             │ expense_monthly (view)   │
                             │ (按 sales_store_code 聚合)│
                             └──────────────────────────┘
                                        │
                               INSERT  ▼
                             ┌──────────────────────────┐
                             │ mv_store_operating_      │
                             │ expense_monthly (table)  │
                             └──────────────────────────┘

┌──────────────────────┐     ┌──────────────────────────┐
│ inventory_cost_      │────▶│ mv_inventory_cost_       │
│ records + mapping    │     │ classified_monthly (MV)  │
└──────────────────────┘     └──────────────────────────┘
```

**关键设计**:
- `bill_fact` 是所有账单分析的基础物化视图，从 `bill_records` 标准化而来
- `mv_store_operating_expense_monthly` 是物化**表**（非视图），需手动 INSERT/UPDATE
- `v_store_operating_expense_monthly` 是普通视图，实时查询费用数据
- 部分API直接查 `bill_records`（如门店日度、排班分析），部分查 `bill_fact`
- 固定月份物化视图（`*_april`）硬编码2026年4月，不随月份参数变化