hi-client/scripts/DATA_CLEANUP_README.md

# 📋 旧数据清理机制说明文档

## 问题背景

**问题现象**: 客户每次安装APP时，个人中心显示旧的测试账号 `calvin.duke@hotmail.com`

**根本原因**:
- 开发环境中登录过测试账号
- 打包时未清理本地Hive数据库
- 旧数据被打包进APP包中
- 新安装的APP恢复了这个旧账号信息

---

## ✅ 解决方案

本修复包含三个层面的防护机制：

### 1️⃣ 应用层 - DEBUG模式清理（生效方式：优先级最高）

**文件**: `lib/app/modules/kr_splash/controllers/kr_splash_controller.dart`

**工作原理**:
- 仅在DEBUG模式（`kDebugMode == true`）下执行
- 在应用启动时（`onInit()`）立即清理旧数据
- 调用 `_kr_clearOldLocalData()` 方法
- 清理内容：`USER_INFO` 和 `DEVICE_INFO` key

**触发时机**:
```
APP启动 → onInit() → 检测kDebugMode → 清理旧数据
```

**优点**:
- ✅ 对用户数据0影响（DEBUG模式下才清理）
- ✅ 自动化，无需手动干预
- ✅ 可在日志中追踪

---

### 2️⃣ 数据验证层 - Token合法性检查

**文件**: `lib/app/common/app_run_data.dart`

**工作原理**:
- 在初始化用户信息时 (`kr_initializeUserInfo()`)
- 调用 `_kr_isValidToken()` 验证Token格式
- 检查是否符合JWT格式：`header.payload.signature`
- 验证payload是否能解析为有效JSON

**验证流程**:
```
读取本地存储
  ↓
解析JSON
  ↓
验证Token格式
  ├─ ❌ 格式错误 → 清理数据 (kr_loginOut)
  ├─ ❌ 账号信息为空 → 清理数据 (kr_loginOut)
  └─ ✅ 全部通过 → 恢复登录状态
```

**检查项目**:
1. Token分段数是否为3 (header.payload.signature)
2. 每段是否非空
3. Payload是否能正确解码为base64
4. 解码后是否为有效JSON

**日志示例**:
```
✅ Token格式验证通过
✅ Token和账号验证通过，设置登录状态为true
📊 恢复账号: user@example.com
```

---

### 3️⃣ 打包前清理 - 预防层

**文件**: `scripts/clean_build_cache.sh`

**工作原理**:
- 打包前手动运行此脚本
- 清理所有平台的本地缓存数据
- 删除Hive数据库文件

**清理内容**:
- ✅ macOS应用数据目录
- ✅ macOS/Linux Hive数据库
- ✅ Flutter构建缓存
- ✅ `.dart_tool` 目录
- ✅ `build/` 产物目录

**使用方法**:
```bash
# 进入脚本目录
cd scripts/

# 运行清理脚本
./clean_build_cache.sh

# 后续步骤
flutter pub get
./build_android.sh  # 或其他平台脚本
```

---

## 🔄 完整流程图

### 新安装APP时的数据恢复流程

```
┌─────────────────────────────────────┐
│ APP启动                              │
└──────────────┬──────────────────────┘
               ↓
┌─────────────────────────────────────┐
│ DEBUG模式清理（第1道防线）           │
│ - 清理USER_INFO                      │
│ - 清理DEVICE_INFO                    │
└──────────────┬──────────────────────┘
               ↓
┌─────────────────────────────────────┐
│ 初始化用户信息                       │
│ kr_initializeUserInfo()              │
└──────────────┬──────────────────────┘
               ↓
┌─────────────────────────────────────┐
│ Token合法性检查（第2道防线）         │
│ _kr_isValidToken()                   │
│                                      │
│ ├─ 格式检查（JWT）                   │
│ ├─ Payload解码检查                   │
│ └─ JSON有效性检查                    │
└──────────────┬──────────────────────┘
               │
      ┌────────┴────────┐
      ↓                 ↓
   ✅ 有效          ❌ 无效
      │                 │
      ↓                 ↓
  恢复登录      清理旧数据
  显示账号      kr_loginOut()
      │                 │
      └────────┬────────┘
               ↓
        进入个人中心
```

---

