smart-crop-ui/src/CHANGE_HISTORY_GUIDE.md

# 农机全生命周期档案变更历史功能指南

## 功能概述

农机全生命周期档案变更历史功能提供了完整的数据变更追踪和审计能力，自动记录所有档案信息的修改操作，包括操作人、时间、旧值和新值，实现数据变更的全程可追溯。

## 核心特性

### 1. 自动变更追踪
- ✅ **智能检测**：自动检测所有字段的变更，无需手动记录
- ✅ **完整记录**：记录操作人、操作时间、旧值、新值等完整信息
- ✅ **字段映射**：自动将字段名转换为中文标签，便于理解
- ✅ **数据格式化**：根据字段类型智能格式化显示（日期、金额、数组等）

### 2. 高级过滤和搜索
- 🔍 **关键词搜索**：支持搜索字段名、旧值、新值、操作人
- 👤 **操作人筛选**：按操作人快速过滤变更记录
- 📋 **字段筛选**：按修改的字段类型筛选
- 📅 **时间排序**：按时间倒序显示最新变更

### 3. 多种视图模式
- **时间轴视图**：以时间顺序展示所有变更，清晰的时间线
- **按日期分组**：将同一天的变更归类显示，便于批量查看

### 4. 统计分析
- 📊 **总变更次数**：统计总共发生的变更次数
- 📈 **变更字段数**：统计被修改过的字段数量
- 👥 **操作人数量**：统计参与修改的操作人数
- ⏰ **最近变更时间**：显示最后一次修改的时间
- 📉 **字段变更频率**：Top 5 最常修改的字段
- 🔢 **操作人统计**：各操作人的变更次数统计

### 5. 友好的用户界面
- 🎨 **现代化设计**：Material Design风格的卡片布局
- 🌈 **视觉层次**：使用颜色和图标突出重要信息
- 📱 **响应式布局**：适配各种屏幕尺寸
- ⚡ **流畅交互**：悬停效果、平滑过渡动画

## 技术实现

### 核心文件

#### 1. `/lib/changeTracker.ts` - 变更追踪工具
```typescript
// 主要功能：
- trackMachineryChanges(): 追踪农机档案的变更
- formatFieldValue(): 格式化字段值用于显示
- groupChangesByDate(): 按日期分组变更记录
- getChangeStats(): 获取变更统计信息
```

**字段映射表**：
```typescript
export const FIELD_LABELS: Record<string, string> = {
  // 基本信息
  name: '设备名称',
  model: '型号规格',
  category: '农机类型',
  usage: '使用场景',
  manufacturer: '生产厂家',
  manufactureDate: '出厂日期',
  purchaseDate: '购买日期',
  
  // 技术参数
  engineNumber: '发动机号',
  chassisNumber: '车架号',
  power: '额定功率',
  weight: '整机重量',
  workingWidth: '工作幅宽',
  
  // 购机信息
  purchasePrice: '购机价格',
  supplier: '供应商',
  invoiceNumber: '发票号码',
  invoiceUrl: '购机发票',
  
  // 保险信息
  insuranceCompany: '保险公司',
  insurancePolicyNumber: '保单号',
  insuranceStartDate: '保险起始日期',
  insuranceEndDate: '保险结束日期',
  insuranceAmount: '保险金额',
  
  // 使用信息
  status: '设备状态',
  currentLocation: '当前位置',
  operator: '操作人员',
  department: '所属部门',
  
  // 其他信息
  remarks: '备注',
  tags: '标签',
};
```

#### 2. `/components/machinery/ChangeHistory.tsx` - 变更历史组件
增强版组件，包含：
- 统计卡片
- 过滤和搜索功能
- 时间轴视图
- 按日期分组视图
- 变更统计图表

#### 3. 数据存储
使用 `machineryStorage.ts` 中的方法：
- `getChangeHistory(machineryId)`: 获取变更历史
- `saveChangeHistory(history)`: 保存变更记录

## 使用指南

### 1. 编辑农机档案时自动记录变更

在 `MachineryArchive.tsx` 或 `MachineryEntry.tsx` 中：

```typescript
import { trackMachineryChanges } from '../../lib/changeTracker';

const handleSaveMachinery = (data: Partial<MachineryRecord>) => {
  const currentUser = '系统管理员'; // 从认证上下文获取
  
  if (editingMachinery) {
    // 更新现有农机
    const updatedMachinery: MachineryRecord = {
      ...editingMachinery,
      ...data,
      updatedAt: new Date().toISOString(),
      updatedBy: currentUser,
    };

    // 自动追踪所有变更
    const changes = trackMachineryChanges(editingMachinery, data, currentUser);
    
    // 保存变更记录
    changes.forEach(change => {
      machineryStorage.saveChangeHistory(change);
    });

    machineryStorage.saveMachinery(updatedMachinery);
    toast.success(`更新成功，记录了${changes.length}项变更`);
  }
};
```

### 2. 查看变更历史

在 `MachineryDetails.tsx` 中已集成变更历史标签页：

```typescript
<TabsContent value="history">
  <ChangeHistory history={history} />
</TabsContent>
```

### 3. 自定义字段标签

如需添加新的字段映射，在 `changeTracker.ts` 中更新 `FIELD_LABELS`：

```typescript
export const FIELD_LABELS: Record<string, string> = {
  // ...现有字段
  newField: '新字段名称',
};
```

## 数据结构

### MachineryChangeHistory 接口

