diff --git a/PLAN.md b/PLAN.md new file mode 100644 index 0000000..7562ace --- /dev/null +++ b/PLAN.md @@ -0,0 +1,241 @@ +# RTU_ALL_AI 项目 — 纯 C AI 开发工作计划 + +> 版本: v1.0 +> 日期: 2026-07-07 +> 远程仓库: http://127.0.0.1:3000/admin/RTU_ALL_AI.git +> 分支策略: master（主分支，所有开发在 master 上直接进行） + +--- + +## 一、项目定位 + +RTU_ALL_AI 是一个**纯 C 编写的嵌入式通讯装置示例工程**，100% 由 AI 编写。项目采用与 RTU 一致的模块化架构，使用 Linux 内核侵入式链表（`list.h`）作为核心数据结构。工程既是 AI 编程能力的验证，也是后续 RTU 实际模块开发的参考模板。 + +--- + +## 二、项目架构（对齐 RTU 结构） + +``` +RTU_ALL_AI/ +├── .gitignore +├── README.md +├── src/ +│ ├── public/ # 公共基础库 +│ │ ├── liblist/ # [P0] Linux 内核侵入式链表 +│ │ │ ├── inc/list.h +│ │ │ └── src/（纯头文件实现，无需 .c） +│ │ ├── libfunc/ # [P0] 基础工具函数库 +│ │ │ ├── inc/myFunc.h +│ │ │ └── src/myFunc.c +│ │ ├── liblog/ # [P0] 日志库 +│ │ │ ├── inc/myLog.h +│ │ │ └── src/myLog.c +│ │ ├── libtask/ # [P1] 任务调度库 +│ │ │ ├── inc/myTask.h +│ │ │ └── src/myTask.c +│ │ ├── libdatacenter/ # [P1] 数据中心（信号存储） +│ │ │ ├── inc/myDatacenter.h +│ │ │ └── src/myDatacenter.c +│ │ └── libcomm/ # [P2] 通讯抽象层 +│ │ ├── inc/myComm.h +│ │ └── src/myComm.c +│ ├── protocol/ # 协议实现层 +│ │ ├── libmodbus/ # [P1] Modbus RTU/TCP 协议站 +│ │ │ ├── inc/myModbus.h +│ │ │ └── src/myModbus.c +│ │ └── lib60870/ # [P2] IEC 60870-5-104 协议站 +│ │ ├── inc/my104.h +│ │ └── src/my104.c +│ ├── system/ # 系统管理层 +│ │ ├── RTU/ # [P2] 主程序入口 +│ │ │ ├── inc/app_sys.h +│ │ │ └── src/main.c +│ │ └── libweb_server/ # [P3] Web 管理界面 +│ │ ├── inc/web_server.h +│ │ └── src/web_server.c +│ └── test/ # 单元测试 +│ ├── test_list.c # [P0] 链表单元测试 +│ ├── test_datacenter.c # [P1] 数据中心单元测试 +│ └── test_modbus.c # [P1] Modbus 单元测试 +└── release/ # 构建系统 + ├── build.sh # 编译脚本 + ├── linux.mk # 编译选项（支持 x86/arm 切换） + ├── makefile # 顶层 Makefile（递归） + ├── inc/ # 对外暴露的公共头文件（软链接/复制） + └── src/ # 每个模块的 makefile + ├── makefile # 第二层 + ├── public/ + │ ├── libfunc/makefile + │ ├── liblog/makefile + │ └── ... + ├── protocol/ + └── system/ +``` + +--- + +## 三、代码规范（严格对齐 RTU 风格） + +### 3.1 命名规范 +| 类型 | 规范 | 示例 | +|------|------|------| +| 文件名 | 驼峰/下划线混合 | `myFunc.c`, `myLog.h`, `app_sys.h` | +| 函数名 | 小写+下划线 | `func_cal_crc16()`, `dc_signal_set()` | +| 结构体 | 小写+`_t` 后缀 | `log_message_t`, `dc_signal_t` | +| 宏/常量 | 全大写+下划线 | `LOG_LEVEL_INFO`, `SHORT_STR_LEN` | +| 全局变量 | `g_` 前缀 | `g_log_path`, `g_tableCRC16` | +| 静态函数 | `LOCAL` 宏修饰 | `LOCAL void helper_func()` | + +### 3.2 头文件规范 +```c +#ifndef _MY_MODULE_H_ // 全大写+下划线 +#define _MY_MODULE_H_ + +#include // 系统头文件在前 + +#ifdef __cplusplus +extern "C" { // 兼容 C++ 调用 +#endif + +// 宏定义 +// 结构体 +// 函数声明 + +#ifdef __cplusplus +} +#endif + +#endif // _MY_MODULE_H_ +``` + +### 3.3 注释规范 +- 函数头部：`/** 功能简述 */` 或 `// 功能描述` +- 复杂逻辑：行间注释 `// 步骤1: xxx` +- 段落分隔：`/******...******/` 分隔不同功能区域 + +### 3.4 编码规范 +- 缩进：Tab（4 空格宽度） +- 所有函数入口参数必须校验（NULL、越界检查） +- 函数行数控制在 80 行以内 +- 复杂逻辑拆分为独立静态函数 +- 错误路径必须打 LOG_E + +--- + +## 四、分阶段开发计划 + +### 阶段 0：基础设施搭建（预计 1-2 天） + +| 序号 | 任务 | 产出 | 状态 | +|------|------|------|------| +| 0.1 | 搭建构建系统 | `release/linux.mk`, `release/makefile`, `release/build.sh` | ⬜ | +| 0.2 | 创建 `myBase.h` 基础定义 | `release/inc/myBase.h` | ⬜ | +| 0.3 | 实现 `liblist` 侵入式链表 | `src/public/liblist/inc/list.h` | ⬜ | +| 0.4 | 实现 `liblog` 日志库 | `src/public/liblog/` | ⬜ | +| 0.5 | 实现 `libfunc` 基础工具 | `src/public/libfunc/` | ⬜ | +| 0.6 | 编写链表单元测试 | `src/test/test_list.c` | ⬜ | +| 0.7 | **编译验证 + 代码审查** | 全量编译通过、测试通过 | ⬜ | + +### 阶段 1：数据中心 + 任务调度（预计 2-3 天） + +| 序号 | 任务 | 产出 | 状态 | +|------|------|------|------| +| 1.1 | 设计信号数据模型 | 设计文档 + `dc_signal_t` 结构体 | ⬜ | +| 1.2 | 实现 `libdatacenter` 信号存储 | CRUD 接口，侵入式链表管理 | ⬜ | +| 1.3 | 实现 `libtask` 任务调度 | 任务注册、定时触发、事件驱动 | ⬜ | +| 1.4 | 编写数据中心单元测试 | `src/test/test_datacenter.c` | ⬜ | +| 1.5 | **编译验证 + 代码审查** | 全量编译通过、测试通过 | ⬜ | + +### 阶段 2：通讯协议（预计 3-4 天） + +| 序号 | 任务 | 产出 | 状态 | +|------|------|------|------| +| 2.1 | 实现 `libcomm` 通讯抽象层 | 串口/TCP 统一接口 | ⬜ | +| 2.2 | 实现 `libmodbus` Modbus 从站 | RTU/TCP 模式，线圈/寄存器读写 | ⬜ | +| 2.3 | 编写 Modbus 单元测试 | `src/test/test_modbus.c` | ⬜ | +| 2.4 | 实现 `lib60870` IEC104 从站 | 总召、遥测、遥信、遥控 | ⬜ | +| 2.5 | **编译验证 + 代码审查** | 全量编译通过、测试通过 | ⬜ | + +### 阶段 3：系统集成（预计 2-3 天） + +| 序号 | 任务 | 产出 | 状态 | +|------|------|------|------| +| 3.1 | 实现 `RTU/main.c` 主程序 | 模块初始化、主循环 | ⬜ | +| 3.2 | 实现 Web 服务器（可选） | `libweb_server` | ⬜ | +| 3.3 | 端到端集成测试 | 多模块联调 | ⬜ | +| 3.4 | **全量编译验证 + 代码审查** | 交叉编译（ARM）、单元测试 | ⬜ | +| 3.5 | 编写 README 文档 | 项目说明、编译指南、架构图 | ⬜ | + +--- + +## 五、AI 开发工作流 + +``` +┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ +│ 1. 制定 │───▶│ 2. AI │───▶│ 3. 编译 │───▶│ 4. 代码 │ +│ 计划 │ │ 编码 │ │ 验证 │ │ 审查 │ +└──────────┘ └──────────┘ └──────────┘ └──────────┘ + ▲ │ + └───────────────────────────────────────────────┘ + 5. 修复 + 迭代 +``` + +### 工作流规则 +1. **计划先行**：每个模块编写前，先输出设计计划（数据结构、API、依赖关系），经审查后再编码 +2. **增量迭代**：每个函数编写后立即编译，消除编译错误再继续 +3. **测试驱动**：先写单元测试框架，再实现功能代码 +4. **审查门禁**：每个模块完成后必须进行代码审查（检查风格、注释、边界处理） +5. **单文件提交**：每个模块或逻辑单元完成后单独 git commit，commit message 使用中文描述 + +--- + +## 六、Git 推送规则（对齐 RTU） + +- **分支**: 所有开发在 `master` 分支 +- **Commit 格式**: `[模块名] 功能描述` + - 例: `[liblist] 实现 Linux 内核侵入式双向链表` + - 例: `[libdatacenter] 添加信号点 CRUD 接口` +- **推送频率**: 每个模块完成后推送一次 +- **远程**: `origin` → `http://admin:admin123@127.0.0.1:3000/admin/RTU_ALL_AI.git` + +--- + +## 七、关键技术点 + +### 7.1 Linux 内核侵入式链表（list.h） +- 使用标准的 `struct list_head` 双向循环链表 +- 实现 `list_add`, `list_add_tail`, `list_del`, `list_for_each_entry` 等宏 +- 所有模块的数据结构使用侵入式链表管理 + +### 7.2 编译系统 +- 支持 `x86`（本地调试）和 `arm`（RK3568 交叉编译）两种模式 +- 每个模块编译为 `.a` 静态库 +- 顶层 makefile 递归构建 +- `build.sh x86` 或 `build.sh arm` 一键编译 + +### 7.3 日志系统 +- 支持控制台 + 文件双输出 +- 异步日志队列（侵入式链表实现） +- 级别：INFO / ERROR + +--- + +## 八、风险与对策 + +| 风险 | 对策 | +|------|------| +| AI 编码风格不一致 | 严格对照 RTU 已有代码，代码审查时逐项检查 | +| 侵入式链表使用不当 | 先写完整单元测试，验证所有链表操作 | +| 编译环境差异 | 优先保证 x86 本地编译通过，ARM 交叉编译作为验证步骤 | +| 模块间耦合过重 | 每个模块独立编译为 .a，依赖通过头文件接口明确 | + +--- + +## 九、审查清单 + +- [ ] 计划是否覆盖所有必要的模块？ +- [ ] 代码规范是否对齐 RTU 风格？ +- [ ] 模块优先级排序是否合理？ +- [ ] 是否需要调整模块范围（增/删/改）？ +- [ ] 构建系统方案是否可行？ +- [ ] 侵入式链表的实现粒度是否合适？