📝 docs(dvp): 更新传感器预配置文档并修复行数定义

- 新增 Mini212G2 传感器预配置指南文档，详细说明外部工具配置步骤
- 修复 DVP 头文件中的 SENSOR_TOTAL_LINES 定义，移除冗余行数
- 在 README 和模式配置文档中添加预配置指南的引用链接
- 新增 OpenSpec 变更记录，包含设计文档、提案、规格和任务清单

📦 build(openspec): 新增传感器预配置规范文档结构

- 在 openspec/changes/archive/ 下创建 2026-03-15-dvp-raw-data-pipeline 变更记录
- 包含设计文档、提案、规格说明和任务清单
- 在 openspec/specs/ 下创建 sensor-preconfig-guide 规格文档

Debug/dvp.h

@@ -4,7 +4,7 @@
 
 #define SENSOR_WIDTH        256
 #define SENSOR_HEIGHT       192
-#define SENSOR_TOTAL_LINES  (SENSOR_HEIGHT + 1)   // +1 参数行
+#define SENSOR_TOTAL_LINES  (SENSOR_HEIGHT)        // TMP 模式无参数行，共 192 行
 #define BYTES_PER_LINE      (SENSOR_WIDTH * 2)     // 每行512字节
 
 #define ALARM_TEMP_RAW      800  // 80.0℃ (raw/10)

README.md

@@ -253,4 +253,5 @@ IDLE → 触发（外部 GPIO 高电平计时 or 内部连续 3 帧超阈值）
 | [Doc/CH32二维运行结构概览.md](Doc/CH32二维运行结构概览.md) | 系统状态机全景图 |
 | [Doc/TCPClient测试指南.md](Doc/TCPClient测试指南.md) | 测试模式使用说明 |
 | [Doc/Mini212G2用户手册.md](Doc/Mini212G2系列用户手册.md) | 传感器硬件手册 |
+| [Doc/Mini212G2预配置指南.md](Doc/Mini212G2预配置指南.md) | **通过外部工具配置传感器的必要参数说明**（CMOS8 LSB、Y16、帧率等） |
 | [Doc/Mini212G2串口通讯协议.md](Doc/Mini212G2串口通讯协议.md) | 传感器通信协议 |

doc/Mini212G2预配置指南.md

