## Context

**项目背景**：CH32V307WCU6 红外热像采集端固件，连接 Mini212G2 (256×192) 传感器，通过 1000M RGMII 以太网上报温度数据。核心功能已稳定运行，但缺少系统性设计文档。

**当前状态**：代码实现完整，包含 FreeRTOS 多任务、DVP+DMA 采集、QDX TLV 协议、双流 TCP 通信、2D/1D 双状态机。现有文档仅覆盖配置参数和协议接口，未形成模块级设计视图。

**读者**：内部开发工程师（理解实现逻辑、维护代码）；外部对接方（ConfigServer/上位机开发团队，需接入协议）。

## Goals / Non-Goals

**Goals:**
- 为 5 个能力模块分别建立规范化的设计文档
- 通过 openspec specs 机制使文档可版本追踪和演进
- 提供外部对接方可直接使用的集成指南（无需阅读源码）

**Non-Goals:**
- 不修改任何代码
- 不覆盖硬件电气原理图（属于硬件文档）
- 不重复协议 HEX 命令表（已在 `Doc/Mini212G2预配置指南.md`）

## Decisions

### 决策 1：每个能力模块生成独立的 spec 文件，Doc/ 目录存放最终可交付文档

**理由**：openspec 的 `specs/<capability>/spec.md` 是规范锚点，实际可读性文档放在 `Doc/设计文档/` 下，分工清晰。每个 spec 描述 WHAT（需求），Doc 中文件描述 HOW（实现细节）。

**备选方案**：一个大 spec 文件 → 拒绝，spec 文件过大时 apply 阶段难以跟踪单个需求。

### 决策 2：集成指南（integration-guide）作为独立能力，单独维护

**理由**：外部对接方只需集成指南，不需要理解内部模块设计。独立文件避免外部文档被内部修改污染，版本可单独管控。

### 决策 3：文档覆盖既有代码的实际行为，不做超前设计

**理由**：这是文档补全变更，不是功能变更。spec 反映的是代码已实现的行为（SHALL = 当前实现保证），不引入新约束。

### 决策 4：2D 状态机和 1D 状态机各自独立描述，不合并

**理由**：两者触发逻辑、收集方式、发送格式完全不同（2D 矩阵 vs 1D 时间序列）。合并描述会造成混淆。两者通过 `Config2D.Enabled` / `Config1D.Enabled` 互斥使能。

## Risks / Trade-offs

- **风险**：文档编写时代码继续演进，导致文档过时 → **缓解**：在 spec 中使用 SHALL 约束当前行为，代码变更时触发 spec 更新 PR 流程。
- **风险**：integration-guide 中的协议字段描述与实际结构体不一致 → **缓解**：所有字段描述直接从 `qdx_protocol.h` 提取，source of truth 为代码。
- **权衡**：文档详细程度 vs 维护成本 → 选择"关键路径详细，边缘情况参考注释"策略，避免过度文档导致维护负担。

## Open Questions

- Doc/ 下设计文档是否需要中英双语（供外部团队使用）？当前按中文优先。
- integration-guide 是否需要提供 Python/C# 示例解析代码片段？后续可作为独立变更补充。