## 🧪 测试验证方法

### 测试场景1：新安装APP（DEBUG模式）

**预期结果**: 看到"DEBUG模式：清理旧本地存储数据"日志

```bash
1. 构建DEBUG版本
2. 安装APP
3. 查看日志：adb logcat | grep "清理旧本地存储数据"
4. 进入个人中心，不应显示旧账号
```

### 测试场景2：手动清理后打包

**步骤**:
```bash
1. cd scripts/
2. ./clean_build_cache.sh  # 清理本地缓存
3. flutter pub get
4. ./build_android.sh      # 打包新APP
5. 安装新APP
6. 进入个人中心，验证没有旧数据
```

### 测试场景3：验证Token验证机制

**模拟被污染的Token**:

在DEBUG模式下修改Hive存储，加入无效Token：
- 格式错误的Token（少于或多于3段）
- 无效base64的payload
- 无法解析为JSON的payload

**预期**: 应用启动时自动清理，不显示任何账号

---

## 🔍 日志信息参考

### 成功清理的日志
```
🧹 DEBUG模式：准备清理旧本地存储数据
🧹 开始清理旧本地存储数据...
✅ 已清理USER_INFO
✅ 已清理DEVICE_INFO
✅ 旧本地存储数据已全部清理
```

### Token验证通过的日志
```
✅ Token格式验证通过
✅ Token和账号验证通过，设置登录状态为true
📊 恢复账号: user@example.com
```

### Token验证失败的日志
```
❌ Token格式无效：分段数不对 (2 != 3)
⚠️ Token验证失败或格式错误，清理该条用户数据
```

---

## ⚠️ 重要注意事项

### ✅ 安全性设计

1. **DEBUG模式专用**: 清理逻辑仅在DEBUG构建中运行，生产环境不受影响
2. **用户数据保护**: 验证失败才清理，不会盲目删除有效数据
3. **完整性检查**: 多层验证确保数据完整性

### ⚠️ 潜在风险

1. **如果手动禁用清理**: 需要确保打包前运行`clean_build_cache.sh`
2. **如果Token损坏**: 自动清理，用户需要重新登录
3. **跨版本兼容**: 确保Token格式保持一致

---

## 📊 修复前后对比

| 方面 | 修复前 | 修复后 |
|-----|------|------|
| 新安装APP | 显示旧测试账号 | ✅ 显示未登录 |
| 损坏数据 | 直接使用 | ✅ 自动检测清理 |
| DEBUG模式 | 无特殊处理 | ✅ 自动清理 |
| 打包防护 | 无 | ✅ 专用清理脚本 |
| 日志追踪 | 无 | ✅ 完整的日志记录 |

---

## 🚀 部署指南

### 对开发人员

1. **本地开发**: 无需特殊操作，DEBUG模式会自动清理
2. **打包前**: 运行 `scripts/clean_build_cache.sh`
3. **CI/CD**: 在构建脚本中加入清理步骤

### 对用户

- **无需任何操作**: 修复完全透明，用户无感知
- **新安装**: 自动清理旧数据
- **现有用户**: 升级后仍可正常登录

---

## 📞 故障排查

### 问题：APP仍显示旧账号

**检查清单**:
1. 是否使用了DEBUG构建？
2. 是否是第一次安装？
3. 检查日志中是否有清理消息

### 问题：登录后无法显示账号

**检查清单**:
1. Token是否有效
2. 查看日志中的Token验证信息
3. 尝试重新登录

### 问题：脚本执行失败

**常见原因**:
1. 脚本没有执行权限：`chmod +x clean_build_cache.sh`
2. 路径不正确：确保在scripts目录下执行
3. Flutter未安装：需要Flutter环境

---

## 📝 修改记录

- **2025-10-31**: 创建数据清理机制
  - 新增DEBUG模式清理
  - 新增Token验证机制
  - 新增打包前清理脚本
  - 新增文档说明

---

## 📚 相关文件

- `lib/app/modules/kr_splash/controllers/kr_splash_controller.dart` - 启动时清理
- `lib/app/common/app_run_data.dart` - Token验证
- `scripts/clean_build_cache.sh` - 打包前清理脚本
- `scripts/VERSION_INCREMENT_README.md` - 版本递增说明