junhong_cmp_fiber/docs/7月迭代/独立方案/新增需求/07-店铺业务员与钱包余额预警.md

禅道补充需求：店铺业务员与钱包余额预警

来源：禅道 #96、#97。最终口径以标准评审稿为准。

一、边界

店铺业务员只表示平台内部的业务归属，用于列表筛选和通知接收。它不建立代理分销关系，不参与店铺上下级、佣金、提现或数据权限计算。

钱包预警阈值固定为 100 元，不做系统配置、角色配置或店铺配置。

二、店铺业务员

tb_shop 增加：

business_owner_account_id BIGINT NULL

• 只允许绑定启用的平台账号。
• 创建、编辑店铺时可不选择。
• 店铺列表支持按业务员筛选，列表和详情返回账号名称。
• 业务员停用或删除后保留关联和历史审计，但不再作为通知接收人；运营可以重新绑定。
• 不建立数据库外键，Application 显式校验账号类型和状态。

API 调整：

POST /api/admin/shops
PUT  /api/admin/shops/{id}
GET  /api/admin/shops?business_owner_account_id={id}

三、固定 100 元余额预警

固定常量：

const AgentWalletLowBalanceThreshold int64 = 10000 // 代理主钱包现金余额预警阈值：100元

只计算代理主钱包现金可用余额：

cash_available = balance - frozen_balance

信用额度不参与预警。触发条件：

before_cash_available > 10000
after_cash_available <= 10000

接收人：

• 店铺启用的主账号。
• 店铺绑定且仍启用的平台业务员。

本期只发送站内通知，不发送企业微信消息。

四、防重复

• 首次跌至 100 元及以下时发送一次。
• 持续低于阈值时，后续扣款不重复通知。
• 余额充值到 100 元以上后重新布防，再次跌破可以重新发送。
• 通知使用钱包 ID、预警轮次和接收人组成稳定业务键。

可以在主钱包保存 low_balance_alert_active，或者使用通知状态投影记录当前预警轮次；无论实现方式如何，资金事务不能因为通知失败而回滚，事件先写 Outbox。

五、前端

• 店铺创建、编辑增加可搜索的平台业务员下拉框。
• 店铺列表和详情展示业务员，并支持筛选。
• 资金概况在现金可用余额小于等于 100 元时显示红色“现金余额不足 100 元”。
• 不展示阈值编辑入口。
• 通知点击后受控跳转到对应店铺资金概况。

六、审计

记录业务员绑定变更、预警触发时的余额/冻结金额、接收人、通知事件 ID 和失败原因。信用额度不得写入余额预警判断结果。