hyb-oa/.trellis/tasks/08-02-corporate-bank-account-payment-order/implement.md

企业银行账户与付款制单实施计划

1. 实施前门禁

• 用户审查并批准 PRD、设计与本实施计划后，才运行 task.py start。
• 运行 trellis-before-dev，读取 backend/frontend/hyb-oa 相关 spec 与研究材料。
• 核对工作树，不提交本地空白银行模板、生成制单文件、真实账号或个人 workspace。
• 记录当前 FIELD_ENCRYPTION_KEY 载荷兼容口径，但不读取或输出任何密钥/真实账号。

2. 依赖与迁移

• 以精确官方 tarball安装 SheetJS 0.20.3，锁定 package-lock 完整性；确认许可证与依赖门禁，不使用 npm registry 的 [email protected]。
• 新增 BankInstitution、PaymentAccount，以及 Employee/PaymentBatch 可空关系、内部快照和制单统计字段。
• 迁移增加同一法人主体单一 active 付款账户的 PostgreSQL 部分唯一索引；不回填存量批次或员工银行机构。
• 更新 Prisma Client 并运行 npm run prisma:validate；核对 migration SQL 和回滚兼容说明。

3. 权限、账户与员工收款资料

• 新增 payment.account.manage/read/read_full 与 payment.order.export，按设计分配角色；清理 finance_mgr 重复的 payment.batch.manage 条目。
• 实现银行机构和付款账户脱敏 CRUD/替换/停用 API，事务内审计并通知 active admin/CEO。
• 实现公司完整账号带原因查看：先写审计，再返回；负向路径不返回明文。
• 扩展员工敏感资料接口：默认脱敏、HR/admin 可写银行机构与账号、finance/finance_mgr 只读；完整查看独立带原因审计。
• 员工本人 API 返回银行名称与脱敏尾号，不返回完整账号。
• 增加管理端企业银行账户页面和人员档案收款信息区；移动端不增加复杂配置入口。

4. 批次冻结快照

• 对报销银行批次解析并锁定单一法人主体、唯一 active CCB 付款账户和完整员工 CCB 收款资料。
• 直接复制现有账号密文进入内部快照；只为脱敏显示做受控解密，不进行解密后再加密。
• 扩展付款 DTO，只映射付款账户/收款账户脱敏字段及制单统计，禁止原始 snapshot 或 v1: 密文外泄。
• 旧批次继续显示兼容信息、允许人工付款，但永久不具备制单资格。

5. BIFF8 制单

• 建立独立制单服务：固定 15 列和三个工作表、稳定排序、单一流水号函数、七列字符串类型、金额两位小数、中文和 CCB-only 校验。
• 实现 POST 制单下载接口：finance/finance_mgr 业务角色 + 独立权限 + reviewed 状态 + 必填原因。
• 在生成任何文件前聚合阻塞项；任何非 CCB、历史快照、缺资料或异常均整批失败，不生成部分文件。
• 首次导出/重导在事务内写制单统计与脱敏审计，之后以内存 buffer 和 no-store 安全响应头下载，不持久化文件。
• 重导确认固定展示重复付款风险原文，不暗示旧文件已作废。

6. 付款详情交互

• DTO 提供制单次数、最近导出摘要、可制单状态与聚合阻塞原因，页面用自然中文逐项说明。
• 未导出新批次主动作显示“下载银行制单”；已导出无回单时主动作显示“上传银行回单”；当前重导为顶部次动作，待详情页结构统一任务再收进正式“更多”槽位。
• 人工付款可直接上传回单，不把制单设为上传或登记付款的门禁。
• 详情显示是否已生成制单；处理进度按未导出/已导出显示两种批准文案。
• 不在本任务重构完整详情页骨架；与未来详情结构统一任务保持组件边界清楚。

7. 自动化与独立读回

• 后端测试覆盖权限矩阵、active 唯一约束、账户替换/停用、通知、审计、默认脱敏和完整查看原因。
• 付款批次测试覆盖单一法人主体、CCB-only、密文复制、员工资料后改不漂移、旧批次拒绝和普通响应无密文。
• 制单测试覆盖 15 列、三个工作表、确定性排序、流水号校验、七列字符串、金额、中文、重导一致性、整批失败和无持久化。
• 增加可复现的 xlrd==2.0.2 独立读回环境和 CI 步骤；合成文件仅存临时目录并自动清理。
• 前端测试覆盖角色可见性、员工本人脱敏、管理表单、导出原因、重导警告、主动作切换和旧批次人工兜底。

8. 全量验证与只读复核

• cd server && npm run prisma:validate。
• 对全部触及的服务端 JS 运行 node --check，运行付款批次/用户/导出/通知聚焦 Vitest。
• cd client && npm run typecheck && npm run build；未新增或运行本任务前端 E2E。
• 运行 BIFF8 独立读回脚本；Excel/WPS 人工打开仍待执行。
• 运行依赖审计、Trellis governance、process contract、敏感扫描、git diff --check；依赖审计保留仓库既有 14 项告警，新增 SheetJS 未命中告警。
• 对权限、状态机、迁移、密文数据流和 API 响应执行一次独立只读 review；发现的聚合阻塞项合同漂移已由主流程修复并复验。

9. 文档、提交与上线边界

• 仅把稳定安全/付款合同更新到现有 spec、产品事实源和管理员手册，不新建无必要业务文档。
• 按逻辑分批中文提交，提交信息引用 corporate-bank-account-payment-order。
• 不在代码任务中写入任何生产银行资料；生产配置、部署和员工资料确认分别取得明确批准。
• 部署后先由 admin 配置 CCB 与公司付款账户，再由 HR/admin 确认员工 CCB；配置完成前暂停新建银行批次。
• 旧杨俊批次继续人工付款并上传回单，不补写快照、不尝试制单。
• 公网门禁通过后才通知王芝玲测试制单；没有独立网银校验步骤时不做生产网银导入试验。

