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

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`（单域托管前端）