SBrainCO/docs/20260812-1/原始数据级导入处理.md

# 原始数据导入处理

## 一、数据源概览

| 数据域 | 原始表 | 导入方式 | 文件格式 | 频率 |
|--------|--------|----------|----------|------|
| 账单数据 | `bill_records` | Python脚本导入 | Excel (.xlsx) | 月度 |
| 经营费用 | `operating_expense_records` | Python脚本导入 | Excel | 月度 |
| 库存成本 | `inventory_cost_records` | Python脚本导入 | Excel | 月度 |
| 菜品成本分析 | `dish_cost_analysis_summary` | Python脚本导入 | Excel | 月度 |
| 考勤数据 | `attendance_records` | Python脚本导入 | Excel | 月度 |
| 薪资数据 | `salary_detail_records` | Python脚本导入 | Excel | 月度 |
| 门店位置 | `store_location_master` | Python脚本导入 | Excel | 按需 |
| 中央厨房 | `central_kitchen_*` (6表) | Python脚本导入 | Excel | 月度 |
| 配送数据 | `distribution_detail_records` | Python脚本导入 | Excel | 月度 |
| 菜品销售 | `dish_sales_details` | Python脚本导入 | Excel | 月度 |

---

## 二、账单数据导入（bill_records）

### 2.1 数据源

- **来源文件**: 正餐事业部_店内订单明细-已结账_*.xlsx
- **来源系统**: 餐饮POS系统导出
- **文件路径**: `数据/4月/` 或 `数据/5月/`

### 2.2 导入脚本

| 脚本 | 说明 |
|------|------|
| `/tmp/import_missing_stores.py` | 导入缺失门店账单（MD00002/MD00003/MD00008/1098/1110） |
| `/tmp/import_remaining_stores.py` | 导入剩余门店账单（哈马尔罕总部基地店0056/大钟寺店0022/茂林居店0021/西安含光店0052/西部马华火锅北三环店0012） |

### 2.3 字段映射

`bill_records` 表使用 c001~c199 编码，关键字段：

| 列号 | 字段含义 | 用途 |
|------|----------|------|
| c002 | 门店编码 | 门店标识 |
| c003 | 门店名称 | 门店名称（用于JOIN） |
| c009 | 消费金额 | 营业收入 |
| c068 | 优惠金额 | 优惠分析 |
| c114 | 理论成本额 | 理论毛利率 |
| c175 | 下单时间 | 时段分析 |
| c176 | 结账时间 | 日度汇总 |
| c178 | 就餐人数 | 客流分析 |
| c181 | 会员卡号 | 会员分析 |
| c185 | 会员标识 | 会员识别 |

### 2.4 导入逻辑

1. 读取 Excel 文件，解析支付方式和金额
2. 按门店名称匹配 `store_name_mapping` 表
3. **删除旧数据**: 按 `c003`（门店名称）和日期范围删除同月旧记录
4. **插入新数据**: 批量 INSERT，自动生成 bill_id
5. 导入后需刷新 `bill_fact` 物化视图

### 2.5 支付方式解析

脚本中定义了支付方式映射，将不同支付渠道（微信/支付宝/现金/会员储值/美团/饿了么等）解析为对应字段。

### 2.6 门店名称映射

| 原始名称 | 门店编码 | 说明 |
|----------|----------|------|
| 哈马尔罕（总部基地店） | 0056 | 新导入 |
| 哈马尔罕（大钟寺店） | 0022 | 新导入 |
| 哈马尔罕（茂林居店） | 0021 | 新导入 |
| 哈马尔罕（西安含光店） | 0052 | 新导入 |
| 西部马华火锅（北三环店） | 0012 | 新导入 |
| 关东店 | 1098 | 编码修正（原错误映射为0033） |

---

## 三、经营费用导入（operating_expense_records）

### 3.1 数据源

- **来源文件**: 各门店费用明细Excel
- **费用科目**: 月薪员工工资、餐厅房租、外卖佣金、电费、燃气费、水费、物业费、宿舍费用、刷卡手续费、清洗费、垃圾费、维修费、菜品提成、自送快递费、烟道清洗、设备租赁费、暖气费

### 3.2 导入流程

1. 读取 Excel，按费用科目和门店单位导入
2. 写入 `operating_expense_records` 原始表
3. 通过 `operating_expense_store_mapping` 映射到销售门店编码
4. `include_in_operating_analysis` 标志控制是否纳入经营分析

### 3.3 门店映射规则

- 一个费用单位可映射到一个销售门店编码（`sales_store_code`）
- 多个费用单位可映射到同一门店（如"哈马尔罕大钟寺店"→"大钟寺店"0022）
- 未映射的费用单位（支持/供应链/特殊业务）不纳入门店评估
- `include_in_operating_analysis = true` 才参与费用分析

### 3.4 导入后处理

- 视图 `v_operating_expense_unit_monthly` 自动反映新数据
- 视图 `v_store_operating_expense_monthly` 按 `sales_store_code` 聚合
- 物化表 `mv_store_operating_expense_monthly` 需手动刷新（INSERT/UPDATE）

