UR#96 店铺业务员归属功能总结

本次交付范围

本次完成店铺业务员归属的六个后端纵向切片：持久化、平台创建设置或继承、代理创建安全继承、独立编辑、列表/详情/候选 Query，以及通知接收人解析 Port/Adapter。

业务员归属是平台内部业务责任关系，只保存当前店铺自己的 business_owner_account_id。它不参与店铺层级、数据权限、佣金、分销或提现计算，也不会因父店铺后续修改而级联变化。

创建与编辑契约

POST /api/admin/shops 支持存在性感知的 business_owner_account_id：平台/超管可显式设置、显式 null 清空；字段缺失时复制直属上级店铺当时保存的原始 ID。
代理创建直属下级店铺时不得提交该字段；字段缺失时由服务端复制直属上级店铺当时保存的原始 ID，包括已停用或软删除账号的历史 ID。
PUT /api/admin/shops/:id 中字段缺失表示保持不变，显式 null 表示清空，正 ID 表示重新绑定。
只有超级管理员和平台账号可以人工设置、清空或更换，并在事务内重新校验候选仍为启用、未删除的普通平台账号。
店铺、初始主账号、账号角色、店铺角色和主/分佣钱包在同一 GORM 事务内创建，避免多表半成品。

Audit Event 写入按七月测试环境 Change 冻结到任务 6.5，本次没有把审计延期扩散到业务事务、权限或可靠性边界。

Query 与前端契约

GET /api/admin/shops 新增 business_owner_account_id 精确筛选，并与其他筛选条件按 AND 组合。创建、编辑、列表和详情统一返回：

business_owner_account_id
business_owner_username
business_owner_phone_summary
business_owner_available

列表只针对当前页收集业务员 ID，并通过一次批量查询投影账号名、前三后四手机号摘要和可用状态，不产生逐店铺 N+1。软删除账号使用只读历史投影保留摘要，并将 business_owner_available 标记为 false。

新增接口：

GET /api/admin/shops/:id：返回与列表一致的店铺及业务员摘要，并继续应用现有店铺数据范围。
GET /api/admin/shops/business-owner-candidates：仅超级管理员和平台账号可调用，只返回启用、未删除的普通平台账号 ID、账号名和手机号摘要；支持用户名/手机号关键词、默认 20、最大 100 的分页。

代理端只读展示业务员摘要，不展示候选选择或清空控件。停用或删除账号应显示历史摘要和“不可用”，空归属显示为“-”。

通知接收人解析边界

NotificationRecipientResolver Port 由 PostgreSQL RecipientResolver Adapter 实现。它按目标店铺当前保存的业务员 ID 解析接收人，并同时返回当前启用、未删除的店铺主账号：

业务员只有仍为 user_type=2、启用且未删除时才返回。
店铺主账号只有仍为代理类型、主账号、启用且未删除时才返回。
同一账号按稳定账号 ID 去重并排序。
店铺不存在、无归属或账号永久不可用时返回空集合，不作为无限重试错误。
数据库故障仍返回可重试错误。
解析不读取父店铺、祖先店铺或创建人，不会把代理数据权限误当作通知关系。

该接缝供公共站内通知的动态接收人解析复用；UR#96 本身不实现套餐临期、钱包低余额等业务触发规则，也不发送短信或企业微信通知。

迁移、发布与回滚

迁移 000169_add_shop_business_owner 为 tb_shop 增加 nullable bigint 字段和普通索引，不建立外键、不回填存量数据、不运行父子级联脚本。

发布前应只读核验店铺层级异常和平台账号状态；发布后抽查平台显式设置/清空、代理继承、父级修改不级联、历史不可用账号展示和接收人解析。应用回滚应保留字段和已产生的历史归属；down 迁移检测到任何非空归属时会拒绝删列，要求前向修复。

当前验证状态

已执行 gofmt、git diff --check 和 go build ./...。按本 Change 的测试环境豁免，本次未新增或运行 _test.go，也未连接真实 PostgreSQL/Redis；集成、HTTP、迁移演练和前端人工验收分别转任务 6.1、6.3 和 6.6。

4.3 KiB Raw Blame History Unescape Escape