hyb-oa/.trellis/tasks/08-07-local-database-migration-readiness/implement.md

# 实施计划

> 当前状态：迁移与接口基线已完成；数据库结论 PASS，浏览器回归为 PASS_WITH_FINDINGS（16/10/0），待只读 review 和收口门禁。

## 1. 执行前固定现场

- [x] 记录当前 HEAD、当前 task、`git status --porcelain`；发现非本任务脏文件时停止确认。
- [x] 确认 `08-05-contract-detail-workspace` 仍为 planning，未提前开始 schema 实施。
- [x] 确认 `artifacts/qa-flow/08-07-local-database-migration-readiness/` 为 gitignored 本地证据目录。
- [x] 复读 `prd.md`、`design.md`、`.trellis/spec/hyb-oa/backend-fastify-prisma.md` 和 `docs/试运行与自动化验证手册.md` 的 migration drift 边界。

## 2. Pre-status 只读基线

- [x] 运行：
  `MIGRATION_DRIFT_REPORT_DIR=artifacts/qa-flow/08-07-local-database-migration-readiness/pre bash scripts/qa/check-local-migration-drift.sh`
- [x] 从原始输出记录 Prisma 实际退出状态；不得把 wrapper 的最终退出 0 当作“无 pending migration”。
- [x] 只记录脱敏目标结论，确认 datasource 为预期回环本地开发数据库。
- [x] 逐项记录 pending migration ID，并复读对应 `migration.sql`。
- [x] pending 集合属于以下已核查 allowlist 子集；本次实际集合为全部六条：
  - `20260717120000_auth_challenge_trusted_proxy_hardening`
  - `20260718120000_add_system_admin_role`
  - `20260718123000_small_team_payment_cancel_reason`
  - `20260727153000_allow_employee_phone_null`
  - `20260801120000_reimbursement_travel_summary`
  - `20260802143000_corporate_bank_account_payment_order`
- [x] 运行 `cd server && npm run prisma:validate`，结果 PASS。

### 强制停止条件

- [x] 目标非回环、目标不明或不是预期本地开发库 → `PAUSED`，零写入；本次未触发，已确认 loopback=true。
- [x] status 显示 failed migration、history divergence、applied migration 异常或 allowlist 外 pending → `PAUSED`，回来确认。— 第一次 pre-status 发现 3 条原 allowlist 外 pending 后已暂停；用户已复核 SQL并明确批准扩展到全部 6 条，继续前须再次确认 pre-status 未变化。
- [x] 实际 SQL 包含删除表、删除列、清空数据、重置或其他未规划破坏性操作 → `PAUSED`，回来确认；六条均未命中，本次未触发。
- [x] status 已是最新但 `/api/me` 仍缺列 → 不运行 deploy，转只读诊断并 `PAUSED`；本次 deploy 后 status current，未触发。

## 3. 唯一迁移写入

- [x] pre-status 非 current，未记录 `SKIPPED_ALREADY_CURRENT`。
- [x] 存在允许的 pending migration，仅运行一次：
  `cd server && npm run prisma:migrate:deploy`
- [x] 记录退出状态和应用的六个 migration ID，不复制数据库连接信息；命令退出码为 0。
- [x] 若命令失败，立即保存输出并只读重跑 status；本次未失败，且未运行 `migrate dev/reset/db push/resolve`、手工 DDL 或迁移历史修改。

## 4. Post-status 与接口基线

- [x] 运行：
  `MIGRATION_DRIFT_REPORT_DIR=artifacts/qa-flow/08-07-local-database-migration-readiness/post MIGRATION_DRIFT_STRICT=1 bash scripts/qa/check-local-migration-drift.sh`
- [x] 确认 strict 退出 0、同一目标、无 pending/failed/diverged migration；原始 post-status 已保存。
- [x] `cd client && npm run build` PASS，并使用当前 checkout 的前端产物启动本地服务；第一次启动缺少必需的字段加密配置，所对应的回归结果作废，随后已用回环 host、`JOBS_ENABLED=false`、`SERVE_CLIENT_DIST=true` 重启并完成有效验证。
- [x] 通过现有认证链路确认 `/api/me` 返回 200；employee、manager、finance、finance manager、admin 五类 fixture 均为 login=200、me=200，未再出现缺列错误。

