XuqmGroup-Web/docs/SDK_PLATFORM_V2_HANDOFF.md

# 租户平台 SDK V2 页面接手说明

SDK 平台的完整服务端契约见 Server 仓库 `docs/SDK_PLATFORM_V2_HANDOFF.md`。

当前 Web 变更：

- 应用详情展示 Config 的配置 ID、版本、签发时间和到期时间。
- 重新生成 Config 时必须明确选择长期有效或指定到期时间；指定时间必须晚于当前时间，并以 ISO 8601 UTC 传给服务端。
- BugCollect 页面统一展示 `RN_SOURCEMAP` 和 `R8_MAPPING`，手动上传示例使用 `/bugcollect/v1/artifacts/upload`。
- 产物上传示例只使用 `Authorization: Bearer XUQM_API_TOKEN`，不得把 Token 放入 URL。
- 已删除废弃的离线 license 服务页面、路由、API、菜单和日志入口。
- 依赖管理统一为根 `package.json` 声明的 Yarn 1 与 `yarn.lock`。
- `Jenkinsfile.tenant-web` 默认 development，仅验证；production 需要人工确认才允许推送、部署和提交版本号。
- Web 生产缓存使用版本目录协议：入口 HTML/manifest 禁止持久缓存，哈希资源使用
  `releases/<SERVICE_VERSION>/assets/` 和一年 `immutable`。
- Jenkins 构建会把上一 `latest` 镜像作为 `PREVIOUS_IMAGE`；新镜像只保留上一版本的
  当前资源目录和本次资源目录。首次从旧布局迁移时保留一次旧 `/assets`，下一版本自动
  淘汰，避免资源无限累积。
- 哈希资源 location 使用 `try_files $uri =404`，不得回退到 SPA `index.html`。

验证：

```bash
yarn install --frozen-lockfile
yarn build:tenant
yarn build:ops
yarn workspace @xuqm/docs-site build
yarn test:web-cache
nginx -t -p "$PWD/" -c scripts/nginx-test.conf
```

2026-07-27 缓存契约测试会使用固定 release ID 重新构建 tenant、ops 与 docs，并校验
HTML 引用、版本目录、Nginx 缓存头及 Docker 上一版本保留门禁。

Jenkins 和线上部署需由发布流程另行执行；本地构建不能代替生产响应头验收。
# 2026-07-27 Jenkins SCM 凭据收口

- tenant-web 显式 checkout 已改用 Gitea SSH URL 和 Jenkins
  `jenkins-ssh-key`，不再引用未配置的 `XUQM_GIT_CREDENTIALS`；其它 Web 作业继续
  复用各自 Jenkins SCM 配置。三套 Web 流水线的版本文件回写均使用
  `sshagent(jenkins-ssh-key)`，避免 checkout 结束后 push 缺少凭据。
- 该修改尚未通过下一次 Web Jenkins 构建验证；缓存策略提交部署前必须先确认
  checkout 与三套前端构建均成功。