zhoujie
b69717b964
✨ feat(system-overview): 创建系统总览文档 - 描述项目背景与硬件平台配置 - 提供 FreeRTOS 任务拓扑表（任务优先级、栈大小、职责） - 详细说明系统启动序列和初始化依赖关系 - 绘制 2D/1D 状态机完整流程图 - 解释 TEMP_REQ 辅助通道工作机制 - 说明任务间同步机制（Frame_Ready_Flag、双缓冲 TX） ✨ feat(dvp-module-design): 创建 DVP 模块设计文档 - 提供 DVP 硬件连接引脚映射表 - 描述 DVP 时序配置（信号极性、工作模式） - 解释 DMA ping-pong 行缓冲机制和切换逻辑 - 说明 DVP IRQ 帧组装流程（STR_FRM/ROW_DONE） - 定义 FrameBuffer 数据格式和像素访问方式 - 说明 TMP 模式温度换算公式和字节序要求 ✨ feat(qdx-protocol-design): 创建 QDX 协议设计文档 - 描述完整 TLV 帧结构（FrameHeader + TLV + CRC） - 列出所有 Class/Type 映射表和用途说明 - 解释零拷贝 TX 缓冲区架构（HeadOffset 机制） - 说明分片机制和最大载荷限制 - 定义 Flags 字段各位含义和使用场景 ✨ feat(tcp-module-design): 创建 TCP 通信模块设计文档 - 描述双流连接架构（控制流 5511 / 数据流 5512） - 说明握手流程和连接建立时序 - 解释心跳机制和 TCP Keepalive 配置 - 描述配置下发与缓存机制 - 说明数据发送队列和背压处理策略 - 解释 WCHNET 网络栈驱动任务工作机制 ✨ feat(integration-guide): 创建对接集成指南 - 提供网络接入参数表（IP、端口、协议） - 详细说明握手流程和配置下发格式 - 提供 2D/1D 温度帧解析方法和示例代码 - 说明检测结果上报和 NG 响应机制 - 解释 TEMP_REQ 按需截图工作方式 - 列出错误码表和对接故障排查步骤
51 lines
3.0 KiB
Markdown
51 lines
3.0 KiB
Markdown
## 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# 示例解析代码片段？后续可作为独立变更补充。
|