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

2026-05-31 09:47:52 +08:00
@@ -0,0 +1,60 @@
+# 实施说明
+
+## 只读排查结论
+
+- `cd server && npx prisma migrate status` 显示本地回归库 `hyb_oa_regression` 有 12 个迁移未应用：
+  - `20260513214500_biz8_purchase_project_link`
+  - `20260517090437_cashier_payment_receipts`
+  - `20260517145928_attendance_unified_wecom_sync`
+  - `20260517200040_hr_wecom_directory_v1`
+  - `20260518184319_wecom_hr_master_sync_v1`
+  - `20260519223206_wecom_approval_archive_minimum_v1`
+  - `20260520124804_wecom_checkin_summary_archive_v1`
+  - `20260522191833_asset_governance_v1`
+  - `20260524193000_owner_self_fallback_role`
+  - `20260526211500_email_code_login`
+  - `20260528113000_policy_acknowledgements`
+  - `20260528162000_business_attachment_governance_v1`
+- 实际列检查显示当前库只命中 `employees.employee_no`，缺少 `asset_cards.asset_type`、`asset_cards.sensitivity_level`、`purchase_requests.project_id`、`approval_rules.owner_self_fallback_role` 等当前代码依赖字段。
+- 缺列来源与未应用迁移一致：
+  - `purchase_requests.project_id` 来自 `20260513214500_biz8_purchase_project_link`
+  - `asset_cards.asset_type` 来自 `20260522191833_asset_governance_v1`
+  - `approval_rules.owner_self_fallback_role` 来自 `20260524193000_owner_self_fallback_role`
+
+## 风险判断
+
+- 这不是前端资产页面问题，也不是 `assets-flow.spec.ts` 的测试假设问题；根因是本地回归库落后于 Prisma schema 和应用代码。
+- 未应用迁移粗查未发现 `DROP`、`TRUNCATE` 或数据库 reset；主要是新增列、表、索引、外键，以及给审批规则兜底角色补默认值。
+- 仍属于数据库结构变更，按项目规则需要明确确认后再执行。
+
+## 建议处理
+
+- 在本地回归库执行 `cd server && npx prisma migrate deploy`，只应用已提交迁移，不做 reset。
+- 应用后运行：
+  - `cd server && npm run prisma:validate`
+  - `cd server && npm run seed:dev-users`（如命令存在且当前测试依赖本地账号）
+  - 聚焦 `assets-flow.spec.ts`
+  - 必要前端回归：`cd client && npm run typecheck && npm run build`
+  - `python3 ./.trellis/scripts/task.py validate 05-31-fix-assets-e2e-schema-drift`
+  - `node scripts/qa/check-trellis-governance.mjs`
+  - `git diff --check`
+
+## 执行结果
+
+- 已获得用户确认后执行 `cd server && npx prisma migrate deploy`，12 个待应用迁移全部成功应用到本地回归库。
+- `cd server && npx prisma migrate status` 复查显示数据库结构已是最新。
+- 关键字段复查已命中：
+  - `approval_rules.owner_self_fallback_role`
+  - `asset_cards.asset_type`
+  - `asset_cards.sensitivity_level`
+  - `purchase_requests.project_id`
+  - `employees.employee_no`
+- `cd server && npm run seed:dev-users` 已完成，开发账号与基础资料可用。
+- `cd client && E2E_BASE_URL=http://127.0.0.1:3000 npx playwright test tests/e2e/assets-flow.spec.ts --workers=1 --reporter=list` 已通过。
+- E2E 修正点：
+  - 创建资产后页面已经进入详情，不再点击列表页旧的 `全范围` 按钮。
+  - 资产详情同时展示流转摘要和资产摘要，归属人/位置断言改为匹配首个可见命中，避免 Playwright strict mode 误判。
+- 本地服务启动修正：
+  - `server/src/index.js` 在读取配置前显式加载 `dotenv/config`，避免 `npm run dev` 在本地 `.env` 存在时仍因缺少 `JWT_SECRET` 失败。
+- 已用正常 `npm run dev` 启动本地服务，并通过 `/ready` 与资产真实 E2E 复核，不再依赖 `node -r dotenv/config` 启动绕过。
+- 已更新 `.trellis/spec/hyb-oa/backend-fastify-prisma.md`，沉淀本地回归库迁移漂移和 server dotenv 启动顺序规则。