fix(deploy): 冒烟脚本与 prod Swagger 开关解耦，默认改联调口径

为什么：prod profile 下 SWAGGER_ENABLED 默认 false 会把 /doc.html 与 /v3/api-docs 一起关掉，
而 smoke.sh 硬期望这两者 200 —— 照文档默认配置部署完，冒烟必然假失败，会被误判成"部署挂了"；
且联调（10-19）需要 /doc.html 在线可查。

- smoke.sh 自适应：显式 SWAGGER_ENABLED 优先；未设置则自动探测（200+openapi=开、统一信封
  code=404=关、其它响应仍 FAIL）；关闭时这三项打印 SKIP 而不是 FAIL，开启时照旧断言 200（断言未删）
- 新增 SWAGGER_REQUIRED 硬开关：联调环境可要求文档必须在线，不满足直接失败
- .env.example 默认改 SWAGGER_ENABLED=true，并写明该开关一次管两个端点
- DEPLOY.md 同步口径与冒烟说明
- 实测：prod+false 时 SKIP + 其余全 PASS + 退出码 0；prod+true 时两端口 /v3/api-docs 与 /doc.html 均 200；
  mvn test 83 条全过、两入口 package 通过

DEPLOY.md

@@ -30,7 +30,7 @@
 | `CORS_ALLOWED_ORIGINS` | 🔴 | prod 下为空则拒绝启动 | 逗号分隔的正式来源，**生产不许用 `*`** |
 | `MEDIA_ROOT_DIR` | 建议 | 默认 `./data/uploads`，容器里必须为 `/data/uploads` | 媒资根目录（挂载卷） |
 | `SERVER_PORT` | Compose 已设 | 默认 8081/8080 | app-api 8081 / admin-api 8080 |
-| `SWAGGER_ENABLED` | 可选 | 默认 false | 生产是否开放 `/doc.html` 与 `/v3/api-docs` |
+| `SWAGGER_ENABLED` | 可选 | 默认 false（**测试/联调请在 `.env` 里设 `true`**，前端要看 `/doc.html`） | **一次开关两个**：`true` = `/doc.html` + `/v3/api-docs` 都开；`false` = 两个都关（生产不想暴露 UI 就设 false，机器可读契约也一并关闭） |
 | `STORE_VERIFIER` / `GOOGLE_PLAY_*` | 可选 | 默认 `disabled` | 商店票据校验，没凭据就保持 disabled（对外返回"尚未配置"） |
 
 **密钥怎么生成**：`openssl rand -base64 48`（每个密钥单独生成，别复用）。
@@ -124,9 +124,13 @@ exit code = **1**（部署脚本可以直接判失败）。**没有 prod profile
 1. `docker compose ps`：三个应用容器 `Up (healthy)`（worker 是 `Up`）。
 2. `tools/smoke.sh`：全 PASS、退出码 0。它检查 `/healthz`、`/app/categories`、`/app/home/feed`、
    两个 `/v3/api-docs`、`/doc.html`，以及未授权路径是否按统一信封拒绝。
+   **关于在线文档那三项**：脚本会按 `SWAGGER_ENABLED` 自适应 —— `true` 时断言 200；
+   `false` 时打印 **SKIP**（不算失败），因为 `/doc.html` 与 `/v3/api-docs` 都被配置关掉了。
+   没设这个变量时脚本自动探测（"200 且含 openapi"算开，"统一信封 code=404"算关，其它响应→FAIL）。
+   联调环境想强制要求文档在线：`SWAGGER_REQUIRED=true tools/smoke.sh`（不满足直接失败）。
 3. `curl -s http://127.0.0.1:8081/healthz`：（从容器里或宿主机）应返回 `{"code":0,...,"status":"UP"}`。
 4. 业务抽查：`curl -s http://127.0.0.1:8081/app/home/feed | head -c 200`（有内容）；
-   后台 `http://127.0.0.1:8080/doc.html`（若 `SWAGGER_ENABLED=true`）。
+   后台 `http://127.0.0.1:8080/doc.html`（**需要 `.env` 里 `SWAGGER_ENABLED=true`**，联调环境请打开）。
 5. 登录一个后台账号，确认能进后台首页（连通数据库与权限体系）。
 
 ## 七、回滚