# 家长首页全面整改计划

> **Status:** Draft
> **Goal:** 修复数据断层、重构视觉布局、提升加载体验
> **涉及模块:** cfc-backend, cfc-frontend

---

## 一、P0 — 功能性 Bug（必须修复）

### 1.1 `familyId` 数据断层

**问题：** `ParentDashboardController.getDashboard()` 不返回 `familyId`，但前端第 483-485 行试图读取 `dashData.familyId`，结果为 `undefined`。这导致第 527 行 `getPendingWishes(this._familyId)` 发送 null 请求。

**改动：**
- **后端** `ParentDashboardController.java`：在 result map 中添加 `familyId`
  ```java
  // 获取当前用户的 familyId
  Long familyId = userService.getUserFamilyId(userId);
  result.put("familyId", familyId);
  ```
- **前端** `api.js`：`getPendingWishes()` 请求体加 `familyId` 判空保护，或 fallback 到独立 API 获取

**涉及文件：**
- `cfc-backend/.../controller/parent/ParentDashboardController.java`
- `cfc-backend/.../service/UserService.java`（可能需要新增 `getUserFamilyId` 方法）
- `cfc-frontend/pages/index/parent-index.vue`

### 1.2 CSS Grid 不兼容微信小程序

**问题：** 第 1219-1222 行 `.pending-grid` 使用 `display: grid`，微信小程序不支持。

**改动：** 将 `.pending-grid` 改为 flexbox 布局：
```css
.pending-grid {
  display: flex;
  flex-wrap: wrap;
  gap: 16rpx;
}
.pending-card {
  width: calc(50% - 8rpx);  /* 2 列 */
}
```

**涉及文件：**
- `cfc-frontend/pages/index/parent-index.vue`

### 1.3 成长建议区块无数据

**问题：** `growthAdvice[]` 在 data 中声明（第 386 行），`v-for` 渲染（第 279-293 行），但整个 `loadData()` 中没有任何 API 调用填充它。该区块要么永远不显示，要么报错。

**改动（二选一）：**
- **方案 A**：删除该区块（如果无实际数据源）
- **方案 B**：从 dashboard API 或新增 `/api/growth/advice` 接口获取数据

**涉及文件：**
- `cfc-frontend/pages/index/parent-index.vue`

---

## 二、P1 — 数据准确性

### 2.1 待完成任务标题是假的

**问题：** 第 588-596 行根据 `pendingTasks` 数量生成 "待完成任务 1/2/3" 这类占位文本。

**改动：** 从后端获取真实任务列表。有两个方案：
- **方案 A（推荐）**：`getChildCompletionStats` 返回值增加 `pendingTaskList[]`（含 id, title），或直接用已有的 `getPendingReviewTasks` 数据筛选未完成的任务
- **方案 B**：新建轻量接口 `/api/tasks/pending-by-child?childId=X` 返回待完成任务列表

**涉及文件：**
- `cfc-backend/.../service/TaskStatsService.java`（扩展返回数据）
- `cfc-frontend/pages/index/parent-index.vue`

### 2.2 "全家平均" 不包含家长

**问题：** `familyAvgCompletionRate`（第 86 行 `totalCompletionRate / childCount`）只计算了孩子的平均完成率，不含家长自己的完成率。

**改动：** 后端计算时将家长自己的完成率纳入平均：
```java
// 家长 + 所有孩子
int totalRate = parentCompletionRate + totalCompletionRate;
int avgRate = childCount > 0 ? totalRate / (childCount + 1) : parentCompletionRate;
result.put("avgCompletionRate", avgRate);
```
或前端直接展示为"孩子平均"并保留"自己的"，同时展示"全家平均 = (家长 + Σ孩子) / (1+孩子数)"。

**涉及文件：**
- `cfc-backend/.../controller/parent/ParentDashboardController.java`
- `cfc-frontend/pages/index/parent-index.vue`（label 文案调整）

### 2.3 降级模式下 myPoints 错误

**问题：** 当 dashboard 降级（第 566-581 行），第 578 行 `this.myPoints = targetChild.totalPoints || 0` 把"自己的积分"设置成了孩子的积分，而非家长的。

**改动：** 降级时 `myPoints` 应从当前用户的 `userInfo` 缓存中读取：
```javascript
var userInfo = uni.getStorageSync('userInfo')
this.myPoints = (userInfo && userInfo.totalPoints) || 0
```

**涉及文件：**
- `cfc-frontend/pages/index/parent-index.vue`

### 2.4 能量概览不加载

**问题：** 第 397 行 `currentChildId: ''`（空字符串），第 613 行 `if (overviewChildId)` 条件不成立，导致 `getEnergyOverview` 永远不会被调用。

**改动：** 加载完 `selectedChild` 后设置 `currentChildId`：
```javascript
// 在 dashboardLoaded 成功后或降级加载 children 后：
this.currentChildId = (this.selectedChild && this.selectedChild.id) || ''
```

**涉及文件：**
- `cfc-frontend/pages/index/parent-index.vue`

---

## 三、P2 — 用户体验重构

