docs: 添加 AnalyzeCommand 使用指南

docs/AnalyzeCommand.md

@@ -0,0 +1,183 @@
+# 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"
+```
+