hyb-oa/.trellis/tasks/08-04-reimbursement-small-team-form-validation/implement.md

小团队报销填报与校验完善：实施计划

1. Backend contracts and focused tests

• 在配置层增加并测试 REIMBURSEMENT_MAX_AGE_DAYS=180|365，默认 365，非法配置启动失败。
• 在报销预检服务增加证据摘要、时效检查和资产提示，复用 date-only/金额工具。
• 为默认期限、180 天、阈值边界、跨年度、未关联发票、整单附件和 assets 类别补单测。

2. Authoritative amount validation

• 收紧手工 item POST/PATCH：金额必须大于零，返回可定位错误。
• submit 行锁事务读取明细，拒绝空明细和非正金额明细。
• submit 在预算与审批规则前重新汇总并使用权威总额。
• 补充空单、零金额模板草稿、修改后提交、陈旧总额修复和审批金额选择回归测试。

3. Shared frontend API and header editing

• 扩展 reimbursement API 类型与通用 PATCH 函数。
• PC 草稿/驳回详情增加报销事由和日期编辑。
• 手机草稿/驳回详情增加适合小屏的同等编辑能力。
• 保存后刷新 detail/list/precheck，并验证非编辑状态和无权限用户只读。

4. Totals, evidence and asset hints

• PC 明细表尾增加条数与报销总额，概况标签改为“报销总额”。
• 手机明细列表尾增加条数与报销总额。
• PC/手机展示明细发票关联状态、整单附件数、时效警告和资产人工建卡提醒。
• 资产入口沿用现有权限；打印页合计不回归。

5. Validation and review gates

• cd server && npm run prisma:validate
• cd server && node --check src/config.js && node --check src/services/feeControl.js && node --check src/routes/reimbursements.js
• 运行本任务新增的后端 Vitest 及现有 reimbursement detail/create/expense-standard 聚焦回归。
• cd client && npm run typecheck && npm run build
• 运行 PC 与 mobile/wecom 报销详情 E2E，覆盖合计、编辑、时效、证据和资产提醒。
• 运行 node scripts/qa/check-process-contract.mjs --baseline --json。
• 运行 node scripts/qa/audit-docs.mjs --check-registry 和 node scripts/qa/check-trellis-governance.mjs。
• git diff --check
• 因提交校验和跨层预检发生变化，实施后进行一次只读 review，重点检查金额竞争、模板兼容和权限边界。

6. Documentation, deployment and rollback

• 仅在形成稳定规则时更新现有报销事实源或 Trellis spec，不新建平行文档。
• 记录环境配置默认值、生产取值和回滚方式，不记录 Secret 或真实票据。
• 用户批准后启动任务；实现、检查、必要 spec 更新完成后使用中文 commit，并引用任务名。
• 若需用户线上测试，完成部署、公网健康检查和合成数据关键路径冒烟后再通知。

Rollback points

• 配置/预检字段为第一回滚点：可独立移除，不影响数据库。
• 正金额提交门禁为第二回滚点：若发现合法流程被误阻断，先回滚该提交校验，不绕过发票/权限门禁。
• 前端编辑与提示为第三回滚点：可回滚 UI，服务端新增字段保持向后兼容。

执行记录（2026-08-04）

• 服务端聚焦回归 9 个文件、86 个用例全部通过；Prisma 与所改 Node 文件语法检查通过。
• 前端 typecheck、生产构建通过；R102 合成 API 浏览器回归覆盖 PC/手机合计、事由日期编辑和材料提示，原 5 个用例通过，新增/修正用例单独复跑通过。
• 任务、环境契约、流程合同、文档注册、Trellis 治理、敏感内容和 git diff --check 均通过；文档注册保留既有 22 个未注册文件 warning，无新增错误。
• 全量后端 1228 个用例中 1224 个通过；3 个既有付款 BIFF8 导出用例因本机未安装 server/requirements/payment-order-biff8.txt 固定 Python 依赖失败，另 1 个本任务引起的环境键计数已修正并复跑通过。
• 已完成主会话只读复核，修正“已完成报销不显示资产提醒”和“超期且跨年只显示一个提示”两处跨层遗漏。
• 未执行生产部署、生产配置写入或公网数据操作；如需线上测试，须按项目规则另行取得明确部署授权。

部署续办（2026-08-04，已授权）

• 确认工作提交已发布到部署入口要求的上游分支，并执行已有部署只读预检。
• 按 deploy-existing.sh 发布已批准提交，不同步或覆盖生产 .env，不执行真实业务写入。
• 验证活动服务 build、/ready、公网只读 smoke、PC/手机关键页面及 180/365 配置生效状态。
• 记录脱敏结果与回滚边界；如应用发布成功但备份合同刷新失败，按既有部分成功分类处理，不重复部署应用。

部署结果

• 发布提交为 3aebfc5e046d；Git 来源已发布，部署前和部署后远端合同均为 13/13 PASS。
• 生产 .env 未同步或覆盖；数据库无待执行迁移，初始化只保留既有配置和账号口令，不执行真实报销、审批或付款写入。
• 应用、外部依赖、运行时功能开关、公网 build 标识和前端资源文案扫描通过；备份合同刷新完整通过，无部分成功状态。
• 公网 /ready 返回当前 build；生产运行时 REIMBURSEMENT_MAX_AGE_DAYS 生效值为默认 365，业务时区已配置。
• 公网基础 Playwright smoke 按企微 ready 状态复跑通过。管理员/员工登录态 smoke 因本机未配置专用 LIVE_SMOKE_* 凭据未执行；未读取、复制或输出生产账号密码。
• PC/手机报销关键交互已由发布前合成 API 浏览器回归覆盖；公网部署后的对应前端资源已命中当前 build 并通过扫描。回滚继续使用既有部署入口切换到上一已发布提交，不修改数据库结构或生产环境文件。