R26-4 R26-5: 优化开关报错并补部署检查清单

deploy/trialrun/checklist.md

@@ -8,6 +8,8 @@
 - [ ] 已在服务器创建 OA 目录（默认 `/opt/hyb-oa-trialrun`）
 - [ ] 已准备 `deploy/trialrun/.env`，并将 `APP_ORIGIN` 改为 OA 公网域名
 - [ ] 已将 `COOKIE_SECURE` 设为 `true`
+- [ ] 已确认 `deploy/trialrun/.env` 作为部署事实源，新增环境变量优先补到该文件
+- [ ] 已尽量使用无引号 env 值；历史带引号值当前兼容，但建议逐步清理
 - [ ] 已将 OA Nginx 配置放到 `/etc/nginx/sites-available/hyb-oa`
 - [ ] 已上传 OA 域名证书到 `/etc/nginx/ssl/<oa-domain>/`
 - [ ] 已执行 `nginx -t && systemctl reload nginx`
@@ -20,6 +22,7 @@
 ## A. 发布前（Pre-flight）
 - [ ] 确认当前版本已打 tag：`git tag -a trialrun-YYYYMMDD-NN -m "trialrun release"`
 - [ ] 本地门禁：`./scripts/check-minimal.sh`
+- [ ] 部署契约校验：`node deploy/trialrun/validate-env-contract.js`
 - [ ] 全量回归（建议）：`cd server && RUN_AUDIT_REGRESSION=1 RUN_OCR_REGRESSION=1 ./scripts/regression-all.sh`
 - [ ] 备份（DB + 文件存储）：
   - [ ] `set -a && source deploy/trialrun/.env && set +a`
@@ -33,6 +36,8 @@
   - [ ] `docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env run --rm init`
 - [ ] 探活：
   - [ ] `curl -fsS http://127.0.0.1:3000/ready`
+- [ ] Runtime smoke：
+  - [ ] `docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env exec -T server node src/scripts/smoke-trialrun-runtime.js`
 - [ ] 登录验证（管理员账号）：
   - [ ] 访问 `http://127.0.0.1:3000`
   - [ ] 登录成功，菜单权限正确

deploy/trialrun/runbook.md

@@ -29,6 +29,12 @@ cp deploy/trialrun/.env.example deploy/trialrun/.env
 - `JWT_SECRET`
 - `APP_ORIGIN`（建议与对外域名一致，例如 `https://oa.example.com`）
 
+环境变量约束：
+- `deploy/trialrun/.env` 现在是 trialrun 部署事实源，`server / worker / init` 统一通过 `env_file` 注入。
+- 推荐使用无引号值，例如 `COOKIE_SECURE=true`、`PORT=3000`。
+- 历史上已经写成带引号的 `.env` 当前仍兼容，但建议后续逐步改成无引号。
+- 正式部署前可先执行 `node deploy/trialrun/validate-env-contract.js` 做静态契约检查。
+
 作业系统建议：
 - 试运行默认 `JOB_DRIVER=pgboss`（基于 Postgres 的队列调度，单机/多进程语义更稳）
 - 如需快速回滚作业调度：将 `JOB_DRIVER` 改回 `cron`
@@ -41,6 +47,7 @@ cp deploy/trialrun/.env.example deploy/trialrun/.env
 ### 1.2 启动数据库与服务
 ```bash
 cd /path/to/hyb-oa
+node deploy/trialrun/validate-env-contract.js
 docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env up -d db
 docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env up -d --build server
 ```
@@ -77,8 +84,13 @@ docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/
 curl -fsS http://127.0.0.1:3000/health
 curl -fsS http://127.0.0.1:3000/ready
 curl -fsS http://127.0.0.1:3000/metrics | head
+docker compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env exec -T server node src/scripts/smoke-trialrun-runtime.js
 ```
 
+说明：
+- `deploy/trialrun/deploy.sh` 现已自动执行 `validate-env-contract.js`、`/ready` 探活与 `smoke-trialrun-runtime.js`。
+- 若再出现“数据库开了但功能被环境硬关”的情况，部署会直接失败，不再等到手工点页面才发现。
+
 浏览器访问：
 - `http://127.0.0.1:3000`（单域托管前端）