Add initial board, HAL, and executor modules

main/MODULE_DEVELOPMENT_GUIDE.md

@@ -0,0 +1,124 @@
+# Sweekar-ESP32 模块化开发与构建系统指南
+
+为了支持多人无冲突协作，并保持系统代码的高内聚、低耦合，Sweekar-ESP32 的 CMake 构建系统采用 **“透明化脚手架 (Transparent Scaffolding) + Kconfig 自动组装”** 架构。
+
+在这套架构下，开发者在添加新的底层硬件驱动、业务服务或测试代码时，**完全不需要修改任何顶层文件（包括 `main/CMakeLists.txt` 和 `main/Kconfig.projbuild`）**，构建系统会自动帮你生成必要的模板文件，而后续的修改则完全交由你掌控，没有任何“黑魔法”。
+
+以下是添加新模块的标准流程和机制说明。
+
+---
+
+## 1. 确定模块归属的目录分类
+系统顶层会自动扫描以下目录下的子文件夹：
+- `04_hal/` : 硬件抽象层代码（如 Codec 驱动、马达驱动等）
+- `05_executors/` : 执行器组件（如 AudioPlayer, Display, 传感器读取等）
+- `05_service/` : 后台服务组件（如 AI RTC、QCloud、WiFi 连接等）
+- `06_behaviors/` : 行为逻辑组件
+- `tests/` : 各种测试模块（如麦克风测试、扬声器测试等）
+- `sweekar_demos/` : 各种组装好的 Demo 入口
+
+*假设我们要添加一个专门测试麦克风的模块，名为 `test_mic`，它显然应该归属于 `tests/` 目录。*
+
+## 2. 新建模块与文件 (自动化部分)
+在对应的分类下新建文件夹，并将你的源码和头文件放进去：
+```bash
+mkdir -p main/tests/test_mic
+touch main/tests/test_mic/test_mic.cc
+touch main/tests/test_mic/test_mic.h
+```
+
+**【核心自动化机制】**
+此时，你**不需要**手动去写 CMake 文件。你只需要在终端执行一次：
+```bash
+idf.py reconfigure
+```
+（或者 `idf.py build` 如果这是你第一次编译该工程）。
+
+构建系统中的 Python 脚本 (`generate_kconfig_modules.py`) 会在配置阶段自动扫描目录。当它发现 `tests/test_mic` 目录下有源码但**没有** `module.cmake` 时，它会**自动为你生成一个 `module.cmake` 脚手架文件**。
+
+自动生成的文件内容类似于：
+```cmake
+# main/tests/test_mic/module.cmake
+# 自动生成的模块脚手架，可直接手工修改。
+# 如果后续添加了新文件，可以手工在此处添加，或者删除本文件让脚本重新生成。
+
+if(NOT CONFIG_ENABLE_TEST_TEST_MIC AND NOT EARLY_EXPANSION)
+    message(STATUS "  [Skip] test_mic module disabled by menuconfig.")
+    return()
+endif()
+
+list(APPEND MODULE_SRCS
+    "tests/test_mic/test_mic.cc"
+)
+
+list(APPEND MODULE_INCLUDE_DIRS
+    "tests/test_mic"
+)
+
+# 需要公开依赖时，在这里手工补充。例如：
+# list(APPEND MODULE_REQUIRES
+#     esp_timer
+#     driver
+# )
+```
+
+## 3. 后续维护与修改 (手工部分)
+
+**“透明化”原则**：一旦 `module.cmake` 被生成，Python 脚本就**再也不会覆盖或修改它**。它现在完全属于你。
+
+### 3.1 当你新增/删除源文件时
+你有两种选择：
+1. **手动修改（推荐）**：直接打开 `module.cmake`，在 `list(APPEND MODULE_SRCS ...)` 中手动添加或删除文件路径。所见即所得，非常直观。
+2. **重新生成（偷懒大法）**：如果你一口气加了十几个文件，不想手写路径，你可以**直接删除**这个 `module.cmake` 文件，然后运行 `idf.py reconfigure`，脚本会重新帮你扫描并生成一份包含所有最新文件的脚手架。
+
+### 3.2 当你需要依赖其他库时
+直接在 `module.cmake` 底部，取消注释并填入你需要的 ESP-IDF 组件名（如 `esp_adc`, `audio_pipeline` 等）：
+```cmake
+list(APPEND MODULE_REQUIRES
+    audio_pipeline
+    driver
+)
+```
+
+## 4. 编写模块内部的 `Kconfig` (可选)
+系统会自动为你的模块生成一个默认的配置开关（例如 `CONFIG_ENABLE_TEST_TEST_MIC`）。
+- `tests/` 目录下的默认开关为关闭(`default n`)。
+- 其他目录默认开启(`default y`)。
+
+如果你需要为你的模块定义更复杂的配置选项（比如定义默认开启、依赖其他模块、或者包含子菜单），你可以在模块目录（`main/tests/test_mic/`）下建立一个名为 `Kconfig` 的文件：
+
+```kconfig
+# main/tests/test_mic/Kconfig
+config ENABLE_TEST_MIC
+    bool "Enable Microphone Test Module"
+    default n
+    help
+        Enable this to compile the microphone testing routines.
+```
+> 系统如果扫描到模块自带 `Kconfig`，就会使用你写的，而不再自动生成默认开关。
+
+## 5. 编译与配置
+1. 运行 `idf.py menuconfig`。
+2. 导航到 `Sweekar Subsystems Configuration` -> 对应的目录（如 `Tests Modules`）。
+3. 找到你刚刚添加的 `Enable test_mic`（或你自己定义的开关名字），按空格键勾选 `[*]`。
+4. 保存退出后，运行 `idf.py build` 即可！
+
+---
+
+## ⚠️ 常见问题与注意事项
+
+### Q: 为什么我新建了一个文件夹或者删除了 `module.cmake`，运行 `idf.py build` 没有反应？
+这是 CMake 的缓存机制导致的。如果你只是增删了目录或文件，但没有修改任何现有的 `CMakeLists.txt` 内容，CMake 会跳过配置阶段直接去编译，导致 Python 扫描脚本没有运行。
+**解决办法**：遇到这种情况，请明确告诉 IDF 重新配置：
+```bash
+idf.py reconfigure
+```
+然后再运行 `idf.py build`。
+
+### Q: 为什么要加 `NOT EARLY_EXPANSION`？
+ESP-IDF 的构建系统分为两步：
+1. **依赖解析阶段 (Early Expansion)**：此时 CMake 快速扫描所有组件收集 `REQUIRES`，但此时 `menuconfig` 的配置尚未加载，所有的 `CONFIG_xxx` 都是空值！
+2. **实际构建阶段 (Build Pass)**：此时配置加载完毕，开始真实编译。
+
+如果在 `module.cmake` 顶部仅仅写 `if(NOT CONFIG_ENABLE_XXX) return()`，会导致在依赖解析阶段该模块就被错误地跳过了，从而丢失其依赖声明，引发“找不到头文件”的编译灾难。
+加入 `AND NOT EARLY_EXPANSION` 后，能保证所有启用的组件依赖都被正确收集到构建树中，实现完美解耦。