# 文档与代码核对报告

## 一、发现的关键差异

### ❌ **差异1：SOC升级包名称不一致**

```
文档描述：
  update_soc.zip

实际代码：
  StorageVolumeEventListener.java:29
  public static final String SOC_UPDATE_FILE = "update.zip";
  
结论：代码检测的是 "update.zip"，不是 "update_soc.zip"
```

---

## 二、完整对照表

### 2.1 升级包名称对照

| 项目 | 文档描述 | 实际代码 | 是否一致 |
|------|----------|----------|----------|
| **MCU升级包** | `update_mcu.zip` | `update_mcu.zip` | ✅ 一致 |
| **SOC升级包** | `update_soc.zip` | `update.zip` | ❌ **不一致** |
| **MCU固件文件** | `cortex-gdm4.bin` | `cortex-gdm4.bin` | ✅ 一致 |
| **SOC升级文件** | `update.zip` | `update.zip` | ✅ 一致 |
| **签名文件** | `ValidationFile.ini` | `ValidationFile.ini` | ✅ 一致 |

---

### 2.2 升级包结构对照

#### **MCU升级包（一致）**

```
文档描述：
  update_mcu.zip
    ├── cortex-gdm4.bin
    └── ValidationFile.ini

实际代码：
  McuM3Update.java:446
    File updateFile = new File(unzippedPath + "cortex-gdm4.bin");
  
  McuM3Update.java:450
    File signatureFile = new File(unzippedPath + "ValidationFile.ini");

结论：✅ 完全一致
```

#### **SOC升级包（有差异）**

```
文档描述：
  update_soc.zip
    ├── update.zip
    └── ValidationFile.ini

实际检测：
  StorageVolumeEventListener.java:92
    File socFile = new File(path + File.separator + SOC_UPDATE_FILE);
    // SOC_UPDATE_FILE = "update.zip"
    
  所以用户插入的U盘里，SOC升级包名称应该是：
    update.zip（不是 update_soc.zip）
    
  解压后的文件：
    SocUpdate.java:149
      File updateFile = new File("/sdcard/zhongqi_soc_update/update.zip");
    
    SocUpdate.java:203
      File signatureFile = new File(unzippedPath + "ValidationFile.ini");

实际结构：
  update.zip（外层，用户插入U盘的文件）
    ├── update.zip（内层，真正的OTA包）
    └── ValidationFile.ini

结论：❌ 文档描述错误
  - 用户U盘里的文件名是 "update.zip"，不是 "update_soc.zip"
  - 解压后的结构一致
```

---

## 三、详细代码验证

### 3.1 升级包检测逻辑

```java
// StorageVolumeEventListener.java:89-102
File mcuFile = new File(path + File.separator + MCU_M3_UPDATE_FILE);
// MCU_M3_UPDATE_FILE = "update_mcu.zip"

File socFile = new File(path + File.separator + SOC_UPDATE_FILE);
// SOC_UPDATE_FILE = "update.zip"

if (mcuFile.exists()) {
    this.mUpdateFiles.add(mcuFile);  // 添加MCU升级包
}
if (socFile.exists()) {
    this.mUpdateFiles.add(socFile);  // 添加SOC升级包
}
```

**结论**：
- MCU检测：`update_mcu.zip` ✅
- SOC检测：`update.zip` ✅（不是 `update_soc.zip`）

---

### 3.2 验证逻辑对照

#### **MCU验证流程**

```java
// McuM3Update.java:427-472
private boolean verify(File zipFile) {
    String unzippedPath = "/sdcard/zhongqi_mcu_update/";
    
    // 1. 解压
    ZipUtils.unzipFile(zipFile, targetDir);
    
    // 2. 计算哈希
    File updateFile = new File(unzippedPath + "cortex-gdm4.bin");
    byte[] fileHash = ZipFileVerifier.computeFileHash(updateFile);
    
    // 3. 读取签名
    File signatureFile = new File(unzippedPath + "ValidationFile.ini");
    byte[] signatureBytes = readSignBytes(signatureFile);
    
    // 4. 加载公钥
    String pem = "-----BEGIN PUBLIC KEY-----\n...";
    PublicKey publicKey = ZipFileVerifier.loadPublicKey(pem);
    
    // 5. 验证签名
    boolean isValid = ZipFileVerifier.verifySignature(fileHash, signatureBytes, publicKey);
    
    return isValid;
}
```

**文档对照**：
- ✅ 解压路径：`/sdcard/zhongqi_mcu_update/`
- ✅ 固件文件：`cortex-gdm4.bin`
- ✅ 签名文件：`ValidationFile.ini`
- ✅ 算法：SHA256withRSA

---

#### **SOC验证流程**

