freedakgmail
c2a9e27e49
文档: - 01-项目概述与架构: 技术架构、数据流、部署拓扑 - 02-数据接入与治理: 原始数据导入、物化视图、门店名映射 - 03-指标体系与API开发: 指标分层、SQL模式、常见陷阱 - 04-前端页面开发: 组件规范、页面模板、月份参数管理 - 05-部署与运维: 部署脚本、FRP隧道、PM2、备份 - 06-调试排查手册: 问题分类、8个实际案例、工具速查 - 07-通用方法论: 核心原则、实施阶段、快速复制Checklist 修复: - situational-awareness.ts: salary_month→salary_period, 日期格式改中文 - 客流-人力匹配: 改用attendance_records打卡数据解析在岗人数 - 客流数据除以30天对齐日均
133 lines
4.7 KiB
Markdown
133 lines
4.7 KiB
Markdown
# 06 · 调试排查手册
|
||
|
||
## 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 - 增强功能**：新指标、新图表 → 按需开发
|