修复资产 E2E 数据库漂移（05-31-fix-assets-e2e-schema-drift）

.trellis/spec/hyb-oa/backend-fastify-prisma.md

@@ -23,6 +23,83 @@ QA script patterns over new abstractions.
 - `cd server && ./scripts/regression-workflow-actions.sh`
 - `cd server && ./scripts/regression-all.sh`
 
+## Scenario: Local Regression Migration Drift
+
+### 1. Scope / Trigger
+
+- Trigger: a local or attached E2E fails with Prisma `missing column`,
+  `column does not exist`, enum missing, or route 500 immediately after a
+  schema-backed feature was added.
+- Applies to `server/prisma/schema.prisma`, `server/prisma/migrations/`,
+  local regression databases such as `hyb_oa_regression`, and Playwright tests
+  that use real API/database flows.
+
+### 2. Signatures
+
+- Read-only drift check: `cd server && npx prisma migrate status`.
+- Apply committed migrations after explicit confirmation:
+  `cd server && npx prisma migrate deploy`.
+- Local service smoke for attached E2E:
+  `HOST=127.0.0.1 PORT=3000 JOBS_ENABLED=false SERVE_CLIENT_DIST=true npm run dev`.
+- Server entrypoints that call `getConfig()` before `buildApp()` must load
+  `dotenv/config` before reading config.
+
+### 3. Contracts
+
+- `migrate status` is safe and read-only; it may be run before asking the user.
+- `migrate deploy` writes database schema state and requires explicit user
+  confirmation unless the current task already approved that exact local DB.
+- Do not use `prisma migrate reset` for E2E recovery without separate backup
+  and destructive-action approval.
+- Attached local E2E should disable background jobs with `JOBS_ENABLED=false`
+  unless the test explicitly validates job behavior.
+
+### 4. Validation & Error Matrix
+
+- `migrate status` reports pending migrations -> record the migration names,
+  inspect whether they are additive/destructive, then ask before applying.
+- Missing `JWT_SECRET` during `npm run dev` while `.env` exists -> verify the
+  entrypoint loads `dotenv/config` before `getConfig()`.
+- Missing column after `migrate deploy` -> inspect actual columns and migration
+  history; do not patch tests to hide schema drift.
+- E2E selector failure after schema is fixed -> treat as page/test contract
+  drift and update the focused E2E assertion, not the database.
+
+### 5. Good/Base/Bad Cases
+
+- Good: run `migrate status`, apply only committed migrations after approval,
+  seed dev users, then rerun the focused Playwright flow.
+- Base: if migrations are already current, skip DB writes and debug the test
+  failure directly.
+- Bad: use `migrate reset` or manually add columns to unblock a test.
+- Bad: start the server with an ad hoc `node -r dotenv/config` workaround and
+  leave `npm run dev` broken.
+
+### 6. Tests Required
+
+- `cd server && npm run prisma:validate`.
+- `bash scripts/qa/check-local-migration-drift.sh` when local DB drift was the
+  cause.
+- `cd server && node --check src/index.js` if server bootstrap changed.
+- Focused Playwright flow that previously failed.
+- Frontend `npm run build` when Playwright or client behavior changed.
+
+### 7. Wrong vs Correct
+
+#### Wrong
+
+```bash
+cd server && npx prisma migrate reset
+```
+
+#### Correct
+
+```bash
+cd server && npx prisma migrate status
+# after explicit approval for the local regression database only
+cd server && npx prisma migrate deploy
+```
+
 ## Scenario: Portal Announcement Acknowledgement
 
 ### 1. Scope / Trigger