## 5. 五个用例补跑

- [x] 运行（第二轮、有效服务配置）：
  `cd client && npx playwright test tests/e2e/procurement-flow.spec.ts tests/e2e/assets-flow.spec.ts tests/e2e/r103-cross-page-ui-consistency.spec.ts tests/e2e/pc-detail-mobile-visual-wave3.spec.ts tests/e2e/global-search.spec.ts --workers=1 --reporter=list`
- [x] 分别记录五个 spec：
  - [x] `procurement-flow.spec.ts`：0 passed / 1 failed / 0 skipped；创建采购后审批摘要仍期待历史英文 `Employee`，实际页面已返回中文申请人摘要。
  - [x] `assets-flow.spec.ts`：0 passed / 1 failed / 0 skipped；创建 API 成功后页面仍停留 `/assets/new`，未跳到预期 canonical 详情路由。
  - [x] `r103-cross-page-ui-consistency.spec.ts`：4 passed / 7 failed / 0 skipped；失败集中在合同标题、采购/资产详情及未保存/中等宽度场景，多个上下文回到登录页。
  - [x] `pc-detail-mobile-visual-wave3.spec.ts`：9 passed / 0 failed / 0 skipped。
  - [x] `global-search.spec.ts`：3 passed / 1 failed / 0 skipped；canonical path 用例第二次回到 portal 后搜索触发器等待超时并落到登录页。
- [x] 记录第二轮总数：16 passed / 10 failed / 0 skipped（26 tests）；第一次缺少本地服务必需加密配置时的 17/9 结果明确作废，不计入最终证据；记录不含凭据、token、原始 payload 或完整本地路径。
- [x] 明确采购、资产真实流产生的本地合成测试记录属于获批副作用；未执行清理、seed 或 reset。

## 6. 失败分流

- [x] migration/status/缺列导致的失败：本次未发生；post strict 与 `/api/me` 均通过，数据库基线层结论为 PASS。
- [x] `/api/me` 已 200 后的路由、页面行为或选择器失败：全部归为产品路由/页面契约或测试桩会话夹具问题，登记为 `08-05-business-detail-routing` follow-up 候选；本任务未改代码/测试。
- [x] 业务前置数据不足：本次未据此归因，也未自动 seed；真实流失败均有可复现的页面/断言首个失败证据。
- [x] 本地服务/端口问题：第一次服务启动配置不完整，已仅恢复当前 checkout 的安全启动条件；未修改产品功能。
- [x] 任何 spec 失败时，未把“数据库基线恢复”写成“五个用例全绿”；已分别记录数据库 PASS 与浏览器 `PASS_WITH_FINDINGS`（16/10/0）。

## 7. 只读 Review

- [x] 启动只读 reviewer，明确 reviewer 不修改文件。
- [x] Reviewer 核对：回环目标、pre/post status、pending allowlist、唯一 deploy 命令、禁用命令未执行、无业务代码/schema/test 改动、失败分类真实；结论 PASS，未修改文件、未运行长测试。
- [x] Reviewer 核对合同任务仍未在迁移基线形成前启动；`08-05-contract-detail-workspace` 仍为 planning。

## 8. 收口门禁

- [x] `python3 ./.trellis/scripts/task.py validate 08-07-local-database-migration-readiness` PASS。
- [x] `node scripts/qa/check-trellis-governance.mjs --json` PASS，0 errors / 0 warnings。
- [x] `git diff --check` PASS。
- [x] 检查 git diff：`git status --porcelain` 仅包含当前 Trellis task 目录；`artifacts/` 保持 ignored，无 server/client/schema/migration/test 改动。
- [x] PRD Acceptance Criteria 按真实证据勾选；非数据库失败保留 `PASS_WITH_FINDINGS`，未伪装为 PASS。
- [ ] 使用中文 commit message 并引用 `08-07-local-database-migration-readiness`；不 push、不部署。— 待用户确认提交计划后执行。

## 9. 执行记录

规划阶段留空。任务启动后按以下字段回填：

