房源核验状态机与分佣台账的工程实现：核验码一致性、指纹去重与结算幂等

存量房交易系统的技术难点，通常不在页面，而在三处不可控：外部核验平台的回执不可控、同一实体被多个角色同时维护、金额与业绩需要能回滚。本文只讨论这三点在数据层与状态层的落地方式，不讨论产品形态。

图 5：房源从草稿到可发布要经过的核验状态，外部回执是唯一放行条件（状态机示意图）

一、把「能不能发布」建成一个状态判定，而不是一段人工流程

房源发布的判定条件通常是多项与关系的集合：委托关系有效、权属核验通过、核验码在有效期内、发布主体有备案、从业人员未跨机构执业。这类判定的常见错误是写成 if-else 堆在业务代码里，结果是每加一条规则就要改一次发布入口，且无法回答「为什么这套房源不能发」。

更稳的写法是两张表：

其一，合规项字典表。每个合规项一行：编码、适用范围（城市 / 房源类型 / 渠道）、是否阻断、责任方、有效期规则、数据来源。城市差异通过适用范围过滤，不需要分支代码。

其二，房源合规项状态表。每套房源 × 每个适用合规项一行：状态（未启动 / 提交中 / 已通过 / 已驳回 / 已过期）、外部单号、回执原文、更新时间、过期时间。

发布入口只做一件事：求当前房源适用合规项集合，与状态表求差集，差集里存在阻断项则拒绝并返回缺项清单。规则变化时改字典表，不改发布入口。

二、外部回执不可控：超时、乱序与重复回调

核验平台是外部系统，工程上必须假设三件事同时发生：回调可能重复、可能乱序、可能永远不来。

处理顺序建议如下：

1. 以外部单号做幂等键。回调先落原始报文表（主键 = 外部单号 + 回执类型），再更新业务状态；同一单号的重复回调只落库不改状态。
2. 状态只允许向前。提交中 → 已通过 / 已驳回 是单向的；若出现「已通过」之后再收到「驳回」，不直接改状态，而是生成一条「状态冲突」记录转人工，避免历史发布记录被静默改写。
3. 对超时做主动轮询，而不是等回调。设置提交后 N 分钟未回执则进入轮询队列，轮询失败超过阈值标记为「待人工核查」，同时把房源置为不可发布。
4. 保留回执原文。回执里的时间戳与状态码是后续争议时的证据，只存解析后的状态是不够的。

这类系统的可用性靠的不是回调及时，而是回调不来时的降级路径明确。

三、核验码一致性：一份快照，多处引用

同一套房源往往同时在自有小程序、门店端、外部渠道展示。核验码在多个出口出现时，问题不在「有没有」，在「是不是同一个」。

可落地的做法是给每次核验通过生成一份发布快照：快照包含核验码、有效期、房源关键字段（挂牌口径、面积、楼层、权属状态）的哈希。所有出口展示的核验码与关键字段都从快照读取，不以房源主表实时值为准。

理由很简单：房源主表会被编辑，核验结果绑定的是提交核验那一刻的事实。主表改了面积而快照未更新，展示出去的核验码就与页面内容不一致，这在核查时属于明显瑕疵。

快照失效的三种情形要显式处理：有效期到期、房源关键字段变更、外部状态被撤销。任一发生即置快照为失效，联动所有出口下架，而不是逐个渠道去改。

四、房源指纹：归一化可以做，自动合并不能做

同一套房子被多个角色录入是常态，去重的目标是「提示重复」，不是「消灭重复」。

归一化字段建议取：行政区、小区标准名（需小区字典，不能用自由文本）、楼栋、房号、建筑面积区间（按 5 平方米分档）、户型。这几项组合后取哈希作为指纹。

工程上要注意三点：

