# 绩效统计功能完整开发文档

## 功能概述

绩效管理模块的绩效统计功能已全面完成开发，实现了基于工时和任务完成数据的完整绩效分析系统，为管理人员提供客观的考评依据。

## 核心功能特性

### 1. 多维度统计视图

#### 1.1 个人绩效统计
- **动态计算**：基于已审核工时记录自动计算个人绩效
- **关键指标**：
  - 总工时（小时）
  - 完成任务数（个）
  - 完成面积（亩）
  - 工作效率（亩/工时）
  - 综合评分（0-100分）
- **自动排名**：按效率指标自动排序，TOP 3 特殊展示

#### 1.2 班组绩效统计
- **班组聚合**：自动聚合班组成员的工时数据
- **团队指标**：
  - 班组总工时
  - 班组完成任务数
  - 班组完成面积
  - 班组平均效率
  - 班组综合评分
- **班组对比**：班组间绩效自动排名对比

### 2. 灵活的时间范围选择

#### 2.1 多时间维度
- **按周统计**：自动计算当前周（周一至周日）
- **按月统计**：自动计算当前月（月初至月末）
- **按季度统计**：自动计算当前季度（3个月）
- **按年统计**：自动计算当前年度（1月至12月）

#### 2.2 日期选择器
- 灵活选择任意日期
- 系统自动计算对应的时间范围
- 实时显示统计周期信息

### 3. 关键指标卡片

展示4个核心总览指标：

1. **总工作量**：所有人员/班组的累计完成面积（亩）
2. **总工时**：所有人员/班组的累计工作时长（小时）
3. **完成任务**：所有完成的任务总数（个）
4. **平均效率**：整体平均工作效率（亩/工时）

### 4. 绩效排行榜

#### 4.1 排名展示
- **TOP 3 特殊标识**：
  - 🥇 第一名：金色边框和背景
  - 🥈 第二名：银色边框和背景
  - 🥉 第三名：铜色边框和背景
- **排名徽章**：圆形彩色徽章显示排名
- **详细指标**：每行显示5项关键指标
- **星级评价**：基于综合评分的五星评级

#### 4.2 空数据处理
- 友好的空状态提示
- 引导用户确保有已审核的工时记录

### 5. 多维度图表分析

#### 5.1 效率与工作量对比图
- **类型**：双Y轴柱状图
- **左Y轴**：工作效率（亩/工时）
- **右Y轴**：工作量（亩）
- **用途**：直观对比效率和工作量的关系

#### 5.2 工时与任务数分布图
- **类型**：柱状图
- **数据**：工时（小时）+ 完成任务数（个）
- **用途**：分析工时投入与任务完成的分布

#### 5.3 班组综合能力雷达图（班组视图专属）
- **类型**：多维度雷达图
- **维度**：
  - 工作量（归一化至0-100）
  - 工作效率（归一化至0-100）
  - 任务数量（归一化至0-100）
  - 工作时长（归一化至0-100）
- **用途**：全面评估班组的综合能力
- **显示条件**：仅在"班组绩效"视图且有数据时显示

#### 5.4 效率趋势分析图
- **类型**：折线图
- **时间跨度**：近3个月
- **用途**：分析绩效的历史趋势变化
- **备注**：当前为示例数据，实际使用时将基于历史数据动态生成

### 6. 数据计算逻辑

#### 6.1 数据来源
- **基础数据**：从工时记录中提取
- **筛选条件**：只统计状态为"已审核"的工时记录
- **时间范围**：根据用户选择的时间范围筛选

#### 6.2 个人绩效计算
```typescript
// 1. 聚合同一人员在时间范围内的所有工时记录
// 2. 累加总工时、总面积
// 3. 统计不同任务ID的数量
// 4. 计算效率 = 总面积 / 总工时
// 5. 计算评分 = 效率 * 20 + 完成面积 * 0.1（最高100分）
// 6. 按效率降序排序并分配排名
```

#### 6.3 班组绩效计算
```typescript
// 1. 根据人员班组信息，聚合同一班组的所有工时记录
// 2. 累加班组总工时、总面积
// 3. 统计班组完成的不同任务ID数量
// 4. 计算班组效率 = 班组总面积 / 班组总工时
// 5. 计算班组评分（同个人评分逻辑）
// 6. 按效率降序排序并分配班组排名
```

#### 6.4 雷达图数据归一化
```typescript
// 为使不同量纲的指标可对比，进行归一化：
// - 工作量：min(100, 完成面积 / 10)
// - 效率：min(100, 效率 * 10)
// - 任务数：min(100, 任务数 * 5)
// - 工时：min(100, 工时 / 2)
```

### 7. 用户交互功能

#### 7.1 筛选控制
- **统计维度切换**：个人绩效 ⇄ 班组绩效
- **时间范围切换**：周/月/季度/年度
- **日期选择**：选择具体日期，自动计算范围

#### 7.2 数据导出
- **导出报表按钮**：导出当前统计结果（功能预留）
- **支持格式**：Excel / PDF（待实现）

