📝 docs(design): 新增系统设计文档集

✨ 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 按需截图工作方式
- 列出错误码表和对接故障排查步骤
This commit is contained in:
2026-03-15 19:17:41 +08:00
parent c347c988f2
commit b69717b964
19 changed files with 1818 additions and 0 deletions
@@ -0,0 +1,37 @@
## ADDED Requirements
### Requirement: TLV 帧结构完整描述
文档 SHALL 描述 QDX 协议的完整帧结构,包含帧头各字段含义、TLV 格式和帧尾 CRC。
#### Scenario: 开发者手动构造一个协议帧
- **WHEN** 开发者需要调试发送内容时
- **THEN** 文档 SHALL 提供帧结构:[FrameHeader 16B] + [TLV_Header 3B] + [Value NB] + [CRC16 2B],其中 FrameHeader = {Magic(2)=0x55AA, Version(1)=0x20, Length(2), Sequence(2), Timestamp(4), Source(1), DevID(2), Class(1), Flags(1)}
#### Scenario: 开发者理解 Class 和 TLV Type 的对应关系
- **WHEN** 开发者解析收到的帧时
- **THEN** 文档 SHALL 列出完整的 Class/Type 映射表:CLASS_CONTROL(0x01)、CLASS_DATA(0x02)、CLASS_RESPONSE(0x03)、CLASS_SYSTEM(0x04);Type 包含 TYPE_HANDSHAKE(0x01)、TYPE_HEARTBEAT(0x02)、TYPE_TEMP_FRAME(0x10)、TYPE_CONFIG_COMMON(0x20)、TYPE_CONFIG_2D(0x22)、TYPE_CONFIG_1D(0x23)、TYPE_ACK_PAYLOAD(0x30)、TYPE_DETECTION_RESULT(0x40) 等
### Requirement: 零拷贝 TX 缓冲区架构描述
文档 SHALL 描述 TcpTxBuffer_t 的双缓冲零拷贝发送架构和 HeadOffset 的使用方式。
#### Scenario: 开发者理解零拷贝的实现方式
- **WHEN** 开发者需要在减少内存拷贝的前提下添加新的帧类型时
- **THEN** 文档 SHALL 说明:`TcpTxBuffer_t` 包含 pBuffer(9216B)、HeadOffset(64B)、ValidPayloadLen;图像数据由预处理模块写入 `pBuffer + HeadOffset` 开始的位置;`TcpLogic_BuildAndSendTemperatureFrame` 在 HeadOffset 前的 64 字节内直接写入帧头(FrameHeader + TLV),**无需额外 memcpy**
#### Scenario: 开发者计算单次可发送的最大像素数
- **WHEN** 开发者调整 ROI 大小时
- **THEN** 文档 SHALL 说明:有效载荷容量 = TotalCapacity(9216) - HeadOffset(64) - CRC(2) - TLV_Header(3) - FrameHeader(16) = 9131 字节,每像素 2 字节,最多 4565 个像素(约 67×67 ROI)
### Requirement: 分片机制描述
文档 SHALL 描述协议层的分片上限和分片标志用法。
#### Scenario: 开发者发送超大载荷时
- **WHEN** 开发者发送超过 MAX_FRAGMENT_PAYLOAD(1400B) 的数据时
- **THEN** 文档 SHALL 说明分片最大载荷为 1400B(受 TCP MSS=1460 限制),大帧通过 FLAG_LAST_FRAGMENT(0x20) 标志标识末片;当前 TX 缓冲区为 9216B,单次发送通常不超过此限制
### Requirement: Flags 字段用法描述
文档 SHALL 描述 FrameHeader.Flags 各位的含义和当前固件的使用情况。
#### Scenario: 开发者解析收到的 Flags 字段
- **WHEN** 上位机解析帧时
- **THEN** 文档 SHALL 说明:FLAG_PRIORITY_MASK(0x03)=优先级(0-3)、FLAG_COMPRESSED(0x04)=压缩(当前未使用)、FLAG_ENCRYPTED(0x08)=加密(当前未使用)、FLAG_ACK_REQ(0x10)=需要 ACK、FLAG_LAST_FRAGMENT(0x20)=末片标志