# 企业银行账户与付款制单设计

## 1. 边界与交付顺序

本任务在 OA 内建立付款准备能力，不连接银行 API、不提交付款、不代替网银复核。交付按同一任务内的三个层次顺序完成：

1. 银行机构与公司付款账户主数据。
2. 员工收款信息默认脱敏、规范化银行标识和付款批次冻结快照。
3. 已复核批次的 BIFF8 制单导出、使用状态与审计。

三层共享同一迁移和权限设计，拆成独立任务会使中间版本产生无法制单或无法建批次的短暂合同，因此本轮保留为一个复杂 Trellis task，按提交批次分层验证。

## 2. 数据模型

### 2.1 BankInstitution

新增银行机构主数据：

- `id` UUID
- `code` 唯一、不可变的规范化代码；首版至少存在 `CCB`
- `name` 展示名称
- `enabled`、`archived_at`
- `created_at/by`、`updated_at/by`

银行机构由 `payment.account.manage` 管理。员工收款资料与公司付款账户都引用同一主数据，不把银行名称字符串当身份键。已被引用的代码不能修改或物理删除；停用只阻止新绑定。

### 2.2 PaymentAccount

新增独立付款账户表并关联 `LegalEntity`：

- `id`、`legal_entity_id`、`bank_institution_id`
- `account_name`
- `account_number_encrypted`
- `enabled`、`archived_at`
- `created_at/by`、`updated_at/by`

PostgreSQL 使用部分唯一索引保证同一法人主体最多一条 `enabled=true AND archived_at IS NULL` 的账户；服务端先做自然中文校验，数据库索引负责并发兜底。

已启用账户不原地覆盖账号。变更操作在同一事务内归档旧记录并创建新记录，保留历史身份；停用只改变旧记录状态。完整账号沿用现有字段加密服务，普通 DTO只计算脱敏尾号。

### 2.3 Employee 与 PaymentBatch

- `Employee` 增加可空 `bank_institution_id`。存量数据不通过自由文本自动猜测；由 HR/admin 在 UI 中确认。
- `PaymentBatch` 增加可空 `legal_entity_id`、`payment_account_id`、内部付款账户快照、制单次数、最近制单时间和操作者。
- 报销付款项的 `snapshot_json.payee` 增加内部密文和银行机构代码；既有姓名、银行显示名和脱敏尾号继续保留。

付款账户快照仅存内部使用字段：账户记录 ID、法人主体 ID、账户名称、银行机构代码/名称、原始密文和脱敏尾号。API 映射层只返回名称、银行名称和脱敏尾号。

迁移全部新增为可空，禁止回填历史完整账号。历史批次因此保持可查看、可人工付款，但制单明确失败关闭。

## 3. 权限与威胁模型

新增权限：

| 权限 | 角色 | 用途 |
| --- | --- | --- |
| `payment.account.manage` | `finance_mgr`、`admin/*` | 银行机构与公司付款账户新增、替换、停用 |
| `payment.account.read` | `finance`、`finance_mgr`、`admin/*` | 公司账户脱敏列表/详情 |
| `payment.account.read_full` | `finance`、`finance_mgr`、`admin/*` | 填理由查看公司完整账号 |
| `payment.order.export` | 明确具有 `finance` 或 `finance_mgr` 业务角色者 | 已复核批次制单；单有 `admin/*` 不作为财务业务角色代办 |

`employee.bank.manage` 不授予财务或 system_admin。员工完整收款账号查看继续使用独立读取权限，但现有 GET 默认改为脱敏；完整值通过带原因的 POST 动作获取并先写审计。

公司付款账户维护防的是误配置、错误来源账户和缺少及时知情，不新增双人审批。真实受益人欺诈边界由“HR/admin 维护员工收款资料”和“finance/finance_mgr 制单”分离控制。

## 4. 主数据 API 与页面

### 4.1 公司付款账户

新增专用路由而不复用 Feature Flag：

- 脱敏列出银行机构与付款账户。
- 创建首个账户、替换当前账户、停用当前账户。
- POST 完整账号查看动作，body 必须有 `reason`。

管理入口放在 PC `管理 -> 基础资料/财务配置 -> 企业银行账户`。默认卡片只显示法人主体、账户名称、银行名称、脱敏尾号和状态；完整账号查看、替换、停用均使用明确动作与后果确认。移动端不提供配置入口。

账户新增、替换或停用在事务内写脱敏审计，并为所有 active admin 与 CEO 创建 OA 通知；通知不带完整账号、密文或本地路径，也不要求 CEO 具备账户主数据页面权限。

### 4.2 员工收款信息

人员档案增加收款信息区：

- HR/admin 可选银行机构并录入账号。
- finance/finance_mgr 只能看银行名称和脱敏尾号。
- 员工本人在个人资料看到自己的银行名称和脱敏尾号。
- 授权角色查看完整账号时填写原因；服务端先审计后返回，前端不会把完整值缓存到长期状态或普通查询缓存。

## 5. 批次创建与冻结快照

对 `entityType=reimbursement` 且银行渠道的新批次：

1. 在同一事务锁定所选报销。
2. 解析每张报销所有人的 `legal_entity_id`，要求非空且全批次一致。
3. 查询该法人主体唯一启用的建行付款账户。
4. 要求每位收款人有 `CCB` 银行机构与可用账号密文。
5. 直接复制员工现有密文，不解密后重新加密；只为脱敏尾号做一次受控解密。
6. 冻结付款账户和每一项收款信息后创建批次。

缺法人主体、混合法人主体、缺付款账户、非建行、缺账号或解密失败时，创建失败并一次性返回自然中文处理建议。其他渠道及非报销实体沿用原流程，但不具备银行制单能力。

