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

## 1. 实施前门禁

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

## 2. 依赖与迁移

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

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

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

## 4. 批次冻结快照

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

## 5. BIFF8 制单

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

## 6. 付款详情交互

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

## 7. 自动化与独立读回

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

## 8. 全量验证与只读复核

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

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

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

## 10. 本地验证记录

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

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

- [x] Excel 人工打开否决 SheetJS 重建输出：字段合同正确，但原模板列宽、行高、字体、底色、边框和对齐丢失。
- [x] 用户批准改为“固定脱敏原模板 + Python BIFF8 保真填充”，不再接受重建工作簿方案。
- [x] 提交经敏感检查的空白模板资产并固定 SHA-256；不提交 `input/` 原件或任何生成制单文件。
- [x] 用固定 Python requirements 实现 stdin JSON / stdout BIFF8 填充器，stderr 仅固定错误码。
- [x] Node 改为子进程桥接，保留现有资格、冻结快照、blockers、排序、流水号、审计与导出统计合同。
- [x] 生产镜像和 CI 使用同一带哈希 requirements 和绝对 venv 解释器；移除服务端 SheetJS 生成依赖。
- [x] 独立读回增加模板视觉签名、超过三行扩展、模板/运行时失败和隐私负向测试。
- [x] 重新运行聚焦/全量后端、前端、治理和只读复核；用合成数据交付 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 个未登记文件警告。
- 本地 Docker 构建因 Alpine 包下载长时间无进展被主动取消，未形成镜像通过证据；生产镜像、部署、公网与网银验证仍待单独批准。
- 当前实现已生成并独立读回一份 gitignored 合成 Excel 验收文件；原型文件此前经用户 Excel 人工打开认可，当前实现文件仍可用于最终人工外观确认。
- 付款/隐私只读复核在资格门禁修订后确认无 Blocker、High 或 Medium；唯一 Low（失败路径缺显式“无成功审计”断言）已补测试并复验。