# 报表统计模块需求分析

**版本**: V1.2
**更新时间**: 2026-04-15

---

## 一、需求清单概览

| 需求ID | 描述 | 优先级 | 状态 |
|--------|------|--------|------|
| REPORT-001 | 个人任务完成统计 | P1 | ❌ 未实现 |
| REPORT-002 | 家庭任务完成统计 | P1 | ❌ 未实现 |
| REPORT-003 | 积分收支明细 | P1 | ❌ 未实现 |
| REPORT-004 | 成长趋势图表 | P1 | ❌ 未实现 |

---

## 二、需求详细描述

### 2.1 个人任务完成统计（REPORT-001）

#### REPORT-001: 个人任务完成统计
- **描述**：统计指定孩子在指定时间范围内的任务完成情况，包括完成任务数、超时数、驳回数、完成率等
- **筛选条件**：
  - 时间范围：今日/本周/本月/自定义
  - 任务分类：学习类/生活类/运动类/其他
  - 任务状态：已完成/已超时/已驳回
- **统计维度**：
  - 任务总数
  - 完成任务数
  - 超时任务数
  - 驳回任务数
  - 完成率
  - 平均完成耗时
- **展示形式**：数字卡片 + 列表 + 筛选条件

---

### 2.2 家庭任务完成统计（REPORT-002）

#### REPORT-002: 家庭任务完成统计
- **描述**：统计整个家庭在指定时间范围内的任务完成情况，支持按孩子分组
- **筛选条件**：
  - 时间范围：今日/本周/本月/自定义
  - 家庭成员：全部/指定孩子
  - 任务分类：学习类/生活类/运动类/其他
- **统计维度**：
  - 家庭任务总数
  - 各孩子完成任务数
  - 各孩子完成率对比
  - 任务完成趋势
  - 分类分布
- **展示形式**：家庭概览卡片 + 孩子对比表格 + 趋势图表

---

### 2.3 积分收支明细（REPORT-003）

#### REPORT-003: 积分收支明细
- **描述**：记录并展示指定孩子或家庭成员的积分变动明细，包括获得积分和扣除积分
- **筛选条件**：
  - 时间范围：今日/本周/本月/自定义
  - 积分类型：获得/扣除/全部
  - 来源类型：任务奖励/打卡奖励/兑换扣除/超时扣分/系统赠送
- **统计维度**：
  - 当前积分余额
  - 积分获得总数
  - 积分扣除总数
  - 积分净变化
  - 各来源占比
- **展示形式**：余额卡片 + 收支明细列表 + 饼图/趋势图

---

### 2.4 成长趋势图表（REPORT-004）

#### REPORT-004: 成长趋势图表
- **描述**：以图表形式展示孩子在一段时间内的成长趋势，包括任务完成、积分变化、打卡连续性等
- **图表类型**：
  - 折线图：任务完成趋势
  - 柱状图：积分变化
  - 热力图：打卡连续性
  - 雷达图：能力维度分布
- **时间粒度**：日/周/月
- **对比功能**：
  - 与自身历史对比
  - 与家庭成员对比
  - 与同龄孩子对比（可选）
- **展示形式**：图表Dashboard + 数据导出

---

## 三、统计维度汇总

### 3.1 任务统计维度

| 维度 | 说明 | 计算方式 |
|------|------|----------|
| 任务总数 | 统计周期内创建的任务数 | COUNT(task_id) |
| 完成任务数 | 状态为已完成的任务数 | COUNT WHERE status='completed' |
| 超时任务数 | 超过截止时间的任務数 | COUNT WHERE status='overdue' |
| 驳回任务数 | 审核被驳回的任务数 | COUNT WHERE reviewResult='rejected' |
| 完成率 | 完成任务数/任务总数 | 完成任务数/任务总数 |
| 平均完成耗时 | 从创建到完成平均耗时 | AVG(completedAt - createdAt) |

### 3.2 积分统计维度

| 维度 | 说明 | 计算方式 |
|------|------|----------|
| 当前积分 | 孩子当前持有的积分余额 | SUM(获得) - SUM(扣除) |
| 获得积分 | 通过任务/打卡获得的积分 | SUM WHERE type='earned' |
| 扣除积分 | 通过兑换/超时扣除的积分 | SUM WHERE type='deducted' |
| 净变化 | 获得积分 - 扣除积分 | 获得积分 - 扣除积分 |

### 3.3 时间粒度说明

| 粒度 | 说明 | 适用场景 |
|------|------|----------|
| 今日 | 当天 00:00 ~ 23:59:59 | 实时查看 |
| 本周 | 周一 ~ 周日 | 周报 |
| 本月 | 1日 ~ 月末 | 月报 |
| 自定义 | 用户选择起止日期 | 专题分析 |

---

## 四、API接口设计

### 4.1 个人统计

| 方法 | 路径 | 功能 | 权限 |
|------|------|------|------|
| GET | /api/reports/child/{childId}/tasks | 个人任务统计 | 孩子/家长 |
| GET | /api/reports/child/{childId}/points | 个人积分统计 | 孩子/家长 |
| GET | /api/reports/child/{childId}/trend | 个人成长趋势 | 孩子/家长 |

### 4.2 家庭统计

| 方法 | 路径 | 功能 | 权限 |
|------|------|------|------|
| GET | /api/reports/family/{familyId}/tasks | 家庭任务统计 | 家长 |
| GET | /api/reports/family/{childId}/points | 家庭积分统计 | 家长 |
| GET | /api/reports/family/{familyId}/ranking | 家庭排行 | 家长 |

### 4.3 导出功能

| 方法 | 路径 | 功能 | 权限 |
|------|------|------|------|
| GET | /api/reports/export/child/{childId} | 导出个人报表 | 孩子/家长 |
| GET | /api/reports/export/family/{familyId} | 导出家庭报表 | 家长 |

---

## 五、前端页面设计

| 页面 | 路径 | 功能 |
|------|------|------|
| 个人统计 | `/pages/report/child` | 个人任务与积分统计 |
| 家庭统计 | `/pages/report/family` | 家庭整体统计与对比 |
| 成长趋势 | `/pages/report/trend` | 图表化成长趋势 |
| 数据导出 | `/pages/report/export` | 报表导出 |

---

## 六、待完善事项

| 功能 | 优先级 | 说明 |
|------|--------|------|
| 个人任务统计API | P1 | 后端统计接口 |
| 家庭任务统计API | P1 | 后端统计接口 |
| 积分明细API | P1 | 后端明细接口 |
| 趋势图表前端 | P1 | 图表组件集成 |
| 数据导出功能 | P2 | PDF/Excel导出 |
| 同龄对比 | P2 | 需要匿名汇总数据 |

---

## 七、后续开发建议

### 7.1 第一阶段：基础统计
1. 个人任务统计 API
2. 个人积分统计 API
3. 基础统计页面

### 7.2 第二阶段：家庭统计
1. 家庭任务统计 API
2. 家庭排行 API
3. 家庭统计页面

### 7.3 第三阶段：可视化
1. 成长趋势图表
2. 打卡热力图
3. 数据导出功能

---

## 八、技术实现建议

### 8.1 统计缓存
- 每日凌晨生成前一日统计快照
- 使用缓存提高查询性能

### 8.2 数据聚合
- MySQL GROUP BY 实现基础统计
- 复杂趋势计算可考虑预计算或定时任务

### 8.3 图表方案
- Web端：ECharts / AntV
- 小程序端：uni-app 图表组件 / uCharts