zhoujie/ch32v307_camera
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
✨ 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:
zhoujie
2026-03-15 19:17:41 +08:00
parent c347c988f2
commit b69717b964
19 changed files with 1818 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
openspec/specs/dvp-module-design/spec.md
+53
View File
@@ -0,0 +1,53 @@
# dvp-module-design Specification
## Purpose
TBD - created by archiving change software-design-doc. Update Purpose after archive.
## Requirements
### Requirement: DVP 硬件初始化配置描述
文档 SHALL 描述 DVP 外设的完整初始化配置，包含 GPIO 引脚映射、工作模式和信号极性。
#### Scenario: 开发者核查 DVP GPIO 引脚分配
- **WHEN** 开发者进行硬件调试时
- **THEN** 文档 SHALL 提供引脚映射表：PA4/5/6/9/10（数据线 D0-D4）、PC8/9/11（D5-D7 + PCLK）、PB3/8/9（VSYNC/HSYNC/PIXCLK），所有引脚配置为浮空输入
#### Scenario: 开发者理解 DVP 信号极性配置
- **WHEN** 开发者对接不同传感器时
- **THEN** 文档 SHALL 说明：VSYNC 高有效（RB_DVP_V_POLAR=1，对应 DIGITAL_FIELD_VALID 高电平有效帧）、HSYNC 高有效（RB_DVP_H_POLAR=0）、PCLK 上升沿采样（RB_DVP_P_POLAR=0），与 Mini212G2 手册时序图一致
### Requirement: DMA ping-pong 行缓冲机制描述
文档 SHALL 描述 DVP DMA 双缓冲的工作原理，包含缓冲切换逻辑和 IRQ 中的正确读取方式。
#### Scenario: 开发者理解 DMA 缓冲切换逻辑
- **WHEN** 开发者排查行数据乱序问题时
- **THEN** 文档 SHALL 说明：DVP 硬件在 DMA_BUF0/BUF1 间自动切换，ROW_DONE 中断触发时硬件已切换到下一个缓冲；BUF_TOG=1 表示 DMA 正在写 BUF0，此时应读 BUF1（公式：`src = (CR1 & BUF_TOG) ? DMA_LineBuf0 : DMA_LineBuf1`）
#### Scenario: 开发者理解行缓冲大小约束
- **WHEN** 开发者修改传感器分辨率时
- **THEN** 文档 SHALL 说明：DMA_LineBuf0/1 各 512 字节（256 像素 × 2 字节），COL_NUM=512，ROW_NUM=1（每行触发一次 IRQ），修改分辨率需同时更新 `BYTES_PER_LINE`、`SENSOR_WIDTH`、`SENSOR_HEIGHT`
### Requirement: DVP IRQ 帧组装逻辑描述
文档 SHALL 描述 `DVP_IRQHandler` 的完整逻辑，包含帧同步机制和 FrameBuffer 组装方式。
#### Scenario: 开发者理解帧同步锚点
- **WHEN** 开发者排查帧错位问题时
- **THEN** 文档 SHALL 说明：STR_FRM 中断（VSYNC 上升沿）将 `current_line_idx` 清零，此为帧同步唯一锚点；ROW_DONE 中断依次将行数据 memcpy 至 `FrameBuffer[current_line_idx]` 并递增
#### Scenario: 开发者理解帧完成标志
- **WHEN** 开发者需要知道何时帧数据可用时
- **THEN** 文档 SHALL 说明：当 `idx == SENSOR_HEIGHT - 1`（即第 191 行完成）时，`Frame_Ready_Flag` 置 1，`Ready_Frame_Count` 更新为当前帧号；业务任务轮询此标志，读取后将其清零
#### Scenario: 开发者理解 IRQ 使用 fast interrupt 属性的原因
- **WHEN** 开发者修改 IRQ 属性时
- **THEN** 文档 SHALL 说明：`__attribute__((interrupt("WCH-Interrupt-fast")))` 使中断处理跳过寄存器入栈，减少中断延迟，确保在下一行像素时钟到来前完成 memcpy（每行约 42.67µs @ 25Hz）
### Requirement: FrameBuffer 数据格式描述
文档 SHALL 描述 FrameBuffer 的内存布局和像素值含义。
#### Scenario: 开发者访问特定像素的温度值
- **WHEN** 开发者需要读取第 row 行第 col 列的温度时
- **THEN** 文档 SHALL 说明：`FrameBuffer` 声明为 `uint8_t[192][512]`，通过 `(uint16_t*)FrameBuffer` 访问，像素值 = `((uint16_t*)FrameBuffer)[row * 256 + col]`，单位 0.1°C/LSB（TMP 模式，需传感器预配置为 TMP）
#### Scenario: 开发者理解字节序要求
- **WHEN** 开发者移植到大端序平台时
- **THEN** 文档 SHALL 说明：CH32V307 为小端序，`uint8_t[0]` = 低字节，`uint8_t[1]` = 高字节；传感器必须配置为 CMOS8(LSB)（低字节先发），否则温度值字节反序
openspec/specs/integration-guide/spec.md
+62
View File
@@ -0,0 +1,62 @@
# integration-guide Specification
## Purpose
TBD - created by archiving change software-design-doc. Update Purpose after archive.
## Requirements
### Requirement: 对接方网络接入参数说明
文档 SHALL 提供上位机（ConfigServer）与采集端建立 TCP 连接所需的全部参数。
#### Scenario: 对接方配置 TCP Server 监听端口
- **WHEN** 对接方开发服务端程序时
- **THEN** 文档 SHALL 提供：MCU 默认 IP=192.168.7.10，Subnet=255.255.255.0，Gateway=192.168.7.1；Server 需在 192.168.7.50 监听两个端口：5511（控制流，MCU 主动连入）和 5512（数据流，MCU 主动连入）；以太网接口为 1000M RGMII
### Requirement: 握手流程说明
文档 SHALL 描述 MCU 上电后的握手过程，使对接方能正确识别采集端设备。
#### Scenario: 对接方接收第一个数据包并识别设备
- **WHEN** MCU 连接后发送握手帧时
- **THEN** 文档 SHALL 说明：MCU 在控制流连接成功后发送 TYPE_HANDSHAKE（Class=CLASS_SYSTEM，含 ProtocolVersion=0x0200、DeviceUUID=MAC 地址、AuthToken=全零）；服务器 SHALL 回复握手响应以完成握手；握手完成后 MCU 才开始正常数据上报
### Requirement: 配置下发格式说明
文档 SHALL 描述服务器向 MCU 下发配置的帧格式和所有配置字段含义。
#### Scenario: 对接方配置 2D 触发模式
- **WHEN** 对接方发送 Config2D 配置帧时
- **THEN** 文档 SHALL 提供 Config2D_t 所有字段：Enabled(uint8_t)、TriggerMode(uint8_t, 0=内部温度/1=外部GPIO)、TriggerDebounceIntervalMs(uint16_t)、TriggerDelayMs(uint16_t)、TriggerBurstCount(uint8_t)、TriggerInternalIntervalMs(uint16_t)、TriggerTemperatureThreshold(int16_t, 0.1°C/LSB)、TriggerCondition(uint8_t, 0=Avg/1=Max)、TriggerRoiX/Y/W/H(uint16_t)、TargetWidth/Height(uint16_t)、NGioDelay(uint16_t, ms)
#### Scenario: 对接方配置 1D 采集模式
- **WHEN** 对接方发送 Config1D 配置帧时
- **THEN** 文档 SHALL 提供 Config1D_t 所有字段：Enabled(uint8_t)、RunMode(uint8_t, 0=STOP/1=RUN)、TriggerType(uint8_t, 1=内部/2=外部)、TriggerTempLimit(int16_t)、HighTimerLimit(uint16_t, ms)、NgCountLimit(uint16_t, 帧数)、BufferSize(uint16_t)、LSizeStart/RSizeStart(uint16_t, 切片参数)
### Requirement: 温度帧数据包格式说明
文档 SHALL 描述 MCU 上报的温度帧数据包的完整格式，使对接方能正确解析。
#### Scenario: 对接方解析收到的 2D 温度帧
- **WHEN** 数据流收到 TYPE_TEMP_FRAME 包时
- **THEN** 文档 SHALL 说明：Value 区域含 PreprocessResult 元数据（ValidWidth × ValidHeight 像素数组）；像素为 uint16_t little-endian，单位 0.1°C/LSB；元数据含 MaxTemp/MinTemp/AvgTemp/RoiTemp（均 int16_t, 0.1°C/LSB）、ValidWidth/ValidHeight（实际 ROI 尺寸）、FrameNumber
#### Scenario: 对接方解析收到的 1D 温度帧
- **WHEN** 数据流收到 1D TYPE_TEMP_FRAME 包时
- **THEN** 文档 SHALL 说明：is2D=0，每个样本 4 字节：[time_off_lo, time_off_hi, temp_lo, temp_hi]，time_offset 为相对采集开始的 ms 偏移（uint16_t），temp 为 uint16_t 0.1°C/LSB
### Requirement: 触发结果上报和 NG 响应机制说明
文档 SHALL 描述采集端如何响应服务器的 DetectionResult 决策和触发 NG 输出。
#### Scenario: 对接方下发检测结果
- **WHEN** 服务器完成图像分析后回传结果时
- **THEN** 文档 SHALL 说明：服务器发送 TYPE_DETECTION_RESULT（含 frameNumber、resultStatus，0=NG/1=OK）；MCU 收到 resultStatus=0 时触发 PA8 高电平 NGioDelay ms（默认 200ms）；对接方可通过 NGioDelay 配置 NG 输出脉宽
### Requirement: TEMP_REQ 按需截图说明
文档 SHALL 描述服务器如何向 MCU 请求即时截图。
#### Scenario: 对接方请求单帧截图
- **WHEN** 服务器需要调试或核查当前热场时
- **THEN** 文档 SHALL 说明：控制流发送 TYPE_CONFIG_COMMON 或专用 TEMP_REQ 命令（含 is2dRequest 字段）；MCU 将在下一个业务循环发送当前最新帧，2D 返回 ROI 裁切后温度矩阵，1D 返回中心行 30 个等间距采样点；仅在对应模式已 Enabled 时响应
### Requirement: 错误码和异常处理说明
文档 SHALL 列出协议层所有错误码含义及对接方应采取的处理措施。
#### Scenario: 对接方收到 ERR 响应帧
- **WHEN** 服务器发送格式错误的配置帧时
- **THEN** 文档 SHALL 列出错误码含义：ERR_CRC(0x1001)=CRC 校验失败、ERR_VERSION(0x1002)=协议版本不匹配、ERR_LENGTH(0x1003)=帧长度异常、ERR_AUTH(0x2001)=认证失败、ERR_BUSY(0x2002)=设备忙、ERR_PARAM(0x3001)=参数非法；收到错误码后对接方 SHALL 检查发送的帧格式后重试
openspec/specs/qdx-protocol-design/spec.md
+41
View File
@@ -0,0 +1,41 @@
# qdx-protocol-design Specification
## Purpose
TBD - created by archiving change software-design-doc. Update Purpose after archive.
## 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)=末片标志
openspec/specs/system-overview/spec.md
+60
View File
@@ -0,0 +1,60 @@
# system-overview Specification
## Purpose
TBD - created by archiving change software-design-doc. Update Purpose after archive.
## Requirements
### Requirement: FreeRTOS 任务拓扑描述
文档 SHALL 列出所有 RTOS 任务的名称、优先级、栈大小、职责及任务间通信方式。
#### Scenario: 开发者查阅任务优先级
- **WHEN** 开发者需要了解任务调度顺序时
- **THEN** 文档 SHALL 提供任务优先级表，包含：task_wchnet（优先级 6，512 字）、task_business（优先级 5，512 字）、task_heartbeat（优先级 3，256 字）、task_test_pattern（优先级 4，256 字，仅 TEST_PATTERN_MODE=1 时存在）
#### Scenario: 开发者理解任务间数据流
- **WHEN** 开发者需要理解 DVP → 业务任务的数据传递时
- **THEN** 文档 SHALL 说明通过 `Frame_Ready_Flag`（volatile 标志）和 `FrameBuffer`（共享内存）传递帧数据，IRQ 置位，业务任务轮询消费
### Requirement: 系统启动序列描述
文档 SHALL 描述 `main()` 的初始化顺序，涵盖所有外设和模块的初始化步骤及其依赖关系。
#### Scenario: 开发者定位初始化顺序问题
- **WHEN** 开发者遇到启动相关 bug 时
- **THEN** 文档 SHALL 提供启动序列：SystemClock → USART3/debug → Flash/SRAM 配置（128K+192K）→ DVP_Init → TIM2_Init → ExtTrigger_GPIO → NG_GPIO → ETH_LibInit → qdx_port_init → Preprocess_Init → TcpLogic_Init → 注册回调 → TcpLogic_Start → 创建 RTOS 任务 → vTaskStartScheduler
### Requirement: 2D 状态机完整描述
文档 SHALL 描述 2D 触发状态机的所有状态、转换条件和行为，包含外部触发和内部触发两种模式。
#### Scenario: 开发者理解 2D 外部触发流程
- **WHEN** 开发者排查外部触发抖动问题时
- **THEN** 文档 SHALL 描述：IDLE → [PA15 上升沿] → DEBOUNCE（等待 DebounceIntervalMs） → DELAY（等待 TriggerDelayMs） → BURST（发 BurstCount 帧，间隔 TriggerInternalIntervalMs） → IDLE
#### Scenario: 开发者理解 2D 内部触发流程
- **WHEN** 开发者配置温度阈值触发时
- **THEN** 文档 SHALL 描述：每帧调用 `Preprocess_CheckInternalTrigger2D`，在 TriggerRoi 区域内 Max/Avg 超过 TriggerTemperatureThreshold 时触发，跳过 DEBOUNCE 直接进入 DELAY → BURST
#### Scenario: 开发者理解双缓冲 TX 逻辑
- **WHEN** 开发者排查发送顺序问题时
- **THEN** 文档 SHALL 说明 `use_buffer_A` 标志在每次发送时取反，g_TxNetBuffer_A / g_TxNetBuffer_B 交替使用，避免前一帧发送未完成时被覆盖
### Requirement: 1D 状态机完整描述
文档 SHALL 描述 1D 采集状态机的所有状态、转换条件、采集逻辑和发送条件。
#### Scenario: 开发者理解 1D 外部触发流程
- **WHEN** 开发者配置 TriggerType=2 时
- **THEN** 文档 SHALL 描述：S1D_IDLE → [PA15 上升沿] → S1D_DEBOUNCE（等待 HighTimerLimit ms） → S1D_COLLECTING（采集 temp+time 样本直到停止条件）→ 发送 → S1D_IDLE
#### Scenario: 开发者理解 1D 内部触发流程
- **WHEN** 开发者配置 TriggerType=1 时
- **THEN** 文档 SHALL 描述：S1D_IDLE 中维护 3 帧滑动窗口，连续 3 帧帧最大温度 ≥ TriggerTempLimit 时进入 S1D_COLLECTING；停止条件：样本数达 BufferSize 或触发后连续 NgCountLimit 帧低温
#### Scenario: 开发者理解 1D 数据格式
- **WHEN** 开发者解析 1D 数据时
- **THEN** 文档 SHALL 说明每个样本 4 字节：[time_offset_lo, time_offset_hi, temp_lo, temp_hi]，time_offset 为相对采集开始的 ms 偏移，temp 为 0.1°C/LSB 的 uint16_t
### Requirement: TEMP_REQ 辅助通道描述
文档 SHALL 描述服务器按需截图（TEMP_REQ）的触发流程和限制条件。
#### Scenario: 开发者理解 TEMP_REQ 工作方式
- **WHEN** 服务器发送 TEMP_REQ 命令时
- **THEN** 文档 SHALL 说明：`g_temp_req_pending` 置位，业务任务在下次循环读取当前 FrameBuffer 发送，is2D=1 走 Preprocess_Execute + 2D 封包，is2D=0 走 send_1d_snapshot（30 个等间距采样点）；仅在对应模式 Enabled 时响应
openspec/specs/tcp-module-design/spec.md
+48
View File
@@ -0,0 +1,48 @@
# tcp-module-design Specification
## Purpose
TBD - created by archiving change software-design-doc. Update Purpose after archive.
## Requirements
### Requirement: 双流连接架构描述
文档 SHALL 描述控制流（5511）和数据流（5512）的职责分工、连接方式和状态管理。
#### Scenario: 开发者理解双流设计意图
- **WHEN** 开发者排查连接问题时
- **THEN** 文档 SHALL 说明：控制流 srcport=5511（MCU 主动连接 Server），用于握手、配置下发、心跳、TEMP_REQ、DetectionResult 上报；数据流 desport=5512（MCU 主动连接 Server），用于温度帧数据上报；两流独立管理，数据流断开不影响控制流
#### Scenario: 开发者理解 TCP 连接建立时序
- **WHEN** 开发者排查首次握手失败时
- **THEN** 文档 SHALL 说明：`TcpLogic_Start` 派生后台连接状态机，先尝试控制流连接 → 连接成功后发送 TYPE_HANDSHAKE（含 DeviceUUID=MAC地址、AuthToken=NULL）→ 收到服务器握手响应后标记连接就绪 → 同步尝试数据流连接
### Requirement: 心跳机制描述
文档 SHALL 描述心跳帧的发送周期、TCP Keepalive 配置和连接保活策略。
#### Scenario: 开发者调整心跳参数
- **WHEN** 网络中间件（NAT/防火墙）超时断连时
- **THEN** 文档 SHALL 说明：应用层心跳 TYPE_HEARTBEAT 由 TcpLogic 内部定时发送；TCP Keepalive 配置：空闲 20 秒（`idle=20000ms`）后开始探测，每次间隔 15 秒（`interval=15000ms`），最多 9 次（`count=9`）探测无响应则断链重连
### Requirement: 配置下发与缓存机制描述
文档 SHALL 描述服务器配置的接收、缓存和通知流程。
#### Scenario: 开发者追踪配置更新流程
- **WHEN** 服务器下发配置后行为未按预期改变时
- **THEN** 文档 SHALL 描述：服务器发送 TYPE_CONFIG_COMMON + TYPE_CONFIG_2D + TYPE_CONFIG_1D → TcpLogic 解析并缓存至内部 shadow 寄存器 → 触发 ConfigUpdateCallback（`OnConfigUpdate`）→ 回调内调用 `Preprocess_Settings_Change` 更新预处理参数；`TcpLogic_GetLatestConfig` 可随时读取最新配置副本
#### Scenario: 开发者理解无配置时的默认行为
- **WHEN** 设备启动后服务器尚未下发配置时
- **THEN** 文档 SHALL 说明：`TcpLogic_GetLatestConfig` 返回 -1，业务任务跳过 2D/1D 处理，仅响应 TEMP_REQ（若有）；默认 burst 参数 DEFAULT_BURST_COUNT=3、DEFAULT_BURST_INTERVAL_MS=200ms 作为 fallback
### Requirement: 数据发送队列和背压处理描述
文档 SHALL 描述温度帧发送的队列机制和发送失败时的处理策略。
#### Scenario: 开发者排查数据帧丢失问题
- **WHEN** 网络繁忙时出现帧丢失时
- **THEN** 文档 SHALL 说明：`TcpLogic_BuildAndSendTemperatureFrame` 返回 0 表示成功入队，返回 <0 表示发送失败（队列满或连接断开）；当前固件对发送失败仅打印 DBG_ERR，不重试；双缓冲 TX 保证当前帧被入队时，下一帧可立即写入另一个缓冲
### Requirement: WCHNET 网络栈驱动任务描述
文档 SHALL 描述 task_wchnet 的职责和与 WCHNET 库的交互方式。
#### Scenario: 开发者理解网络栈如何被驱动
- **WHEN** 开发者排查网络响应迟缓问题时
- **THEN** 文档 SHALL 说明：`task_wchnet_entry` 每 5ms 轮询一次，调用 `WCHNET_MainTask`（协议栈心跳）和 `WCHNET_HandleGlobalInt`（socket 事件分发）；socket 接收/连接/断开事件通过 `qdx_port_sock_*_notify` 转发给 QDX 网络层；`qdx_port_net_lock/unlock` 用互斥量保护 WCHNET 调用，防止业务任务和网络任务并发访问