junhong_cmp_fiber/openspec/changes/add-employee-collection-bills/specs/employee-collection-bill/spec.md

Purpose

为后台账号代客户经办的线下套餐购买和代理预存款充值建立独立的员工应收、外部付款核验和企业微信终审闭环；该能力只保存可追溯的本地业务事实，不推测或回填历史第三方付款。

ADDED Requirements

Requirement: 员工代收款账单来源、金额与上线边界

系统 SHALL 仅为功能上线后新发生的下列业务创建员工代收款账单，并以实际发起该业务的后台账号作为不可修改的欠款人：

• 平台业务员或超级管理员创建的、会生成账单的后台线下套餐订单，账单金额取订单 actual_paid_amount；代理代购和无代理归属自营 C 端均适用。该订单创建成功后仍按既有规则立即激活。
• 代理线下预存款/主钱包充值在企业微信最终通过且完成入账后，账单金额取对应充值记录 amount。

客户自行线上支付、平台代理 C 端客户充值资产钱包、订单失败或取消、赠送套餐等不产生员工账单的既有线下订单，以及“其他”手工来源 MUST NOT 创建账单。系统 MUST 为同一来源业务建立至多一张账单，并保存来源类型、来源 ID、来源单号、客户/店铺快照、欠款人、应收金额和创建时间；上线前业务不回填、不补建。

Scenario: 后台线下套餐订单产生账单

• WHEN 平台业务员或超级管理员成功创建一个需要生成账单的后台线下套餐订单
• THEN 系统以该操作账号为欠款人、以订单 actual_paid_amount 为应收金额创建唯一待核销账单，且订单无需因未上传付款凭证而阻断

Scenario: 审批入账的代理充值产生账单

• WHEN 功能上线后代理线下预存款/主钱包充值经企业微信最终通过并完成入账
• THEN 系统以实际发起充值的后台账号和充值 amount 创建唯一待核销账单

Scenario: 重复来源或历史业务不产生重复账单

• WHEN 同一来源业务被重复处理、重复回调，或业务发生在功能上线前
• THEN 系统至多保留一张来源关联账单，且不补建上线前账单

Requirement: 账单余额、状态与关闭

账单 SHALL 独立维护 待核销、部分核销、已核销、已关闭 状态及应收金额、已核销金额、审批中预占金额和剩余可核销金额。只有企业微信最终通过的分摊增加已核销金额；审批中的分摊预占剩余可核销金额，防止并发申请超额核销。账单已核销金额等于应收金额时 MUST 为已核销；关闭账单只作废当时未核销余额，已核销金额必须保留。

欠款人离职、禁用或变更组织后，账单欠款人身份和既有账单范围 MUST 保持不变。员工仅可查询本人账单和申请；财务与超级管理员可按既有数据范围查询；仅超级管理员可代办创建、修改或重提申请，且必须记录实际代办人和原因。

Scenario: 部分核销后仍可继续核销

• WHEN 一张账单存在企业微信已通过但未结清的分摊
• THEN 系统增加已核销金额、将账单标记为部分核销，并仅允许新的分摊使用未被已通过或审批中分摊占用的余额

Scenario: 关闭未结清账单

• WHEN 超级管理员对待核销、部分核销或已驳回关联申请的账单填写关闭原因并执行关闭，且账单不存在审批中申请
• THEN 系统作废未核销余额、将账单标记为已关闭、保留已核销金额和操作审计

Scenario: 审批中账单不可关闭

• WHEN 超级管理员尝试关闭存在审批中核销申请的账单
• THEN 系统拒绝关闭，账单金额和状态不变

Requirement: 外部付款核销申请与分摊

员工 SHALL 按一笔外部付款创建一张核销申请。申请 MUST 选择一个启用的线下收款方式字典项，并保存其稳定编码和名称快照；必须保存经人工确认的付款金额、付款方、付款时间、外部交易流水号、至少一个支付凭证和可选其他凭证、备注及一个或多个账单分摊。申请人只能通过勾选可见账单创建分摊，系统带出只读来源订单、客户和资产信息。

