发生了什么
房东是把自己的房屋或场地交给平台做合作经营的一方。系统会为每个房东建一份商户档案,档案上有一个“合作模式”字段,它由两个维度组成:主体是企业还是个人,以及是直接签约还是通过第三方签约。合作模式不只是展示信息,它决定后续结算单付给谁、发票开给哪个主体,也决定哪些框架协议和规则可以套用。
正常流程是:房东入驻时,入驻接口按传入参数确定合作模式,校验这个模式是否允许用于房东,然后建档。建档之后,日常维护走“编辑合作信息”,可以改名称、简称、联系电话、合作城市和合并支付开关。
这次的诉求是把一位房东从“直签企业”改成“直签个人”,也就是主体要从企业换成个人。运营在编辑页里找不到合作模式这一项;改用系统已有的合作模式切换接口,接口直接返回失败,只提示“不支持的切换类型”。
这条档案目前是“已失效”,原因是收款银行卡被删空后系统自动置为失效,与合作期无关。它名下没有网点,也没有账单和结算单,所以这次变更没有影响任何存量结算数据。实际处置是按“直签个人”重新建档、重新绑定收款账户,原档案按合作结束收尾。
本质
这条链路上有两处缺口,叠在一起让诉求无处可走。
- 编辑接口只更新五项基础信息。修改请求被转换成更新对象时,只写入了名称、简称、合作城市、电话和合并支付开关,没有把合作模式放进去。所以即使调用方在请求里带了模式,写库时也会被直接丢弃,页面上自然也没有这一项可填。
- 切换接口的白名单只覆盖同主体互切。合法组合只有四组:三方个人与直签个人互换、三方企业与直签企业互换。企业换个人属于跨主体,不在白名单里,判断返回 false,调用方随即结束流程,只回一个笼统的失败,没有告诉运营下一步该做什么。
- 模式合法性只在入驻建档时校验一次。建档之后的生命周期里没有设计跨主体的变更路径,而模式一旦变化,结算单的支付对象和开票主体都要跟着变,它并不是一个可以随手改的普通字段。
叠加起来,建档时主体类型选错,运行期就没有纠正入口。关键属性只在创建时校验、创建后没有变更路径,选错一次就只能重建。
修复方向有两条:一是把跨主体变更做成独立的变更流程,扩展切换白名单,并同步更新结算对象与开票主体等依赖信息;二是不扩能力,但让切换接口明确返回“需按新模式重新建档”,编辑接口在收到模式差异时直接报错,而不是静默丢弃。修复上线状态待确认。
下面两段是脱敏教学示例,用于说明错误与修复思路,不代表实际项目源码或已上线实现。
错误代码
// 编辑合作信息:更新对象只装了五项基础信息
public boolean updateCooperationInfo(EditRequest req) {
MerchantUpdate update = new MerchantUpdate();
update.setSimpleName(req.getSimpleName());
update.setMerchantName(req.getMerchantName());
update.setCityGuids(req.getCityGuids());
update.setPhone(req.getPhone());
update.setMergePayment(req.isMergePayment());
// 为什么错:请求里的合作模式没有写进更新对象,
// 界面上也没有这一项,模式永远改不了
return merchantMapper.update(update) > 0;
}
// 合作模式切换:白名单只放了同主体互切
public boolean isValidSwitchType(Mode from, Mode to) {
return (from == THIRD_PERSON && to == DIRECT_PERSON)
|| (from == DIRECT_PERSON && to == THIRD_PERSON)
|| (from == THIRD_ENTERPRISE && to == DIRECT_ENTERPRISE)
|| (from == DIRECT_ENTERPRISE && to == THIRD_ENTERPRISE);
// 为什么错:直签企业改成直签个人不在白名单,
// 调用方拿到 false 就结束,只回“不支持的切换类型”
}
修复代码示例
// 编辑入口不承担模式变更:收到模式差异时明确拒绝
public boolean updateCooperationInfo(EditRequest req) {
Merchant current = merchantMapper.selectById(req.getMerchantId());
if (req.getCooperationMode() != null
&& req.getCooperationMode() != current.getMode()) {
// 为什么这样改:不再静默丢弃,明确告知走模式变更流程
throw new BizException("合作模式不在编辑范围,请走模式变更流程");
}
return merchantMapper.update(buildUpdate(req)) > 0; // 其余五项沿用原逻辑
}
// 模式变更入口:同主体原地切换,跨主体给出重新建档指引
public SwitchResult switchMode(long merchantId, Mode target) {
Merchant m = merchantMapper.selectById(merchantId);
if (m.getMode().sameSubjectType(target)) {
return modeService.switchInPlace(m, target); // 保留原切换
}
// 为什么这样改:跨主体会改结算对象与开票主体,
// 不再静默失败,而是要求按新模式重新建档
return SwitchResult.recreateRequired(target, "请按目标模式重新建档");
}
修复的关键不是简单放开白名单,而是把两条路径说清楚:同一主体类型仍可原地切换;跨主体则要求按新模式重新建档,并在返回结果里写明原因和下一步。
下次遇到这些场景要警惕
- 给档案增加“创建时确定”的关键字段:把所有写入入口列一遍,新增、编辑、切换、批量导入、后台修数都要看,逐个确认要么写入要么明确拒绝;构造只改该字段的请求,看它是落库、报错,还是被静默丢弃。
- 复用切换或变更白名单:把取值的全部组合两两列出来,逐一断言放行还是拦截;被拦截时检查返回给运营的提示是否说清下一步,只回“不支持”等于没有路径。
- 跨主体、跨类型的变更:先确认会牵动哪些下游数据,包括结算支付对象、开票主体和依赖该字段的规则,再决定原地变更还是重新建档;两条路径都要验证新档案的生效状态和合作期能否自动衔接。
- 变更能力上线后:用一条真实档案分别验证允许和不允许的变更,允许的确认落库且下游同步,不允许的确认返回原因和替代操作,不能只看接口返回成功。