#### 7.3 实时更新
- 切换筛选条件时，数据实时重新计算
- 图表自动更新以反映最新数据
- 关键指标卡片同步更新

## 技术实现细节

### 1. 状态管理
```typescript
// 绩效统计筛选条件
const [perfTimeRange, setPerfTimeRange] = useState<'week' | 'month' | 'quarter' | 'year'>('month');
const [perfViewType, setPerfViewType] = useState<'individual' | 'team'>('individual');
const [perfPeriod, setPerfPeriod] = useState(new Date().toISOString().split('T')[0]);
```

### 2. 核心计算函数
- `getPerfDateRange()` - 根据时间范围和选择日期计算起止日期
- `filterPerfWorkHours()` - 筛选时间范围内的已审核工时
- `calculateIndividualPerformance()` - 计算个人绩效
- `calculateTeamPerformance()` - 计算班组绩效
- `formatPeriodLabel()` - 格式化周期标签显示

### 3. 数据流向
```
工时记录数据 (workHours)
    ↓
时间范围筛选 (filterPerfWorkHours)
    ↓
已审核工时记录
    ↓
个人/班组聚合计算
    ↓
排名和评分
    ↓
图表数据转换
    ↓
UI展示
```

### 4. 图表组件
使用 Recharts 库实现：
- `<BarChart>` - 柱状图
- `<LineChart>` - 折线图
- `<RadarChart>` - 雷达图
- `<ResponsiveContainer>` - 响应式容器

## 使用指南

### 快速开始

1. **进入绩效管理模块**
   ```
   农事管理 → 绩效管理 → 绩效统计 Tab
   ```

2. **选择统计维度**
   - 点击"统计维度"下拉框
   - 选择"个人绩效"或"班组绩效"

3. **选择时间范围**
   - 点击"时间范围"下拉框
   - 选择"按周"、"按月"、"按季度"或"按年"
   - 选择具体日期

4. **查看统计结果**
   - 查看关键指标卡片的总览数据
   - 查看绩效排行榜的详细排名
   - 查看各类图表的可视化分析

### 业务场景

#### 场景1：月度绩效考核
```
1. 选择"个人绩效"
2. 选择"按月"
3. 选择当前月的任意日期
4. 查看排行榜，找出TOP员工
5. 导出报表用于绩效面谈
```

#### 场景2：班组对比分析
```
1. 选择"班组绩效"
2. 选择"按季度"
3. 查看班组排行榜
4. 查看雷达图的综合能力对比
5. 分析各班组的优劣势
```

#### 场景3：效率趋势跟踪
```
1. 选择"个人绩效"
2. 切换不同月份查看排名变化
3. 查看效率趋势图
4. 分析效率提升或下降原因
```

## 数据要求

### 前置条件
1. 系统中已有人员信息
2. 已录入工时记录
3. 工时记录已通过审核（状态为"已审核"）

### 数据完整性
- **工时记录必填字段**：
  - 员工姓名
  - 日期
  - 开始时间
  - 结束时间
  - 工作面积
- **可选但建议填写**：
  - 关联任务ID（用于统计任务数）
  - 地块名称
  - 工作类型

## 优势特点

### 1. 数据驱动
- 基于真实工时记录，客观公正
- 自动计算，减少人工统计误差
- 实时更新，数据时效性强

### 2. 多维分析
- 个人和班组双视角
- 多种时间粒度
- 丰富的图表可视化

### 3. 智能排名
- 自动按效率排序
- TOP 3 视觉突出
- 星级评价直观

### 4. 灵活查询
- 任意时间范围
- 快速切换维度
- 友好的用户界面

## 未来规划

### 短期优化
1. [ ] 实现报表导出功能（Excel/PDF）
2. [ ] 添加绩效对比功能（选择多个周期对比）
3. [ ] 增加绩效目标设定和达成率

### 中期规划
1. [ ] 基于历史数据生成真实的趋势图
2. [ ] 添加绩效预警功能（效率低于目标值）
3. [ ] 支持自定义评分权重

### 长期规划
1. [ ] 与薪酬系统集成，自动计算绩效工资
2. [ ] AI智能分析，提供绩效提升建议
3. [ ] 移动端优化，支持随时随地查看绩效

## 注意事项

1. **数据准确性**
   - 绩效统计只基于"已审核"的工时记录
   - 请确保工时审核流程的及时性和准确性

2. **时间范围选择**
   - 周统计：从周一开始到周日结束
   - 月统计：从1号到月末
   - 季度统计：1季度(1-3月)、2季度(4-6月)、3季度(7-9月)、4季度(10-12月)

3. **空数据情况**
   - 如果选择的时间范围内没有已审核工时，将显示空数据提示
   - 请确保工时记录和审核的及时性

4. **性能考虑**
   - 大数据量时（如年度统计），计算可能需要一定时间
   - 建议按需选择合适的时间范围

## 技术支持

如有问题或建议，请联系技术团队。

---

**开发完成日期**：2025-01-20  
**版本**：v1.0.0  
**状态**：✅ 已完成并可用