@@ -0,0 +1,149 @@
+# Mini212G2 模组预配置指南
+
+> **适用场景**：MCU 端 `SENSOR_UART_ENABLE=0`，传感器通过外部工具（USB/串口调试软件）预先配置并保存到 Flash。  
+> **配置工具**：可使用厂家上位机软件或通用串口调试工具，连接传感器 USB 接口或 UART 接口（115200 8N1）。  
+> **参考文档**：`Doc/Mini212G2串口通讯协议.md`、`Doc/Mini212G2系列用户手册.md`
+
+---
+
+## 必须配置的参数（共 4 项）
+
+以下参数与 MCU DVP 驱动强耦合，任意一项配置错误将导致图像数据完全错误。
+
+### 1. 数字口类型 → CMOS
+
+| 属性 | 值 |
+|------|-----|
+| 设置值 | CMOS |
+| 串口命令 | `55 AA 07 02 01 02 00 00 00 02 04 F0` |
+| 原因 | MCU 使用 DVP 8-bit 并行接口接收数据，必须选 CMOS 模式 |
+
+---
+
+### 2. CMOS 接口 → **CMOS8(LSB)**  ⛔ 关键，必须为 LSB
+
+| 属性 | 值 |
+|------|-----|
+| **设置值** | **CMOS8(LSB)** |
+| 串口命令 | `55 AA 07 02 01 04 00 00 00 02 02 F0` |
+| ❌ 禁止设置 | CMOS8(MSB) → `55 AA 07 02 01 04 00 00 00 01 01 F0` |
+
+**原因（字节序）**：
+
+CH32V307 是小端序（Little-Endian）处理器，DVP DMA 按字节顺序依次写入 `FrameBuffer`，代码通过 `(uint16_t*)FrameBuffer` 直接读取 16-bit 温度值：
+
+```
+FrameBuffer[row][0] → uint16_t 低字节（bits[7:0]）
+FrameBuffer[row][1] → uint16_t 高字节（bits[15:8]）
+```
+
+| 传感器模式 | DVP 先收到 | uint16_t 读取结果 |
+|---|---|---|
+| LSB（低字节先发） | 低字节 | ✅ 正确 |
+| MSB（高字节先发） | 高字节 | ❌ 字节反序，温度值完全错误 |
+
+---
+
+### 3. CMOS 内容 → **TMP**  ⛔ 关键，必须为 TMP（不是 Y16）
+
+| 属性 | 值 |
+|------|-----|
+| **设置值** | **TMP** |
+| 串口命令 | `55 AA 07 02 01 03 00 00 00 08 0F F0` |
+| ❌ 禁止设置 | Y16 → `55 AA 07 02 01 03 00 00 00 02 05 F0` |
+
+> **Mini212G2 是测温型产品，支持 TMP 模式。** 若不确定，使用前请与厂家确认。
+
+**为什么必须选 TMP，不能选 Y16**：
+
+| 模式 | 数据含义 | MCU 是否可直接使用 |
+|------|----------|--------------------|
+| **TMP（温度矩阵）** | 传感器内部已完成辐射定标，16-bit 值 = 实际温度 × 10（单位 0.1°C/LSB） | ✅ 直接使用，与代码假设完全匹配 |
+| Y16（红外辐射原始数据） | 原始 ADC 计数值，不是温度，数值越大表示越热但无对应温度 | ❌ 需要读出厂标定参数 + 手写温度解算公式才能转换为温度 |
+
+MCU 代码（`qdx_preprocess.c`）将像素值直接当 0.1°C/LSB 的温度使用——这正是 **TMP 模式输出的格式**（协议文档等温阈值范围 -400~5500 对应 -40.0~550.0°C 即 0.1°C/LSB）。若配置为 Y16，所有温度判断将得到错误结果，但系统不会报错。
+
+其他禁止选项：
+- `TMP+参数行`（参数行会打乱行计数，`SENSOR_HEIGHT=192` 对应到 193 行后中断异常）
+- `TMP+YUV422`（YUV 通道数据会覆盖温度帧）
+
+---
+
+### 4. 帧率 → 25Hz 或 30Hz
+
+| 属性 | 值 |
+|------|-----|
+| 推荐值 | 25Hz |
+| 串口命令（25Hz） | `55 AA 07 02 01 05 00 00 00 00 01 F0` |
+| 串口命令（30Hz） | `55 AA 07 02 01 05 00 00 00 00 01 F0` *(参见协议文档帧率表)* |
+
+---
+
+## 配置后必须保存
+
+配置完成后发送保存命令，否则断电后配置丢失：
+
+```
+保存设置：55 AA 07 01 00 04 00 00 00 01 03 F0
+```
+
+> ⚠️ 保存后重新上电，配置才从 Flash 生效。
+
+---
+
+## TMP 模式温度值格式确认
+
+Mini212G2 TMP 模式输出格式（协议文档 §2.4.5 等温阈值范围 -400~5500 对应 -40.0~550.0°C）：
+
+| 参数 | 值 |
+|------|----|
+| 单位 | 0.1°C/LSB |
+| 编码 | 有符号 16-bit（int16_t） |
+| 示例 | 25.0°C → 250，-10.0°C → -100，100.0°C → 1000 |
+
+MCU 代码使用方式：
+
+```c
+// qdx_preprocess.c 中直接将像素值当温度（0.1°C/LSB）
+// 示例：testPattern 阈值
+#define TEMP_RAW(deg_c)  ((uint16_t)((deg_c) * 10))
+// 35.0°C → 350，80.0°C → 800，90.0°C → 900
+```
+
+**联调验证步骤**（TMP 模式，首次上电后执行）：
+
+1. 将传感器对准已知温度目标（如室温约 25°C 的平板物体）
+2. 通过串口 log 打印 DVP 帧中心像素原始值
+3. 确认中心像素值约等于 **250**（25.0°C × 10）
+4. 如输出值异常（如约 2980 或约 7450），说明配置的不是纯 TMP 模式，需重新检查步骤 3 的配置
+
+| 实测中心值（约） | 说明 |
+|-----------------|------|
+| ~250 | ✅ TMP 0.1°C/LSB，与代码一致 |
+| ~2980 | ❌ 可能是开尔文模式（K×10），配置错误 |
+| ~7450 | ❌ 可能是 Y16 原始 ADC 值，应切换为 TMP 模式 |
+
+---
+
+## 配置命令汇总表
+
+| 步骤 | 功能 | 命令（HEX） |
+|------|------|-------------|
+| 1 | 数字口 → CMOS | `55 AA 07 02 01 02 00 00 00 02 04 F0` |
+| 2 | **CMOS 接口 → CMOS8(LSB)** | `55 AA 07 02 01 04 00 00 00 02 02 F0` |
+| 3 | **CMOS 内容 → TMP** | `55 AA 07 02 01 03 00 00 00 08 0F F0` |
+| 4 | 帧率 → 25Hz | `55 AA 07 02 01 05 00 00 00 00 01 F0` |
+| 5 | **保存设置** | `55 AA 07 01 00 04 00 00 00 01 03 F0` |
+
+> 每条命令发送后等待 ACK：`55 AA 01 00 01 F0`，收到后再发下一条。
+
+---
+
+## 不需要配置的项目
+
+| 参数 | 说明 |
+|------|------|
+| 外同步 | 保持默认关闭（内同步），MCU DVP 作为接收方 |
+| VSYNC/HSYNC 极性 | MCU 侧已配置 `VSYNC active-high`，传感器默认输出一致 |
+| 分辨率 | Mini212G2 固定 256×192，无需配置 |
+| NUC 快门补偿 | 运行时按需触发（`55 AA 07 02 01 08 00 00 00 01 0D F0`），不属于启动配置 |

