重构智脑实施方法论：引入FDE模式，八步工作法，适配中国连锁经营企业国情

2026-08-12 11:32:51 +08:00
parent c2a9e27e49
commit 64d2cd8043
16 changed files with 5001 additions and 20 deletions
@@ -0,0 +1,132 @@
+# 12 · 技术参考：调试排查手册
+
+## 1. 问题分类与排查流程
+
+### 1.1 页面空白 / 无数据
+
+```
+页面空白
+  ↓
+检查API返回 → curl测试
+  ↓
+API报错？ → 查看error字段
+  ↓
+SQL报错？ → 直查数据库验证
+  ↓
+数据不存在？ → 检查月份/物化视图刷新状态
+```
+
+### 1.2 API报错排查
+
+| 错误信息 | 根因 | 修复方法 |
+|---------|------|---------|
+| `relation "xxx" does not exist` | Schema前缀错误 | 查 `pg_matviews` 确认实际schema |
+| `column "xxx" does not exist` | 列名不匹配 | 查 `information_schema.columns` |
+| `Route not found` | 路由未注册或文件路径错 | 检查 `index.ts` 中 `app.use` |
+| 查询返回0条 | 日期格式不匹配 | 检查实际数据格式（如中文日期） |
+| 数据量异常增大 | 物化视图stale | 重建物化视图 |
+
+### 1.3 数据不一致排查
+
+```
+前端显示 vs 数据库实际
+  ↓
+1. curl API 看返回值
+  ↓
+2. 直接 psql 查同一条件
+  ↓
+3. 不一致？→ 检查物化视图是否stale
+  ↓
+4. 一致但数值异常？→ 检查SQL逻辑（如月度汇总vs日均）
+```
+
+## 2. 实际案例与修复记录
+
+### 2.1 Dashboard空白（默认月份问题）
+
+**症状**：部署后Dashboard显示"0家"
+**根因**：前端用 `new Date().toISOString().slice(0,7)` 获取当前月份（8月），但数据只到4月
+**修复**：统一使用 `DEFAULT_MONTH = '2026-04'`
+
+### 2.2 /stores/risk 报错（列名不存在）
+
+**症状**：`column "risk_score" does not exist`
+**根因**：SQL显式列名包含物化视图中不存在的列
+**修复**：改为 `SELECT *` 或用 `0 AS column_name` 替代
+
+### 2.3 /channel 报错（Schema前缀）
+
+**症状**：`relation "analytics.mv_channel_daily" does not exist`
+**根因**：`mv_channel_daily` 在 `public` schema，代码写了 `analytics.`
+**修复**：移除schema前缀
+
+### 2.4 /situational-awareness/correlation 报错（列名错误）
+
+**症状**：`column s.salary_month does not exist`
+**根因**：实际列名是 `salary_period`，代码写了 `salary_month`
+**修复**：改为 `s.salary_period`
+
+### 2.5 考勤数据返回0条（日期格式）
+
+**症状**：hr_revenue 为空
+**根因**：`salary_period` 格式是"2026年4月"，代码用 `to_char($1, 'YYYY-MM')` 生成"2026-04"
+**修复**：改为 `to_char($1::date, 'YYYY"年"FMMM"月"')`
+
+### 2.6 异常账单数据量暴增（物化视图stale）
+
+**症状**：异常账单从3万变3.5万，实收从225万变461万
+**根因**：旧物化视图数据stale，重建后刷新到最新
+**附加修复**：异常阈值从0.05元提高到1元，过滤舍入差异
+
+### 2.7 客流-人力匹配在岗人数不合理
+
+**症状**：双安总店74人全天在岗不变
+**根因**：用月度总员工数作为每小时在岗人数
+**修复**：改用 `attendance_records` 打卡记录解析每小时实际在岗人数
+
+### 2.8 客流-人力匹配人均产出过高
+
+**症状**：人均产出300+单/小时
+**根因**：客流是月度汇总（3万+），在岗人数是日均（30人）
+**修复**：客流也除以30天对齐日均
+
+## 3. 调试工具速查
+
+```bash
+# 1. 获取Token
+TOKEN=$(curl -s 'https://dm.all8ai.top/api/auth/login' \
+  -H 'Content-Type: application/json' \
+  -d '{"username":"总部管理员","password":"123"}' \
+  | python3 -c "import sys,json;print(json.load(sys.stdin)['data']['token'])")
+
+# 2. 测试单个API
+curl -s "https://dm.all8ai.top/api/xxx?month=2026-04" \
+  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool
+
+# 3. 批量测试API
+for api in "/api/a" "/api/b" "/api/c"; do
+  echo -n "$api => "
+  curl -s "https://dm.all8ai.top${api}?month=2026-04" \
+    -H "Authorization: Bearer $TOKEN" \
+    | python3 -c "import sys,json;d=json.load(sys.stdin);print('OK' if d['success'] else 'ERROR: '+d.get('error','?'))"
+done
+
+# 4. 直查数据库
+ssh ubuntu@152.136.182.184 "PGPASSWORD= psql -h 127.0.0.1 -p 15432 -U freedak -d bill_query -c \"SQL\""
+
+# 5. 查看后端日志
+ssh ubuntu@152.136.182.184 "pm2 logs sbrain-server --lines 100"
+
+# 6. 检查物化视图
+ssh ubuntu@152.136.182.184 "PGPASSWORD= psql -h 127.0.0.1 -p 15432 -U freedak -d bill_query -c \"SELECT schemaname, matviewname FROM pg_matviews ORDER BY 1,2\""
+
+# 7. 检查表结构
+ssh ubuntu@152.136.182.184 "PGPASSWORD= psql -h 127.0.0.1 -p 15432 -U freedak -d bill_query -c \"SELECT column_name, data_type FROM information_schema.columns WHERE table_name = 'xxx' ORDER BY ordinal_position\""
+```
+
+## 4. 修复优先级
+
+1. **P0 - 页面完全不可用**：API报错、路由不存在 → 立即修复
+2. **P1 - 数据不正确**：数值异常、数据不一致 → 验证后修复
+3. **P2 - 体验问题**：空状态、加载慢 → 优化处理
+4. **P3 - 增强功能**：新指标、新图表 → 按需开发