# tcp_ser 模块说明

> 本文档描述 `CCU621_M` 工程 `app/tcp_ser` 目录的职责划分、**完整文件清单**、各源文件功能、TCP/BLE 双链路与命令处理流程。  
> 返回主说明：[README](../../README.md)

**文档版本**：与当前工程树同步（含 BLE 调试、`debug_link` 链路层；**阶段1** 已合并 `comm_link`+Socket；**阶段2** 已合并文件类业务；**不含** `fwbin_protocol` / `fwup_protocol`）。

## 快速跳转

- [1. 模块总览](#1-模块总览)
- [2. 目录与文件清单（完整）](#2-目录与文件清单完整)
- [3. Keil 工程源文件](#3-keil-工程源文件)
- [4. 各文件功能说明](#4-各文件功能说明)
- [5. 分层架构与调用关系](#5-分层架构与调用关系)
- [6. TCP / BLE 双链路](#6-tcp--ble-双链路)
- [7. 已支持命令与处理路径](#7-已支持命令与处理路径)
- [8. 关键流程](#8-关键流程)
- [9. 固件升级（FirmwareUpgrade）](#9-固件升级firmwareupgrade)
- [10. GunInfo 数据规则](#10-guninfo-数据规则)
- [11. CustomData / HistoryOperations](#11-customdata--historyoperations)
- [12. 编译开关与运行条件](#12-编译开关与运行条件)
- [13. 维护注意事项](#13-维护注意事项)
- [14. 已移除 / 不在树内的文件](#14-已移除--不在树内的文件)
- [关联文档](#关联文档)

---

## 1. 模块总览

`tcp_ser` 是 CCU621 的 **上位机调试服务**模块：协议与业务在 `tcp_server` / `tcp_protocol` 中**共用**，物理链路通过 `comm_link` 在 **以太网 TCP** 与 **蓝牙 BLE（FC41D）** 之间切换。

| 职责 | 说明 |
|---|---|
| 链路适配 | `comm_link`：DIP1 选 TCP 或 BLE，对上统一 `receive/send/process` |
| TCP 服务 | 监听端口（默认 **9699**），单客户端 |
| BLE 服务 | FC41D GATT 非透传（fff1/fff2/fff3），广播名默认 `CCU621_Debug` |
| 周期上送 | 每 **2s** 推送 `SystemInfo` + 双枪 `GunInfo`（客户端发 `Heartbeat` 保活） |
| 命令处理 | JSON v2.0 解析、分发、组响应 |
| 业务解耦 | 协议层与充电控制、参数、文件、升级等分离 |

```
上位机 / 小程序
    │  JSON（同一套 v2.0 协议）
    ▼
tcp_server.c              ← RX 缓冲、JSON 抽帧、周期上送、连接管理
    │
    ├── debug_link.c        ← 链路层（comm_link 分发 + TCP Socket + 会话上下文）
    │     └── ble_link/fc41d_ble.c  （UART7 AT + GATT，BLE 后端）
    │
    └── tcp_protocol.c    ← JSON 解析 / 组包 / 命令路由
            ├── debug_files.c         ← FileOperations + FirmwareUpgrade
            ├── system_data.c
            └── system_paracfg.c
```

---

## 2. 目录与文件清单（完整）

当前 `app/tcp_ser/` 共 **19 个文件**（含 `ble_link/` 子目录；`.c` 源文件 7 个）：

```
app/tcp_ser/
├── tcp_ser_task.c              # FreeRTOS 任务入口
├── tcp_ser_task.h
├── tcp_server.c                # 调试服务主逻辑（经 comm_link 收发）
├── tcp_server.h
├── debug_link.c                # 链路层：comm_link 分发 + lwIP Socket + 会话上下文
├── debug_link.h                # 链路层对外 API 与类型
├── debug_files.c               # 文件类业务：FileOperations + FirmwareUpgrade
├── debug_files.h               # 文件类业务对外 API 与类型
├── tcp_protocol.c              # JSON v2.0 协议
├── tcp_protocol.h
├── system_data.c               # 运行时数据、充电控制、历史、CustomData
├── system_data.h
├── system_paracfg.c            # 参数映射表
├── system_paracfg.h
├── ble_link/                   # ── BLE 子目录（BLE_DEBUG_EN=1 时编入）
│   ├── fc41d_ble.c             # FC41D 完整实现 + comm_link 后端
│   ├── fc41d_ble.h             # 配置宏、对外 API
│   └── fc41d_ble_priv.h        # BLE 私有上下文（与 tcp_link_ctx union）
├── TCP_DEBUG_PROTOCOL.md       # JSON 报文字段说明
└── tcp_ser模块说明.md          # 本文档
```

| 子目录 | 说明 |
|---|---|
| `ble_link/` | 仅 FC41D 蓝牙；UART7 AT 辅助函数为 **本目录 static**，不扩展公共 `BSP/com/usart.c` |

---

## 3. Keil 工程源文件

`Project/GD32H759.uvprojx` 中 `tcp_ser` 相关 **.c** 源文件（按工程登记）：

| 源文件 | 路径 |
|---|---|
| `tcp_ser_task.c` | `app/tcp_ser/` |
| `tcp_server.c` | `app/tcp_ser/` |
| `debug_link.c` | `app/tcp_ser/` |
| `fc41d_ble.c` | `app/tcp_ser/ble_link/` |
| `tcp_protocol.c` | `app/tcp_ser/` |
| `system_data.c` | `app/tcp_ser/` |
| `system_paracfg.c` | `app/tcp_ser/` |
| `debug_files.c` | `app/tcp_ser/` |

头文件通过 Include Path `..\app\tcp_ser` 及子目录引用，无需单独加入工程。

---

## 4. 各文件功能说明

### 4.1 任务与调度

| 文件 | 功能 |
|---|---|
| **`tcp_ser_task.c`** | `v_tcp_ser_task`：任务锁、看门狗；`BLE_DEBUG_EN` 时 `ble_link_wait_dip_ready()` 后 `comm_link_set_type(comm_link_type_from_dip())`；每 2s 重试 `tcp_server_start()`；循环 `tcp_server_process()`。 |
| **`tcp_ser_task.h`** | 声明 `v_tcp_ser_task`。 |

### 4.2 链路层（`debug_link`）

| 文件 | 功能 |
|---|---|
| **`debug_link.c`** | 阶段1 合并实现，分三段：<br>• **会话上下文**：单例 `comm_link_ctx_t`（`session` + `backend` union）<br>• **TCP Socket 后端**（本文件内 `static`）：lwIP `init/accept/receive/send/close` 等<br>• **comm_link 分发**：`comm_link_start/stop/process`、`comm_link_receive_data`、`comm_link_send_data` 等；按 `session.type` 转发到 TCP 或 `comm_link_ble_*` |
| **`debug_link.h`** | 链路层统一头：`COMM_LINK_TCP/BLE`、`comm_link_*` API、`comm_link_ctx_*`、`tcp_link_ctx_t`、`comm_link_backend_u` |

### 4.3 传输后端（BLE）
| **`ble_link/fc41d_ble.c`** | FC41D：AT 层、PE6 复位、BLE 状态机、GATT Notify 发送、`+QBLERECV` 解析；实现 `comm_link_ble_*`；UART7 **固定 115200**（`FC41D_UART_BAUD`），阻塞收包在 `fc41d_ble.c` 内 static 实现。 |
| **`ble_link/fc41d_ble.h`** | 硬件/AT 超时宏、`FC41D_BLE_NAME`、GATT UUID、`ble_link_is_bt_mode()`、`comm_link_ble_*` API。 |
| **`ble_link/fc41d_ble_priv.h`** | AT 缓冲、link/app RX 环、状态机枚举与 `fc41d_ble_ctx_t`。 |

### 4.4 服务主控层

| 文件 | 功能 |
|---|---|
| **`tcp_server.c`** | 核心状态机：<br>• 动态 RX 缓冲：常态 **1024B**，固件升级 **8192B**（`tcp_server_rx_upgrade_begin/end`）<br>• `comm_link_receive_data` 收包 → JSON 括号抽帧<br>• 周期上送：每 **2s** `SystemInfo` + 双枪 `GunInfo`；BLE 枪间加延时<br>• 升级进行中暂停周期上送；跳过前导垃圾字节（BLE 分片）<br>• 心跳超时 30s（升级中不判超时）<br>• TCP 回包可追加 `\r\n`；BLE 纯 JSON 无 CRLF |
| **`tcp_server.h`** | `tcp_server_state_t`、`tcp_server_start/process/stop`、`tcp_server_rx_upgrade_*`。 |

### 4.5 协议层

| 文件 | 功能 |
|---|---|
| **`tcp_protocol.c`** | JSON v2.0 组包/解析/分发；**BLE 链路拒绝 `FirmwareUpgrade`**；其余命令与 TCP 相同。 |
| **`tcp_protocol.h`** | `CMD_*`、结构体、状态枚举。 |

### 4.6 业务层

| 文件 | 功能 |
|---|---|
| **`system_data.c`** | `tcp_get_default_system_info/gun_data`、充电启停、`tcp_process_custom_data`、故障与历史记录；GunInfo 见 [§10](#10-guninfo-数据规则)。 |
| **`system_data.h`** | 业务接口与历史查询结构。 |
| **`system_paracfg.c/h`** | 七类参数映射表与读写。 |
| **`debug_files.c`** | 阶段2 合并实现，分两段：<br>• **FileOperations**（`FATFS_EN=1`）：Query/Delete/Download/Upload<br>• **FirmwareUpgrade**：TCP JSON+Base64 写外置 Flash；`system_filetransfer_is_active`、空闲超时等 |
| **`debug_files.h`** | 文件类业务统一头：`file_operation_data_t`、`firmware_upgrade_context_t`、`system_filectrl_*`、`system_filetransfer_*` |

### 4.7 协议文档

| 文件 | 功能 |
|---|---|
| **`TCP_DEBUG_PROTOCOL.md`** | 上位机 JSON 字段与示例（TCP/BLE 共用）。 |

---

## 5. 分层架构与调用关系

| 层次 | 文件 | 职责 |
|---|---|---|
| **任务** | `tcp_ser_task.c` | 选链路、启服务、周期 `tcp_server_process` |
| **服务** | `tcp_server.c` | 缓冲、抽帧、定时上送、连接/超时 |
| **链路** | `debug_link.c` | TCP/BLE 字节流统一接口 + Socket 后端 |
| **后端** | `debug_link.c`（TCP）/ `fc41d_ble.c`（BLE） | 物理收发 |
| **协议** | `tcp_protocol.c` | JSON ↔ 结构体、路由 |
| **业务** | `system_data.c` / `system_paracfg.c` / `debug_files.c` | 桩数据、参数、升级、文件 |

扩展新命令：改 `tcp_protocol.h/c` → 对应 `system_*.c` 或 `debug_files.c` → 更新 `TCP_DEBUG_PROTOCOL.md`。

---

## 6. TCP / BLE 双链路

### 6.1 选路

| 条件 | 物理链路 |
|---|---|
| `BLE_DEBUG_EN=0` | 恒为 TCP（DIP1=1 仅打日志，仍走 TCP） |
| `BLE_DEBUG_EN=1` 且 DIP1=0 | 以太网 TCP，端口 **9699** |
| `BLE_DEBUG_EN=1` 且 DIP1=1 | FC41D BLE GATT |

DIP 来源：副板 `sub_comm` → `u8_sub_comm_yx_get(E_SUB_DIP_1)`。

### 6.2 协议差异

| 项目 | TCP | BLE |
|---|---|---|
| 报文格式 | JSON v2.0 | 同左 |
| 下行结束符 | 可选 `\r\n` | 无 CRLF |
| 周期上报 | 2s SystemInfo + GunInfo×2 | 同左（枪间 ~80ms 间隔） |
| `FirmwareUpgrade` | 支持 | **拒绝**（`tcp_protocol.c`） |
| 固件相关 RX 缓冲放大 | 8192B | 同左（若走 TCP 升级） |

### 6.3 硬件（BLE）

| 项目 | 说明 |
|---|---|
| 模组 | Quectel FC41D |
| UART | UART7，PE1/PE0 |
| 复位 | PE6，`FC41D_RST` 高有效 |
| 广播名 | `CCU621_Debug`（可宏改） |
| 服务/特征 | fff1 / fff2(Write) / fff3(Notify) |

---

## 7. 已支持命令与处理路径

| command | 方向 | TCP | BLE | 业务入口 |
|---|---|:---:|:---:|---|
| `Heartbeat` | 双向 | ✓ | ✓ | 更新 `last_heartbeat_received_tick` |
| `SystemInfo` | 设备→上位机 | ✓ | ✓ | `tcp_get_default_system_info` |
| `GunInfo` | 设备→上位机 | ✓ | ✓ | `tcp_get_default_gun_data` |
| `ChargeControl` | 上位机→设备 | ✓ | ✓ | `system_data_start/stop_charge` |
| `ParamQuery` / `ParamModify` | 上位机→设备 | ✓ | ✓ | `system_paracfg` |
| `FileOperations` | 上位机→设备 | ✓ | ✓ | `system_filectrl_process_*` |
| `HistoryOperations` | 上位机→设备 | ✓ | ✓ | `tcp_history_build/clear_records` |
| `FaultInfo` | 上位机→设备 | ✓ | ✓ | `tcp_get_system_fault_data` |
| `CustomData` | 上位机→设备 | ✓ | ✓ | `tcp_process_custom_data` |
| `FirmwareUpgrade` | 上位机→设备 | ✓ | **✗** | `system_filetransfer_*`（仅 TCP） |

---

## 8. 关键流程

### 8.1 下行（上位机 → 设备）

```
comm_link_receive_data()
  → tcp_rx_buffer_append()
  → tcp_rx_buffer_extract_json()     // 括号匹配；升级期可 skip 前导垃圾
  → tcp_server_process_received_data()
  → tcp_parse_json_message()
  → tcp_process_received_message()
  → system_* 业务
  → tcp_generate_*_json()
  → comm_link_send_data()
```

### 8.2 上行（周期，每 2s）

`tcp_server_send_ctrl()`：

1. 发送 `SystemInfo`
2. BLE 延时 ~120ms / TCP ~20ms
3. 依次发送枪 1、枪 2 的 `GunInfo`（BLE 枪间 ~80ms）

固件升级进行中：**不**做周期上送。

### 8.3 任务主循环

```
v_tcp_ser_task
  ├─ [BLE] ble_link_wait_dip_ready + comm_link_set_type(DIP1)
  ├─ tcp_server_start() → comm_link_start()
  └─ tcp_server_process()
        ├─ comm_link_process()        // BLE 状态机
        ├─ comm_link_accept_client()  // 仅 TCP
        ├─ comm_link_receive_data()
        ├─ tcp_server_process_rx_buffer()
        ├─ system_filetransfer_poll_idle_timeout()
        └─ tcp_server_send_ctrl()
```

---

## 9. 固件升级（FirmwareUpgrade）

**仅 TCP 链路**。JSON + Base64 分包，写外部 Flash 升级区。

| subCommand | 关键字段 |
|---|---|
| `Start` | `fileSize`, `totalPackets`, `packetSize`, `firmwareVersion` |
| `Data` | `packetIndex`, `data`(Base64), `crc` |
| `End` | `status`, `errorMessage` |
| `Response` | `response`(ACK/NAK), `packetIndex` |

实现：`tcp_protocol.c` + `debug_files.c`（原 `system_filetransfer`）。升级时 RX 缓冲扩至 8192B，并可用 `system_filetransfer_get_expected_packet_bytes` 判断 Data JSON 是否收齐。

---

## 10. GunInfo 数据规则

`tcp_get_default_gun_data()`（`system_data.c`）：

1. **空闲 / 仅插枪**（`chargingStatus <= CONNECTED`）：`energy`、`cost`、`batterySOC`、`chargingTime` 置 **0**；`userId`、`orderNumber` 置 **空串**（避免 Flash 残留导致 JSON 过长、BLE 分片异常）。
2. **充电中**：从 `v_meterlog_put_char_log_data` 填实时量；`tcp_copy_log_field()` 安全拷贝用户/订单字段（遇非可打印 ASCII 或 `'\0'` 停止）。
3. **SOC**：限制 0–100。

---

## 11. CustomData / HistoryOperations

### CustomData

| functionField | 行为 |
|---|---|
| `paramInit` | `v_public_param_init()` |
| `reboot` | 应答后 `v_sys_reboot()` |
| `faultInfo` | 当前故障摘要 |

### HistoryOperations

`subCommand=Query`，`historyType=fault`：分页 `queryId` / `startIndex` / `fetchCount`，`content` 格式：  
`location,code,desc,actType,value1,value2`。

---

## 12. 编译开关与运行条件

| 宏 | 默认值 | 说明 |
|---|---|---|
| `TCP_DEBUG_EN` | `1` | 总开关；为 0 时整模块空桩 |
| `BLE_DEBUG_EN` | `1` | 为 0 时不编入 `fc41d_ble.c` 有效代码，恒 TCP |
| `TCP_DEBUG_PORT` | `9699` | TCP 监听端口 |
| `TCP_DEBUG_MAX_CLIENTS` | `1` | 单客户端 |

约束：`BLE_DEBUG_EN` 要求 `TCP_DEBUG_EN=1`（`#error` 保护）。

运行前提：

- **TCP**：lwIP 已初始化、网口可用  
- **BLE**：FC41D 硬件 + UART7；`BSP/GPIO` 中 `FC41D_RST_PORT/PIN`（PE6）  
- **文件操作**：FatFS 已挂载  
- **固件升级**：外部 Flash + IAP  

---

## 13. 维护注意事项

1. **协议与链路分离**：JSON 逻辑只在 `tcp_server` / `tcp_protocol`；换链路只动 `comm_link` 与后端。  
2. **勿改公共 usart**：FC41D 的 UART7 固定 **115200**（`FC41D_UART_BAUD`），阻塞收包在 `fc41d_ble.c` 内 static 实现。  
3. **GunInfo 字符串**：订单/用户字段必须用 `tcp_copy_log_field`，禁止对定长 `U8_T[]` 直接 `%s` / `strcpy`。  
4. **BLE 包长**：单条 GunInfo JSON 宜控制在 GATT 分片友好范围；空闲态勿带长 `orderNumber`。  
5. **Keil**：勿再加入已删除的 `fwbin_protocol.c`、`fwup_protocol.c`、`comm_link*.c`、`tcp_server_socket.c`、`system_filectrl.c`、`system_filetransfer.c`；须包含 `debug_link.c`、`debug_files.c`、`ble_link/fc41d_ble.c`。  
6. **DIP 调试**：无模组时设 `BLE_DEBUG_EN=0` 或 DIP1=0 走 TCP。

---

## 14. 已移除 / 不在树内的文件

以下文件**不在**当前 `app/tcp_ser` 目录，亦**不应**加入 Keil 工程：

| 文件 | 说明 |
|---|---|
| `fwbin_protocol.c/h` | FWBIN 二进制升级（`F0 F9`），已废弃 |
| `fwup_protocol.c` | FWUP 行协议升级，已废弃 |
| `tcp/tcp_socket.c` | 旧路径；Socket 已合并进 `debug_link.c` |
| `comm_link.c` / `comm_link_ctx.c` / `tcp_server_socket.c` | 阶段1 已合并为 `debug_link.c` |
| `system_filectrl.c` / `system_filetransfer.c` | 阶段2 已合并为 `debug_files.c` |
| `comm_link.h` / `comm_link_ctx.h` / `system_filectrl.h` / `system_filetransfer.h` / `tcp/` | 兼容头已删除，统一 `#include "debug_link.h"` / `"debug_files.h"` |
| `_backup_phase1/` / `_backup_phase2/` | 合并过程临时备份，已删除 |

历史方案可参考备份目录 `CCU621_M-蓝牙功能升级失败-退回前保存` 与 `docs/CCU621_M_固件升级十六进制协议_FWUP.md`（**已过时**）。

---

## 关联文档

| 文档 | 说明 |
|---|---|
| [`CCU621_M/README.md`](../../README.md) | 工程主索引 |
| [`TCP_DEBUG_PROTOCOL.md`](TCP_DEBUG_PROTOCOL.md) | JSON 报文字段与示例 |
| [`docs/CCU621_M_蓝牙调试通信方案.md`](../../docs/CCU621_M_蓝牙调试通信方案.md) | 蓝牙联调方案 |
| 本文 | `app/tcp_ser/tcp_ser模块说明.md` |