doc/模式配置与功能说明.md

@@ -115,6 +115,7 @@
 
 > 当前模组已通过 USB 预配置，MCU UART 配置功能已用 `#if 0` 关闭。
 > **USART2 (PA2/PA3) 引脚已被占用，不可用于传感器通信。**
+> 预配置必需配置的参数详见：[Doc/Mini212G2预配置指南.md](Mini212G2预配置指南.md)
 
 | 宏名 | 当前值 | 说明 |
 |------|--------|------|

openspec/changes/archive/2026-03-15-dvp-raw-data-pipeline/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-15

openspec/changes/archive/2026-03-15-dvp-raw-data-pipeline/design.md

@@ -0,0 +1,53 @@
+## Context
+
+**背景**：MCU 固件中 `SENSOR_UART_ENABLE=0`，mini212g2.c 中所有传感器 UART 配置命令均被 `#if` 屏蔽，传感器完全依赖外部工具（USB 串口/厂家上位机）进行预配置。现有代码在以下两处隐含了对传感器输出格式的假设：
+
+1. **字节序假设**：`dvp.c` 对 DMA 采集到的 `uint8_t FrameBuffer[192][512]` 直接强转 `(uint16_t*)` 使用，CH32V307 为小端序（Little-Endian），因此要求传感器以 **LSB 先发**（低字节先到 DVP 数据线）输出 CMOS8 格式。
+2. **Y16 单位假设**：`qdx_preprocess.c` 将 Y16 原始值直接当 `int16_t` 使用，在比较和上报时按 0.1°C/LSB 理解，要求传感器输出的 Y16 量纲与此一致。
+
+当前无文档说明这些约束，现场部署时可能因传感器配置错误导致数据完全错误。
+
+**变更范围**：仅新增文档；MCU 代码不变。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 明确列出外部工具必须配置的所有 Mini212G2 参数及其原因
+- 提供每个配置项的串口命令 HEX，使现场工程师可操作
+- 解释字节序原理，防止误选 MSB 模式
+- 提供 Y16 单位的现场联调验证方法
+
+**Non-Goals:**
+- 不修改 MCU 驱动代码（`SENSOR_UART_ENABLE` 保持 0）
+- 不涉及网络协议或上位机修改
+- 不提供 Mini212G2 全量功能手册（已有 `Doc/Mini212G2系列用户手册.md`）
+
+## Decisions
+
+### 决策 1：文档形式采用 操作指南（How-to）而非参考文档（Reference）
+
+**理由**：目标读者是现场调试工程师，需要明确的步骤顺序和可操作的命令，而不是完整的参数字典。操作指南格式（按步骤编号）更直接。
+
+**备选方案**：直接在模式配置文档中追加一节 → 拒绝，因为该文档定位是固件变量说明，混入硬件配置步骤会破坏结构。
+
+### 决策 2：将 CMOS8(LSB) 标注为 ⛔ 关键步骤
+
+**理由**：字节序错误会导致所有温度数据完全错误，且表现不明显（不是崩溃，而是系统正常运行但数值错误）。强调标注可防止工程师跳过该步骤。
+
+### 决策 3：Y16 单位列出三种常见格式对照表，而非硬编码结论
+
+**理由**：Mini212G2 不同固件版本可能存在差异，现场联调时工程师需要人工判断。对照表（K×100、K×10、℃×10）让判断有据可查。
+
+### 决策 4：在 README 和模式配置文档中添加指向预配置指南的链接
+
+**理由**：保证文档可达性，防止孤立文件不被发现。两个入口文档均有传感器相关章节，是链接的自然落点。
+
+## Risks / Trade-offs
+
+- **风险**：Mini212G2 固件升级后命令 HEX 可能变化 → **缓解**：文档顶部注明适用固件版本为 V1.x，并要求升级后重新验证。
+- **风险**：工程师忽略预配置指南直接上电 → **缓解**：在 README"快速上手"章节前置一条警告，指向预配置指南。
+- **权衡**：文档方式无法从固件层面强制约束传感器配置，只能依赖操作规范 → 可接受，因修改驱动增加的复杂度和维护风险更高。
+
+## Open Questions
+
+- Mini212G2 具体 Y16 量纲（K×10 / ℃×10 / 其他）需联调后确认，当前文档提供验证方法但无结论。

