one-pipe-system/openspec/changes/add-business-user-group-management/proposal.md

Change: 业务用户组管理与店铺批量交接/导入（AUG26-003）

Why

后台需要把平台用户账号按业务线归入"业务用户组"，并基于组对店铺做筛选、批量交接负责人与 CSV 导入负责人。当前前端只有单个店铺设置平台业务员的能力，缺少业务用户组维护、成员归属、按组筛选、批量交接与导入入口；且现有 11 个新端点仅超管与平台账号可访问。

What Changes

• 新增业务用户组管理模块（API 层 + 维护页面 + 成员管理）：
  • GET/POST /api/admin/business-user-groups、GET/PUT/DELETE /api/admin/business-user-groups/{id}
  • PUT /api/admin/business-user-groups/{id}/members、DELETE /api/admin/business-user-groups/members
  • 编码创建后不可改；删除需 {"confirm": true} 且仅无成员组可删；更新支持部分字段，business_line 三态（缺省=不改 / ""=清空 / 枚举=设置）。
  • 成员归属整批校验（全部启用平台用户 + 目标组启用），任一无效整批不生效；一账号至多一组。
• 店铺列表/详情读取侧扩展：
  • GET /api/admin/shops 新增 business_user_group_id / business_line / ungrouped 筛选。
  • 列表/详情响应新增 5 个只读推导字段（组 ID/编码/名称/启用/业务线）；组停用仍返回组且 enabled=false（不算未分组）；前端不缓存、不回写，改组后重新拉列表。
• 勾选批量交接：
  • PUT /api/admin/shops/business-owner/batch：shop_ids（1-500，去重）+ business_owner_account_id；字段缺失=400，null=清空，ID=换绑；任一店铺无效或目标非启用业务员 -> 整批不写入，统一按 1005 提示。
• CSV 导入：
  • 复用 StorageService.getUploadUrl + 预签名 PUT 直传（FilePurpose 增加 shop_import）。
  • POST /api/admin/shops/business-owner-imports 创建异步任务，轮询详情、展示行级结果；前端自带模板（表头 店铺编码,操作类型,业务员登录账号,备注，换绑/清空）。
• 入口与权限（代理/企业不渲染入口）：
  • 路由 meta roles ['R_SUPER', 'R_ADMIN']；按钮权限码：
    • business_user_group:page / business_user_group:create / business_user_group:update / business_user_group:delete / business_user_group:members
    • shop:business_owner_batch
    • shop:business_owner_import

Not In Scope

• 不实现后端接口、不改数据库。
• 业务用户组不承载角色权限/数据范围语义；前端不引入组层级与组管理员概念。
• 导入结果不支持导出，仅在页面展示行级明细。

Impact

• Affected specs: business-user-group-management（新增）、shop-management（扩展）
• Affected code:
  • src/types/api/businessUserGroup.ts（新增）
  • src/api/modules/businessUserGroup.ts（新增）
  • src/types/api/shop.ts、src/api/modules/shop.ts
  • src/api/modules/storage.ts（FilePurpose 增加 shop_import）
  • src/views/shop-management/business-user-groups/index.vue（新增页面）
  • src/views/shop-management/list/index.vue
  • src/router/routes/asyncRoutes.ts、src/router/routesAlias.ts、src/locales/langs/{zh,en}.json
  • src/template/业务负责人导入模板.csv（前端自带模板）
• API contracts: 11 个端点（7 个业务用户组 + 店铺筛选/字段 + 批量交接 + 导入三步）
• Dependencies:
  • docs/产品迭代8月份/业务用户组.md（7 个组端点 OpenAPI）
  • AUG26-003 前端对接说明（店铺侧端点）

待确认

• 成员选择器复用 GET /api/admin/shops/business-owner-candidates（启用平台账号）；若组成员可包含非业务员平台账号，需后端补充平台账号列表端点。
• 导入任务与行级结果字段名（file_key、status、items[] 等）以生成文档为准，提案按对接说明先行对齐。