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

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

已交付基线（2026-08-04）

以下 1–6 节已由原任务实施、验证和部署；本次恢复任务后只需回归，不重复开发。

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，并引用任务名。
• 若需用户线上测试，完成部署、公网健康检查和合成数据关键路径冒烟后再通知。

本次后续复核实施计划（待批准）

7. 事由与付款批次入口

• PC、移动报销详情复用 isTravelReimbursement：普通报销显示日期和报销事由，差旅报销只在头部编辑日期并由差旅摘要独占出差事由。
• 核对列表、打印、搜索、工作流标题和通知对 description/travel_purpose 的消费，保证本轮不迁移、不丢失既有数据。
• 报销进度组装完成两阶段语义后，只给实际当前/终止/最终付款阶段设置付款批次链接。
• 增加普通/差旅 PC 与移动断言，以及 draft/reviewed/executed/failed/cancelled、取消前后和无权限的链接矩阵测试。

8. 付款批次费用明细

• 扩展付款批次详情查询，一次批量加载批次内报销费用明细及费用类型；列表接口保持轻量。
• 详情 DTO 增加最小 expenseItems 和服务端明细合计，补隐私负向断言与历史空数据降级。
• 页面章节改为“本批次报销单”，每张卡依次显示报销摘要、费用明细/小计、付款信息、付款结果和原报销单入口。
• PC 使用紧凑对齐布局，移动端使用纵向事实卡；不得产生横向溢出，按钮保持触控尺寸和可见焦点。

9. 银行回单在线查看

• 文件路由增加兼容的 preview mode：固定预览用途、独立审计动作、安全 inline MIME，同时保留下载用途门禁和既有下载响应。
• 复用并回归权限、部门数据范围、作废、隔离、文件不存在、大小、内容类型和存储校验；拒绝 HTML/SVG/未知主动内容。
• 前端增加认证 Blob 在线预览弹窗，支持 PDF/图片、加载/失败/关闭反馈、键盘与焦点管理，并可靠释放对象 URL。
• 下载继续弹用途框；通用徽标文案改为“下载需说明用途”，回归采购、合同、报销等既有消费者的语义和视觉。

10. 验证、只读审查与文档

• 运行付款语义、报销详情、付款批次、回单附件治理聚焦 Vitest；记录并区分本机 BIFF8 固定 Python 依赖缺失基线。
• 运行 Prisma validate、所改 Node 文件语法检查、客户端 typecheck/build。
• 运行 PC/移动合成 E2E，覆盖事由去重、唯一批次入口、费用明细与小计、PDF/图片预览、下载用途和无权限/异常文件。
• 运行 Trellis task validate、流程合同、文档注册、Trellis 治理、敏感内容和 git diff --check。
• 按项目约束执行一次只读 review，重点检查付款状态投影、批次详情隐私、回单权限/审计与 PC/移动一致性；reviewer 不改代码。
• 仅将稳定规则更新到现有 docs/报销发票附件规则.md、docs/产品设计规则.md 或对应 Trellis spec，不新建平行文档。

11. Commit and deployment gate

• 全部本地门禁通过后使用中文 commit，并引用 reimbursement-small-team-form-validation。
• 本次规划不包含部署授权；代码完成后另行申请公网部署许可。
• 获得部署授权后使用既有部署入口，验证 build、/ready、数据库无迁移、回单预览与付款详情脱敏冒烟；通过后才通知用户测试。

Rollback points

• 配置/预检字段为第一回滚点：可独立移除，不影响数据库。
• 正金额提交门禁为第二回滚点：若发现合法流程被误阻断，先回滚该提交校验，不绕过发票/权限门禁。
• 前端编辑与提示为第三回滚点：可回滚 UI，服务端新增字段保持向后兼容。
• 后续复核新增回滚点：先关闭前端回单预览，再回滚详情 DTO，再回滚纯展示条件；均不改写业务数据。

后续复核执行记录（2026-08-05）

• 差旅详情已收敛为单一“出差事由”；日期编辑请求不发送普通报销 description。报销进度的付款批次链接已按五状态和取消前后分支唯一投影。
• 付款批次详情仅在详情 DTO 批量加载最小费用明细，列表及创建、复核、执行、取消响应不携带明细；空明细不重复显示金额不一致警告。
• PDF 与 PNG 回单预览均通过实际内容复检、固定用途审计和安全 inline 响应验证；下载仍要求用途。前端 19 项 PC/移动合成 E2E 全部通过。
• Prisma、Node 语法、前端 typecheck/build、Trellis task、流程、文档、治理、敏感信息和差异门禁通过。后端聚焦 80 项中 79 项通过；唯一失败为实施前已存在的 BIFF8 银行制单用例，本机缺固定 Python 依赖导致预期 200、实际 409，与本轮改动无关。
• 已完成主会话只读复核并修正四处边界：写接口不附带费用明细、空明细不重复告警、差旅日期编辑不回传普通事由、历史差旅付款批次不冒充报销明细或生成错误报销入口。未执行部署、生产配置、真实数据或付款操作。

执行记录（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 并通过扫描。回滚继续使用既有部署入口切换到上一已发布提交，不修改数据库结构或生产环境文件。