Pārlūkot izejas kodu

docs(design): 家庭工作台重构设计规范 2026-11-13

Agnes Agent 5 dienas atpakaļ
vecāks
revīzija
4e2974449d
1 mainītis faili ar 97 papildinājumiem un 0 dzēšanām
  1. 97 0
      docs/design/2026-11-13-family-workbench-redesign.md

+ 97 - 0
docs/design/2026-11-13-family-workbench-redesign.md

@@ -0,0 +1,97 @@
+# 家庭运营工作台 × 家庭工作台 重构方案(2026-11-13)
+
+> 状态:方案定稿,开发会话按此实现
+> 归属模块:cfc-web(管理端)为主,cfc-backend 少量只读查询端点补充
+> 分支:`feature/family-workbench-redesign`(当前 worktree `E:/tmp/family-workbench`,基线 origin/cfclub 29eba26d0)
+
+## 1. 目标与分类口径(唯一原则)
+
+| 层 | 页面 | 放什么 | 原则 |
+|---|---|---|---|
+| **家庭运营工作台** | 现有 `/families`(Families.vue,重构) | **所有家庭**相关的信息:全局运营统计、跨家庭管理模块快捷入口、家庭列表 | 运营视角/跨家庭 |
+| **家庭工作台** | 新增 `/family-workbench?familyId=`(FamilyWorkbench.vue,新建) | **只放与当前家庭有关**的信息:该家庭统计数字 + 指标曲线 + 各模块明细列表与操作 | 单家庭视角 |
+
+**分类处理的具体动作**:
+- 家庭列表每行操作**只保留【进入工作台】【编辑】**;其余功能(查看成员、报告明细、方案明细、任务明细、CF值、奖励、心愿、消息、优惠券、收益、配置)**全部移到家庭工作台**。
+- 家庭运营工作台"上半部分"(统计带 + 快捷入口)只保留**跨家庭/全局**内容;凡属单家庭的点击直达明细(如行内报告数/方案数/任务数/优惠券数链接、"更多"下拉)全部移除。
+
+## 2. 家庭运营工作台(Families.vue 重构)
+
+保留并整理:
+1. **页头**:标题/副标题「家庭管理 · 运营总览(跨家庭)」+ 刷新。
+2. **运营统计带(全局/跨家庭口径)**:家庭总数、成员总数、报告总数、方案总数、任务总数(保持现有"本页合计"的实现即可,标注清楚);**移除「家庭总收益 —」(无接口的占位)**。
+3. **快捷入口网格(跨家庭模块,全部保留)**:家庭列表、孩子管理、积分管理、积分记录、心愿管理、奖励管理、CF值管理(现有 quickEntries 缺 CF 值入口、可补 `/cf-value`)、收益提现审核、家庭收益、家庭优惠券、汇总方式配置。
+4. **家庭列表表格**:
+   - 移除:行内「上传报告数/方案数/任务数/优惠券数量」的点击链接(改为纯文本即可,保留列)、“启用状态”保留;
+   - 操作列:只保留【进入工作台】(type=primary,新跳转)与【编辑】;
+   - **删除「更多」下拉**与 `handleMoreCmd`、`openDetailDialog`、`goCouponManage`、`goProxyReportUpload`、`openPlanGen` 等单家庭明细逻辑;`getFamilyOverview`/`getFamilyTasks` 相关 import 若不再使用需一并清理;
+   - **保留**:多条件检索、批量导出、批量启停(占位)、成员数字链接→查看成员弹窗(可保留在列表,也可仅保留“进入工作台”后查看;建议保留成员数字链接点击查看成员弹窗,属于轻量查看,不影响分类原则)、分页、排序。
+5. **「进入工作台」跳转**:`this.$router.push({ path: '/family-workbench', query: { familyId: row.id } })`。
+
+## 3. 家庭工作台(新 FamilyWorkbench.vue,路由 `/family-workbench`)
+
+### 3.1 页面结构
+1. **页头**:返回列表按钮 + 家庭名称 + 邀请码 + 创建时间 + 成员数概览。
+2. **统计卡片带(可点击,点击切换下方 tab)**:
+   - 成员数(→ 成员 tab)
+   - 报告数(→ 报告 tab;角标:待解析/PENDING 数可选)
+   - 方案数(→ 方案 tab;角标:待审核 pending_review 数,**必做**,对应"方案审核")
+   - 任务数(→ 任务 tab;角标:待办进行中数,对应"创建任务")
+   - CF 值合计(→ CF值 tab;来自新接口 cf-summary)
+   - 奖励(→ 奖励 tab;getRewardsList familyId 过滤的 total)
+   - 心愿(→ 心愿 tab;getWishesList familyId 过滤的 total)
+   - 咨询消息(→ 消息 tab;新接口 messages 的 total)
+3. **指标曲线区(ECharts,`echarts@6.1.0` 已在依赖)**:
+   - 曲线一「报告趋势」:基于 overview.reports 按 reportDate 聚合数量(前端计算即可);无 ECharts 用 `import * as echarts from 'echarts'`。
+   - 曲线二「CF 值变动趋势」:基于新接口 cf-summary 返回的近 N 条日志(按 createdAt 聚合/累计);数据为空时展示空态提示。
+4. **tab 明细区(每个 tab 只展示该家庭数据 + 操作按钮)**:
+
+| tab | 列表数据源(已核实复用) | 操作/跳转 |
+|---|---|---|
+| 报告 | `getFamilyOverview(familyId).reports` 全量 | 顶部按钮「代传报告」→ `/report-proxy-upload?familyId=`(该页用下拉选家庭,保持现状即可) |
+| 方案 | `getFamilyOverview(familyId).plans` 全量(筛选活页内可过滤状态) | 顶部按钮「方案管理/审核」→ `/health-plan-manage`(带 familyId query 善后) |
+| 任务 | `getFamilyTasks(familyId, {page,size})` 分页 | 顶部按钮「创建任务」→ `/tasks`(该页 familyId 为行内筛选,跳转后运营人员可在任务首页筛选) |
+| CF值 | **新接口** `POST /api/admin/families/{id}/cf-summary` | 成员 CF 余额表 + 合计 + 最近日志 |
+| 奖励 | `getRewardsList({familyId, page, size})` 分页 | 「去奖励管理」→ `/rewards` |
+| 心愿 | `getWishesList({familyId, status, page, size})` 分页;待处理数用 `getPendingWishes(familyId)` | 「去心愿管理」→ `/wishes` |
+| 咨询消息 | **新接口** `POST /api/admin/families/{id}/messages` 分页 | 「去消息管理」→ `/admin/teacher-messages`(按现状路由名确认) |
+| 成员 | `getFamilyMembers(familyId)` | 沿用现有查看成员弹窗的表格(昵称/手机/性别/年龄/积分/角色)+ 设为管理员/撤销按钮(setMemberAdminRole) |
+
+### 3.2 后端新增(轻量只读,2 个端点,遵循 AGENTS.md 流程)
+> 新增前先查 `docs/superpowers/api/API_REFERENCE.md` 确认无重复;新增路由后用
+> `grep -rn '@Mapping' cfc-backend/src/.../controller/` 检查路由重复;不动 schema、不加迁移。
+
+1. `POST /api/admin/families/{id}/cf-summary`
+   - 入参:`page/size`(日志分页,默认 1/20)
+   - 返回结构建议:`{ familyId, members: [{memberId, name, available, frozen, totalEarned, ...}], totalAvailable, totalFrozen, logs: [{id, userId, userName, amount, balanceAfter, refType, remark, createdAt}] }`
+   - 实现要点:`buildOverview` 同款成员解析(family_members 关联 User);CF 余额走 `UserPlatformBalanceMapper`(按 userId in 成员 userIds);日志走 `PlatformBalanceLog` 按 userId in 查询 createdAt 倒序(若 mapper 已有按 userId 查询则逐人查再合并,量小可接受;需自行评估后端已有 service 能力,`PlatformPointsService` 已有 getBalance(userId)/getLogs(userId,page,size),优先复用,逐个成员调用合并)。
+   - 角色校验:`@RequestAttribute("role")` 必须 admin,与 `AdminFamilyOverviewController` 一致。
+2. `POST /api/admin/families/{id}/messages`
+   - 入参:`page/size`
+   - 返回:分页 `TeacherMessage`(按 familyId 过滤 + createdAt 倒序),参考 `TeacherMessageController.getMessages` 的补全昵称模式回填家长姓名/老师姓名(`TeacherMessageService` 已有 mapper 能力,改造或新写 service 方法,注意 `startTx`/事务无关、纯查询)。
+   - 角色校验:admin。
+
+### 3.3 前端新文件/改动
+- 新建 `cfc-web/src/views/FamilyWorkbench.vue`(组件复用:`StatusTag`、`SortMixin`/`ListStateMixin` 如需要、`formatDate`;样式沿用 admin 变量:`--adm-*`)。
+- 修改 `cfc-web/src/router/index.js`:注册 `/family-workbench`,`meta: { title: '家庭工作台', perm: 'family:list' }`(与家庭列表同权限;如存在 family:read 权限考虑之,取现有家庭列表权限即可)。**不追加 Layout 菜单项**(从家庭列表进入即可)。
+- 修改 `cfc-web/src/api/admin.js`:新增 `getFamilyCfSummary(id, params)` 与 `getFamilyMessages(id, params)`。
+- 修改 `cfc-web/src/views/Families.vue`(见 §2)。
+
+## 4. 实现纪律(必须遵守)
+
+1. **只在本 worktree `E:/tmp/family-workbench` 内工作**;严禁对 `E:/cfc` 主工作树执行任何 git 写操作(禁 `reset --hard`/`checkout -- .`/`clean`/`stash`/`add -A`)。
+2. git 操作只在这条特性分支:`git add` 精确到目标文件 → `git commit`(消息含 `feat(family-workbench)` 前缀)→ `git push -u origin feature/family-workbench-redesign`。CRLF/LF:本项目文件大概率 LF,不要批量改写行尾,避免假 diff。
+3. 提交前:`git diff --cached --name-only | wc -l` 确认变更数合理(预期 ≤ 8 个文件);`git status --porcelain` 除目标文件外无其他改动。
+4. 后端改动必须 `mvn clean compile`(cfc-backend 模块,Java 8/Spring Boot 2.7);前端改动 `cd cfc-web && npm run lint`(或项目现有 lint 脚本,见 cfc-web/package.json scripts)与 build 不影响其他模块。若 build 耗时过长,至少保证语法/编译级验证(vue-cli-service lint 优先)。
+5. 完成 = 已 `git push` 远端 + worktree 干净(除未跟踪文件外) + 编译/lint 通过;完成后在会话内逐条汇报:改了哪几个文件、每个文件改了什么、后端编译是否通过、前端 lint/build 结果、push 的 commit sha。
+
+## 5. 验收清单
+
+- [ ] `/families` 操作列只有【进入工作台】【编辑】,无「更多」下拉、无行内明细链接
+- [ ] 统计带移除「家庭总收益 —」占位;快捷入口完整(含 CF 值管理)
+- [ ] `/family-workbench?familyId=N` 可打开,统计卡片数字真实(来自 overview/各列表接口),点击切 tab
+- [ ] 报告 tab 有「代传报告」按钮;方案 tab 有待审核角标与审核入口;任务 tab 有「创建任务」入口
+- [ ] CF值 tab 显示成员余额+合计+趋势曲线;消息 tab 显示该家庭咨询
+- [ ] 指标曲线至少渲染「报告趋势」(有数据时),CF 趋势有数据渲染、无数据显示空态
+- [ ] 后端 2 端点 mvn clean compile 通过;前端 lint 通过
+- [ ] commit 已 push 到 `feature/family-workbench-redesign`