hyb-oa/.trellis/tasks/08-05-contract-detail-workspace/implement.md

实施计划

1. Schema 与迁移

• 在 ContractRegistry 增加 terminated_at/reason/by、terminator 关系，在 Employee 增加反向关系。
• terminated_reason 限制 1000，terminated_by 使用 onDelete: Restrict；按查询需要添加索引。
• 生成纯增量 migration，检查只有可空列、外键/索引，无历史回填、drop 或状态改写。
• 运行 cd server && npm run prisma:format && npm run prisma:validate && npm run prisma:generate。

2. 状态与服务端不变量

• 持久/筛选状态加入 terminated，一般 create/PATCH 可写状态仍排除 terminated。
• 增加 terminated 筛选、effective status、expiring 排除和 renew 拒绝测试。
• 增加详情 GET，按列表相同范围查询 owner/project/terminator/document refs，并投影安全 history。
• 增加专用 terminate schema 和接口，reason trim 后 10–1000。
• 终止 transaction 原子写三字段、status 和 required audit；模拟 audit failure 证明全回滚。
• 阻止 archived/terminated 普通字段覆盖与终止绕过；导入脚本也拒绝终止状态和覆盖既有终止合同。
• 归档/恢复改为 required audit；实现归档后追加修正记录，不覆盖主合同；修正使用 updated_at 乐观保护。
• 保持续约 active/expired 语义和事务审计，并覆盖续约审计失败回滚。

3. 客户端 API 与状态映射

• 客户端合同类型加入 terminated 与三个终止字段、terminator、document refs、history DTO。
• contractStatusLabel 增加“已终止”，未知兜底为“未知状态”而非原值。
• 增加 fetch detail、terminate、correction 等必要 API 函数，不暴露 raw audit/document path。

4. 列表、详情和表单

• 合同列表移除内联 editor，仅保留筛选、提醒、导出、状态和查看详情。
• 新建合同详情路由和页面元数据，权限 guard 与现有列表一致。
• 建设状态/下一步、摘要、证据区、历史和动作面板；窄屏复用共享底部动作容器，并隐藏 PC 管理动作。
• 证据区展示归档位置、离线档案号、涉密资料索引和强制引导文案；不显示空附件区或附件完整性列。
• 迁移编辑、续约、归档/恢复；按动作矩阵隐藏或禁用。
• 终止输入持续显示至少 10 字要求；禁用时显示原因；确认包含合同编号、相对方、金额和后果。
• 归档后只提供授权修正追加入口，不覆盖普通字段。
• 只展示真实 project 摘要与跳转；采购/付款无稳定关联时不渲染。

5. 后端与迁移验证

• cd server && node --check src/routes/contractsRegistry.js（并检查 src/scripts/import-project-ledgers.js）。
• cd server && npm test -- tests/unit/routes/contractsRegistry.test.js tests/unit/routes/exports.contractsRegistry.test.js tests/unit/scripts/import-project-ledgers.test.js --run：25 passed。
• cd server && npm run prisma:validate。
• cd server && npx prisma migrate status（只读；不得未经批准 deploy/reset）：65 migrations，Database schema is up to date!。
• 检查生成 migration SQL 和既有数据兼容，记录应用回滚前/后首次终止写入的不同边界。

6. 前端与交互验证

• cd client && npm run typecheck。
• cd client && npm run build。
• 增加合同详情聚焦 Playwright：列表进入、深链刷新、无权限/不存在、dirty guard、涉密引导、无附件区。
• 覆盖终止原因不足、确认摘要、成功状态、重复终止、审计失败和窄屏动作安全区；合同详情 + Wave3 共 12 passed。
• 覆盖归档锁定、修正追加、恢复、续约和未知状态兜底。

7. 只读 Review 与治理

• 实施完成后启动只读 reviewer，按 design 第 9 节逐项审查，明确 reviewer 不改代码；首轮 finding 已记录并修复。
• 主会话修复 finding 后重新运行聚焦测试并请求只读复查；最终结论 PASS。
• 运行 task validate、process contract、docs registry、Trellis governance、敏感内容检查和 git diff --check。
• 将终态字段、required audit、导入写路径和修正乐观保护沉淀到 .trellis/spec/hyb-oa/backend-fastify-prisma.md，不新建平行文档。

8. 提交、部署与回滚

• 使用中文 commit message 并引用 08-05-contract-detail-workspace。
• 本地实现提交不等于批准生产 migration 或部署。
• 生产发布另行获批后，显式验证 migration status、/ready、合同详情和权限负向路径。
• 首次生产终止写入前保留应用回滚窗口；产生 terminated 行后优先 roll-forward，不自动 drop 列或回退到不识别 terminated 的旧应用。

实施证据与边界（2026-08-07）

• migration SQL 为三个可空列、一个 Restrict 外键和索引；未执行生产 migration、reset、db push、resolve 或手工 DDL。
• 只读迁移原始结论：Datasource=hyb_oa_regression at localhost:5432；65 migrations found；Database schema is up to date!。
• 合同聚焦后端 25/25 passed；合同详情与受影响 Wave3 Playwright 12/12 passed；client typecheck/build、Prisma validate、node syntax、task/process/governance/sensitive/flow/route-manifest gates 均通过。
• 仓库全量 Vitest 结果为 179 个文件（177 passed、2 failed）、1248 个测试（1245 passed、3 failed）；失败仅为既有付款批次/BIFF8 模板环境问题（paymentBatches.reimbursement.test.js 1 条、paymentOrderXls.test.js 2 条），不属于本合同任务改动，未通过改页面或数据库掩盖。
• 本地 127.0.0.1:3000/ready 返回 200；企业微信真机、生产/公网部署仍未验证，不能据此宣称用户可测试。
• 首轮只读 reviewer 结论为 PASS_WITH_FINDINGS；主会话修复并补测后，最终只读复查结论为 PASS，reviewer 未修改代码、未写数据库。