# 工时记录完整闭环功能使用指南

## 功能概述

工时记录系统提供了与任务执行联动的自动记录和手动补录两种方式，并支持完整的增、删、改、查功能，确保工时数据准确性以供薪酬核算使用。

## 核心功能

### 1. 自动同步工时（与任务执行联动）

**功能路径**：农事管理 > 绩效管理 > 工时记录 > "从任务同步工时"按钮

**工作原理**：
- 系统自动从"农事管理 > 任务管理"中读取状态为"已完成"的任务
- 提取任务的执行人、起止时间、作业类型、地块、面积等信息
- 自动计算工作时长（总工时）
- 生成工时记录并标记为"自动记录"
- 自动通过审核状态（因为来自已完成任务）

**数据来源**：
```typescript
任务执行记录 → 工时记录
- 任务ID → taskId
- 任务名称 → taskName
- 执行人 → staffName
- 实际开始时间 → startTime
- 实际结束时间 → endTime
- 作业类型 → workType
- 地块名称 → fieldName
- 作业面积 → area
```

**使用步骤**：
1. 进入"农事管理 > 绩效管理 > 工时记录"
2. 点击"从任务同步工时"按钮
3. 系统自动检测未同步的已完成任务
4. 自动创建工时记录并显示同步数量
5. 已同步的任务不会重复创建记录

### 2. 手动录入工时

**功能路径**：农事管理 > 绩效管理 > 工时记录 > "手动录入工时"按钮

**适用场景**：
- 补录历史工时数据
- 记录未关联任务的零散工时
- 修正自动记录的数据

**必填字段**：
- 员工：从系统员工列表中选择
- 工作类型：深翻、旋耕、播种、施肥、灌溉等
- 日期：工作日期
- 开始时间：作业开始时间
- 结束时间：作业结束时间

**可选字段**：
- 关联任务：可填写任务名称
- 地块名称：作业地块
- 作业面积：完成的作业面积（亩）
- 备注信息：工作情况说明

**系统自动计算**：
- 总工时 = (结束时间 - 开始时间) / 小时
- 实时显示预计工时

### 3. 工时记录管理（CRUD）

#### 查看（Read）
- 列表展示所有工时记录
- 每条记录显示：
  - 员工姓名、工作类型
  - 日期、起止时间、总工时
  - 地块、面积、效率（亩/时）
  - 关联任务、审核状态
  - 记录类型（自动记录/手动录入）
  - 备注信息

#### 编辑（Update）
1. 点击工时记录右侧的"编辑"按钮
2. 在弹出对话框中修改信息
3. 点击"保存工时记录"
4. 修改后状态变为"待审核"

#### 删除（Delete）
1. 点击工时记录右侧的"删除"按钮
2. 确认删除操作
3. 记录被永久删除（不可恢复）
4. 建议仅删除明显错误的记录

### 4. 审核流程

**状态说明**：
- **待审核**：新创建或修改的记录，需要管理员审核
- **已审核**：审核通过，可用于薪酬核算
- **已驳回**：审核未通过，需要修改

**审核操作**：
1. 对于"待审核"状态的记录，可进行：
   - 点击"审核通过"按钮 → 状态变为"已审核"
   - 点击"驳回"按钮 → 状态变为"已驳回"
2. 已审核的记录计入薪酬核算
3. 已驳回的记录需要重新编辑或删除

### 5. 薪酬核算支持

**数据准确性保证**：
- 时间验证：结束时间必须晚于开始时间
- 必填项检查：确保关键信息完整
- 数据溯源：区分自动记录和手动录入
- 审核机制：只有已审核的记录参与核算

**核算依据**：
- **工作时长**：精确到0.01小时
- **作业类型**：不同类型可能有不同时薪标准
- **作业面积**：计算工作效率
- **日期范围**：按周期统计工时

**导出功能**（后续开发）：
- 按时间范围导出工时汇总
- 按员工统计总工时
- 按作业类型分类统计
- 生成薪酬核算报表

## 数据存储

**LocalStorage 键名**：`smart_agriculture_work_hours`

