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