openspec/changes/archive/2026-03-15-dvp-raw-data-pipeline/proposal.md

@@ -0,0 +1,27 @@
+# Proposal: DVP 原始数据采集流程验证与传感器预配置规范
+
+## Why
+
+MCU 端驱动不通过 UART 配置传感器（`SENSOR_UART_ENABLE=0`），而是依赖外部工具预先宼入。当前无文档明确说明需要配置哪些参数，导致两个关键风险：
+① CMOS8 字节序：传感器必须配置为 **LSB 模式**，否则 CH32V307（小端序）将 `uint16_t` 读到字节完全反序的错误温度值；
+② Y16 单位：代码按 0.1°C/LSB 使用，需确认实际传感器输出的温度单位一致。
+
+## What Changes
+
+- 新增 **Mini212G2 预配置指南**（`Doc/Mini212G2预配置指南.md`），明确列出外部工具需要设置的所有参数及原因
+- MCU 驱动代码不作任何修改（`SENSOR_UART_ENABLE` 保持为 0）
+
+## Capabilities
+
+### New Capabilities
+- `sensor-preconfig-guide`: Mini212G2 预配置指南文档
+
+### Modified Capabilities
+
+(无，MCU 代码不变)
+
+## Impact
+
+- **新增文档**：`Doc/Mini212G2预配置指南.md`
+- **不涉及** MCU 代码修改
+- 配置错误情况下所有温度判断和上报数据均为错误值

openspec/changes/archive/2026-03-15-dvp-raw-data-pipeline/specs/sensor-preconfig-guide/spec.md