### 3.1 区块精简与重组

**问题：** 11 个区块堆叠，用户需要大量滚动。核心数据（统计 + AI）埋得太深。

**改动方案：**

```
当前顺序：
  Banner → 成员条 → 孩子卡片 → 能量沙盘 → 会员Banner → 成长数据(2卡) → AI入口 → 今日重点 → 里程碑 → 待办网格 → 建议+审核+快捷

建议重组（压缩至 6 区块）：
  [第1屏] Banner + 成员条
  [第2屏] 孩子卡片 + 快捷操作（融合）
  [第3屏] 成长数据（2卡） + AI 助手入口（融合在一行）
  [第4屏] 能量沙盘（折叠式，默认收起，点击展开）
  [第5屏] 今日重点 + 待办网格（合并为"今日概要"）
  [第6屏] 待审核任务（保留，可滑动删除）
```

**关键改动：**
1. **AI 入口上移**：从第 7 位移到第 3 位，与 stat cards 同行或紧随其后
2. **能量沙盘可折叠**：默认展示概要，展开显示完整沙盘
3. **删除**：会员 Banner（无实际功能）、成长建议（无数据源）
4. **合并**："待审核任务"独立区块 → 并入"待办网格"中展开
5. **快捷操作下移**：改为悬浮固定在底部或作为 TabBar 扩展

**涉及文件：**
- `cfc-frontend/pages/index/parent-index.vue`

### 3.2 动画 class 去重

**问题：** `animate-stagger-9` 在第 279 行（成长建议）和第 320 行（快捷操作）重复使用。

**改动：** 重新编号，确保整个模板内 stagger 编号唯一。

**涉及文件：**
- `cfc-frontend/pages/index/parent-index.vue`

---

## 四、P3 — 加载体验优化

### 4.1 骨架屏 / 分区加载

**问题：** 当前一次性 `BaseLoading` 等待所有 API 完成后才显示内容。dashboard + 多个独立 API 串行导致白屏时间长。

**改动：** 拆分为分区加载：
1. 立即显示骨架框架（内容占位）
2. 每个区块的 API 完成后独立更新
3. 首个数据（dashboard）到达后优先渲染孩子卡片 + stat cards
4. 能量沙盘、成员条等次级数据后加载

### 4.2 下拉刷新

**改动：** 添加 `onPullDownRefresh` 生命周期钩子：
```javascript
onPullDownRefresh() {
  this.loadData().finally(function() {
    uni.stopPullDownRefresh()
  })
}
```
并在 `pages.json` 对应页面配置 `"enablePullDownRefresh": true`。

**涉及文件：**
- `cfc-frontend/pages/index/parent-index.vue`
- `cfc-frontend/pages.json`

### 4.3 错误状态 UI

**问题：** 所有 API 失败仅 `console.log`，用户无感知。

**改动：** 每个主要区块添加错误兜底状态：
- Stat cards 失败 → 显示 `--` 或 "数据加载失败"
- 孩子列表失败 → 显示 "点击重试" 按钮
- 能量沙盘失败 → 隐藏该区块

---

## 五、执行顺序与工作量估算

```
Phase 1 — 基础修复（1-2 人天）
  ├── P0-1: familyId 数据断层       ← 后端 0.5d + 前端 0.2d
  ├── P0-2: CSS Grid → Flex         ← 前端 0.1d
  ├── P0-3: 成长建议区块处理        ← 前端 0.1d
  └── P1-34: 降级/能量初始化        ← 前端 0.3d

Phase 2 — 数据准确性（1 人天）
  ├── P1-1: 待完成任务真实标题      ← 后端 0.3d + 前端 0.3d
  ├── P1-2: 全家平均含家长          ← 后端 0.1d + 前端 0.1d
  └── P4-2: 下拉刷新                ← 前端 0.2d

Phase 3 — UI 重构（2-3 人天）
  ├── P2-1: 区块精简重组            ← 前端 1-2d（含测试）
  ├── P2-2: 动画 class 去重         ← 前端 0.1d
  ├── P4-1: 骨架屏                  ← 前端 0.5d
  └── P4-3: 错误状态 UI             ← 前端 0.3d
```

**优先执行 Phase 1**（修复现有功能断裂），**Phase 2** 视数据重要性决定是否并行，**Phase 3** 为视觉/体验升级。

---

## 六、涉及文件清单

| # | 文件 | 改动量 | Phase |
|---|------|--------|-------|
| 1 | `cfc-backend/.../ParentDashboardController.java` | +10 行 | 1 |
| 2 | `cfc-backend/.../service/UserService.java` | 新增 `getUserFamilyId` | 1 |
| 3 | `cfc-backend/.../service/TaskStatsService.java` | 扩展返回 `pendingTaskList` | 2 |
| 4 | `cfc-frontend/pages/index/parent-index.vue` | 100-300 行变更 | 1/2/3 |
| 5 | `cfc-frontend/pages.json` | +3 行 (pullRefresh) | 2 |
| 6 | `cfc-frontend/utils/api.js` | 可能微调 | 1/2 |