API 映射函数必须显式挑选安全字段。测试扫描所有普通批次/API/AP 响应，断言不存在 `v1:` 密文、完整账号或原始 `snapshot_json`。

## 6. 制单服务与接口

### 6.1 资格校验

POST 制单接口接收 `{ reason }`，仅允许明确 finance/finance_mgr 业务角色、`payment.order.export` 权限和 `reviewed` 状态。它必须拒绝：

- 历史/不完整快照
- 非报销或非银行渠道
- 公司或任一员工不是 `CCB`
- 缺完整密文、账号解密失败
- 缺金额、业务编号或付款账户
- 其他四种批次状态

校验聚合所有业务阻塞项后统一返回；权限失败仍立即拒绝，不泄露批次内容。

### 6.2 确定性行与字段

项目按 `entity_code ASC, id ASC` 显式排序。唯一 ID 仅作同业务编号异常重复时的兜底，不进入银行文件。

- 序号：从 1 开始的字符串。
- 付款方账号/名称：付款账户快照。
- 行别代码：固定字符串 `01`。
- 收款方账号/名称、开户行：收款快照。
- 联行号：空字符串。
- 客户流水号：单一 `buildCustomerReference(batchNo, rowIndex)` 函数生成，写入前校验长度、字符集和批内唯一。
- 金额：初版数值单元格 + 两位小数格式。
- 用途：`报销款`。
- 备注：报销单编号。
- 短信标志：字符串 `0`；手机号与附加信息留空。

禁止部分成功：任意一项失败时不生成文件、不更新制单状态、不写成功导出审计。

### 6.3 BIFF8 与下载

- 使用 SheetJS 官方精确 `0.20.3` tarball并锁定 package-lock 完整性。
- 运行时代码只调用生成 API，不解析上传文件或用户提供的工作簿。
- 显式构建七个字符串字段的 `{ t: "s", v: value }` 单元格；金额使用数值类型和两位小数格式。
- 工作簿按顺序创建 `Sheet1`、`Sheet2`、`Sheet3`，Sheet1 固定 15 列表头。
- 内存生成 `bookType: "biff8"` buffer，先完成审计和制单计数事务，再设置 `application/vnd.ms-excel`、安全附件名、`nosniff`、`private, no-store` 等响应头并发送。
- 不写对象存储或服务器持久目录。网络中断后的已记录导出按保守口径视为已生成，用户可填写新原因重导。

## 7. 页面动作与进度

付款批次 DTO 返回脱敏付款账户摘要、`paymentOrderExportCount`、最近导出时间/人和 `canExportPaymentOrder`/阻塞原因。

- 新快照 + reviewed + 未导出：顶部主动作 `下载银行制单`；回单区仍可直接上传，人工路径不被阻断。
- 已导出且无回单：主动作 `上传银行回单`，`重新下载制单` 放入 `更多`。
- 重导确认固定展示：`重新下载不会作废之前的文件。如果上一份已在网银导入，请勿重复提交。`
- 已有回单：主动作 `登记付款完成`。
- 旧批次或资料不完整：不显示可执行制单动作，展示具体原因；原人工付款动作保持。
- 详情显示 `未生成制单` 或 `已生成 N 次`；处理进度按是否导出显示已批准的两种文案。

整体详情页结构统一仍由后续独立任务负责，本任务只在当前操作组和处理进度数据中接入制单状态，不顺带重构页面骨架。

## 8. 审计、通知与隐私

审计动作至少覆盖：付款账户创建/替换/停用、公司完整账号查看、员工完整账号查看、银行制单首次导出/重导和失败阻断摘要。审计 extra 只存业务 ID、法人主体、批次号、笔数、合计金额、原因、导出次数和结果代码；不存完整账号、密文、工作簿 buffer 或原始快照。

普通日志只记录固定错误码、批次 ID/业务号和数量。依赖或解密错误返回自然中文业务错误，禁止裸 `Error` 使页面白屏，也禁止把底层加密异常文本返回客户端。

## 9. 验证与依赖门禁

- Node 单元/路由测试覆盖权限矩阵、单一启用账户并发约束、通知、审计、批次快照、历史拒绝、CCB-only、确定性排序、重导和隐私负向断言。
- 使用合成数据生成 `.xls`，由 CI 明确安装的 `xlrd==2.0.2` 独立读回三个工作表、15 列、七个字符串字段、金额、中文和重复导出一致性。
- 用合成非建行项证明整批失败且没有文件、制单计数或成功审计。
- Excel/WPS 人工打开验证中文、长字符串和金额；企业网银只有存在明确“仅校验”步骤时才使用虚构建行数据做最终确认。
- 安装依赖后运行 npm audit/许可证与 lockfile 审查；如官方精确 tarball不可重复获取或引入不可接受告警，暂停而非换用 registry 旧版。

## 10. 迁移、上线与回滚

- 迁移只新增表、可空关系、可空快照和制单统计字段，不修改或回填存量账号/批次。
- 部署后先由 admin 建立 CCB 主数据与公司付款账户，再由 HR/admin 为员工确认 CCB 机构；这两类生产写入必须另行批准，完整账号不经过聊天或仓库。
- 配置完成前暂停创建新的银行渠道付款批次，避免产生无法制单的新历史快照；已有杨俊批次继续人工付款。
- 公网 `/ready`、角色/隐私只读检查和一条合成/受控流程通过后才通知财务使用制单。
- 代码回滚保留新增表和可空字段，不删除已产生的审计、通知或制单统计；旧应用忽略新字段并继续人工付款。