@@ -0,0 +1,45 @@
+## ADDED Requirements
+
+### Requirement: 提供 Mini212G2 传感器预配置操作指南
+操作指南文档（`Doc/Mini212G2预配置指南.md`）SHALL 明确说明在使用 MCU 固件采集前，必须通过外部工具完成的所有 Mini212G2 参数配置步骤、对应串口命令 HEX 及原因说明。
+
+#### Scenario: 工程师查阅配置步骤
+- **WHEN** 工程师准备部署传感器时
+- **THEN** 文档 SHALL 提供编号的步骤列表，包含每步的操作内容和串口命令
+
+#### Scenario: 工程师查找特定参数的命令 HEX
+- **WHEN** 工程师需要向传感器发送配置命令时
+- **THEN** 文档 SHALL 包含完整的命令 HEX 汇总表，包含参数名称、命令 HEX、说明三列
+
+### Requirement: 强制配置 CMOS 内容为 TMP 模式
+指南 SHALL 要求 CMOS 内容配置为 **TMP**（不是 Y16），并说明原因：MCU 代码将像素值直接当温度使用（0.1°C/LSB），这是 TMP 模式输出的格式，而非 Y16 原始 ADC 值。
+
+#### Scenario: 工程师理解为何必须选 TMP 而非 Y16
+- **WHEN** 工程师阅读 CMOS 内容配置步骤时
+- **THEN** 文档 SHALL 解释：TMP 输出的 16-bit 值直接是温度（传感器内部已完成定标），Y16 是原始 ADC 计数值需另行温度解算；代码假设的 0.1°C/LSB 就是 TMP 格式
+
+#### Scenario: 工程师误选了 Y16 模式
+- **WHEN** 工程师将传感器 CMOS 内容配置为 Y16 时
+- **THEN** 所有温度判断将得到错误结果（原始 ADC 值被当做温度），但系统不会报错；文档 SHALL 以 ⛔ 警告标注此风险
+
+### Requirement: 提供 TMP 模式温度格式联调验证方法
+指南 SHALL 提供至少一种可操作的现场验证方法，使工程师能确认 TMP 模式输出的 16-bit 值就是 0.1°C/LSB 格式。
+
+#### Scenario: 验证 TMP 输出格式正确
+- **WHEN** 工程师首次联调时
+- **THEN** 文档 SHALL 提供通过已知温度目标对比中心像素原始值的验证步骤，预期中心像素均值约等于实际温度 × 10（如 25°C 对应 250）
+
+#### Scenario: 验证结果与预期不符
+- **WHEN** 工程师发现像素值不符合 0.1°C/LSB 预期时
+- **THEN** 文档 SHALL 列出常见错误值对应的可能原因（如配置为 Y16 模式，或 MSB 字节序错误）并说明如何排查
+
+### Requirement: 从入口文档链接至预配置指南
+`README.md` 和 `Doc/模式配置与功能说明.md` SHALL 包含指向 `Doc/Mini212G2预配置指南.md` 的可导航链接。
+
+#### Scenario: 工程师从 README 进入预配置指南
+- **WHEN** 工程师阅读 README 参考文档章节时
+- **THEN** 文档列表中 SHALL 存在指向预配置指南的条目
+
+#### Scenario: 工程师从模式配置文档进入预配置指南
+- **WHEN** 工程师阅读模式配置文档的传感器相关章节时
+- **THEN** 相关位置 SHALL 有注释或链接指向预配置指南

openspec/changes/archive/2026-03-15-dvp-raw-data-pipeline/tasks.md

@@ -0,0 +1,23 @@
+## 1. 创建预配置指南主体文档
+
+- [x] 1.1 新建 `Doc/Mini212G2预配置指南.md`，列出 4 项必须配置的参数（视频格式 Y16、CMOS8 LSB、帧率、图像尺寸）
+- [x] 1.2 在文档中说明 CMOS8(LSB) 的字节序原理（CH32V307 小端序 + DVP 直接强转 `uint16_t*`）
+- [x] 1.3 在文档中添加 ⛔ 关键警告：误选 MSB 模式将导致所有温度数据完全错误
+- [x] 1.4 提供每个配置步骤对应的串口命令 HEX 汇总表
+
+## 2. TMP 模式温度格式确认（已更新）
+
+- [x] 2.1 在预配置指南中说明 TMP 与 Y16 的本质区别（传感器内部定标 vs 原始 ADC 值）
+- [x] 2.2 提供 TMP 模式联调验证步骤（已知温度目标对比，期望中心像素值 ≈ 实际°C × 10）
+- [x] 2.3 说明若验证值异常，可能原因（误配为 Y16 或 MSB 字节序）及排查方法
+
+## 3. 更新入口文档链接
+
+- [x] 3.1 在 `README.md` 参考文档表中新增 `Mini212G2预配置指南` 链接条目
+- [x] 3.2 在 `Doc/模式配置与功能说明.md` 传感器相关章节添加指向预配置指南的链接注释
+
+## 4. 联调验证（硬件）
+
+- [ ] 4.1 按指南完成传感器外部配置，确认视频格式为 Y16、字节序为 LSB
+- [ ] 4.2 上电后检查 DVP 采集的中心像素原始值，与已知温度目标对照，确认 Y16 量纲
+- [ ] 4.3 若量纲与 0.1°C/LSB 不一致，在预配置指南中补充实测结论及换算公式

