发票、收款、提成与订单状态数据流

本文基于 2026 年 8 月 24 日 当前代码实现，说明 CRM 中以下状态如何变化：

• 发票申请状态
• 回款审批状态
• 商机的订单状态
• 商机的财务状态
• 商机提成状态

本文描述的是系统当前实际执行逻辑，不把页面按钮、流程名称或历史设计当作已经生效的业务能力。

一、核心结论

1. 商机是主聚合对象：发票和回款都通过 orderId 关联商机，最终回写商机的 financialStatus。
2. 发票只有进入“已开票”才计入开票金额：待申请、待审核、已驳回、待上传都不参与财务状态计算。
3. 回款只有“审核通过”才计入已收款金额：草稿、审批中、审核不通过、已取消都不计入。
4. 财务状态只对“赢单”商机自动重算：非赢单商机触发重算时会直接跳过。
5. 订单状态与财务状态都为“完成”时才生成待提成记录：以后完成的那个状态决定 qualifiedSource。
6. 提成记录生成后不会因订单或财务状态回退而自动撤销。
7. 订单状态和财务状态都保留人工直接修改入口：人工修改为完成也可能直接触发提成资格。

二、总体数据流图

三、关键数据对象

系统中另有 crm_sales_commission“销售提成记录”模块，它是人工维护的收入、底薪等统计记录，没有提成状态，也不参与本文的自动资格链路。本文的“提成状态”指 crm_business_commission。

四、发票状态流转

4.1 状态定义

4.2 状态流转图

4.3 操作与业务影响

4.4 发票金额口径

商机已开票金额为：

SUM(crm_order_invoice.amount)，查询条件是同一 order_id 且发票状态为 50-已开票。

因此：

• 申请金额不代表已开票金额。
• 审核通过但仍待上传时，不计入已开票金额。
• 审核时附文件，或者后续上传正式发票，才会触发财务状态重算。
• 发票可以在商机尚未赢单时创建并开具，但自动财务重算会因商机不是赢单状态而跳过。

五、回款状态流转

5.1 状态定义

5.2 当前实际流转图

5.3 当前操作与业务影响

5.4 回款金额口径

商机已收款金额为：

SUM(crm_receivable.price)，查询条件是同一 order_id 且审批状态为 20-审核通过。

5.5 回款计划对逾期的影响

存在以下回款计划时，商机可能被计算为“付款逾期”：

• 计划属于当前商机；
• receivable_id 为空，表示尚未绑定回款；
• 计划回款时间早于当天开始时间。

创建回款并绑定某个回款计划后，系统会立即把回款编号写入计划。即使回款仍处于审批中，该计划也不再满足“未绑定回款”的逾期条件。

六、商机财务状态

6.1 状态定义

6.2 自动重算触发源

项目中存在 CrmBusinessFinancialStatusJob 处理器，但仓库内没有发现固定的 Quartz 初始化记录。是否按计划周期执行，取决于运行环境中是否另行配置了定时任务。

6.3 自动重算前置条件

只有同时满足以下条件才会计算：

• 商机存在；
• 商机总金额不为空；
• 商机结束状态为“赢单”。

如果不满足，系统保留当前 financialStatus，不会自动修改。

6.4 当前计算顺序

6.5 计算示例

假设商机总金额为 100 元：

重要口径：当前“款票完成”并不要求开票金额或回款金额达到商机总金额，只要求二者都大于 0，且回款金额不小于开票金额。因此“开票 30、回款 30、商机金额 100”也会被判定为款票完成。

6.6 人工修改财务状态

商机详情页提供财务状态下拉框。有 crm:business:financial 权限并具备商机写权限的人员，可以把财务状态直接改为任意合法枚举值。

人工修改：

• 不校验实际发票金额、回款金额和逾期计划；
• 修改为“款票完成”时，也会执行提成资格判断；
• 后续再次触发自动重算或执行批量重算任务时，可能被实际数据覆盖。

七、订单状态

7.1 状态定义

7.2 订单状态数据流图

7.3 自动同步限制

• 创建项目只有在商机订单状态仍为“未成单”时，才自动改为“立项”。
• 项目“开始报名”和“开始进行”事件目前只写日志，不直接改变订单状态。
• 商机订单状态一旦为“完成”，后续项目交付阶段事件不会再把它改回其他状态。
• 项目交付阶段只会自动写入“交付中”或“测试完成”，不会自动写入“测试中”。
• 人工修改接口没有固定的前后状态迁移限制，可以跨级或回退到任意合法状态。

7.4 人工修改订单状态

商机详情页提供订单状态下拉框。有 crm:business:status 权限并具备商机写权限的人员，可以直接选择任意合法状态。

当人工把订单状态改为“完成”时，系统同样会检查财务状态；如果财务状态已经是“款票完成”，会生成待提成记录。

八、提成状态

8.1 状态定义

8.2 提成资格生成规则

8.3 最后完成条件

提成记录的 qualifiedSource 表示哪个条件最后完成：

8.4 提成确认

8.5 当前不可逆行为

• 没有“取消提成”或“退回待提成”接口。
• 订单状态或财务状态从完成回退后，已经生成的提成记录不会删除。
• 已提成记录不会因订单退款、发票调整、回款状态回退而自动撤销。
• 每个租户的每个商机最多只有一条提成记录，数据库唯一键为 (tenant_id, business_id)。
• 修改赢单时间不会触发新的提成资格判断。

九、端到端业务场景

场景 A：先完成订单，后完成款票

1. TVP 全部关联项目结束，订单状态变为“完成”。
2. 此时财务状态未完成，不生成提成。
3. 正式发票上传，或者回款审批通过，触发财务状态重算。
4. 财务状态变为“款票完成”。
5. 系统发现订单已完成，创建“待提成”，qualifiedSource = FINANCIAL_STATUS。
6. 有确认权限的人员点击“确认提成”，状态变为“已提成”。

场景 B：先完成款票，后完成订单

1. 财务状态先变为“款票完成”。
2. 此时订单未完成，不生成提成。
3. 后续全部 TVP 项目结束，或人工把订单状态改为“完成”。
4. 系统发现财务已经完成，创建“待提成”，qualifiedSource = ORDER_STATUS。

场景 C：人工直接完成

1. 有权限的人员人工把财务状态改为“款票完成”，无需真实发票或审核通过回款。
2. 再人工把订单状态改为“完成”。
3. 系统会生成待提成记录。

这说明当前提成资格依赖的是两个状态字段，不会再次校验款票原始数据和项目实际完成数据。

场景 D：完成后回退

1. 订单和财务都完成，系统生成待提成记录。
2. 后续人工把订单改回“交付中”，或者把回款审批状态改回非通过导致财务状态重算回退。
3. 已生成的待提成或已提成记录仍然保留。

十、当前实现与业务确认项

以下内容是代码当前行为，建议业务负责人明确是否符合管理规则：

十一、业务操作速查

十二、代码实现位置