# 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 - 增强功能**：新指标、新图表 → 按需开发