- HEAD：`0124a2b`
- Pre status reportRef：`artifacts/qa-flow/08-07-local-database-migration-readiness/pre/prisma-migrate-status.txt`
- Pre Prisma exit/status：Prisma status `1`；wrapper 按设计返回 `0`，人工核读为 6 条 pending。
- Loopback/target match：`loopback=true`，预期本地回归数据库匹配。
- Pending migration IDs：
  - `20260717120000_auth_challenge_trusted_proxy_hardening`（当前 allowlist 外；增加认证挑战字段/索引，并使本地未使用验证码失效）
  - `20260718120000_add_system_admin_role`（当前 allowlist 外；增加 enum 值）
  - `20260718123000_small_team_payment_cancel_reason`（当前 allowlist 外；增加可空字段）
  - `20260727153000_allow_employee_phone_null`
  - `20260801120000_reimbursement_travel_summary`
  - `20260802143000_corporate_bank_account_payment_order`
- Deploy：`2026-08-07` 执行一次 `cd server && npm run prisma:migrate:deploy`，exit=0；六条 pending 全部成功应用。
- Post status reportRef：`artifacts/qa-flow/08-07-local-database-migration-readiness/post/prisma-migrate-status.txt`
- Post Prisma exit/status：Prisma 原始 status exit=0（strict wrapper exit=0）；输出为 `Database schema is up to date!`，同一 datasource、无 pending/failed/diverged。
- `/api/me`：五类本地 fixture（employee、manager、finance、finance manager、admin）login=200、me=200；未出现 `employees.bank_institution_id` 缺列错误。
- Five-spec result：26 tests，16 passed / 10 failed / 0 skipped；按 spec 数字见第 5 节。`pc-detail-mobile-visual-wave3.spec.ts` 全绿，其余四个含失败。
- Failure classification：数据库迁移层 PASS；10 条失败均在迁移对齐和 `/api/me` 恢复后出现，归为路由/页面行为、E2E 断言契约或 mock 会话夹具问题，登记 `08-05-business-detail-routing` follow-up 候选；本任务未改产品代码、测试或数据。
- Read-only review：PASS；bounded reviewer 只读完成，确认同一 loopback 目标、六条 allowlist、一次 deploy、post current、16/10/0 数字自洽、无业务代码/schema/migration/test/权限/生产配置改动；未修改文件。
- Spec/docs update：无需新增稳定 spec；`.trellis/spec/hyb-oa/backend-fastify-prisma.md` 的 `Local Regression Migration Drift` 已覆盖 status → 显式批准 deploy → 缺列消失后将选择器/页面失败分流的完整规则，本任务仅补充当前 Trellis 证据。
- Remaining PAUSED/NOT RUN：本地数据库迁移基线已恢复；浏览器回归为 `PASS_WITH_FINDINGS`，非迁移失败待后续 task；企业微信真机、生产/公网仍按 R10 保持 PAUSED，合同任务启动仍需独立批准。

## 10. 回归失败证据索引

- `client/test-results/assets-flow-E2E-资产流转主链路：建卡→领用归还→调拨→盘点/error-context.md`：POST 创建返回成功，但页面停留 `/assets/new`，未完成 canonical 详情跳转。
- `client/test-results/procurement-flow-E2E-采购主链路：员工提单→经理审批→财务归档/error-context.md`：审批详情已渲染中文采购摘要，断言仍要求 `Employee`。
- `client/test-results/global-search-E2E-全局搜索：采购与资产忽略旧-href-并使用实体-canonical-路径/error-context.md`：第二次回到 portal 后 `global-search-trigger` 等待超时，页面为登录态。
- `client/test-results/r103-cross-page-ui-consist-2485f-务台账标题区保持一主操作加至多一个更多，列表工具不常驻/error-context.md`：合同列表标题未出现。
- `client/test-results/r103-cross-page-ui-consist-bed95-cy-采购页使用安全格式上传并通过认证-Blob-下载/error-context.md`、`06cda-资产列表、详情各自只请求职责内数据并恢复-URL-筛选/error-context.md`、`aa8b7-与资产长表单详情对-403-404-使用同一安全错误态/error-context.md`、`c9ebc-ncy-采购长表单切回记录列表时支持取消保持与确认放弃/error-context.md`、`b8364-cy-共享未保存保护覆盖浏览器返回取消、确认与刷新拦截/error-context.md`、`b7ec9-ursements-在中等宽度下操作列可达且页面不横溢/error-context.md`：均在页面契约断言前回到登录页，归为 mock 会话/页面环境问题，未归因于 migration。