oa-email-code-login 记录部署公网验证

.trellis/spec/hyb-oa/deployment-trialrun.md

@@ -9,9 +9,79 @@ operations require explicit approval and evidence.
 
 - Use `SYNC_ENV=0 bash deploy/trialrun/deploy.sh` only when deployment is
   approved; do not overwrite remote `.env`.
+- When `server/src/config.js` reads a new environment key, add the same key to
+  `deploy/trialrun/.env.example` before deployment; `deploy/trialrun/deploy.sh`
+  runs `node deploy/trialrun/validate-env-contract.js` at step 0 and must fail
+  if the example contract drifts.
 - After deployment, report commit hash, `/ready`, public smoke results and
   whether the user can test.
 - Real business writes are manual unless an Issue explicitly authorizes a
   controlled test write.
 - Do not execute real payments, import bank statements, connect payment
   providers or write ERP without a separate approved Issue.
+
+## Scenario: Deployment Env Contract
+
+### 1. Scope / Trigger
+
+- Trigger: any backend config, deployment compose, or trialrun env wiring change.
+- Purpose: prevent deploy-time surprises where local code compiles but the
+  deployment contract rejects the release or silently misses a runtime default.
+
+### 2. Signatures
+
+- Command: `node deploy/trialrun/validate-env-contract.js`
+- Deployment entry: `SYNC_ENV=0 bash deploy/trialrun/deploy.sh`
+- Contract sources:
+  - `server/src/config.js`
+  - `deploy/trialrun/.env.example`
+  - `deploy/trialrun/docker-compose.yml`
+
+### 3. Contracts
+
+- Every `process.env.KEY` or `requiredEnv("KEY")` in `server/src/config.js`
+  must be present in `deploy/trialrun/.env.example`.
+- `server`, `worker`, and `init` services must load `./.env` through
+  `env_file`.
+- Compose service-level `environment` overrides are limited to the explicit
+  allowlist in `validate-env-contract.js`.
+- `SYNC_ENV=0` is the default public deploy mode; it does not overwrite remote
+  `.env`.
+
+### 4. Validation & Error Matrix
+
+- Missing key in `.env.example` -> `validate-env-contract.js` exits non-zero.
+- Service omits `env_file: ./.env` -> contract exits non-zero.
+- Unauthorized compose override -> contract exits non-zero.
+- Remote `.env` missing -> deploy step 4 exits before migration.
+
+### 5. Good/Base/Bad Cases
+
+- Good: add `EMAIL_LOGIN_CODE_TTL_SECONDS` to `config.js`, document it in
+  `.env.example`, then run contract validation before deploy.
+- Base: code-only feature without env changes still runs the contract gate.
+- Bad: add a config key only in `config.js`; deploy fails at step 0.
+
+### 6. Tests Required
+
+- Always run `node deploy/trialrun/validate-env-contract.js` after env-related
+  changes and before public deployment.
+- For public deploys, also run or verify `/ready`, runtime smoke, external deps
+  smoke, public bundle copy scan, and live smoke when credentials exist.
+
+### 7. Wrong vs Correct
+
+#### Wrong
+
+```bash
+# Config key exists only in server/src/config.js.
+SYNC_ENV=0 bash deploy/trialrun/deploy.sh
+```
+
+#### Correct
+
+```bash
+# Add the key to deploy/trialrun/.env.example first.
+node deploy/trialrun/validate-env-contract.js
+SYNC_ENV=0 bash deploy/trialrun/deploy.sh
+```