docs: 归档历史文档 + 新增战略外脑实施方法论

- 归档根目录散落文档到 docs/20260812/ 和 docs/20260812-1/ - 新增 16-战略外脑实施方法论.md：七项能力、十二步工作法、AI与决策治理、成熟度和验收 - 新增 17-SBrainCO战略外脑建设对照表.md：方法论映射为领域模型、产品模块、API和分阶段待办 - 新增调查表/战略外脑能力验收Checklist.csv：35项能力验收检查项 - 更新 01-总体框架与八步工作法.md：新增战略外脑扩展章节 - 更新 README.md：新增战略外脑体系导航 Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
2026-08-12 22:28:51 +08:00
parent a0343294b6
commit 7ea6a2515f
56 changed files with 660 additions and 0 deletions
@@ -0,0 +1,233 @@
+# 原始数据导入处理
+
+## 一、数据源概览
+
+| 数据域 | 原始表 | 导入方式 | 文件格式 | 频率 |
+|--------|--------|----------|----------|------|
+| 账单数据 | `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 聚合