提供独立路径的海外PDA测试H5部署

README.md

@@ -74,3 +74,19 @@ Android App 启动后会读取 `VITE_PDA_UPDATE_URL` 并检查海外 PDA 的独
 2. wgt 发布至少递增 `versionName`，并使用与已安装原生包兼容的 uni-app 编译器生成；新增原生模块、权限或不兼容运行时能力时必须发布 APK，不能只发 wgt。
 3. 更新清单与下载地址使用 HTTPS，先在测试设备验证可选更新、强制更新、断网重试、APK 覆盖安装、wgt 重启及扫码作业回归，再切换正式清单。
 4. 海外和国内更新记录、文件目录及发布权限保持隔离，服务端必须按请求中的 `appid` 拒绝跨应用更新包。
+
+## TEST H5 静态托管
+
+发布构建使用 `/pda-overseas/` 资源 base 与 hash 路由；开发服务仍使用根路径。浏览器入口为 `/pda-overseas/#/`，不能将 Vite 开发代理当作静态服务器配置。
+
+执行 `npm run build:h5`。无需启动 Vite 开发服务器；`npm run build:app` 不属于 H5 发布。
+
+`deploy/Dockerfile.h5` 只复制已构建 `dist/build/h5/` 及静态 Nginx 配置，不在镜像中复制源码、依赖或重新编译。`.dockerignore` 只放行这两类输入。容器静态目录为 `/srv/pda-h5/pda-overseas/`。
+
+从本仓库执行 `docker compose -f deploy/docker-compose.h5.test.yml build --pull=false`，再由获授权的部署流程执行 `docker compose -f deploy/docker-compose.h5.test.yml up -d --wait --wait-timeout 120`。必须设置 `IMAGE_TAG`，`NGINX_BASE_IMAGE` 可指定已缓存的兼容 Alpine Nginx 镜像。容器名及网络别名为 `pda-overseas-h5-test`，仅在外部 `firstleg-test-network` 暴露容器 80，不发布宿主端口。健康检查同时请求 `/healthz` 与 `/pda-overseas/` 的实际首页。
+
+Admin Nginx 将 `/pda-overseas/` 原样代理至 `http://pda-overseas-h5-test:80`，不去掉路径前缀；无尾斜杠入口重定向为 `/pda-overseas/`。PDA 容器只提供本应用静态目录，其他路径返回 404，缺失资源不回退首页，HTML 使用 `Cache-Control: no-store`。API 全部由 Admin 入口代理：国内 `/gateway-api/` 转统一 Gateway `/api/`，海外同源 `/api/` 保持路径。入口须保留 Authorization，支持文件上传下载及至少 11m 请求体。环境域名与上游只在部署侧配置，不修改宿主 Nginx 权限，也不编入 PDA 源码。
+
+部署配置检查：`node --test tests/h5-deployment.test.mjs`。没有 Docker 运行时的本地合同检查不能替代目标主机 `docker compose config`、Nginx 启动与真实 HTTP 验收。
+
+构建后执行 `node scripts/verify-h5.mjs`，核对 HTML/JS/CSS 资源路径、同源 API 和无本机/旧海外配置泄漏。该检查与本地构建仅证明产物；TEST 页面登录、仓权限、业务操作和 Android 真机另行验收。