|
|
@@ -0,0 +1,80 @@
|
|
|
+# 服务商「我的团队」多团队管理（设计）
|
|
|
+
|
|
|
+- 日期：2026-10-30
|
|
|
+- 状态：待派发
|
|
|
+- 优先级：P1
|
|
|
+- 模块：cfc-backend / cfc-frontend
|
|
|
+- 需求方：廖总
|
|
|
+- 需求原文：小程序「我的团队」页面（从「我的页面 → 我的成就」进入的 `/pages/vendor/team-system/team-system`，页面文案「服务商团队管理」）应支持多团队管理，一个人可能在多个团队里同时出现。
|
|
|
+- 展示交互（已与需求方确认）：顶部团队切换器（标签页/下拉），选中哪个团队就看哪个团队的成员、客户与统计数据。
|
|
|
+
|
|
|
+## 1. 背景与现状（只读摸底结论）
|
|
|
+
|
|
|
+「我的团队」页 = `cfc-frontend/pages/vendor/team-system/team-system.vue`（623 行），数据源：
|
|
|
+
|
|
|
+| 前端函数 | 后端接口 | 参数 |
|
|
|
+|---|---|---|
|
|
|
+| `getVendorSystemInfo()` | `/api/admin/supply-system/my-system` | 无（取「我的」默认系统） |
|
|
|
+| `getVendorHierarchyInfo()` | `/api/admin/supply-hierarchy/my` | 无 |
|
|
|
+| `getVendorTeamMembers(systemId)` | `/api/admin/supply-team/members` | **有 systemId ✅** |
|
|
|
+| `getVendorTeamCustomers(params)` | `/api/admin/supply-team/customers` | params（应含 systemId） |
|
|
|
+
|
|
|
+后端数据模型：
|
|
|
+- `DistributionSystem`（`distribution_systems` 表）：`id / name / description / ownerId / profitRate / enabled`。一个团队实体。
|
|
|
+- `DistributionRelation`（`distribution_relations` 表）：用户与分销团队的关系（归属/上下级）。
|
|
|
+- **已支持一人多团队**：`DistributionService.getUserTeams(userId)`（行 182）返回 `List<DistributionSystem>`；对应接口 `DistributionInviteController.myTeams`（`/api/.../my-teams`）。
|
|
|
+
|
|
|
+现状缺口：
|
|
|
+- 页面只渲染「我的单个」团队（systemInfo 无 systemId 参数，隐式取当前服务商默认团队），无团队列表、无切换 UI。
|
|
|
+- `getVendorTeamMembers` 虽已支持 systemId，但页面未维护/传递 currentSystemId。
|
|
|
+- 一人已在多个分销团队的场景下，页面无法切换查看。
|
|
|
+
|
|
|
+## 2. 方案（定稿）
|
|
|
+
|
|
|
+### 2.1 后端（cfc-backend）
|
|
|
+
|
|
|
+1. **「我的团队列表」接口**（若无可复用现有 `my-teams` / `getUserTeams`）——小程序端专享、鉴权到当前用户，返回 `List<DistributionSystem>`（含 id/name/ownerId/enabled）。复用 `DistributionInviteController.myTeams` 或新增 `/api/distribution/my-teams`（注意：现有 my-teams 路径在 DistributionInviteController，确认小程序端可调用鉴权；如沿用 `/api/admin/*` 通道须确认服务商角色放行）。
|
|
|
+2. **各团队信息接口显式支持 teamId / systemId 参数**：
|
|
|
+ - `supply-system/my-system`：支持可选 `systemId`；缺省取当前用户默认团队，传入则查指定团队。
|
|
|
+ - `supply-hierarchy/my`：同上支持 `systemId`。
|
|
|
+ - `supply-team/members` / `supply-team/customers`：确认参数已含 `systemId`（前端已传），后端按 systemId 过滤。
|
|
|
+3. **成员跨团队**（可选增强）：若「一个人可能在多个团队里同时出现」指成员维度（某客户/下级同属多个团队），确认 `distribution_relations` 是否允许多条归属；如需在成员列表标注「同时所属其他团队」，由接口附带 `otherTeamIds`。本期先聚焦团队切换，成员跨团队标注列为可选。
|
|
|
+
|
|
|
+### 2.2 小程序前端（cfc-frontend/pages/vendor/team-system/team-system.vue）
|
|
|
+
|
|
|
+1. **顶部团队切换器**（用户选定交互）：页面顶部加「团队切换器」——标签页（多个团队并排，当前高亮）或下拉选择器；数据来自「我的团队列表」接口。
|
|
|
+2. **状态维护**：页面 `data` 增加 `teamList: []`、`currentSystemId: null`；选中团队 → 写 `currentSystemId`。
|
|
|
+3. **联动刷新**：`onLoad` / 切换团队时，用 `currentSystemId` 调 `getVendorSystemInfo` / `getVendorHierarchyInfo` / `getVendorTeamMembers(currentSystemId)` / `getVendorTeamCustomers({ systemId })`，刷新团队规模、成员、客户、统计数据。
|
|
|
+4. **新建团队（可选）**：切换器旁加「+ 新建团队」入口，调现有创建团队接口（确认 `DistributionService` 是否有 createSystem / 由 `getUserTeams` 反查创建入口；若无则由开发会话评估新增）。本期可先做切换，新建留作增强。
|
|
|
+
|
|
|
+### 2.3 涉及文件清单
|
|
|
+
|
|
|
+| 层 | 文件 | 改动 |
|
|
|
+|---|---|---|
|
|
|
+| 后端 | `cfc-backend/.../controller/DistributionInviteController.java` | 确认/新增「我的团队列表」小程序接口；my-system/my 支持 systemId |
|
|
|
+| 后端 | `cfc-backend/.../service/DistributionService.java` | getUserTeams 复用；my-system 按 systemId 查询 |
|
|
|
+| 小程序 | `cfc-frontend/pages/vendor/team-system/team-system.vue` | 顶部团队切换器 + currentSystemId 联动刷新 |
|
|
|
+| 小程序 | `cfc-frontend/utils/api.js` | getVendorSystemInfo / getVendorHierarchyInfo 增 systemId 参数透传 |
|
|
|
+
|
|
|
+## 3. 验收标准
|
|
|
+
|
|
|
+- [ ] 小程序「我的团队」页顶部出现团队切换器，列出当前用户所属/创建的多个团队。
|
|
|
+- [ ] 切换团队后，团队成员、客户、统计数据随之刷新为所选中团队的数据（与后端单团队查询一致）。
|
|
|
+- [ ] 仅有单个团队时，切换器退化显示单个团队（不报错）。
|
|
|
+- [ ] 后端「我的团队列表」接口按当前用户鉴权返回其全部团队（非他人团队泄漏）。
|
|
|
+- [ ] `mvn clean compile`（cfc-backend）通过；`npm run build:mp-weixin`（cfc-frontend）通过。
|
|
|
+- [ ] 小程序无可选链 `?.`、无 CSS Grid、`:key` 用方法调用（遵循 AGENTS.md 小程序限制）。
|
|
|
+
|
|
|
+## 4. 技术约束（AGENTS.md 铁律）
|
|
|
+
|
|
|
+- 后端接口统一 `@PostMapping`；`@Resource` 注入；控制器内手动检查 `@RequestAttribute("role")`（服务商角色放行确认）。
|
|
|
+- 新增/修改接口前查阅 `docs/superpowers/api/API_REFERENCE.md` 避免重复。
|
|
|
+- 小程序禁用可选链、禁用 CSS Grid、禁用 `:key` 表达式、禁用直接 `new Date(string)`。
|
|
|
+- 一人多团队查询须带当前 userId 鉴权，禁止越权读取他人团队。
|
|
|
+
|
|
|
+## 5. 边界与取舍
|
|
|
+
|
|
|
+- 本期聚焦「我在多个团队间切换管理」（团队维度）；成员「跨多个团队同时出现」标注列为可选增强，不影响主线。
|
|
|
+- 复用现有分销体系实体与 `getUserTeams`，不新建团队表。
|
|
|
+- 若后端 `my-system` 当前强依赖「当前登录服务商身份」无法按 systemId 切换，须改造为显式 systemId（重点验收项）。
|
|
|
+- 接口路径现有 `/api/admin/*` 前缀，小程序端调用需确认鉴权通道（服务商身份）；如不通，开发会话须同步新增小程序可调用接口或调整路由。
|
Agnes Agent