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/09-部署与运维.md

@@ -25,18 +25,28 @@
 ### 2.1 本地
 
 ```bash
-cd deploy && docker compose up -d          # xt-pg(5432) + xt-redis(16379)
+cd deploy && docker compose up -d          # xt-pg(5432) + xt-redis(16379) + xt-nginx(80)
+cd frontend-mp && pnpm build:h5            # nginx 挂的是产物目录 → 先出产物
 cd backend
 mvn -DskipTests package
 java -jar xt-server/target/xt-server-1.0.0-SNAPSHOT.jar --spring.profiles.active=dev
 ```
 
-- ⚠️ **工作目录必须是 `backend/`**：两处相对路径依赖它 ——
-  `application-local.yml`（本地私有配置，不提交）在这里；
-  H5 静态目录配的是 `file:../frontend-mp/dist/build/h5/`
+- ⚠️ **工作目录必须是 `backend/`**：`application-local.yml`（本地私有配置，不提交）在那里，
+  是靠相对路径找到的
 - 跑的是 **jar 不是热加载**：改后端要重新 package（先停进程，否则 jar 被占用）
-- H5 没有独立 dev server：`cd frontend-mp && pnpm build:h5`，然后访问
-  `http://localhost:8080`（由后端托管）
+- **H5 由 `xt-nginx` 托管（`http://localhost/`），后端只提供 `/api`**（2026-10 调整）。
+  两者**同源**是硬要求：微信网页授权的「授权回调页面域名」只能配一个，
+  而 H5 的接口地址取自 `location.origin` —— 跨源会让请求打到 nginx 自己身上（页面能开、接口全 404）。
+  端口与产物目录在 `deploy/.env`（`H5_PORT` / `H5_DIR`），站点配置是 `deploy/nginx/xt.conf`。
+  - ⚠️ **内网穿透要指到 nginx 的端口（80），不是后端的 8080** ——
+    指到 8080 的表现是"接口好用、页面 404"。
+  - nginx 那份配置里有两条**不能删**的：`client_max_body_size 50m`
+    （默认 1m，学生传一张照片就可能 413，而**后端日志里一个字都没有**）与
+    `/assets/`、`*.html` 的缓存头（没有它浏览器会启发式缓存，发版后学生看到旧页面，
+    见 `ApiNoStoreFilter` 的类注释）。
+- 只想改学生端页面时不必走 nginx：`cd frontend-mp && pnpm dev:h5` → `http://localhost:5174`
+  （自带 `/api` 代理，**改一行不用重新 build**）
 
 ### 2.2 CI（GitLab）
 
@@ -45,7 +55,7 @@ java -jar xt-server/target/xt-server-1.0.0-SNAPSHOT.jar --spring.profiles.active
 | 阶段 | 做什么 | 为什么这样切 |
 |---|---|---|
 | `check` | 契约对账、实体列对账、文档一致性、**e2e 脚本语法扫描** | 都不需要数据库，几十秒出结果，先在最快的阶段挡掉低级错误 |
-| `build` | 后端打包、管理端 typecheck/build、**H5 build** | H5 产物是后面 e2e 的输入，不能跳过 |
+| `build` | 后端打包、管理端 typecheck/build、**H5 build** | H5 build 现在是**编译检查**（2026-10 起不再由后端托管、e2e 也不消费它），学生端没有单独的 typecheck |
 | `e2e` | 起 PG+Redis 容器 → 起后端（`test` profile）→ **依次跑全部 `scripts/e2e-*.py`** | 这个仓库**没有单元测试**，E2E 就是主验证手段；一个只跑编译的流水线在这里等于没跑 |
 
 另外单独一个 job `生产环境自检` 跑 `scripts/e2e-prodguard.py` ——
@@ -72,8 +82,8 @@ curl -sf http://127.0.0.1:8080/actuator/health   # 探活用这个，不是 /
 ⚠️ **滚动发布期间会有两个版本同时在跑**，所以：
 - **迁移必须是"向后兼容"的**（只加列/加表，不改列类型、不删列）——
   否则旧实例会在新库上出错。改列要走"两次发布"：这次加新列并双写，下次删旧列。
-- **H5 静态产物要一起发**：它是后端托管的，前后端不同步会出现
-  "页面调用了还不存在的接口"。
+- **H5 静态产物要和新后端一起发**：H5 由 nginx/网关托管（不再由后端托管，2026-10 调整），
+  但"同源"没变，前后端不同步还是会出现"页面调用了还不存在的接口"。
 
 ---
 
@@ -186,7 +196,9 @@ XT_TENANT_DOMAIN_ENABLED=true    # 如果要按域名区分单位
 |---|---|---|
 | 服务起不来 | 启动日志里的 `生产环境启动自检未通过` | §3.4 的六条 |
 | 学生上传失败 | `xt-server.log` 里 `MaterialFileService` | 存储密钥错 / 空间名错（开 `XT_STORAGE_SELF_CHECK=true` 能在启动时暴露） |
-| 页面 404 但接口正常 | `spring.web.resources.static-locations` | H5 构建产物没放对目录（**应用不会报错**） |
+| 页面 404 但接口正常 | 穿透/网关指到了哪个端口 | H5 由 nginx 托管（80），**指到后端的 8080 就只剩接口**；另看 `deploy/.env` 的 `H5_DIR` 是否指向真实产物目录（目录不存在时 docker 会建一个**空目录**，nginx 一切正常而页面 404） |
+| 上传报 413（后端日志里没有这条请求） | nginx 的 `client_max_body_size` | 默认 1m；`deploy/nginx/xt.conf` 已设 50m，**换网关时别漏这一条** |
+| 本机 8080 被别的项目占用 | `netstat -ano \| findstr :8080` | 用 `--server.port=8081` 起后端，e2e 脚本加 `XT_BASE=http://localhost:8081`（脚本读这个环境变量）；**不要去杀别人的进程** |
 | 定时任务没生效 | 手工触发一次：`POST /api/v1/schedules/run {"job":"close"}` | 见下 |
 | 「查不到数据」但库里有 | 租户上下文 | 定时任务/匿名接口的线程里没有登录用户，租户拦截器默认拒绝 |