备用金归还接口说明

1. 适用范围

本文描述当前揽月内部 /api/finance/ 路由，使用登录会话。旧商户订单 V1 / V2 的商户号、MD5 / RSA2 签名不能替代这里的登录、公司范围和权限。

当前验收使用本地 Mock 数据。本文不是开放第三方生产调用的承诺。读取任务、展示二维码、返回本地支付状态，都不证明已经获得支付宝产品权益、发生真实到账或完成真实宜搭回写。

资金方向为员工向公司归还备用金。财务创建任务并交付一任务一码；员工认领、制单授权、本人付款确认、支付结果、到账和核销分别记录。财务查看二维码不会发起资金交易。

依据：src/application.js、src/finance-workbench.js、src/group-payment-service.js、src/finance-materials-router.js、src/finance-materials.js，以及本次对应回归测试。代码变更时应同步核对本说明。

2. 登录、权限与公司范围

1. 在已配置的公司财务域名登录。服务端依据请求 Host 解析公司，登录账号的 company_id 必须与该公司一致。平台管理员角色也不能绕过财务域名与账号的绑定要求。
2. 已登录页面通过 GET /api/session 取得当前会话及 csrfToken。使用同源 Cookie；不在 URL、日志或文档里放 Cookie、密码或令牌。
3. 读取需要 orders:read；写入需要 orders:create，并发送 x-csrf-token。JSON 写入使用 Content-Type: application/json。
4. 请求里的 companyId 只能声明当前公司，不能用来切换公司。列表参数不提供跨公司查询；任务 ID、材料 ID 仍在服务端核对归属。
5. 页面只展示服务端 availableActions 允许的操作；点击后服务端会再次校验。隐藏按钮不是权限保障。

下面示例里的 ID 都是占位值，必须来自当前登录公司真实返回的选项。不要把演示 ID、令牌或地址复制到生产环境。

3. 先读取可用选项与任务

任务关键字段：id / taskNo / batchNo / companyId / companyName / receiptAccountId / receiptAccountName / amountCents / availableActions。amountCents 为整数分；amount 为两位小数字符串元。身份信息仅使用接口提供的脱敏投影。

materialSummary 是附件登记数量与是否选过模板：{attachmentCount:2,templateSelected:true}。未开启材料功能时为 null，不能解释为“零附件”。登记摘要不是文件完整性、签署、归档或审批通过的证明；完整材料仍通过材料接口核对。

4. 创建一批独立任务

POST /api/finance/pending-scan-task-batches

{
  "companyId": 1,
  "authorizationName": "TEST 备用金归还",
  "idempotencyKey": "TEST-return-20260919-001",
  "items": [{
    "repaymentObligationId": 11,
    "receiptAccountId": 21,
    "amount": "10.00"
  }]
}

• companyId 必须是当前公司；名称必填、最多 120 字；items 为 1–100 行。各行必须关联本公司的归还义务与可用收款账户；义务需要满足核销完结、余额与预占校验。
• amount 使用正数元字符串，最多两位小数，不使用浮点计算。当前通用任务层接受大于 0 的分值；具体支付产品还有独立限制。已实现的“批量付款到户有密”适配器最低为 1.00 元，不能从“任务能创建”推断金额可提交支付宝。
• 可选项：note（最多 255 字）；每行 materialIds（最多 5 个 UUID v4）及 contractTemplateId。主线资金方向默认 EMPLOYEE_TO_COMPANY，收款模式默认 COMPANY_SELF；其他模式不是通过随意传收款账户即可获准的捷径。
• idempotencyKey 为 8–128 位，允许字母、数字、点、下划线、冒号和连字符。同一个公司、同一个 key、相同规范化请求返回原批次；改变内容返回 409 IDEMPOTENCY_CONFLICT。修改用户意图才生成新 key；传输失败不能自动换 key。
• 新建返回 HTTP 201，重放返回 200；结构为 {batch:{...},tasks:[...],idempotent:false|true}。整批在事务内创建，一行校验失败不会保留半批新任务。

创建结果应再读取任务投影。创建任务不等于审批完成、二维码已生成或付款成功。旧单任务创建接口仍存在，但当前前台使用本批次入口承载创建与幂等恢复。

5. 材料、政策与员工资料

附件功能目前仅在 mode=mock && allowMockTools=true 开启，其他情况下材料路由返回 404。上传 PDF、PNG、JPEG，单文件最多 5 MiB、每行最多 5 个。服务端检查文件头尾、大小、名称、类型并计算摘要；这不等于文件内容获得法律效力或经过病毒扫描。

材料政策组合：REQUIRED 配 MANUAL_ARCHIVE / ESIGN / OTHER_APPROVED_METHOD；NOT_REQUIRED 配 NOT_APPLICABLE，并提供真实制度依据与版本。上传≠签署，模板≠签署文件，材料满足≠审批通过。归还任务的管理审批由既有后台流程完成。

6. 建码、查看、取消和重建

有效期以 qrExpiresAt 为准；常规旧 Mock 建码默认 30 分钟，授权接入运行时可采用单独设置的分钟数，不应在客户端写死。

“本批建码”是客户端先精确查批次、冻结合格任务 ID，再顺序调用单任务建码；不存在新增的批量资金支付接口。“查看本批二维码”只读取已有可查看任务，不自动建码、重建、认领或付款。逐张交付仍是一任务一码。

批内查看以开始查看时的任务集合为准，每次切换重新核对；读取时已过期、已认领或已作废的任务不展示二维码。显示期间到达过期时间会清除图片；其他人的操作不会实时推送到已打开窗口，最终可用性仍由扫码时的服务端校验决定。关闭后刷新可重新整理本批清单。

7. 支付结果与核销如何判断

1. GET 任务 / workbench 只读取当前记录，不会向支付宝发送主动查单。
2. 制单授权、员工确认、PAY_SUCCESS、查询证据、公司到账、回单、核销与业务回写分别核对。页面回跳、二维码生成、跳转成功不能作为付款成功证据。
3. 任务投影含 paymentAttempt、query、writeback、reconciliation、closure 和 timeline。当前 reconciliation.providerBillVerified=false 明示尚未验证真实机构账单；LOCAL_QUERY_VERIFIED 仅为本地验证结果。
4. 需补查时，使用既有管理后台的查询操作及其权限/环境限制。财务侧本文不提供越权激活、生产查单或直接触发付款指令。

禁止用于本归还方向：POST .../:id/submit-transfer 与 POST .../:id/query-transfer 为旧主动转账路径，当前返回 409 FUNDING_DIRECTION_MISMATCH，不能用它们实现员工还款。

8. 失败恢复与排查

排查记录保留请求时间、公司、任务/批次号、动作、HTTP 状态、业务 error 和 x-request-id。不要记录明文 Cookie、CSRF、二维码令牌、付款参数、密钥或完整员工身份信息。

本文不包含实际凭据、不执行示例请求、不改变接口权限。真实支付宝联调、到账与回单闭环须单独授权并依据官方契约验收。