chore: split dev and production deployment env

docs/ENVIRONMENT_DEPLOYMENT.md

@@ -0,0 +1,91 @@
+# 环境拆分与流水线规则
+
+`role-user` 是 Next.js standalone 服务。测试环境和生产环境通过独立部署目录、独立运行时环境变量和独立后端 API 地址拆分。
+
+## 环境约定
+
+| 环境 | 触发方式 | 代码依据 | 构建命令 | 默认部署目录 | 默认端口 | 后端 API |
+| --- | --- | --- | --- | --- | --- | --- |
+| 测试环境 | `develop` 合并后自动触发 Jenkins | `develop` 最新提交 | `pnpm build:test` | `/srv/www/test/role-user/current` | `3211` | `http://127.0.0.1:3501/api` |
+| 生产环境 | Jenkins 手动触发 | Gitea 项目 Tag | `pnpm build:prod` | `/srv/www/production/role-user/current` | `3210` | `http://127.0.0.1:3500/api` |
+
+生产环境禁止因代码合并自动部署。生产部署时必须在 Jenkins 参数中选择 `DEPLOY_ENV=production` 并填写已存在的 `RELEASE_TAG`。
+
+## Jenkins 参数
+
+| 参数 | 说明 |
+| --- | --- |
+| `DEPLOY_ENV` | `test` 或 `production`。默认 `test`。 |
+| `RELEASE_TAG` | 生产环境必填，必须是 Gitea 仓库中已存在的 Tag。 |
+| `SKIP_DEPLOY` | 为 `true` 时只执行安装、检查、构建，不部署。 |
+
+`Jenkinsfile` 会强制校验：
+
+- 测试环境只在 `develop` 分支自动部署。
+- 生产环境必须手动触发。
+- 生产环境必须填写 `RELEASE_TAG`。
+- 生产环境构建会先 checkout 到该 Tag 对应的提交，再部署。
+
+## 运行时环境变量
+
+真实环境变量必须留在服务器，不提交到仓库。
+
+部署脚本默认读取：
+
+```text
+/srv/www/test/role-user/shared/.env.test
+/srv/www/production/role-user/shared/.env.production
+```
+
+示例文件：
+
+```text
+.env.test.example
+.env.production.example
+```
+
+`ACCESS_MANAGE_API_BASE_URL` 是服务端 BFF 使用的运行时变量，不加 `NEXT_PUBLIC_`，不会暴露到浏览器 bundle。Cookie 名测试和生产应分开，避免同域下会话互相覆盖。
+
+## standalone 产物
+
+`next.config.ts` 已启用 `output: "standalone"`。Jenkins 构建后会打包：
+
+```text
+.next/standalone
+.next/static
+public
+```
+
+部署脚本会发布到：
+
+```text
+${DEPLOY_BASE_DIR}/${DEPLOY_ENV}/role-user/releases/<build>-<commit>
+```
+
+并更新：
+
+```text
+${DEPLOY_BASE_DIR}/${DEPLOY_ENV}/role-user/current
+```
+
+如果 Jenkins 不在目标服务器上运行，可以配置：
+
+```text
+DEPLOY_REMOTE=user@server
+```
+
+## 生产发布流程
+
+1. 在需要发布的提交上创建 Tag。
+2. 推送 Tag 到 Gitea。
+3. Jenkins 手动 Build With Parameters。
+4. 选择 `DEPLOY_ENV=production`。
+5. 填写 `RELEASE_TAG`。
+6. 执行构建部署。
+
+示例：
+
+```bash
+git tag -a v2026.06.05-1 -m "role-user production release 2026-06-05"
+git push origin v2026.06.05-1
+```