docs(2026-05-07): refund 申诉补企微 OA 提交 (PR #1774)

后端纯内部修复,前端无配合,运维补 nacos 三套 + 7 控件 ID。 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-07 10:27:01 +08:00
@@ -0,0 +1,65 @@
+# 修 admin wx-security 6 接口全 404 — 网关路由白名单缺项
+
+**日期**: 2026-05-05
+**类型**: fix（网关路由配置补漏，无前端影响）
+**PR**: wx/HL #1679（已合并到 dev）
+**关联工单**: #1678
+**关联 PR**: #1668（Phase 2D admin 后台，未同步改 gateway）/ #1669 / #1675
+
+## 背景
+
+PR #1668 新增 6 个 admin wx-security Controller (`AdminWxSecurityHitLogController` / `Blacklist` / `Whitelist` / `ManualReview` / `Avatar` / `UserRisk`),但 0 改动 `hl-gateway/src/main/resources/application.yml`。后续 PR #1669 / #1675 也未补。测试服 nacos `hl-gateway-*.yml` 三 dataId 全 not exist,gateway 完全靠 jar 内 yml,导致 `/admin/wx-security/**` 6 接口在 gateway 兜底层全部 404。
+
+mmg 同事从 hl-ui-admin (https://localhost:9527) 走 vue.config.js proxy → 测试服 https://api.test.1814.love:9443 网关时暴露,backend 单测/本地 8081 直连验收均无法发现。
+
+## 铁证
+
+- 故障接口 HTTP 404 + body 是 Spring Boot 默认 5 字段格式 (`{"timestamp","path","status","error","requestId"}`),**无 `code` 字段** → gateway 兜底,不是 controller
+- 兄弟 `/admin/sys/dict/all` 返回 `{"code":401,"message":"..."}` → user-service 在线、controller 正常
+- `git show e90a7dd6 --stat`(PR #1668) 0 涉及 hl-gateway/
+
+## 修复
+
+`hl-gateway/src/main/resources/application.yml` 在 line 138 后插入 4 行新路由(+ 1 行注释,共 +5):
+
+```yaml
+        # 微信内容安全 admin 端 (黑/白名单/命中日志/人工复审/头像/用户风险 6 controller, PR #1668)
+        - id: admin-wx-security-service
+          uri: lb://hl-user-service
+          predicates:
+            - Path=/admin/wx-security/**
+```
+
+一条 Path predicate 覆盖 6 个 controller,无需 metadata。
+
+## 影响范围
+
+- 受波及接口: wx-security admin 全部 6 个 controller (HitLog/Blacklist/Whitelist/ManualReview/Avatar/UserRisk)
+- mp 端 `/mp/security/**` 不受影响(line 50-53 早有 Path predicate)
+- 数据污染: 无(请求未到达 service / DB)
+- 回滚: 不需要(前向修复即可)
+
+## 部署 + 验证
+
+需运维/管理员在 [Deploy Panel](https://dep.test.1814.love) 触发 hl-gateway 部署 dev 分支,redeploy 完成后 round-trip 6 接口:
+
+```bash
+TOKEN="<admin token>"
+for path in hit-log/page blacklist/page whitelist/page manual-review/page avatar/page user-risk/page; do
+  curl -k "https://api.test.1814.love:9443/admin/wx-security/$path?page=1&pageSize=10" \
+       -H "Authorization: Bearer $TOKEN" -w "\nHTTP=%{http_code}\n\n"
+done
+```
+
+验收标准: 6 接口都返回带 `code` 字段的 Result body (HTTP 200, code 0/200 数据正常 或 401 鉴权)。
+
+## 经验沉淀
+
+落 `memory/experience/backend-dev/admin-controller-without-gateway-route-cascade-404.md` — 同模式踩坑 PR #1048 / #1293 / #1668 三连发,从未沉淀。**3 秒辨识法**: 响应 body 无 `code` 字段 = gateway 兜底,直接锁配置不必深挖代码。
+
+强化 memory `feedback_api-test-must-go-through-gateway.md` cadence: 凡新增 `/admin/<新模块>/**` 类 controller,**API 验收必经 9443 网关**,user-service 直连 8081 单测全绿不算数。
+
+## 通知
+
+- @mmg: 网关路由已补,等运维部署 dev 后 hl-ui-admin 9527 → 9443 proxy 链路即恢复,所有 wx-security admin 页面可正常访问
+- 后端无前端改动需求,前端不用动