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 聚合