---

## 四、库存成本导入（inventory_cost_records）

### 4.1 数据源

- **来源文件**: 库存盘点Excel
- **内容**: 各门店库存消耗金额、原料分类

### 4.2 导入流程

1. 读取 Excel，按门店和原料分类导入
2. 写入 `inventory_cost_records` 原始表
3. 通过 `inventory_store_mapping` 映射到销售门店编码
4. `include_in_operating_cost` 标志控制是否纳入成本分析

### 4.3 导入后处理

- 刷新 `mv_inventory_cost_classified_monthly` 物化视图
- 刷新 `mv_store_theoretical_actual_cost_monthly` 物化视图

---

## 五、菜品成本分析导入（dish_cost_analysis_summary）

### 5.1 数据源

- **来源文件**: 菜品成本分析Excel
- **内容**: 每个菜品的理论成本、实际成本、毛利率

### 5.2 导入流程

1. 读取 Excel，按菜品导入
2. 写入 `dish_cost_analysis_summary` 和 `dish_cost_analysis_material_detail`
3. 记录导入日志到 `dish_cost_analysis_import_log`
4. 按 `report_month` 和 `import_id` 区分批次

---

## 六、考勤薪资导入

### 6.1 考勤数据

- **原始表**: `attendance_records`（38列）
- **导入日志**: `attendance_import_log`
- **内容**: 员工打卡记录（上班/下班/迟到/早退）

### 6.2 薪资数据

- **原始表**: `salary_detail_records`（102列）
- **导入日志**: `salary_import_log`
- **内容**: 员工薪资明细（基本工资/加班/社保/公积金等）

---

## 七、门店位置导入（store_location_master）

### 7.1 数据源

- **来源文件**: 门店位置信息Excel
- **内容**: 门店地址、经纬度（GCJ02）、面积、租约到期日、营业时间

### 7.2 导入流程

1. 读取 Excel，写入 `store_location_source_rows` 原始行
2. 匹配到 `sales_store_location_mapping` 建立门店编码关联
3. 更新 `store_location_master` 主数据

### 7.3 关键字段

| 字段 | 说明 |
|------|------|
| `area_sqm` | 营业面积（平米），用于坪效计算 |
| `lease_expiry_date` | 租约到期日，用于续租风险 |
| `latitude_gcj02` / `longitude_gcj02` | GCJ02坐标，用于地图展示 |
| `business_address` | 营业地址 |

---

## 八、数据导入后的标准操作流程

```
1. 导入原始数据到 public.* 表
   ↓
2. 刷新 bill_fact 物化视图
   REFRESH MATERIALIZED VIEW analytics.bill_fact;
   ↓
3. 刷新依赖 bill_fact 的物化视图
   REFRESH MATERIALIZED VIEW analytics.mv_daily_revenue;
   REFRESH MATERIALIZED VIEW analytics.mv_store_risk_rating_monthly;
   REFRESH MATERIALIZED VIEW analytics.mv_store_theoretical_actual_cost_monthly;
   REFRESH MATERIALIZED VIEW analytics.mv_dish_sku_abc_monthly;
   REFRESH MATERIALIZED VIEW analytics.mv_dish_sku_summary_monthly;
   ... (所有依赖 bill_fact 的物化视图)
   ↓
4. 更新 mv_store_operating_expense_monthly 物化表
   （从 v_store_operating_expense_monthly 视图 INSERT/UPDATE）
   ↓
5. 刷新库存成本物化视图
   REFRESH MATERIALIZED VIEW analytics.mv_inventory_cost_classified_monthly;
   ↓
6. 验证数据一致性
   - 对比 bill_fact 和 mv_store_risk_rating_monthly 门店数
   - 对比 bill_fact 和 mv_store_theoretical_actual_cost_monthly 实收合计
   - 检查是否有遗漏门店
```

---

## 九、已知问题与修复记录

### 9.1 门店编码映射错误

- **问题**: 关东店编码错误映射为0033，实际应为1098
- **修复**: 更新 `store_name_mapping` 表

### 9.2 旧数据误删

- **问题**: 导入新数据时误删了旧账单记录（bill_records），导致历史数据丢失
- **修复**: 从数据库备份 `bill_query_full_20260802_150344.dump` 恢复，使用 `pg_restore` 恢复到临时库后提取缺失数据

### 9.3 费用单位重复映射

- **问题**: "哈马尔罕大钟寺店"的费用记录未映射到"大钟寺店"(0022)，导致费用未纳入门店评估
- **修复**: 更新 `operating_expense_store_mapping`，将 `sales_store_code` 设为 0022，`include_in_operating_analysis = true`

### 9.4 视图聚合问题

- **问题**: `v_store_operating_expense_monthly` 视图未按 `sales_store_code` 聚合，导致多个费用单位映射到同一门店时出现重复行
- **修复**: 重建视图，增加 `expense_agg` CTE 按 `sales_store_code` GROUP BY 聚合