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. 调试工具速查

# 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. 修复优先级

P0 - 页面完全不可用：API报错、路由不存在 → 立即修复
P1 - 数据不正确：数值异常、数据不一致 → 验证后修复
P2 - 体验问题：空状态、加载慢 → 优化处理
P3 - 增强功能：新指标、新图表 → 按需开发

4.7 KiB Raw Blame History Unescape Escape