```java
// SocUpdate.java:180-225
private boolean verify(File zipFile) {
    String unzippedPath = "/sdcard/zhongqi_soc_update/";
    
    // 1. 解压
    ZipUtils.unzipFile(zipFile, targetDir);
    
    // 2. 计算哈希
    File updateFile = new File(unzippedPath + "update.zip");
    byte[] fileHash = ZipFileVerifier.computeFileHash(updateFile);
    
    // 3. 读取签名
    File signatureFile = new File(unzippedPath + "ValidationFile.ini");
    byte[] signatureBytes = readSignBytes(signatureFile);
    
    // 4. 加载公钥
    String pem = "-----BEGIN PUBLIC KEY-----\n...";
    PublicKey publicKey = ZipFileVerifier.loadPublicKey(pem);
    
    // 5. 验证签名
    boolean isValid = ZipFileVerifier.verifySignature(fileHash, signatureBytes, publicKey);
    
    return isValid;
}
```

**文档对照**：
- ✅ 解压路径：`/sdcard/zhongqi_soc_update/`
- ✅ 固件文件：`update.zip`（内层）
- ✅ 签名文件：`ValidationFile.ini`
- ✅ 算法：SHA256withRSA

---

### 3.3 文件清理逻辑

```java
// UpdateService.java:394-411
private void deleteFile() {
    String soc_path = "/sdcard/zhongqi_soc_update/";
    File soc_directory = new File(soc_path);
    deleteDirectory(soc_directory);
    
    String mcu_path = "/sdcard/zhongqi_mcu_update/";
    File mcu_directory = new File(mcu_path);
    deleteDirectory(mcu_directory);
}
```

**文档对照**：
- ✅ 清理SOC目录：`/sdcard/zhongqi_soc_update/`
- ✅ 清理MCU目录：`/sdcard/zhongqi_mcu_update/`
- ✅ 递归删除：`deleteDirectory()`

---

## 四、修正后的正确流程

### 4.1 正确的升级包结构

```
用户U盘中的文件：

MCU升级包：
  update_mcu.zip
    ├── cortex-gdm4.bin
    └── ValidationFile.ini
        内容：sign=<256字节签名>

SOC升级包：
  update.zip（注意：不是 update_soc.zip！）
    ├── update.zip（内层真正的OTA包）
    └── ValidationFile.ini
        内容：sign=<256字节签名>
```

---

### 4.2 正确的文件名

| 类型 | U盘文件名 | 解压后固件文件 | 签名文件 |
|------|-----------|----------------|----------|
| **MCU** | `update_mcu.zip` | `cortex-gdm4.bin` | `ValidationFile.ini` |
| **SOC** | `update.zip` | `update.zip`（内层） | `ValidationFile.ini` |

---

## 五、总结

### 5.1 一致的部分 ✅

```
✅ 核心算法：SHA256withRSA
✅ 验证步骤：解压 → 计算哈希 → 读取签名 → 验证签名
✅ MCU升级包结构：update_mcu.zip
✅ MCU固件文件：cortex-gdm4.bin
✅ SOC解压后文件：update.zip
✅ 签名文件：ValidationFile.ini
✅ 公钥硬编码位置：McuM3Update.java / SocUpdate.java
✅ 文件清理逻辑：自动删除临时文件
```

### 5.2 不一致的部分 ❌

```
❌ SOC升级包名称：
   文档写的：update_soc.zip
   实际代码：update.zip
   
   影响：用户制作升级包时，SOC包名应该是 update.zip，不是 update_soc.zip
```

### 5.3 修正建议

**需要修正文档中的以下内容**：

```
第四章"升级包格式"部分：

错误：
  update_soc.zip

修正为：
  update.zip

说明：
  用户U盘中的SOC升级包名称是 "update.zip"，不是 "update_soc.zip"
  解压后的内部结构保持不变（内层还是 update.zip）
```

---

## 六、实际流程确认

### 6.1 用户操作流程（修正版）

```
用户制作升级包：

MCU升级：
  1. 准备 cortex-gdm4.bin 文件
  2. 用私钥签名，生成 ValidationFile.ini
  3. 打包成 update_mcu.zip
  4. 复制到U盘根目录

SOC升级：
  1. 准备 update.zip（OTA升级包）
  2. 用私钥签名，生成 ValidationFile.ini
  3. 打包成 update.zip（注意：外层也叫 update.zip）
  4. 复制到U盘根目录

用户升级：
  1. 插入U盘
  2. 系统自动检测 update_mcu.zip 或 update.zip
  3. 自动验证签名
  4. 验证通过后升级
  5. 升级完成自动删除临时文件
```

### 6.2 文件命名总结

```
✅ 正确命名：
  MCU：update_mcu.zip
  SOC：update.zip

❌ 错误命名：
  SOC：update_soc.zip（文档错误描述）
```

---

## 七、建议

1. **修正文档**：将文档中的 `update_soc.zip` 改为 `update.zip`
2. **添加说明**：说明SOC升级包外层和内层都叫 `update.zip`，避免混淆
3. **统一命名**：建议未来版本考虑统一命名规范，如：
   - MCU：`update_mcu.zip`
   - SOC：`update_soc.zip`（需要同时修改代码）

---

**核对完成时间**: 2025-05-07
**核对范围**: 全部核心代码文件
**发现差异**: 1处（SOC升级包名称）