zhoujie b69717b964 📝 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 按需截图工作方式
- 列出错误码表和对接故障排查步骤

2026-03-15 19:17:41 +08:00

3.6 KiB

Raw Blame History

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 调用，防止业务任务和网络任务并发访问

3.6 KiB Raw Blame History Unescape Escape