```typescript
export interface MachineryChangeHistory {
  id: string;              // 变更记录唯一ID
  machineryId: string;     // 关联的农机ID
  fieldName: string;       // 字段名（英文）
  fieldLabel: string;      // 字段标签（中文）
  oldValue: any;           // 旧值
  newValue: any;           // 新值
  operator: string;        // 操作人
  operatedAt: string;      // 操作时间（ISO格式）
}
```

### 变更记录示例

```json
{
  "id": "change-1697461234567-abc123",
  "machineryId": "machinery-001",
  "fieldName": "status",
  "fieldLabel": "设备状态",
  "oldValue": "正常",
  "newValue": "待维护",
  "operator": "张三",
  "operatedAt": "2025-10-16T10:30:00.000Z"
}
```

## 功能截图说明

### 1. 统计卡片区域
```
┌─────────────┬─────────────┬─────────────┬─────────────┐
│ 总变更次数  │ 变更字段数  │ 操作人数    │ 最近变更    │
│    25       │     12      │     3       │  2小时前    │
└─────────────┴─────────────┴─────────────┴─────────────┘
```

### 2. 过滤器区域
```
┌──────────────────────────────────────────────────────┐
│ [搜索框]  [操作人选择]  [字段选择]  [时间轴] [按日期] │
└──────────────────────────────────────────────────────┘
```

### 3. 时间轴视图
```
●━━━ 设备状态 已修改
│    旧值: 正常
│    新值: 待维护
│    张三 | 2小时前
│
●━━━ 设备名称 已修改
│    旧值: 拖拉机A
│    新值: 东方红拖拉机
│    李四 | 1天前
```

### 4. 按日期分组视图
```
📅 2025-10-16  3项变更
   ├─ 设备状态: 正常 → 待维护
   ├─ 当前位置: A地块 → B地块
   └─ 操作人员: 张三 → 李四

📅 2025-10-15  2项变更
   ├─ 购机价格: ¥50,000 → ¥48,000
   └─ 供应商: 供应商A → 供应商B
```

### 5. 变更统计区域
```
字段变更频率 Top 5          操作人变更统计
├─ 设备状态    8次         ├─ 张三    12次
├─ 当前位置    5次         ├─ 李四     8次
├─ 操作人员    4次         └─ 王五     5次
├─ 购机价格    3次
└─ 供应商      2次
```

## 最佳实践

### 1. 确保操作人信息准确
```typescript
// 从认证上下文获取当前用户
const { authState } = useAuth();
const currentUser = authState.user?.name || '未知用户';
```

### 2. 处理敏感信息
某些字段可能包含敏感信息，可以在 `changeTracker.ts` 中添加到排除列表：

```typescript
const EXCLUDED_FIELDS = [
  'id',
  'qrCode',
  'createdAt',
  'updatedAt',
  'createdBy',
  'updatedBy',
  'sensitiveField', // 添加需要排除的字段
];
```

### 3. 自定义值格式化
对于特殊字段，可以在 `formatFieldValue` 函数中添加自定义格式化逻辑：

```typescript
export function formatFieldValue(fieldName: string, value: any): string {
  // 自定义格式化
  if (fieldName === 'customField') {
    return `自定义：${value}`;
  }
  
  // 默认格式化
  // ...
}
```

### 4. 性能优化
- 使用 `useMemo` 缓存过滤和统计结果
- 限制单次显示的记录数量（如500条）
- 对于大量数据，考虑分页加载

## 扩展功能建议

### 未来可以添加的功能：

1. **导出变更报告**
   - 导出为 Excel/PDF 格式
   - 自定义导出时间范围和字段

2. **变更对比功能**
   - 选择两个时间点进行对比
   - 高亮显示差异

3. **变更回滚**
   - 选择历史记录点进行回滚
   - 需要权限控制

4. **变更通知**
   - 关键字段变更时发送通知
   - 配置通知规则

5. **审计日志**
   - 记录查看变更历史的操作
   - 符合审计合规要求

6. **可视化图表**
   - 变更趋势图
   - 活跃度热力图
   - 字段变更分布饼图

## 注意事项

1. **数据隐私**：确保变更历史数据的安全性，限制访问权限
2. **存储空间**：长期运行可能积累大量变更记录，需定期清理或归档
3. **性能影响**：每次编辑都会记录变更，确保不影响用户体验
4. **时区处理**：确保时间戳的时区一致性
5. **数组和对象**：复杂数据类型的变更检测需要深度比较

## 故障排查

### 问题：变更没有被记录
- 检查是否调用了 `trackMachineryChanges`
- 确认 `EXCLUDED_FIELDS` 中没有排除该字段
- 验证旧值和新值确实不同

### 问题：显示的时间不正确
- 检查浏览器时区设置
- 确认 `operatedAt` 使用 ISO 格式字符串
- 验证 `formatDate` 函数的时区处理

### 问题：变更记录加载缓慢
- 检查变更记录数量
- 考虑添加分页或虚拟滚动
- 优化过滤和排序算法

## 总结

农机全生命周期档案变更历史功能为系统提供了完整的数据审计能力，帮助用户：
- 📝 追踪所有数据变更
- 🔍 快速定位问题
- 📊 分析操作模式
- ✅ 满足合规要求
- 🛡️ 提升数据安全性

通过自动化的变更追踪和友好的用户界面，该功能大大提升了系统的可靠性和可维护性。