docs: reorganize project documentation

README.md

@@ -0,0 +1,105 @@
+# TCP2UART 项目说明
+
+`TCP2UART` 是一个基于 `STM32F103RCT6 + CH390D` 的 TCP 与双串口透传固件。系统运行在 `FreeRTOS` 上，网络协议栈使用 `lwIP NO_SYS=0 + netconn API`，通过 `SEGGER RTT` 输出调试日志，工程入口为 Keil MDK 项目 `MDK-ARM/TCP2UART.uvprojx`。
+
+本仓库当前文档已经收敛为两类：
+
+1. 面向开发者的代码阅读与系统理解文档。
+2. 面向上位机、测试和联调人员的 AT 命令接口文档。
+
+## 硬件与软件基线
+
+| 项目 | 内容 |
+|------|------|
+| 主控 | `STM32F103RCT6` |
+| 以太网芯片 | `CH390D` |
+| 配置串口 | `USART1` |
+| 数据串口 | `USART2`、`USART3` |
+| RTOS | `FreeRTOS` |
+| TCP/IP | `lwIP`，`NO_SYS=0`，启用 `netconn` API |
+| 调试输出 | `SEGGER RTT` |
+| 构建工程 | `MDK-ARM/TCP2UART.uvprojx` |
+
+`USART1` 只承担 AT 配置面。`USART2/USART3` 是业务数据口，可工作在普通透传模式或 MUX 帧模式。网络侧提供 2 路 TCP Server 实例和 2 路 TCP Client 实例，统一使用 `LINK` 配置模型管理。
+
+## 当前文档地图
+
+| 文档 | 读者 | 内容 |
+|------|------|------|
+| `README.md` | 所有人 | 项目总览、文档入口、快速理解路径 |
+| `项目代码阅读指南.md` | 固件开发、调试、交接人员 | 代码目录、启动流程、任务模型、数据流、阅读顺序、调试线索 |
+| `AT固件使用手册.md` | 上位机、测试、联调人员 | AT 命令、参数模型、默认值、配置流程、常见错误 |
+
+旧的需求说明、技术实现、调试交接、Prompt 和单点问题复盘文档已经合并到上述文档中。临时调试结论不再作为根目录入口，避免把某一轮现场状态误认为长期项目事实。
+
+## 一句话架构
+
+```text
+远端 TCP 连接
+    |
+    v
+TcpSrvTask_S1/S2 或 TcpCliTask_C1/C2
+    |
+    v
+route_msg_t + FreeRTOS Queue
+    |
+    v
+UartRxTask / uart_trans
+    |
+    v
+USART2 / USART3
+```
+
+反向数据流也走同一套路由对象：数据口收到字节后由 `UartRxTask` 判断普通透传或 MUX 帧，再投递到对应 `xLinkTxQueues[]`，最终由 TCP 任务调用 `netconn_write()` 发回网络。
+
+## 快速阅读顺序
+
+首次接手建议按下面顺序阅读：
+
+1. `README.md`：确认硬件、软件、文档入口。
+2. `项目代码阅读指南.md` 的“总体架构”和“业务数据流示例”：先建立整体图。
+3. `Core/Src/main.c`：理解上电初始化顺序。
+4. `Core/Src/freertos.c`：理解队列、信号量和任务创建。
+5. `App/config.c`、`AT固件使用手册.md`：理解配置模型和 AT 命令。
+6. `App/tcp_server.c`、`App/tcp_client.c`、`App/uart_trans.c`、`App/route_msg.c`：理解 TCP 与 UART 如何互相转发。
+7. `App/task_net_poll.c`、`Drivers/CH390/*`、`Drivers/LwIP/src/netif/ethernetif.c`：需要定位网络底层问题时再深入。
+
+## 核心配置模型
+
+固件内部把所有链路抽象为 4 条 `LINK`：
+
+| 角色 | 内部索引 | 端点编码 | 含义 |
+|------|----------|----------|------|
+| `S1` | `CONFIG_LINK_S1` | `0x10` | TCP Server 1 |
+| `S2` | `CONFIG_LINK_S2` | `0x20` | TCP Server 2 |
+| `C1` | `CONFIG_LINK_C1` | `0x01` | TCP Client 1 |
+| `C2` | `CONFIG_LINK_C2` | `0x02` | TCP Client 2 |
+| `UART2` / `U0` | `LINK_UART_U0` | `0x04` | 数据串口 0 |
+| `UART3` / `U1` | `LINK_UART_U1` | `0x08` | 数据串口 1 |
+
+每条 `LINK` 记录包含：启用状态、本地端口、远端 IP、远端端口、绑定的数据串口。外部配置命令见 `AT固件使用手册.md`。
+
+## 常用开发入口
+
+| 目的 | 文件 |
+|------|------|
+| 上电初始化 | `Core/Src/main.c` |
+| 任务和队列创建 | `Core/Src/freertos.c` |
+| AT 命令与 Flash 参数 | `App/config.c`、`App/flash_param.c` |
+| 路由消息池 | `App/route_msg.c` |
+| UART DMA/IDLE、普通透传、MUX 帧 | `App/uart_trans.c` |
+| TCP Server | `App/tcp_server.c` |
+| TCP Client | `App/tcp_client.c` |
+| 网络初始化和轮询 | `App/task_net_poll.c` |
+| CH390 与 lwIP netif | `Drivers/CH390/*`、`Drivers/LwIP/src/netif/ethernetif.c` |
+| RTT 日志封装 | `Core/Src/debug_log.c` |
+
+## 调试提示
+
+1. 启动阶段先看 RTT 中的 `debug_log_boot()` 里程碑，例如 `hal-init`、`clock-config`、`peripherals-ready`、`tasks-created`、`scheduler-start`。
+2. 网络阶段重点看 `NetPollTask` 的 `tcpip-init`、`netif-init`、`netif-ready`、`post-ready free/min heap` 日志。
+3. TCP 或 UART 透传异常时，优先检查 `route_send()` 返回的 `pool`、`queue`、`invalid`，它们能区分消息池耗尽、队列满和参数错误。
+4. HardFault、MemManage、BusFault、UsageFault 会进入 `Debug_TrapWithRttHint()`，应先保留 RTT 现场再修改代码。
+5. `STM32F103RCT6` RAM 余量有限；如果 full-task 模式下问题呈现强资源相关特征，应优先核对堆、栈、水位和 lwIP 池配置，不要只看业务逻辑。
+
+更详细的阅读和调试路线见 `项目代码阅读指南.md`。