**数据结构**：
```typescript
interface WorkHour {
  id: string;                           // 工时记录ID
  staffId: string;                      // 员工ID
  staffName: string;                    // 员工姓名
  taskId?: string;                      // 关联任务ID（可选）
  taskName?: string;                    // 关联任务名称（可选）
  date: string;                         // 工作日期
  startTime: string;                    // 开始时间 HH:mm
  endTime: string;                      // 结束时间 HH:mm
  totalHours: number;                   // 总工时
  workType: string;                     // 工作类型
  fieldName: string;                    // 地块名称
  area: number;                         // 作业面积（亩）
  notes: string;                        // 备注
  status: '待审核' | '已审核' | '已驳回';
  recordType: '自动记录' | '手动录入';
  createdAt: string;                    // 创建时间
}
```

## 与其他模块的集成

### 1. 员工管理模块
- **数据来源**：系统配置 > 用户管理 > 员工管理
- **读取字段**：员工ID、姓名、岗位、班组
- **用途**：工时记录的执行人选择

### 2. 任务管理模块
- **数据来源**：农事管理 > 任务管理
- **读取字段**：任务ID、名称、执行人、起止时间、作业类型、地块、面积
- **同步条件**：任务状态为"已完成"
- **防重复**：已同步的任务不会再次创建工时记录

### 3. 绩效统计模块
- **数据输出**：工时记录汇总到绩效统计
- **统计维度**：
  - 个人总工时
  - 完成任务数
  - 完成面积
  - 工作效率（亩/时）
  - 月度/季度趋势

## 最佳实践

### 1. 日常使用流程
```
任务计划 → 任务执行 → 任务完成 → 自动同步工时 → 审核确认 → 薪酬核算
```

### 2. 定期维护
- **每日**：检查待审核的工时记录
- **每周**：同步本周已完成任务的工时
- **每月**：审核本月工时，准备薪酬核算
- **每季度**：导出工时汇总，进行绩效分析

### 3. 数据质量控制
- ✅ 及时同步任务工时，避免遗漏
- ✅ 手动录入时仔细核对信息
- ✅ 定期审核待审核记录
- ✅ 发现错误及时修改或删除
- ✅ 保持备注信息完整，便于追溯

### 4. 常见问题处理

**Q: 工时记录显示为空？**
A: 
1. 检查是否有已完成的任务，点击"从任务同步工时"
2. 如果没有任务，点击"手动录入工时"补录
3. 点击"刷新数据"重新加载

**Q: 同步工时后数量为0？**
A: 
1. 确认任务管理中有状态为"已完成"的任务
2. 确认任务有执行人和实际起止时间
3. 已同步的任务不会重复创建记录

**Q: 如何修改已审核的工时？**
A: 
1. 点击编辑按钮修改
2. 保存后状态会变回"待审核"
3. 需要重新审核通过

**Q: 删除的记录能恢复吗？**
A: 不能。删除是永久性的，请谨慎操作。建议使用"驳回"代替删除。

## 辅助工具

系统提供了 `workHourTracker.ts` 工具库，包含以下函数：

- `createWorkHourFromTask()`: 从任务创建工时记录
- `saveWorkHour()`: 保存工时记录
- `batchCreateWorkHoursFromTasks()`: 批量创建工时
- `getStaffWorkHourStats()`: 获取员工工时统计
- `exportWorkHoursForPayroll()`: 导出薪酬核算数据

## 未来增强

- [ ] 工时批量导入（Excel）
- [ ] 工时批量导出（Excel/PDF）
- [ ] 异常工时预警（超时、缺勤）
- [ ] 工时成本计算（基于时薪标准）
- [ ] 工时可视化报表（图表展示）
- [ ] 移动端工时打卡
- [ ] GPS位置验证
- [ ] 生物识别考勤

## 总结

工时记录系统实现了完整的闭环管理：
1. ✅ **自动化**：与任务执行联动，自动记录工时
2. ✅ **灵活性**：支持手动补录历史数据
3. ✅ **完整性**：提供增删改查全功能
4. ✅ **准确性**：数据验证+审核机制
5. ✅ **可用性**：直接支持薪酬核算

系统确保了工时数据的准确性和完整性，为薪酬核算提供了可靠的数据基础。
