迭代方案确认

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

@@ -0,0 +1,81 @@
+# 禅道补充需求：店铺业务员与钱包余额预警
+
+> 来源：禅道 #96、#97。最终口径以标准评审稿为准。
+
+## 一、边界
+
+店铺业务员只表示平台内部的业务归属，用于列表筛选和通知接收。它不建立代理分销关系，不参与店铺上下级、佣金、提现或数据权限计算。
+
+钱包预警阈值固定为 100 元，不做系统配置、角色配置或店铺配置。
+
+## 二、店铺业务员
+
+`tb_shop` 增加：
+
+```text
+business_owner_account_id BIGINT NULL
+```
+
+- 只允许绑定启用的平台账号。
+- 创建、编辑店铺时可不选择。
+- 店铺列表支持按业务员筛选，列表和详情返回账号名称。
+- 业务员停用或删除后保留关联和历史审计，但不再作为通知接收人；运营可以重新绑定。
+- 不建立数据库外键，Application 显式校验账号类型和状态。
+
+API 调整：
+
+```text
+POST /api/admin/shops
+PUT  /api/admin/shops/{id}
+GET  /api/admin/shops?business_owner_account_id={id}
+```
+
+## 三、固定 100 元余额预警
+
+固定常量：
+
+```go
+const AgentWalletLowBalanceThreshold int64 = 10000 // 代理主钱包现金余额预警阈值：100元
+```
+
+只计算代理主钱包现金可用余额：
+
+```text
+cash_available = balance - frozen_balance
+```
+
+信用额度不参与预警。触发条件：
+
+```text
+before_cash_available > 10000
+after_cash_available <= 10000
+```
+
+接收人：
+
+- 店铺启用的主账号。
+- 店铺绑定且仍启用的平台业务员。
+
+本期只发送站内通知，不发送企业微信消息。
+
+## 四、防重复
+
+- 首次跌至 100 元及以下时发送一次。
+- 持续低于阈值时，后续扣款不重复通知。
+- 余额充值到 100 元以上后重新布防，再次跌破可以重新发送。
+- 通知使用钱包 ID、预警轮次和接收人组成稳定业务键。
+
+可以在主钱包保存 `low_balance_alert_active`，或者使用通知状态投影记录当前预警轮次；无论实现方式如何，资金事务不能因为通知失败而回滚，事件先写 Outbox。
+
+## 五、前端
+
+- 店铺创建、编辑增加可搜索的平台业务员下拉框。
+- 店铺列表和详情展示业务员，并支持筛选。
+- 资金概况在现金可用余额小于等于 100 元时显示红色“现金余额不足 100 元”。
+- 不展示阈值编辑入口。
+- 通知点击后受控跳转到对应店铺资金概况。
+
+## 六、审计
+
+记录业务员绑定变更、预警触发时的余额/冻结金额、接收人、通知事件 ID 和失败原因。信用额度不得写入余额预警判断结果。
+