4、源码目录规划：主控固件、上位机工具、测试脚本、文档目录的划分与命名规范

智能门锁项目交付时，源码目录的组织方式直接决定了接手工程师、测试人员乃至客户技术团队的第一体验。一个混乱的目录结构会让“找文件”变成一场灾难：固件代码与测试脚本混在一起，上位机工具散落在各个临时文件夹，文档命名随意（如“最终版_v2_改3”），最终导致交付验收时反复沟通、返工甚至信任危机。本章将围绕主控固件、上位机工具、测试脚本、文档四大核心模块，给出可落地的目录划分原则、命名规范以及配套的版本管理策略，帮助你在交付时呈现一份结构清晰、易于维护、符合行业惯例的源码包。

4.1 核心原理：为什么目录规划是交付质量的“第一张名片”

源码目录规划的本质，是对项目知识结构的物理映射。智能门锁项目涉及嵌入式固件（通常基于STM32、ESP32或国产GD32等MCU）、PC端上位机（用于调试、参数配置、OTA升级包制作）、自动化测试脚本（Python或Shell为主）以及大量技术文档（硬件设计说明、通信协议、测试报告、用户手册）。这四类产物的生命周期、使用者、更新频率完全不同：固件由嵌入式工程师维护，上位机由上位机或测试开发工程师维护，测试脚本由测试工程师维护，文档则由全体成员共同维护。如果将它们混放在同一个目录下，或者用“新建文件夹(3)”这样的命名，那么每次版本迭代都会产生大量“孤儿文件”，最终无人能说清哪个是正式版本。

从工程管理角度看，目录规划需要遵循三个核心原则：单一职责（每个目录只承载一类内容）、层级可控（深度不超过4层，避免嵌套过深）、命名自解释（看到目录名就能猜到内容）。此外，还需要考虑版本控制系统的特性——Git或SVN的忽略规则（.gitignore）、子模块（submodule）策略、以及标签（tag）管理，这些都与目录结构紧密相关。例如，固件目录下的build/文件夹应当被Git忽略，而docs/下的PDF报告则可能需要使用Git LFS进行管理。

4.2 判断方法与操作流程：从零搭建标准目录结构

在动手创建目录之前，建议先完成一次“交付物盘点”。以智能门锁项目为例，你需要列出所有将要交付的产物，并按照“类型-用途-使用者”三个维度进行分类。下表是一个典型的盘点结果：

产物类型	典型内容	主要使用者	更新频率
主控固件源码	MCU工程文件、启动代码、外设驱动、业务逻辑（指纹/密码/刷卡/蓝牙）、低功耗管理	嵌入式工程师	高（每次功能迭代）
上位机工具源码	串口调试助手、参数配置工具、OTA固件打包器、产线校准工具	上位机工程师、测试工程师	中（随固件版本更新）
测试脚本	单元测试用例、接口自动化脚本、硬件在环测试脚本、压力测试脚本	测试工程师	高（随需求变更）
文档	需求规格书、硬件设计说明、通信协议文档、测试报告、用户手册、交付清单	全体成员、客户	低（阶段性更新）

基于上述盘点，推荐采用以下标准目录结构（以项目根目录 smart_lock_delivery/ 为例）：

smart_lock_delivery/
├── firmware/                  # 主控固件（MCU）
│   ├── app/                   # 应用层业务逻辑
│   │   ├── unlock/            # 开锁逻辑（指纹/密码/刷卡）
│   │   ├── ble/               # 蓝牙通信模块
│   │   └── low_power/         # 低功耗管理
│   ├── drivers/               # 外设驱动（LCD、触摸、电机、蜂鸣器）
│   ├── bsp/                   # 板级支持包（时钟、GPIO、中断配置）
│   ├── config/                # 板级配置头文件（如 pin_map.h, board.h）
│   ├── build/                 # 编译输出（不纳入版本控制）
│   └── Makefile 或 CMakeLists.txt
├── host_tools/                # 上位机工具（PC端）
│   ├── debugger/              # 串口调试助手（Qt/Python实现）
│   ├── configurator/          # 参数配置工具（读写设备参数）
│   ├── ota_packager/          # OTA固件打包与签名工具
│   └── requirements.txt       # Python依赖（若适用）
├── test_scripts/              # 测试脚本
│   ├── unit/                  # 单元测试（针对固件模块）
│   ├── integration/           # 集成测试（多模块联动）
│   ├── hardware/              # 硬件在环测试（HIL）
│   ├── data/                  # 测试数据（如指纹模板、测试日志）
│   └── conftest.py            # pytest全局配置
├── docs/                      # 文档中心
│   ├── design/                # 设计文档（架构、协议、原理图说明）
│   ├── test_reports/          # 测试报告（按版本归档）
│   ├── user_manual/           # 用户手册（安装、使用、维护）
│   └── delivery_checklist.md  # 交付清单（验收核对表）
├── .gitignore                 # Git忽略规则
├── README.md                  # 项目总览（如何构建、测试、烧录）
└── CHANGELOG.md               # 版本变更记录

