snap-user/docs/SNAPSHOT_FEATURE_GUIDE.md

# 用户快照功能使用指南

## 概述

快照功能允许为用户的当前状态创建一个"快照"，用户可以选择使用快照数据而不是原始数据。这对于以下场景非常有用：

- 数据回滚：当用户数据被错误修改时，可以快速恢复到之前的正确状态
- 数据对比：可以比较不同时间点的用户数据
- 数据备份：在重要操作前创建快照作为备份

## 核心机制

### 1. 快照字段
在 `User` 实体中添加了 `snapshotId` 字段：
- 如果为 `null` 或空字符串：使用原始用户数据
- 如果有值：使用对应快照的数据

### 2. 快照实体
`UserSnapshot` 实体存储完整的用户数据快照，包括：
- 基本信息（姓名、邮箱、电话等）
- 业务信息（部门、职位、薪资等）
- 系统信息（状态、登录记录等）
- 快照元数据（创建时间、原因等）

## 启用快照功能

### 方法1：使用配置文件
```yaml
# application.yml
app:
  snapshot:
    enabled: true
```

### 方法2：使用命令行参数
```bash
mvn spring-boot:run -Dspring-boot.run.arguments="--app.snapshot.enabled=true"
```

### 方法3：使用配置文件
```bash
mvn spring-boot:run -Dspring-boot.run.arguments="--spring.profiles.active=snapshot"
```

## API 接口

### 1. 创建快照
```bash
# 为用户创建快照（不应用）
curl -X POST http://localhost:8080/api/users/1/snapshots \
  -H "Content-Type: application/json" \
  -d '{"reason":"数据备份"}'

# 响应
{
  "snapshotId": "SNAP_1234567890abcdef",
  "message": "快照创建成功"
}
```

### 2. 创建并应用快照
```bash
# 创建快照并立即应用
curl -X POST http://localhost:8080/api/users/1/snapshots/apply \
  -H "Content-Type: application/json" \
  -d '{"reason":"重要操作前备份"}'

# 响应
{
  "snapshotId": "SNAP_1234567890abcdef",
  "message": "快照创建并应用成功"
}
```

### 3. 获取用户快照列表
```bash
curl http://localhost:8080/api/users/1/snapshots

# 响应
[
  {
    "snapshotId": "SNAP_1234567890abcdef",
    "createTime": "2024-01-15T10:30:00.000+00:00",
    "reason": "数据备份"
  },
  {
    "snapshotId": "SNAP_abcdef1234567890",
    "createTime": "2024-01-14T15:20:00.000+00:00",
    "reason": "重要操作前备份"
  }
]
```

### 4. 恢复到指定快照
```bash
curl -X POST http://localhost:8080/api/users/1/snapshots/SNAP_1234567890abcdef/restore

# 响应
{
  "message": "快照恢复成功"
}
```

### 5. 清除快照设置
```bash
curl -X DELETE http://localhost:8080/api/users/1/snapshots

# 响应
{
  "message": "快照设置清除成功"
}
```

### 6. 删除快照
```bash
curl -X DELETE http://localhost:8080/api/snapshots/SNAP_1234567890abcdef

# 响应
{
  "message": "快照删除成功"
}
```

## 使用场景示例

### 场景1：数据备份和恢复

1. **创建用户**
```bash
curl -X POST http://localhost:8080/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"张三","email":"zhangsan@example.com","phone":"13800138000"}'
```

2. **创建快照**
```bash
curl -X POST http://localhost:8080/api/users/1/snapshots \
  -H "Content-Type: application/json" \
  -d '{"reason":"初始状态备份"}'
```

3. **修改用户数据**
```bash
curl -X PUT http://localhost:8080/api/users/1 \
  -H "Content-Type: application/json" \
  -d '{"name":"张三丰","email":"zhangsanfeng@example.com","phone":"13800138001"}'
```

4. **恢复到快照**
```bash
curl -X POST http://localhost:8080/api/users/1/snapshots/SNAP_xxx/restore
```

### 场景2：重要操作前的备份

1. **创建快照并应用**
```bash
curl -X POST http://localhost:8080/api/users/1/snapshots/apply \
  -H "Content-Type: application/json" \
  -d '{"reason":"薪资调整前备份"}'
```

2. **执行重要操作**
```bash
curl -X PUT http://localhost:8080/api/users/1/employee \
  -H "Content-Type: application/json" \
  -d '{"department":"技术部","position":"高级工程师","salary":20000}'
```

3. **如果操作有问题，可以恢复到快照**
```bash
curl -X POST http://localhost:8080/api/users/1/snapshots/SNAP_xxx/restore
```

## 技术实现细节

### 1. 服务层抽象
- `SnapshotService`：核心快照逻辑
- `UserManagementServiceWithSnapshot`：支持快照的用户管理服务
- 通过装饰器模式扩展原有服务

### 2. 数据层
- `UserSnapshotRepository`：快照数据访问
- 在 `UserRepository` 中添加快照相关查询方法

### 3. 配置驱动
- 通过 `app.snapshot.enabled` 配置控制功能开关
- 使用 `@ConditionalOnProperty` 注解实现条件装配

### 4. 事务管理
- 快照操作使用 `@Transactional` 确保数据一致性
- 删除快照时检查是否有用户正在使用

## 注意事项

1. **性能考虑**：快照会增加数据库存储空间，建议定期清理不需要的快照
2. **数据一致性**：快照创建时使用事务确保数据一致性
3. **并发安全**：多个用户同时操作同一用户时需要注意并发问题
4. **快照管理**：建议为快照设置合理的保留策略

## 扩展功能

### 1. 快照版本管理
可以扩展支持快照的版本管理，允许比较不同快照之间的差异。

### 2. 自动快照
可以添加定时任务，自动为用户创建快照。

### 3. 快照策略
可以支持不同的快照策略，如：
- 按时间间隔创建快照
- 按数据变更幅度创建快照
- 按重要操作创建快照

### 4. 快照压缩
对于长期存储的快照，可以考虑数据压缩以减少存储空间。