openspec/specs/sensor-preconfig-guide/spec.md

@@ -0,0 +1,45 @@
+## ADDED Requirements
+
+### Requirement: 提供 Mini212G2 传感器预配置操作指南
+操作指南文档（`Doc/Mini212G2预配置指南.md`）SHALL 明确说明在使用 MCU 固件采集前，必须通过外部工具完成的所有 Mini212G2 参数配置步骤、对应串口命令 HEX 及原因说明。
+
+#### Scenario: 工程师查阅配置步骤
+- **WHEN** 工程师准备部署传感器时
+- **THEN** 文档 SHALL 提供编号的步骤列表，包含每步的操作内容和串口命令
+
+#### Scenario: 工程师查找特定参数的命令 HEX
+- **WHEN** 工程师需要向传感器发送配置命令时
+- **THEN** 文档 SHALL 包含完整的命令 HEX 汇总表，包含参数名称、命令 HEX、说明三列
+
+### Requirement: 强制配置 CMOS 内容为 TMP 模式
+指南 SHALL 要求 CMOS 内容配置为 **TMP**（不是 Y16），并说明原因：MCU 代码将像素值直接当温度使用（0.1°C/LSB），这是 TMP 模式输出的格式，而非 Y16 原始 ADC 值。
+
+#### Scenario: 工程师理解为何必须选 TMP 而非 Y16
+- **WHEN** 工程师阅读 CMOS 内容配置步骤时
+- **THEN** 文档 SHALL 解释：TMP 输出的 16-bit 值直接是温度（传感器内部已完成定标），Y16 是原始 ADC 计数值需另行温度解算；代码假设的 0.1°C/LSB 就是 TMP 格式
+
+#### Scenario: 工程师误选了 Y16 模式
+- **WHEN** 工程师将传感器 CMOS 内容配置为 Y16 时
+- **THEN** 所有温度判断将得到错误结果（原始 ADC 值被当做温度），但系统不会报错；文档 SHALL 以 ⛔ 警告标注此风险
+
+### Requirement: 提供 TMP 模式温度格式联调验证方法
+指南 SHALL 提供至少一种可操作的现场验证方法，使工程师能确认 TMP 模式输出的 16-bit 值就是 0.1°C/LSB 格式。
+
+#### Scenario: 验证 TMP 输出格式正确
+- **WHEN** 工程师首次联调时
+- **THEN** 文档 SHALL 提供通过已知温度目标对比中心像素原始值的验证步骤，预期中心像素均值约等于实际温度 × 10（如 25°C 对应 250）
+
+#### Scenario: 验证结果与预期不符
+- **WHEN** 工程师发现像素值不符合 0.1°C/LSB 预期时
+- **THEN** 文档 SHALL 列出常见错误值对应的可能原因（如配置为 Y16 模式，或 MSB 字节序错误）并说明如何排查
+
+### Requirement: 从入口文档链接至预配置指南
+`README.md` 和 `Doc/模式配置与功能说明.md` SHALL 包含指向 `Doc/Mini212G2预配置指南.md` 的可导航链接。
+
+#### Scenario: 工程师从 README 进入预配置指南
+- **WHEN** 工程师阅读 README 参考文档章节时
+- **THEN** 文档列表中 SHALL 存在指向预配置指南的条目
+
+#### Scenario: 工程师从模式配置文档进入预配置指南
+- **WHEN** 工程师阅读模式配置文档的传感器相关章节时
+- **THEN** 相关位置 SHALL 有注释或链接指向预配置指南