# AnalyzeCommand 使用指南

数据分析命令，支持 Ploss 余量分析与 Qfod 标定阈值分析。

## 命令语法

```bash
WCTDataMiner analyze --type <ploss|qfod> [选项]
```

## 分析类型

| 类型 | 说明 | 必需参数 |
|------|------|----------|
| `ploss` | Ploss 余量/delta_p 分析 | `--file` |
| `qfod` | Qfod 标定阈值计算 | `--pure`, `--foreign` |

---

## Ploss 分析

### 语法

```bash
WCTDataMiner analyze --type ploss --file <日志文件路径>
```

### 参数

| 参数 | 说明 |
|------|------|
| `--file` | 日志文件路径（支持 `.log` 和 `.DAT` 格式） |

### 输出示例

```
=== Ploss Analysis: sample.DAT ===
Total: 35 (TwoLine: 35, Legacy: 0), FOD: 1, Errors: 0
Normal margin>2000: 34/34 (100.0%)
FOD margin>2000: 1/1 (100.0%)
Identity (delta_p = Tx - Rx - pow_loss - ploss): 35/35

FOD rows (delta_p back-solve):
  Line 92     [two-line] pow_loss=3394 delta_p=605 ploss=1750 threshold=2000 margin=250
    -> delta_p'=605
    rewrite: pow_loss = 3394, delta_p = 605
```

### 输出字段说明

| 字段 | 说明 |
|------|------|
| **Total** | 总记录数，按格式分类（TwoLine: 两行格式，Legacy: 旧单行格式） |
| **FOD** | FOD 标记行数（Field12 == 1） |
| **Errors** | 解析错误行数 |
| **Normal margin>2000** | 正常行中余量 > 2000 的比例 |
| **FOD margin>2000** | FOD 行中余量 > 2000 的比例 |
| **Identity** | 恒等式成立行数（delta_p = Tx - Rx - pow_loss - ploss） |

### FOD 行反解

当存在 FOD 行时，输出包含 `delta_p'` 反解结果：

- `delta_p'` = 反解后的 delta_p 值
- `rewrite` = 重写后的 header 字段（pow_loss, delta_p）

### 支持的日志格式

#### 两行格式（推荐）

```
HEADER-> 18768 2001 -18347 3394 1750 2000 ...
FOD-> 12 18801 2001 -18447 3394 1750 2000 0 1750 2000 1 0 0 0 0 0
```

#### 旧单行格式（兼容）

```
FOD-> 0 0 0 12 18801 2001 -18447 3394 1750 2000 0 1750 2000 1 0 0 0
```

#### Field1 十六进制支持

Field1 支持以下十六进制格式：

| 格式 | 示例 | 说明 |
|------|------|------|
| `0x` 前缀 | `0xFF`, `0x0C` | 标准 C 风格十六进制 |
| `0` 前缀 | `0FF`, `0C` | 简写十六进制（仅含 A-F 时识别） |
| 十进制 | `12`, `255` | 普通十进制 |

---

## Qfod 标定

### 语法

```bash
WCTDataMiner analyze --type qfod --pure <纯手机日志> --foreign <异物日志>
```

### 参数

| 参数 | 说明 |
|------|------|
| `--pure` | 纯手机充电日志路径 |
| `--foreign` | 手机 + 异物充电日志路径 |

### 输出示例

```
=== Qfod Calibration ===
  Pure phone: pure.log
    count=21 min=3 max=5 avg=4.0
  Foreign object: foreign.log
    count=7 min=-49 max=-5 avg=-27.7

Threshold = (pureMax + foreignMin) / 2 = (5 + -49) / 2 = -22
Margin: pureMax - threshold = 27 (负为安全), foreignMin - threshold = -27 (正为安全)
```

### 输出字段说明

| 字段 | 说明 |
|------|------|
| **count** | 记录条数 |
| **min** | ΔQ 最小值 |
| **max** | ΔQ 最大值 |
| **avg** | ΔQ 平均值 |
| **Threshold** | 标定阈值 = (pureMax + foreignMin) / 2 |

### 标定原理

1. **纯手机充电**：ΔQ 稳定在正值区间（如 3~5）
2. **异物干扰**：ΔQ 衰减到负值区间（如 -49~-5）
3. **阈值计算**：取两组数据的中间值，实现最大区分度

### 安全余量解读

| 指标 | 期望值 | 说明 |
|------|--------|------|
| `pureMax - threshold` | **负值** | 纯手机数据不误触发 |
| `foreignMin - threshold` | **正值** | 异物数据可靠检出 |

---

## 错误处理

| 场景 | 输出 |
|------|------|
| 缺少 `--type` | `Required option '--type' was not specified.` |
| 未知类型 | `Unknown type: foo. Use 'ploss' or 'qfod'.` |
| Ploss 缺少文件 | `Please specify --file for Ploss analysis` |
| Qfod 缺少参数 | `Please specify --pure and --foreign for Qfod calibration` |
| 文件不存在 | `[filename] FAILED: File not found` |

---

## 典型使用场景

### 场景 1：产线数据质量检验

```bash
# 检查 Ploss 余量是否达标（margin > 2000 比例）
WCTDataMiner analyze --type ploss --file "产线数据.DAT"
```

### 场景 2：FOD 事件溯源

```bash
# 定位 FOD 行，查看 delta_p' 反解结果
WCTDataMiner analyze --type ploss --file "异常日志.log"
```

### 场景 3：Qfod 阈值标定

```bash
# 使用纯净数据 + 异物数据计算最佳阈值
WCTDataMiner analyze --type qfod \
  --pure "pure.log" \
  --foreign "foreign.log"
```