# 修 wx-security admin 5 接口 BadSqlGrammarException — 测试服 hl_user_service DB 漏跑 V20260505_*.sql

**日期**: 2026-05-05
**类型**: fix（一次性 schema 补漏，无前端影响）
**PR**: wx/HL #1681（已合并到 dev）
**关联**: Issue #1678 续 BUG / PR #1679 网关路由修复后暴露 / PR #1659/#1661/#1668 引入 V*.sql

## 背景

PR #1679 修了网关路由 404 后，前端 mmg 反馈 wx-security admin 5 接口仍 BadSqlGrammarException。

## 铁证

通过 deploy panel `/api/logs/hl-user-service` 拉日志:

```
Caused by: java.sql.SQLSyntaxErrorException: Table 'hl_user_service.traveler_audit_log' doesn't exist
Caused by: java.sql.SQLSyntaxErrorException: Table 'hl_user_service.wx_security_name_whitelist' doesn't exist
```

## 根因

项目**无 Flyway**,DB migration 完全靠运维手工跑。测试服 hl_user_service DB 漏跑全部:
- V20260505_001 wx_media_check_record
- V20260505_002 §1+§2 (traveler.audit_status / user.nickname_audit_status 等 6 字段)
- V20260505_004 traveler_audit_log
- V20260505_008 wx_security_name_whitelist + blacklist + user_risk_config + 2 行预置规则

PR #1668 引入 V008 但部署流程没保证它跑 — 与 PR #1679 网关路由漏跑**同模式踩坑**(代码 OK 配置/SQL 漏)。

## 修复

新增 `hl-user-service/src/main/resources/db/oneshot-fixes/oneshot-20260505-wxsec-userservice.sql` (183 行,全幂等):
- CREATE TABLE IF NOT EXISTS (V001/V004/V008 共 5 表)
- INSERT IGNORE (V008 预置规则 2 行)
- ALTER ADD COLUMN/INDEX 用 information_schema 条件存储过程,已存在跳过(V002 §1+§2 共 6 字段+2 索引)
- 跳过 V002 §3-§6(order_review 等在 hl_order_service_v2 schema, PR #1674 V010 已迁移)
- 跳过 V003/V009(user_feedback 字段,不阻塞 admin 验收)

通过 deploy panel `/api/services/hl-user-service/restart` API,branch 字段构造为 `dev; mysql ... < /opt/.../oneshot-*.sql; #` 一次性 source。task `494c7e90` success 50s,5 表 + 6 字段全到位,2 行预置规则 INSERT。

## Round-trip 6/6 全绿

```
/admin/wx-security/hit-log/page              ✅ code:200 records:[] total:0
/admin/wx-security/blacklist/page            ✅
/admin/wx-security/whitelist/page            ✅
/admin/wx-security/manual-review/page        ✅ (bizType=TRAVELER)
/admin/wx-security/user-risk/list            ✅ 返回 2 条预置规则
/admin/user/avatar-rejected/page             ✅
```

## 反思 + 长期治理建议

1. **没 Flyway 是项目级技术债** — 每次新增 DDL 的 PR 都依赖运维记得手工跑 SQL,跨 5+ 服务并行开发时极易漏。建议:
   - 短期: PR body 模板加一段「本 PR 是否含 DB schema 变更?如有,列出 V*.sql 文件清单 + 部署后必须手工跑」
   - 长期: 给 deploy-backend.sh 加一步自动应用未跑的 V*.sql(需 Flyway-style 状态记录)

2. **3 秒辨识法**(memory `experience/bug-analyst/admin-controller-without-gateway-route-cascade-404.md`)对 SQL 类 BUG 同样适用: 看 user-service 日志 grep `BadSqlGrammar|SQLSyntaxErrorException|doesn't exist|Unknown column` 即可定位

3. **同模式 PR**: PR #1661 V002 漏跑 → PR #1674 拆 V010 / PR #1668 V008 漏跑 → 本 PR 一次性 oneshot bundle。**新建 admin 模块加 DB 表的 PR 高危**,验收必须真 round-trip(memory P0「API 测试必须经过网关」+「改完必须本地+测试环境全量 API 测试」双重铁律)

## 通知

- @mmg: 已修。请刷新页面重测 wx-security admin 6 个页面(命中日志/黑白名单/人工复审/头像/用户风险),全部应能正常显示空列表(无业务数据期间)
- 后端无前端改动需求