• 小区名必须走字典。「XX 花园」「XX花园一期」「xx花园」在自由文本下会生成三个指纹，去重直接失效。小区字典需要维护别名表。
• 指纹命中只进待确认队列。给录入人展示疑似重复项与差异字段，由人选择「并入已有房源」或「新建并标注」。自动合并会破坏业绩归属，属于不可逆的数据事故。
• 面积用区间而非精确值。录入习惯差异（89.6 / 89.62 / 90）在精确匹配下必然漏判。

五、分佣台账：事件溯源 + 结算快照 + 冲正

分佣的技术难点不是计算，是可回滚与可解释。一笔成交的佣金可能经历：成交确认、分期到账、部分退单、跨月结算、税率调整。若无事件记录，任何一次对账争议都只能靠人回忆。

结构上建议三层：

| 层 | 表 | 职责 | 关键约束 |

|---|---|---|---|

| 事实层 | 成交事件表 | 记录每一次业务事实（成交、退单、改价） | 只追加，不修改；事件时间与录入时间分开存 |

| 计算层 | 分佣明细表 | 按规则版本把事件展开为多角色明细 | 记录规则版本号，规则变更不回算历史 |

| 结算层 | 结算单表 | 按周期汇总明细，生成应收应付 | 结算单一旦确认即冻结，调整走新单据 |

三个工程细节：

1. 规则版本化。分佣规则必须带版本号和生效时间。历史明细引用当时的版本，规则调整后只影响新事件。否则每次改规则，历史账目全部漂移。
2. 冲正而非删除。退单发生时生成负向明细冲抵原明细，原明细保留。删除会让「为什么这个月少了钱」永远说不清。
3. 结算单幂等。同一周期重复生成结算单要有唯一键（周期 + 主体 + 币种），重复请求返回既有单据而不是新建。

资金侧还有一条硬约束：结算单只是应收应付的凭据，实际付款走对公账户或持牌机构的分账指令。系统不应持有可支配资金，也就不需要处理资金池的账务问题。

六、权限与交接：把「人走了」当成一次事务

多层级组织中，权限不是角色列表，是数据可见域。可行做法是把可见域表达为四个维度的组合：组织节点、房源归属状态（公盘 / 私盘 / 联卖）、角色、时间窗。判定在查询层统一注入，不在每个接口里各写一遍。

人员离职是高频故障点：私盘挂在离职人员名下、委托关系未转移、账号未注销。处理方式是把离职做成一次事务：冻结账号 → 列出待交接资源（私盘、在跟客源、未结佣金）→ 指定接收人 → 批量转移并留痕 → 注销账号。任何一步失败则整体回滚，不允许「先注销再说」。

图 6：事实层只追加、计算层带规则版本、结算层冻结，三层职责不混（数据结构示意图）

七、几处容易踩的坑

| 现象 | 根因 | 处理 |

|---|---|---|

| 房源页显示已下架，渠道端仍可见 | 出口各自读主表，未联动快照失效 | 引入快照 + 统一失效广播 |

| 回调重复导致状态来回跳 | 无幂等键，状态允许回退 | 外部单号去重，状态单向 |

| 同一房源两条业绩 | 指纹自动合并或归属规则缺失 | 指纹只提示不合并；归属三要素判定 |

| 结算金额与明细对不上 | 规则变更回算了历史明细 | 规则版本化，历史不回算 |

| 离职后私盘失联 | 交接非事务化 | 离职流程做成整体事务 |

图 7：指纹命中后进待确认队列，由归属三要素判定业绩，不由系统自动合并（流程对比示意图）

八、小结

这类系统的工程质量，取决于三件事是否被显式建模：外部依赖的失败路径、事实的可追溯性、规则的版本化。把「能不能发布」做成状态判定、把核验结果做成快照、把分佣做成事件溯源，后面每加一条城市规则或一类分佣角色，都只是加数据，不是改代码。

反过来，若这三处都写在业务分支里，系统在上线半年后就会进入「没人敢改」的状态——这才是真正的技术债。