10. 本地验证记录

• 服务端全量：176 个测试文件、1186 项测试通过。
• 本任务聚焦：付款批次与 BIFF8 服务 57 项测试通过；公司账户、员工敏感资料和个人资料测试包含在全量结果中。
• 前端：TypeScript 检查和生产构建通过。
• 数据与文件：Prisma schema 校验通过；xlrd==2.0.2 独立读回确认三个工作表、15 列、长账号字符串、01 字符串、数值金额与中文。
• 治理：Trellis task 校验、governance、process contract、敏感内容扫描和 git diff --check 通过；文档注册审计仅保留仓库既有 22 个未登记文件警告。
• 依赖：[email protected] 来自官方精确 tarball且锁定；生产依赖审计仍有 14 项仓库既有告警，未执行破坏性 npm audit fix --force。
• 尚未完成：Excel/WPS 人工打开、前端 E2E/截图、生产数据库迁移、真实资料配置、部署、公网检查和企业网银校验。

11. 原模板保真修订（2026-08-03）

• Excel 人工打开否决 SheetJS 重建输出：字段合同正确，但原模板列宽、行高、字体、底色、边框和对齐丢失。
• 用户批准改为“固定脱敏原模板 + Python BIFF8 保真填充”，不再接受重建工作簿方案。
• 提交经敏感检查的空白模板资产并固定 SHA-256；不提交 input/ 原件或任何生成制单文件。
• 用固定 Python requirements 实现 stdin JSON / stdout BIFF8 填充器，stderr 仅固定错误码。
• Node 改为子进程桥接，保留现有资格、冻结快照、blockers、排序、流水号、审计与导出统计合同。
• 生产镜像和 CI 使用同一带哈希 requirements 和绝对 venv 解释器；移除服务端 SheetJS 生成依赖。
• 独立读回增加模板视觉签名、超过三行扩展、模板/运行时失败和隐私负向测试。
• 重新运行聚焦/全量后端、前端、治理和只读复核；用合成数据交付 Excel 人工复核，不部署。

修订验证记录

• 受控模板仅有 15 个表头和三行预格式化空数据行；模板 SHA-256 与运行时常量一致，字符串扫描未发现账号、URL、凭据或业务数据。
• 固定 Python 环境的独立读回已确认三个工作表、15 列、账号/01 文本、数值金额 0.00，并逐格比较列宽、行高、字体/加粗、底色、边框、对齐；第四笔扩展行同样通过。
• 聚焦测试在资格门禁修订后为 70 项通过；新增覆盖 admin 非财务拒绝、四种非 reviewed 状态、历史 item 非银行 override、模板 hash、依赖缺失、子进程超时/输出越界和 stderr 隐私。
• 后端全量最终为 176 个文件、1199 项全部通过；此前 Dockerfile 缓存层文本合同失败已通过恢复独立 RUN cd server && npm ci 修复并纳入最终全量。
• 前端 typecheck/build、Prisma validate、流程合同、Trellis governance、敏感扫描和 diff 检查通过；文档审计仅保留仓库既有 22 个未登记文件警告。
• 本地生产镜像已真实构建通过；Alpine Python 3.14.5 成功从带哈希 requirements 安装固定依赖，镜像内生成与独立 BIFF8 读回合同通过。部署、公网与网银验证仍待单独批准。
• 当前实现已生成并独立读回一份 gitignored 合成 Excel 验收文件；原型文件此前经用户 Excel 人工打开认可，当前实现文件仍可用于最终人工外观确认。
• 付款/隐私只读复核在资格门禁修订后确认无 Blocker、High 或 Medium；唯一 Low（失败路径缺显式“无成功审计”断言）已补测试并复验。

12. Excel 富文本与流水号可读性修订（2026-08-03）

• Excel 人工验收发现原模板红色必填星号在生成文件中变黑；xlrd 诊断确认原模板存在 rich-text run，而生成文件的 run map 为空。
• 用户批准显式恢复模板富文本，并把客户流水号从 批次号-001 改为 批次号-R001；首份文件尚未导入网银，不产生历史格式兼容成本。
• 从模板逐段复制全部字体属性并调用 write_rich_text，不硬编码近似红色字体。
• 独立读回逐段断言必填星号红色、其余文字黑色，并覆盖模板其他富文本表头。
• 更新流水号单元测试与独立读回，重新生成 Excel 交付人工验收。
• 完成聚焦/全量验证和生产镜像真实构建；构建通过前不批准部署。

富文本修订验证记录

• 模板读取保持 formatting_info=True；填充器显式恢复所有模板富文本 run，并逐段复制字体名、字号、粗体、颜色、字符集及其他字体属性。
• 独立读回逐段比较模板与生成文件，确认必填星号使用模板红色、其余表头文字使用模板黑色；第四笔扩展行样式仍与模板首个数据行一致。
• 客户流水号已统一为 批次号-R三位行号，合成验收文件确认首行 R001、第四行 R004；固定验证夹具日期与 PRD 示例统一为 2026-08-03。
• 一次人工验收文件校验失败被定位为诊断阶段名滞后：空短信附加信息实际为 BIFF8 BLANK，真正失败来自后续固定流水号夹具日期不一致；校验器已为字段值断言设置独立阶段名，避免再次误报为空单元格问题。
• 聚焦测试 70 项、服务端全量 1199 项、宿主机独立 BIFF8 合同和已构建生产镜像内合同均通过；未部署、未写生产银行资料。