系统 SHALL 按账单产生时间从早到晚用本次付款金额预填分摊，最后一张填入剩余金额；申请人可修改各分摊金额。单笔分摊 MUST 大于零且不得超过该账单可核销余额；分摊总额 MUST 不超过本次人工确认付款金额。同一外部付款可被多个核销申请引用，本期 MUST NOT 对跨申请累计分摊金额实施系统防重或金额上限校验。

Scenario: 一笔付款分摊多张账单

• WHEN 员工选择多张可见账单并提交一笔外部付款的核销申请
• THEN 系统按账单时间预填分摊、校验每张账单可核销余额和申请总额，并为该申请创建唯一企业微信审批实例

Scenario: 账单并发申请预占

• WHEN 两个核销申请并发选择同一账单的剩余余额
• THEN 系统至多接受不超过该账单未核销余额的审批中和已通过分摊，其余申请返回余额不足且不创建超额分摊

Requirement: 核销申请审批、重提与幂等

核销申请状态 SHALL 为 审批中、已通过、已驳回、已撤销/已关闭，且不得以申请状态覆盖账单核销状态。提交或重提时系统 MUST 冻结当次收款方式、外部付款、附件、备注、账单分摊及审批材料快照，并创建新的企业微信审批实例。

企业微信最终通过时，系统 MUST 幂等地将申请标记为已通过、将各分摊写入账单已核销金额并释放其预占；最终驳回时 MUST 标记申请已驳回、释放全部预占且保留审批意见。已驳回申请可修改全部申请内容后重提，历史审批实例、材料和结果不得覆盖；已通过分摊不可修改。企业微信提交失败、回调延迟或结果未知时申请保持在途，系统 MUST 使用既有查询/恢复机制确认渠道结果，且不得由本地人工通过或拒绝绕过企业微信。

Scenario: 企业微信通过核销申请

• WHEN 企业微信对含多笔分摊的核销申请返回最终通过，且该结果首次被消费
• THEN 系统仅一次更新申请、各账单已核销金额和状态，并保留审批实例及冻结快照

Scenario: 企业微信驳回后重提

• WHEN 企业微信最终驳回核销申请
• THEN 系统释放预占、保留驳回实例和意见；员工或有代办权限的超级管理员修改申请后重提时创建新的审批实例

Requirement: 收款方式字典、退款联动与可追溯性

系统 SHALL 提供唯一固定分类的线下收款方式字典。超级管理员可维护名称、稳定编码、排序、启停和备注；已被业务引用的字典项 MUST NOT 被物理删除，只能停用，且历史申请继续显示冻结名称。

来源套餐订单全额退款且账单从未存在已通过分摊时，系统 MUST 自动关闭账单并记录“来源订单全额退款”；部分退款且从未存在已通过分摊时，系统 MUST 按退款金额冲减账单应收金额并保留来源订单退款冲销记录。账单存在任一已通过分摊时，系统 MUST NOT 自动冲销，仅在账单详情提示来源订单退款。退款不恢复已核销账单的员工欠款。

账单、申请、分摊、附件、审批实例、字典快照、关闭和退款冲销 MUST 可按权限查询并记录操作审计；审计和日志不得保存完整支付凭证敏感内容。OCR 若可用仅用于预填，必须允许申请人或审核人更正，且识别值不是资金事实。

Scenario: 来源订单部分退款且未核销

• WHEN 来源套餐订单部分退款，且其账单不存在任何已通过分摊
• THEN 系统按退款金额冲减账单应收金额，保留退款冲销关联，并重新计算账单状态和可核销余额

Scenario: 被引用字典项停用

• WHEN 超级管理员停用已被核销申请引用的线下收款方式
• THEN 新申请不可选择该方式，历史申请仍展示其冻结名称和稳定编码