操作流程建议如下：第一步，在项目启动初期就创建上述骨架，而不是在交付前临时整理；第二步，在 .gitignore 中明确忽略 build/、*.o、*.bin、__pycache__/ 等中间产物；第三步，在 README.md 中写明每个目录的用途和构建命令；第四步，每次提交代码时，确保文件放入正确的目录，而不是“先提交，以后再移动”。

4.3 命名规范：让文件名“会说话”

目录结构确定后，文件命名规范同样重要。智能门锁项目中的命名规范应覆盖固件源文件、上位机脚本、测试用例和文档四类。以下是一套经过实践检验的命名规则：

• 固件源文件：使用小写字母+下划线，模块名在前，功能在后。例如 ble_controller.c、motor_driver.c。头文件使用相同的命名规则，如 ble_controller.h。避免使用“v1”、“final”等后缀，版本信息交给Git管理。
• 上位机工具：使用驼峰命名法（CamelCase），工具名+版本号。例如 LockDebugger_v2.1.py、OtaPackager_v1.0.exe。如果使用Python，建议遵循PEP8规范，模块名使用小写字母，类名使用驼峰。
• 测试脚本：使用“test_”前缀+被测模块名。例如 test_ble_connection.py、test_fingerprint_unlock.py。测试数据文件使用“data_”前缀，如 data_fp_templates.csv。
• 文档：使用“文档类型_项目_版本”的格式。例如 设计文档_智能门锁_v1.2.pdf、测试报告_指纹模块_v2.0.pdf。日期可以放在版本号之后，如 测试报告_指纹模块_v2.0_20250115.pdf。

4.4 案例拆解：某型号智能锁交付时的目录重构实战

2024年，某智能锁ODM厂商在向客户交付一款全自动智能锁（支持指纹、密码、NFC、蓝牙开锁）时，遇到了典型的目录混乱问题。初始交付包结构如下：

交付包_最终版/
├── 主控程序/
│   ├── 新建文件夹(1)/  # 实际是STM32工程
│   ├── 最终代码.c
│   └── 备份_老版本/
├── 电脑工具/
│   ├── 调试助手.exe
│   └── 配置工具_改3.exe
├── 测试/
│   ├── 测试报告.docx
│   └── 自动化脚本.py
└── 说明文档.txt

客户在验收时，无法确认“最终代码.c”是否与“调试助手.exe”版本匹配，也无法定位到对应的测试报告。项目被迫延期一周进行整理。复盘后，团队按照本章标准进行了重构：

1. 盘点与分类：将所有文件按固件、上位机、测试、文档四类归档，删除“备份_老版本”等冗余文件夹（Git历史中已有记录）。
2. 建立标准骨架：创建 firmware/、host_tools/、test_scripts/、docs/ 四个顶层目录，并按照4.2节的模板细化子目录。
3. 重命名文件：将“最终代码.c”重命名为 main.c 并放入 firmware/app/；将“调试助手.exe”重命名为 LockDebugger_v2.1.exe 放入 host_tools/debugger/；将“自动化脚本.py”拆分为 test_ble.py、test_fingerprint.py 等，放入 test_scripts/integration/。
4. 补充缺失文档：编写 README.md 说明构建和烧录步骤，编写 CHANGELOG.md 记录版本变更，生成 delivery_checklist.md 供客户逐项验收。
5. 验证与提交：在干净的Linux环境中，按照README步骤从零构建固件，运行全部测试脚本，确认通过后打上Git标签 v1.0.0。

重构后的交付包，客户工程师仅用半天时间就完成了环境搭建和初步验证，比预期快了2天。更重要的是，后续的固件升级（v1.1.0）和新增测试用例（如NFC开锁测试）都能快速定位到对应目录，团队协作效率显著提升。

4.5 常见误区与总结复盘

在指导多个智能门锁项目交付后，我总结了以下高频误区，供你对照自查：

• 误区一：忽略构建产物与源码的分离。将 .o、.hex、.bin 等编译产物直接放在源码目录中，导致Git仓库迅速膨胀，且容易误提交。正确做法是使用 build/ 目录并在 .gitignore 中忽略。
• 误区二：文档与代码版本脱节。测试报告、设计文档没有与对应的代码版本关联。建议在文档文件名中嵌入版本号，并在Git提交信息中引用文档路径。
• 误区三：测试脚本依赖路径。脚本中写死 C:\Users\xxx\Desktop\... 这样的路径，换一台电脑就无法运行。应使用相对路径或通过环境变量配置。
• 误区四：忽略“交付清单”的作用。没有 delivery_checklist.md，客户不知道应该检查哪些内容，容易遗漏关键项（如固件版本号、测试报告覆盖范围）。

总结复盘：源码目录规划是智能门锁项目交付的“地基工程”。本章给出的四层结构（firmware、host_tools、test_scripts、docs）并非唯一答案，但提供了一个经过验证的起点。核心要点可以归纳为：按类型划分、按模块组织、按规范命名、按版本管理。在实际操作中，建议在项目启动的第一天就建立目录骨架，并在每次代码评审时检查目录结构是否被破坏。记住，一个整洁的目录结构，不仅是为了交付给客户看，更是为了让你自己的团队在三个月后还能高效地维护这套代码。