refactor(h5)!: H5 改由 nginx 托管，后端退回纯 API

用户决定：后端不再对外发静态文件，学生端 H5 交给网关。两者**仍然同源**
（微信只给一个授权回调域名；H5 的接口地址取自 location.origin），
所以前端业务代码、微信后台、application-dev.yml 的 h5-base-url 都不用改。

后端
- 删掉 dev/test/prod 三份 profile 里的 spring.web.resources.static-locations
- 主配置加 spring.web.resources.add-mappings=false —— 用开关而不是"指到空目录"：
  后者会连带启用 Spring Boot 的默认位置（classpath:/static 等），谁丢个文件进去就悄悄对外可见
- StaticCacheHeaderFilter → ApiNoStoreFilter，只剩 /api/** 的 no-store
  （静态资源的缓存策略整体归 nginx，避免"改一处漏一处"）
- 补 NoHandlerFoundException → 404：关掉静态映射后未匹配路径不再经过
  ResourceHttpRequestHandler，抛的是 NoHandlerFoundException，只处理
  NoResourceFoundException 时访问 / 会变成 500「系统繁忙」并刷 ERROR 日志

deploy
- 新增 xt-nginx（80）：发 frontend-mp/dist/build/h5 + /api 反代 8080（host.docker.internal，
  Linux 靠 extra_hosts host-gateway），端口与产物目录走 .env 的 H5_PORT/H5_DIR
- 三条"删了就会出事"的都已带上理由：client_max_body_size 50m（默认 1m，超了回 413
  而后端日志一个字都没有）、/assets 的 immutable 与 *.html 的 no-cache（§一·十 那个
  "发版后学生看到旧页面"的坑）、健康检查写 127.0.0.1（容器里 localhost 先解析到 IPv6，
  nginx 只听 IPv4 → 永远 starting 而首页是好的）

CI 与文档
- CI：学生端 H5 构建从"e2e 的输入"改为编译检查，不再留 artifact（e2e 不消费它）
- 同步 AGENTS.md / README.md / docs/09（启动步骤、CI 表、发布注意、排障表）/ docs/11
- 交接摘要新增 §一·四十三（含理由、验证数字、要人工做的一步与环境限制）

验证
- mvn clean package 通过（必须 clean：删掉的旧类会留在 target/classes 被组件扫描）
- 后端直连：/ 与 /assets/* → 404（{"code":40001,"msg":"接口不存在"}）、
  /api/.../captcha → 200 + no-store、/doc.html → 302→200、/v3/api-docs 与 /actuator/health → 200
- 经 nginx(80)：首页 200 + no-cache、/assets/*.js 200 + immutable、/nope.js 404（无回退）、
  /api 200 + no-store、gzip 生效；2MB multipart 上传 → 401（与直连一致 ⇒ 未踩 1m 的坑）、
  55MB → 413
- e2e（XT_BASE=http://localhost，全程走 nginx）：e2e-m0.py 37/37、e2e-m3-h5-auth.py 24/24、
  e2e-m2-scope.py 38/38
- verify-all.py --quick 6/6；check-test-profile.py：test profile 仍能起来

docs/交接摘要.md

@@ -887,6 +887,9 @@ P4 写 M5 校验引擎时，我凭记忆用了一套 VAL 编号，**与 PRD 权
    `*.html` `no-cache`、`/api/**` `no-store`。
    > 上一轮"浏览器加载旧 chunk"的悬案就是它 —— 已用
    > 「从 8080 下载 chunk 与磁盘文件比 SHA-256」证实不是构建问题。
+   > ⚠️ **2026-10 起**：H5 改由 nginx 托管，这个类只剩 `/api/**` 的 `no-store`
+   > （并更名为 `ApiNoStoreFilter`）；`/assets/**` 与 `*.html` 这两条**搬到了**
+   > `deploy/nginx/xt.conf` —— 结论没变，只是换了个地方执行。见 §一·四十三。
 
 5. **`edit` 工具的 `oldString` 是子串匹配**。上一轮我把 `function doSubmit() {`
    当锚点，而原文是 **`async function doSubmit() {`** —— 于是 `async` 被留在
@@ -3155,8 +3158,9 @@ CI/CD 与 test/prod 环境 → 压测 → 用户手册与客服话术 → 缩略
 
 ### 七、构建产物也要重跑（**源码改了产物不会变**）
 
-改品牌名时最容易漏的一环：`frontend-mp` 的 H5 是**后端托管的构建产物**
-（`dist/build/h5/`，见 `AGENTS.md` 的"先做 H5"），源码改了它一个字都不会变。
+改品牌名时最容易漏的一环：`frontend-mp` 的 H5 是**构建产物**
+（`dist/build/h5/`，见 `AGENTS.md` 的"先做 H5"；2026-10 起托管方从后端换成 `xt-nginx`，
+但"源码改了产物一个字都不会变"这条不变，见 §一·四十三），源码改了它一个字都不会变。
 本次实测：源码改完后产物里**仍是「填报通」**。
 
 已重跑并复查：
@@ -3717,3 +3721,90 @@ const feedbackNodes = children || feedback ? (…) : this.renderExplains.length
 
 
 
+---
+
+## §一·四十三　H5 托管从后端搬到 nginx（2026-10，用户决定）
+
+**决定**：后端不再对外发任何静态文件（`spring.web.resources.add-mappings=false`），
+学生端 H5 由 `deploy/` 里的 **`xt-nginx`（80）** 托管，同一个 server 把 `/api` 反代到后端 8080。
+PC 管理端不受影响（它一直是独立静态托管）。
+
+### 一、"不托管"不等于"可以跨源"（换托管方时这三条必须继续满足）
+
+| 约束 | 为什么 |
+|---|---|
+| H5 与 `/api` **同源** | 微信网页授权的「授权回调页面域名」**只能配一个**，回调落在 `/api/v1/mp/h5/callback`，学生 302 回来的页面必须同域 |
+| H5 的接口地址是 `location.origin` | `frontend-mp/src/config/index.ts`：跨源时请求会打到页面所在的源，表现是"页面能开、接口全 404" |
+| 同源还省掉 CORS | 否则要放开 `fill.cors.allowed-origins`（`WebConfig` 里那段只在 dev 放行 localhost/内网） |
+
+所以 nginx 的形态是"**页面与接口都从 80 出**"，而不是"H5 一个端口、接口另一个端口"。
+`application-dev.yml` 的 `h5-base-url`（穿透域名，不带端口）因此**一个字都不用改**。
+
+### 二、改了什么
+
+| 位置 | 改动 |
+|---|---|
+| `application-{dev,test,prod}.yml` | 删掉三份里的 `spring.web.resources.static-locations` |
+| `application.yml` | 新增 `spring.web.resources.add-mappings: false` —— 用开关而不是"指到空目录"：后者会连带启用 Spring Boot 的**默认**位置（`classpath:/static` 等），谁丢个文件进去就悄悄对外可见 |
+| `ApiNoStoreFilter`（原 `StaticCacheHeaderFilter`） | 只剩 `/api/**` → `no-store`；静态资源缓存头整体交给 nginx |
+| `GlobalExceptionHandler` | **补 `NoHandlerFoundException` → 404**（见第五节，这是本次改动**引出来**的） |
+| `deploy/nginx/xt.conf`（新）、`xt-nginx` 容器（新）、`.env.example` 加 `H5_PORT`/`H5_DIR` | 静态站 + `/api` 反代 + 缓存头 + `client_max_body_size` |
+| `.gitlab-ci.yml` | H5 build 从"e2e 的输入"改为**编译检查**，不再留 artifact（e2e 不消费它） |
+| `frontend-mp/src/config/index.ts`、`vite.config.ts`、`scripts/e2e-m3-flow.py`、`scripts/_verify-student-flow.py` | 只改注释与提示文案 —— **学生端业务代码一行没动**（同源这个前提没变） |
+| `AGENTS.md` / `README.md` / `docs/09` / `docs/11` | 同步（端口、产物去向、排障表、启动步骤） |
+
+### 三、nginx 那份配置里两条"删了就会出事"的
+
+1. `client_max_body_size 50m`：nginx 默认 **1m**，学生从聊天记录里选一张照片就可能超，
+   超了 nginx 直接回 **413**，而**后端日志里一个字都没有**（请求根本没到应用）——
+   排查时会一路怀疑"请求没发出去"。
+2. `/assets/` 的 `immutable` 与 `*.html` 的 `no-cache`：就是 §一·十 那条踩过的坑
+   （启发式缓存 → 发版后学生看到旧页面），只是执行者从 Java 过滤器换成了 nginx。
+   另外 `location /` **故意不做** history 回退：H5 是 hash 路由，回退会让缺失的 chunk
+   返回 200+HTML，浏览器报 `Unexpected token '<'`，而真因只是文件不存在。
+3. 容器**健康检查要写 `127.0.0.1`，不能写 `localhost`**：容器里 localhost 先解析到 IPv6 `::1`，
+   而 nginx 的 `listen 80` 只监听 IPv4 → wget 报 `Connection refused`，
+   健康状态永远停在 starting（首页从宿主机看却是 200，极易误判）。
+
+### 四、验证（实测，2026-10-19）
+
+| 手段 | 结果 |
+|---|---|
+| `mvn clean package` | 通过。⚠️ **必须带 `clean`**：被删掉的旧类会留在 `target/classes` 里，仍会被组件扫描到 |
+| 后端直连（8081） | `/`、`/index.html`、`/assets/index.js` → **404**（`{"code":40001,"msg":"接口不存在"}`）；`/api/v1/auth/captcha` → 200 + `Cache-Control: no-store`；`/doc.html` → 302 → `/swagger-ui/index.html` 200；`/v3/api-docs`、`/actuator/health` → 200（**证明 `add-mappings` 不影响 springdoc 与 actuator**） |
+| nginx（80） | `/` → 200 + `no-cache`；`/assets/index-*.js` → 200 + `public, max-age=31536000, immutable`；`/nope.js` → **404**（无回退）；`/api/...` 经反代 → 200 + `no-store`；gzip 生效（265KB 包 → `Content-Encoding: gzip`） |
+| 包体上限 | 2MB multipart 上传经 nginx → **401**（与直连一致，证明默认 1m 的坑已避开）；55MB → **413**（上限按设计生效） |
+| e2e（`XT_BASE=http://localhost`，**全程走 nginx**） | `e2e-m0.py` **37/37**、`e2e-m3-h5-auth.py` **24/24**（H5 授权与 302 落点）、`e2e-m2-scope.py` **38/38** |
+| `verify-all.py --quick` | 6/6（契约 / 实体 / 文档 / 手册 / 接线 / 脚本语法） |
+| `check-test-profile.py` | test profile **能起来**（随机端口 50767，10.5 秒）—— CI 那套配置在删掉 static-locations 后仍可启动 |
+
+### 五、顺带修掉一个"改出来的"回归（值得记住的因果）
+
+关掉静态映射后，未匹配路径不再经过 `ResourceHttpRequestHandler`，于是抛的是
+**`NoHandlerFoundException`**（连 handler 都没有）而不是 `NoResourceFoundException`（资源处理器在、文件不在）。
+原代码只处理了后者 → 前者落到兜底 → **访问 `/` 得到 500「系统繁忙」**，日志里还刷 `ERROR 未预期异常`。
+已补一个 handler 返回同样的 404 形状。**教训：这类"关掉一个框架默认行为"的改动，
+要顺手把它的异常路径也想一遍** —— 否则一个正常的 404 会被报成服务端故障。
+
+（另有一处**既存**、本次未改：`Content-Type: application/octet-stream` 打到上传接口会得到 500
+而不是 415 —— `HttpMediaTypeNotSupportedException` 也没进处理器。是否收编由后续决定。）
+
+### 六、要人工做的一步 + 一个环境限制
+
+1. **内网穿透要改指到 nginx 的 80 端口**（原来是 `192.168.3.139:8080`）。
+   指到 8080 的表现是"**接口好用、页面 404**"。改完之后前端与微信后台都不用动。
+2. **本机 8080 现在被别的项目占着**（`com.jxyunge.AdminApplication`）。我们的后端起不来时，
+   `java -jar ... --server.port=8081` 可以起，但**约 19 个 e2e 脚本把 base 写死成 8080**
+   （`BASE = "http://localhost:8080"` 或 `Request("http://localhost:8080"+path)`），
+   `XT_BASE` 对它们无效 —— 本次能跑的三个是认 `XT_BASE` 的。**不要去杀别人的进程。**
+
+### 七、显式不做
+
+1. **不把 PC 管理端搬进来**：它仍是独立静态托管（`pnpm dev` 5173 / 生产由网关发 `dist/`）。
+2. **不给 nginx 加 `/actuator/**`、`/doc.html` 的反代**：actuator 只在内部暴露、文档在生产关闭，
+   要调试直接打后端端口。
+3. **不做 HTTPS / 证书**：本地由穿透层负责；生产形态由部署侧决定。
+
+
+
+