diff --git a/PLAN.md b/PLAN.md index 22b852d..e7bdbed 100644 --- a/PLAN.md +++ b/PLAN.md @@ -1,6 +1,6 @@ -# RTU_ALL_AI 项目 — 纯 C AI 开发工作计划 +# RTU_ALL_AI 项目 — AI 开发工作计划 -> 版本: v1.1 +> 版本: v2.0 > 日期: 2026-07-07 > 远程仓库: http://127.0.0.1:3000/admin/RTU_ALL_AI.git > 分支策略: master（主分支，所有开发在 master 上直接进行） @@ -9,7 +9,14 @@ ## 一、项目定位 -RTU_ALL_AI 是一个**纯 C 编写的嵌入式通讯装置示例工程**，100% 由 AI 编写。项目采用与 RTU 一致的模块化架构，使用 Linux 内核侵入式链表（`list.h`）作为核心数据结构。工程既是 AI 编程能力的验证，也是后续 RTU 实际模块开发的参考模板。 +RTU_ALL_AI 是一个**C/C++ 混合编程的嵌入式通讯装置工程**，100% 由 AI 编写。项目采用与 RTU 一致的模块化架构。 + +**编程语言策略**： +- **对外接口强制 C 接口**：所有 `.h` 头文件使用 `extern "C"` 包裹，兼容 C/C++ 调用者 +- **内部实现灵活选择**：核心逻辑优先用 C（如链表、协议栈、日志），允许使用 C++ 容器简化复杂业务（如 XML 解析保留 tinyxml2 的 C++ 实现），但代码风格需保持 C 开发者可读 +- **不硬性纯 C**：以功能实现为目的，安全稳定为前提 + +工程既是 AI 编程能力的验证，也是后续 RTU 实际模块开发的参考模板。 --- @@ -19,157 +26,126 @@ RTU_ALL_AI 是一个**纯 C 编写的嵌入式通讯装置示例工程**，100% RTU_ALL_AI/ ├── .gitignore ├── README.md +├── CHANGELOG.md # 开发问题解决记录（每个模块遇到的问题 + 解决方案） +├── COMPLETION.md # 各模块开发完成事项清单 ├── src/ -│ ├── public/ # 公共基础库（对齐 RTU 全部 11 个模块） -│ │ ├── liblist/ # [P0★] Linux 内核侵入式链表（纯C，纯头文件） +│ ├── public/ # 公共基础库（12 个模块） +│ │ ├── liblist/ # [P0★] 侵入式链表（纯C头文件） │ │ │ └── inc/list.h -│ │ ├── libfunc/ # [P0★] 基础工具函数（CRC、校验、文件操作） +│ │ ├── libfunc/ # [P0★] 基础工具（纯C：CRC、校验、文件操作） │ │ │ ├── inc/myFunc.h │ │ │ └── src/myFunc.c -│ │ ├── liblog/ # [P0★] 日志系统（控制台+文件，异步队列） +│ │ ├── liblog/ # [P0★] 日志系统（纯C：异步队列，控制台+文件） │ │ │ ├── inc/myLog.h │ │ │ └── src/myLog.c -│ │ ├── libtask/ # [P1★] 任务调度（定时器、事件循环） +│ │ ├── libtask/ # [P1★] 任务调度（C接口 + C++内部线程/chrono） │ │ │ ├── inc/myTask.h -│ │ │ └── src/myTask.c -│ │ ├── libdatacenter/ # [P1★] 数据中心（信号点 CRUD，侵入式链表） +│ │ │ └── src/myTask.cpp +│ │ ├── libdatacenter/ # [P1★] 数据中心（C接口 + C++内部容器） │ │ │ ├── inc/myDatacenter.h -│ │ │ └── src/myDatacenter.c +│ │ │ └── src/myDatacenter.cpp │ │ ├── libcJSON/ # [P1★] JSON 解析（纯C，cJSON 裁剪版） │ │ │ ├── inc/cJSON.h │ │ │ └── src/cJSON.c -│ │ ├── libxml/ # [P2★] XML 解析（纯C，tinyxml2 裁剪版） -│ │ │ ├── inc/tinyxml2.h -│ │ │ └── src/tinyxml2.c -│ │ ├── libmd5/ # [P1★] MD5 摘要算法 +│ │ ├── libxml/ # [P2★] XML 解析（C接口 + tinyxml2 C++内部） +│ │ │ ├── inc/myXml.h # <- C 接口封装头文件 +│ │ │ └── src/myXml.cpp # <- C++ 内部实现 +│ │ ├── libmd5/ # [P1★] MD5 摘要（纯C） │ │ │ ├── inc/myMd5.h │ │ │ └── src/myMd5.c │ │ ├── libmy_xxhash/ # [P1★] xxHash 快速哈希（纯C） │ │ │ ├── inc/xxhash.h │ │ │ └── src/xxhash.c -│ │ ├── libcomm/ # [P2★] 通讯抽象层（串口/TCP 统一接口） +│ │ ├── libcomm/ # [P2★] 通讯抽象层（C接口 + C++内部） │ │ │ ├── inc/myComm.h -│ │ │ └── src/myComm.c -│ │ ├── libcmd/ # [P2★] 命令处理框架（注册/分发/回传） +│ │ │ └── src/myComm.cpp +│ │ ├── libcmd/ # [P2★] 命令处理（C接口 + C++内部map/queue） │ │ │ ├── inc/myCmd.h -│ │ │ └── src/myCmd.c -│ │ └── libmy_mosquitto/ # [P3○] MQTT 客户端（mosquitto C 封装） +│ │ │ └── src/myCmd.cpp +│ │ └── libmy_mosquitto/ # [P3○] MQTT 客户端（C接口，预留） │ │ ├── inc/myMosquitto.h -│ │ └── src/myMosquitto.c -│ ├── protocol/ # 协议实现层（对齐 RTU 全部 6 个模块） -│ │ ├── libmodbus/ # [P1★] Modbus RTU/TCP 从站协议栈 +│ │ └── src/myMosquitto.cpp +│ ├── protocol/ # 协议实现层（6 个模块） +│ │ ├── libmodbus/ # [P1★] Modbus 协议栈（纯C） │ │ │ ├── inc/myModbus.h │ │ │ └── src/myModbus.c -│ │ ├── lib60870/ # [P2★] IEC 60870-5-101/103/104 协议栈 +│ │ ├── lib60870/ # [P2★] IEC 60870 协议栈（纯C） │ │ │ ├── inc/lib60870_common.h -│ │ │ ├── inc/lib60870_public.h │ │ │ ├── inc/gb101.h / gb103.h / gb104.h │ │ │ └── src/*.c -│ │ ├── libicp67/ # [P2○] ICP67 专有协议 +│ │ ├── libicp67/ # [P2○] ICP67 协议（纯C，预留） │ │ │ ├── inc/icp67.h │ │ │ └── src/icp67.c -│ │ ├── libmms_m/ # [P3○] IEC 61850 MMS 主站（客户端） +│ │ ├── libmms_m/ # [P3○] MMS 主站（C接口 + C++内部，预留） │ │ │ ├── inc/myMms_m.h -│ │ │ └── src/myMms_m.c -│ │ ├── libmms_s/ # [P3○] IEC 61850 MMS 从站（服务端） +│ │ │ └── src/myMms_m.cpp +│ │ ├── libmms_s/ # [P3○] MMS 从站（C接口 + C++内部，预留） │ │ │ ├── inc/myMms_s.h -│ │ │ └── src/myMms_s.c -│ │ └── libmongoose/ # [P3○] 嵌入式 HTTP/WebSocket 服务 +│ │ │ └── src/myMms_s.cpp +│ │ └── libmongoose/ # [P3○] HTTP/WebSocket（纯C，预留） │ │ ├── inc/mongoose.h │ │ └── src/mongoose.c -│ ├── system/ # 系统管理层（对齐 RTU 全部 9 个模块） -│ │ ├── RTU/ # [P2★] 主程序入口（初始化、主循环） +│ ├── system/ # 系统管理层（9 个模块） +│ │ ├── RTU/ # [P2★] 主程序（C/C++ 入口） │ │ │ ├── inc/app_sys.h │ │ │ ├── inc/app_cmd.h │ │ │ └── src/main.c -│ │ ├── libiec/ # [P2★] IEC 规约点表定义与解析 +│ │ ├── libiec/ # [P2★] IEC 点表解析（C接口 + C++内部） │ │ │ ├── inc/iec.h │ │ │ ├── inc/iec_point.h │ │ │ ├── inc/iec_method.h -│ │ │ └── src/iec_cfg_parse.c -│ │ ├── libcom_decode/ # [P2★] 通讯通道解码与分发 +│ │ │ └── src/iec_cfg_parse.cpp +│ │ ├── libcom_decode/ # [P2★] 通讯通道解码（C接口 + C++内部） │ │ │ ├── inc/com_decode.h │ │ │ ├── inc/com_channel_def.h -│ │ │ └── src/com_decode.c -│ │ ├── libmodbus_m/ # [P2★] Modbus 主站管理（轮询/采集） +│ │ │ └── src/com_decode.cpp +│ │ ├── libmodbus_m/ # [P2★] Modbus 主站管理（C接口 + C++内部） │ │ │ ├── inc/modbus_m.h -│ │ │ └── src/modbus_m.c -│ │ ├── libiec61850m/ # [P3○] IEC 61850 MMS 主站管理 +│ │ │ └── src/modbus_m.cpp +│ │ ├── libiec61850m/ # [P3○] 61850 主站管理（预留） │ │ │ ├── inc/iec61850m.h │ │ │ ├── inc/parse_xml.h -│ │ │ └── src/iec61850m.c -│ │ ├── libiec61850s/ # [P3○] IEC 61850 MMS 从站管理 +│ │ │ └── src/iec61850m.cpp +│ │ ├── libiec61850s/ # [P3○] 61850 从站管理（预留） │ │ │ ├── inc/iec61850s.h │ │ │ ├── inc/parse_xml.h -│ │ │ └── src/iec61850s.c -│ │ ├── libplc/ # [P3○] PLC 逻辑引擎 +│ │ │ └── src/iec61850s.cpp +│ │ ├── libplc/ # [P3○] PLC 逻辑引擎（预留） │ │ │ ├── inc/plc.h -│ │ │ └── src/plc.c -│ │ ├── libself_ptl/ # [P3○] 内部自定义协议 +│ │ │ └── src/plc.cpp +│ │ ├── libself_ptl/ # [P3○] 内部自定义协议（预留） │ │ │ ├── inc/self_ptl.h │ │ │ ├── inc/method.h -│ │ │ └── src/self_ptl.c -│ │ └── libweb_server/ # [P2★] Web 管理服务（REST + WebSocket） +│ │ │ └── src/self_ptl.cpp +│ │ └── libweb_server/ # [P2★] Web 管理服务（C接口 + C++内部） │ │ ├── inc/web_server.h │ │ ├── inc/ws_method.h -│ │ └── src/web_server.c -│ └── test/ # 单元测试（每个模块一个 test_xxx.c） -│ ├── test_list.c # [P0★] 链表操作全量测试 -│ ├── test_log.c # [P0★] 日志队列测试 -│ ├── test_datacenter.c # [P1★] 数据中心 CRUD 测试 -│ ├── test_cjson.c # [P1★] JSON 解析测试 -│ ├── test_modbus.c # [P1★] Modbus 协议测试 -│ └── test_60870.c # [P2★] IEC104 协议测试 +│ │ └── src/web_server.cpp +│ └── test/ # 单元测试 +│ ├── test_list.c # [P0★] 链表测试（纯C） +│ ├── test_log.c # [P0★] 日志测试（纯C） +│ ├── test_datacenter.cpp # [P1★] 数据中心测试（C++，调用C接口） +│ ├── test_cjson.c # [P1★] JSON 测试（纯C） +│ ├── test_modbus.c # [P1★] Modbus 测试（纯C） +│ └── test_60870.c # [P2★] IEC104 测试（纯C） └── release/ # 构建系统（与 RTU 结构完全一致） ├── build.sh # 编译脚本（x86 / arm 一键切换） ├── linux.mk # 公共编译选项（CROSS_COMPILE、路径） ├── makefile # 顶层 Makefile（递归 src/） ├── pack_web.sh # Web 资源打包脚本（P3 阶段） ├── inc/ # 对外暴露的公共头文件 - └── src/ # 每个模块的 makefile - ├── makefile # 第二层（递归 public/protocol/system） - ├── public/ - │ ├── makefile # 第三层 - │ ├── liblist/makefile - │ ├── libfunc/makefile - │ ├── liblog/makefile - │ ├── libtask/makefile - │ ├── libdatacenter/makefile - │ ├── libcJSON/makefile - │ ├── libxml/makefile - │ ├── libmd5/makefile - │ ├── libmy_xxhash/makefile - │ ├── libcomm/makefile - │ ├── libcmd/makefile - │ └── libmy_mosquitto/makefile - ├── protocol/ - │ ├── makefile - │ ├── libmodbus/makefile - │ ├── lib60870/makefile - │ ├── libicp67/makefile - │ ├── libmms_m/makefile - │ ├── libmms_s/makefile - │ └── libmongoose/makefile - └── system/ - ├── makefile - ├── RTU/makefile - ├── libiec/makefile - ├── libcom_decode/makefile - ├── libmodbus_m/makefile - ├── libiec61850m/makefile - ├── libiec61850s/makefile - ├── libplc/makefile - ├── libself_ptl/makefile - └── libweb_server/makefile + └── src/ # 每个模块的 makefile（同 RTU 多层结构） ``` -> **图例**: [P0★] 本期实现 | [P2★] 本期实现 | [P3○] 后续扩展（预留目录+stub） +> **图例**: [P0★] 本期实现 | [P1★] 本期实现 | [P2★] 本期实现 | [P3○] 预留（目录+stub） +> **文件后缀**: `.c` = 纯C | `.cpp` = C++（内部可用容器，对外C接口） --- -## 三、代码规范（严格对齐 RTU 风格） +## 三、代码规范 + +### 3.1 命名规范（对齐 RTU 风格） -### 3.1 命名规范 | 类型 | 规范 | 示例 | |------|------|------| | 文件名 | 驼峰/下划线混合 | `myFunc.c`, `myLog.h`, `app_sys.h` | @@ -179,26 +155,36 @@ RTU_ALL_AI/ | 全局变量 | `g_` 前缀 | `g_log_path`, `g_tableCRC16` | | 静态函数 | `LOCAL` 宏修饰 | `LOCAL void helper_func()` | -### 3.2 头文件规范 +### 3.2 C/C++ 混合编程规范 + +**对外头文件模板（强制 C 接口）**： ```c -#ifndef _MY_MODULE_H_ // 全大写+下划线 +#ifndef _MY_MODULE_H_ #define _MY_MODULE_H_ -#include // 系统头文件在前 +#include #ifdef __cplusplus -extern "C" { // 兼容 C++ 调用 +extern "C" { #endif -// 宏定义 -// 结构体 -// 函数声明 +/* 所有对外接口声明放这里 — 纯 C 兼容 */ +int my_module_init(void); +int my_module_do_something(uint32_t id, const char *data); #ifdef __cplusplus } #endif -#endif // _MY_MODULE_H_ +#endif /* _MY_MODULE_H_ */ +``` + +**内部 .cpp 实现模板**： +```cpp +#include "myModule.h" +#include // 内部可用 C++ STL 容器，但保持 C 开发者可读 +#include +// ... C++ 实现代码 ... ``` ### 3.3 注释规范 @@ -228,7 +214,7 @@ extern "C" { // 兼容 C++ 调用 ## 五、分阶段开发计划 -### 阶段 0：基础设施搭建（预计 1-2 天） +### 阶段 0：基础设施搭建 | 序号 | 任务 | 模块 | 产出 | 状态 | |------|------|------|------|------| @@ -237,11 +223,11 @@ extern "C" { // 兼容 C++ 调用 | 0.3 | 实现侵入式链表 | `liblist` | `src/public/liblist/inc/list.h` | ⬜ | | 0.4 | 实现日志系统 | `liblog` | `src/public/liblog/inc/myLog.h`, `src/myLog.c` | ⬜ | | 0.5 | 实现基础工具函数 | `libfunc` | `src/public/libfunc/inc/myFunc.h`, `src/myFunc.c` | ⬜ | -| 0.6 | 创建全部预留模块的目录+stub | 所有 P3 | 26 个模块的 `inc/` + stub `src/` 骨架 | ⬜ | +| 0.6 | 创建全部预留模块的目录+stub | 所有 P3 | 7 个预留模块的目录骨架 + 返回 0 的 stub | ⬜ | | 0.7 | 链表 + 日志单元测试 | — | `src/test/test_list.c`, `test_log.c` | ⬜ | | 0.8 | **编译验证 + 代码审查** | — | 全量编译通过、测试通过 | ⬜ | -### 阶段 1：数据基础设施（预计 2-3 天） +### 阶段 1：数据基础设施 | 序号 | 任务 | 模块 | 产出 | 状态 | |------|------|------|------|------| @@ -249,72 +235,127 @@ extern "C" { // 兼容 C++ 调用 | 1.2 | 实现 xxHash 快速哈希 | `libmy_xxhash` | `src/public/libmy_xxhash/` | ⬜ | | 1.3 | 实现 cJSON 解析 | `libcJSON` | `src/public/libcJSON/`（从 RTU 裁剪） | ⬜ | | 1.4 | 设计信号数据模型 | — | `dc_signal_t` 等结构体设计文档 | ⬜ | -| 1.5 | 实现数据中心 | `libdatacenter` | CRUD 接口，侵入式链表管理信号点 | ⬜ | -| 1.6 | 实现任务调度 | `libtask` | 任务注册、定时触发、事件驱动 | ⬜ | -| 1.7 | 编写单元测试 | — | `test_cjson.c`, `test_datacenter.c` | ⬜ | +| 1.5 | 实现数据中心 | `libdatacenter` | C 接口 CRUD，C++ 内部用 std::map/vector | ⬜ | +| 1.6 | 实现任务调度 | `libtask` | C 接口，C++ 内部 std::thread + std::chrono | ⬜ | +| 1.7 | 编写单元测试 | — | `test_cjson.c`, `test_datacenter.cpp` | ⬜ | | 1.8 | **编译验证 + 代码审查** | — | 全量编译通过、测试通过 | ⬜ | -### 阶段 2：通讯与协议（预计 3-4 天） +### 阶段 2：通讯与协议 | 序号 | 任务 | 模块 | 产出 | 状态 | |------|------|------|------|------| -| 2.1 | 实现通讯抽象层 | `libcomm` | 串口/TCP 统一接口（打开/发送/接收/关闭） | ⬜ | -| 2.2 | 实现命令处理框架 | `libcmd` | 命令注册、分发、回调执行 | ⬜ | -| 2.3 | 实现 XML 解析 | `libxml` | `src/public/libxml/`（tinyxml2 裁剪版） | ⬜ | -| 2.4 | 实现 Modbus 协议栈 | `libmodbus` | RTU/TCP 从站，线圈/寄存器读写 | ⬜ | -| 2.5 | 实现 IEC 60870-5-104 | `lib60870` | 总召、遥测、遥信、遥控、对时 | ⬜ | -| 2.6 | 实现 IEC 点表解析 | `libiec` | `src/system/libiec/`，iec_cfg_parse | ⬜ | -| 2.7 | 实现 Modbus 主站管理 | `libmodbus_m` | 轮询、采集、数据分发 | ⬜ | +| 2.1 | 实现通讯抽象层 | `libcomm` | 串口/TCP 统一 C 接口，内部 C++ 封装 | ⬜ | +| 2.2 | 实现命令处理框架 | `libcmd` | C 接口，内部 std::unordered_map + std::queue | ⬜ | +| 2.3 | 实现 XML 解析 | `libxml` | C 接口（myXml.h），内部 tinyxml2 C++ 实现 | ⬜ | +| 2.4 | 实现 Modbus 协议栈 | `libmodbus` | RTU/TCP 从站，纯C | ⬜ | +| 2.5 | 实现 IEC 60870-5-104 | `lib60870` | 总召、遥测、遥信、遥控，纯C | ⬜ | +| 2.6 | 实现 IEC 点表解析 | `libiec` | `src/system/libiec/` | ⬜ | +| 2.7 | 实现 Modbus 主站管理 | `libmodbus_m` | 轮询队列、采集调度 | ⬜ | | 2.8 | 编写单元测试 | — | `test_modbus.c`, `test_60870.c` | ⬜ | | 2.9 | **编译验证 + 代码审查** | — | 全量编译通过、测试通过 | ⬜ | -### 阶段 3：系统集成（预计 2-3 天） +### 阶段 3：系统集成 | 序号 | 任务 | 模块 | 产出 | 状态 | |------|------|------|------|------| -| 3.1 | 实现通讯通道解码 | `libcom_decode` | 多通道帧解析、分发到各协议栈 | ⬜ | -| 3.2 | 实现 Web 管理服务 | `libweb_server` | REST API + WebSocket 实时推送 | ⬜ | -| 3.3 | 实现主程序入口 | `RTU` | 模块初始化、主循环、信号处理 | ⬜ | -| 3.4 | 端到端集成测试 | — | 多模块联调、协议互通验证 | ⬜ | -| 3.5 | **编译验证 + 代码审查** | — | x86 本地 + ARM 交叉编译全通过 | ⬜ | -| 3.6 | 编写 README 文档 | — | 项目说明、编译指南、模块架构图 | ⬜ | +| 3.1 | 实现通讯通道解码 | `libcom_decode` | 多通道帧解析、协议识别分发 | ⬜ | +| 3.2 | 实现 Web 管理服务 | `libweb_server` | REST API + WebSocket | ⬜ | +| 3.3 | 实现主程序入口 | `RTU` | 模块初始化、主循环 | ⬜ | +| 3.4 | 端到端集成测试 | — | 多模块联调 | ⬜ | +| 3.5 | **编译验证 + 代码审查** | — | x86 + ARM 交叉编译全通过 | ⬜ | +| 3.6 | 编写 README 文档 | — | 编译指南、架构图、使用说明 | ⬜ | ### 阶段 4（后续扩展）：预留模块实现 -| 序号 | 任务 | 模块 | 优先级 | 状态 | -|------|------|------|------|------| -| 4.1 | ICP67 专有协议 | `libicp67` | P3 ○ | ⬜ | -| 4.2 | IEC 61850 MMS 主站 | `libmms_m` + `libiec61850m` | P3 ○ | ⬜ | -| 4.3 | IEC 61850 MMS 从站 | `libmms_s` + `libiec61850s` | P3 ○ | ⬜ | -| 4.4 | 嵌入式 HTTP 服务 | `libmongoose` | P3 ○ | ⬜ | -| 4.5 | MQTT 客户端 | `libmy_mosquitto` | P3 ○ | ⬜ | -| 4.6 | PLC 逻辑引擎 | `libplc` | P3 ○ | ⬜ | -| 4.7 | 内部自定义协议 | `libself_ptl` | P3 ○ | ⬜ | +| 序号 | 任务 | 模块 | 状态 | +|------|------|------|------| +| 4.1 | ICP67 专有协议 | `libicp67` | ⬜ | +| 4.2 | IEC 61850 MMS 主站 | `libmms_m` + `libiec61850m` | ⬜ | +| 4.3 | IEC 61850 MMS 从站 | `libmms_s` + `libiec61850s` | ⬜ | +| 4.4 | 嵌入式 HTTP 服务 | `libmongoose` | ⬜ | +| 4.5 | MQTT 客户端 | `libmy_mosquitto` | ⬜ | +| 4.6 | PLC 逻辑引擎 | `libplc` | ⬜ | +| 4.7 | 内部自定义协议 | `libself_ptl` | ⬜ | --- -## 五、AI 开发工作流 +## 六、单模块开发流程（质量保证） + +每次只开发一个模块，严格按照以下流程执行： ``` -┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ -│ 1. 制定 │───▶│ 2. AI │───▶│ 3. 编译 │───▶│ 4. 代码 │ -│ 计划 │ │ 编码 │ │ 验证 │ │ 审查 │ -└──────────┘ └──────────┘ └──────────┘ └──────────┘ - ▲ │ - └───────────────────────────────────────────────┘ - 5. 修复 + 迭代 +┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ +│ 1. 模块 │───▶│ 2. 设计 │───▶│ 3. AI │───▶│ 4. 编译 │ +│ 启动 │ │ 评审 │ │ 编码 │ │ 验证 │ +└────────────┘ └────────────┘ └────────────┘ └────────────┘ + │ +┌────────────┐ ┌────────────┐ ┌────────────┐ │ +│ 8. 推送 │◀───│ 7. 完成 │◀───│ 6. 代码 │◀──────────┘ +│ 远程 │ │ 事项 │ │ 审查 │ +└────────────┘ └────────────┘ └────────────┘ ``` -### 工作流规则 -1. **计划先行**：每个模块编写前，先输出设计计划（数据结构、API、依赖关系），经审查后再编码 -2. **增量迭代**：每个函数编写后立即编译，消除编译错误再继续 -3. **测试驱动**：先写单元测试框架，再实现功能代码 -4. **审查门禁**：每个模块完成后必须进行代码审查（检查风格、注释、边界处理） -5. **单文件提交**：每个模块或逻辑单元完成后单独 git commit，commit message 使用中文描述 +### 6.1 流程详细说明 + +| 步骤 | 名称 | 动作 | 产出 | +|------|------|------|------| +| 1 | **模块启动** | 选定单一模块，确认依赖已就绪 | 无阻塞启动 | +| 2 | **设计评审** | 输出数据结构、API 签名、依赖关系，人工审查 | 设计文档（可嵌入代码注释） | +| 3 | **AI 编码** | 按计划编写 .h + .c/.cpp + makefile | 可编译源代码 | +| 4 | **编译验证** | `make` 消除所有编译错误/警告 | 编译 0 error 0 warning | +| 5 | **单元测试** | 编写 test_xxx，覆盖正常路径 + 边界条件 | 测试通过 | +| 6 | **代码审查** | 检查风格、注释、边界处理、内存安全 | 审查通过 | +| 7 | **完成事项** | 写入 `COMPLETION.md`：API、已知限制、测试覆盖率 | 完成事项条目 | +| 8 | **推送远程** | `git commit` + `git push` | 远程同步 | + +### 6.2 开发问题解决文档（CHANGELOG.md） + +每个模块开发过程中遇到的问题，记录到 `CHANGELOG.md`，格式如下： + +```markdown +## [模块名] 开发记录 — YYYY-MM-DD + +### 问题 1: [问题简述] +- **现象**: xxx +- **原因**: xxx +- **解决方案**: xxx +- **影响范围**: xxx + +### 问题 2: ... +``` + +### 6.3 开发完成事项（COMPLETION.md） + +每个模块开发完成后，在 `COMPLETION.md` 中添加条目： + +```markdown +## [模块名] — 完成日期: YYYY-MM-DD + +### 基本信息 +- **语言**: C / C++ 混合 / 纯C +- **对外接口**: C 接口（extern "C"） +- **依赖模块**: liblist, liblog +- **被依赖模块**: libdatacenter, libmodbus_m + +### API 清单 +| 函数 | 功能 | 参数 | 返回值 | +|------|------|------|--------| +| xxx_init() | 初始化 | void | 0=成功 | +| xxx_do() | 执行 | id, data | 0=成功 | + +### 已知限制 +- xxx + +### 测试覆盖 +- 正常路径: ✅ +- 边界条件: ✅ +- 错误路径: ✅ +- 内存泄漏: ✅（valgrind 检查通过） +``` --- -## 六、Git 推送规则（对齐 RTU） +## 七、Git 推送规则（对齐 RTU） - **分支**: 所有开发在 `master` 分支 - **Commit 格式**: `[模块名] 功能描述` @@ -325,86 +366,100 @@ extern "C" { // 兼容 C++ 调用 --- -## 七、关键技术点 +## 八、关键技术点 -### 7.1 Linux 内核侵入式链表（list.h） +### 8.1 编程语言分布 + +| 层级 | 纯C 模块 | C接口+C++内部 | 说明 | +|------|---------|--------------|------| +| public/ | liblist, libfunc, liblog, libcJSON, libmd5, libmy_xxhash | libtask, libdatacenter, libxml, libcomm, libcmd | 基础库优先C | +| protocol/ | libmodbus, lib60870, libmongoose | libmms_m, libmms_s, libicp67 | 协议栈优先C | +| system/ | — | RTU, libiec, libcom_decode, libmodbus_m, libweb_server | 管理模块可用C++ | +| test/ | test_list, test_log, test_cjson, test_modbus, test_60870 | test_datacenter | 测试对应实现语言 | + +### 8.2 Linux 内核侵入式链表（list.h） - 使用标准的 `struct list_head` 双向循环链表（`/usr/include/linux/list.h` 精简版） - 实现 `list_add`, `list_add_tail`, `list_del`, `list_del_init`, `list_for_each_entry` 等宏 -- 实现 `list_empty`, `list_entry`, `list_first_entry` 辅助宏 - 所有模块的数据结构使用侵入式链表管理 -### 7.2 编译系统 +### 8.3 编译系统 - 支持 `x86`（本地调试）和 `arm`（RK3568 交叉编译）两种模式 - 每个模块编译为 `.a` 静态库，顶层递归构建 +- `.c` 用 `gcc`，`.cpp` 用 `g++`，makefile 自动识别 - `build.sh x86` 或 `build.sh arm` 一键编译 - 公共头文件统一复制到 `release/inc/` -### 7.3 日志系统 +### 8.4 日志系统 - 支持控制台 + 文件双输出，异步日志队列（侵入式链表实现） - 级别：INFO / ERROR，宏：`LOG_I` / `LOG_E` -- 文件日志支持按大小轮转（`LOG_FILE_MAX_SIZE` / `LOG_FILE_MAX_COUNT`） +- 文件日志支持按大小轮转 -### 7.4 基础公共库（public/） -| 模块 | 来源 | 核心功能 | -|------|------|------| -| `liblist` | Linux 内核 | 侵入式双向循环链表，纯头文件 | -| `libfunc` | 自研 | CRC16/32、校验和、文件操作、环境变量、字节序 | -| `liblog` | 自研 | 异步日志（控制台+文件）、按大小轮转 | -| `libtask` | 自研 | 任务注册/调度、定时器、线程池 | -| `libdatacenter` | 自研 | 信号点 CRUD、侵入式链表索引、xxHash 查找 | -| `libcJSON` | cJSON 裁剪 | JSON 解析/生成，纯 C，无动态内存溢出风险 | -| `libxml` | tinyxml2 裁剪 | XML 解析（用于 IEC 61850 SCL 文件） | -| `libmd5` | RFC 1321 | MD5 摘要，用于文件校验和协议认证 | -| `libmy_xxhash` | xxHash | 极速哈希，用于数据中心信号点快速查找 | -| `libcomm` | 自研 | 串口/TCP 统一抽象（open/send/recv/close） | -| `libcmd` | 自研 | 命令注册表、分发执行、异步回调 | -| `libmy_mosquitto` | mosquitto 封装 | MQTT 客户端，发布/订阅（预留 P3） | +### 8.5 基础公共库（public/） -### 7.5 协议层（protocol/） -| 模块 | 来源 | 核心功能 | -|------|------|------| -| `libmodbus` | libmodbus 裁剪 | Modbus RTU/TCP 从站，01/03/05/06/15/16 功能码 | -| `lib60870` | lib60870 裁剪 | IEC 101/103/104 从站，总召/对时/遥控 | -| `libicp67` | 自研 | ICP67 专有协议（预留 P3） | -| `libmms_m` | libiec61850 封装 | MMS 客户端（预留 P3） | -| `libmms_s` | libiec61850 封装 | MMS 服务端（预留 P3） | -| `libmongoose` | mongoose | 嵌入式 HTTP/WebSocket（预留 P3） | +| 模块 | 语言 | 来源 | 核心功能 | +|------|------|------|------| +| `liblist` | 纯C | Linux 内核 | 侵入式双向循环链表，纯头文件 | +| `libfunc` | 纯C | 自研 | CRC16/32、校验和、文件操作、字节序 | +| `liblog` | 纯C | 自研 | 异步日志（控制台+文件）、轮转 | +| `libtask` | C+C++ | 自研 | 任务调度、定时器、线程池（std::thread） | +| `libdatacenter` | C+C++ | 自研 | 信号点 CRUD、侵入式链表索引、xxHash 查找 | +| `libcJSON` | 纯C | cJSON 裁剪 | JSON 解析/生成 | +| `libxml` | C+C++ | tinyxml2 | XML 解析（C接口封装 + tinyxml2 C++内部） | +| `libmd5` | 纯C | RFC 1321 | MD5 摘要 | +| `libmy_xxhash` | 纯C | xxHash | 极速哈希 | +| `libcomm` | C+C++ | 自研 | 串口/TCP 统一抽象 | +| `libcmd` | C+C++ | 自研 | 命令注册表、分发执行 | +| `libmy_mosquitto` | C+C++ | mosquitto | MQTT 客户端（预留 P3） | -### 7.6 系统管理层（system/） -| 模块 | 来源 | 核心功能 | -|------|------|------| -| `RTU` | 自研 | 主入口：模块初始化、主循环、信号周期处理 | -| `libiec` | 自研 | IEC 规约点表定义、解析、映射到数据中心 | -| `libcom_decode` | 自研 | 通讯通道帧解析、协议识别、分发 | -| `libmodbus_m` | 自研 | Modbus 主站：轮询队列、采集调度 | -| `libiec61850m` | 自研 | 61850 主站管理（预留 P3） | -| `libiec61850s` | 自研 | 61850 从站管理（预留 P3） | -| `libplc` | 自研 | PLC 逻辑引擎（预留 P3） | -| `libself_ptl` | 自研 | 内部自定义协议（预留 P3） | -| `libweb_server` | 自研 | REST API + WebSocket，嵌入式 Web 管理 | +### 8.6 协议层（protocol/） + +| 模块 | 语言 | 来源 | 核心功能 | +|------|------|------|------| +| `libmodbus` | 纯C | libmodbus 裁剪 | Modbus RTU/TCP 从站，01/03/05/06/15/16 功能码 | +| `lib60870` | 纯C | lib60870 裁剪 | IEC 101/103/104 从站，总召/对时/遥控 | +| `libicp67` | — | 预留 P3 | ICP67 专有协议 | +| `libmms_m` | — | 预留 P3 | MMS 客户端 | +| `libmms_s` | — | 预留 P3 | MMS 服务端 | +| `libmongoose` | — | 预留 P3 | 嵌入式 HTTP/WebSocket | + +### 8.7 系统管理层（system/） + +| 模块 | 语言 | 来源 | 核心功能 | +|------|------|------|------| +| `RTU` | C/C++ | 自研 | 主入口：模块初始化、主循环 | +| `libiec` | C+C++ | 自研 | IEC 规约点表定义、解析、数据中心映射 | +| `libcom_decode` | C+C++ | 自研 | 通讯通道帧解析、协议识别、分发 | +| `libmodbus_m` | C+C++ | 自研 | Modbus 主站：轮询队列、采集调度 | +| `libiec61850m` | — | 预留 P3 | 61850 主站管理 | +| `libiec61850s` | — | 预留 P3 | 61850 从站管理 | +| `libplc` | — | 预留 P3 | PLC 逻辑引擎 | +| `libself_ptl` | — | 预留 P3 | 内部自定义协议 | +| `libweb_server` | C+C++ | 自研 | REST API + WebSocket | --- -## 八、风险与对策 +## 九、风险与对策 | 风险 | 对策 | |------|------| -| AI 编码风格不一致 | 严格对照 RTU 已有代码（`myFunc.c`, `myLog.c` 等），代码审查时逐项检查 | -| 侵入式链表使用不当 | 先写完整单元测试，覆盖增删改查、空链表、边界条件 | -| 编译环境差异 | 优先保证 x86 本地编译通过，ARM 交叉编译作为验证步骤 | -| 模块间耦合过重 | 每个模块独立编译为 .a，依赖通过 `release/inc/` 头文件接口明确 | -| cJSON/tinyxml2 安全漏洞 | 裁剪版本，移除不受信输入路径；单元测试覆盖畸形输入 | -| P3 预留模块过度设计 | P3 模块仅创建目录 + 返回 0 的 stub 函数，不实现业务逻辑 | +| AI 编码风格不一致 | 严格对照 RTU 已有代码，代码审查逐项检查 | +| C++ 内部实现过于复杂 | C 开发者需能读懂；避免模板元编程、lambda 嵌套 | +| 侵入式链表使用不当 | 先写完整单元测试，覆盖增删改查、空链表、边界 | +| 编译环境差异 | 优先 x86 本地编译通过，ARM 交叉编译作为验证 | +| 模块间耦合过重 | 每个模块独立 .a，依赖通过 `release/inc/` 接口明确 | +| cJSON/tinyxml2 安全漏洞 | 裁剪版本，单元测试覆盖畸形输入 | +| P3 预留模块过度设计 | P3 仅创建目录 + 返回 0 的 stub 函数 | --- -## 九、审查清单 +## 十、审查清单 -- [ ] 模块列表是否覆盖了 RTU 的全部 26 个模块？ +- [ ] 编程语言策略是否合理（C 接口 + C++ 内部）？ +- [ ] 模块列表是否覆盖了 RTU 全部 27 个模块（12+6+9）？ - [ ] 模块优先级（P0/P1/P2/P3）排序是否合理？ -- [ ] 代码规范是否严格对齐 RTU 风格？ -- [ ] 构建系统方案是否可行（递归 makefile + x86/arm 切换）？ -- [ ] 侵入式链表的实现粒度（宏列表）是否合适？ -- [ ] JSON/XML/MD5/xxHash 裁剪方案是否可行？ -- [ ] P3 预留模块的 stub 策略是否合适？ +- [ ] 单模块开发流程是否清晰可执行？ +- [ ] CHANGELOG.md + COMPLETION.md 格式是否满足质量追溯需求？ +- [ ] 代码规范（命名/注释/头文件模板）是否对齐 RTU？ +- [ ] 构建系统方案是否可行（gcc/g++ 混合编译）？ +- [ ] XML 库 C++ 实现但对外 C 接口的方案是否合理？ - [ ] 是否需要调整模块范围（增/删/改优先级）？