Praxis Software Structure Model

模块边界：firmware

解释 firmware 的包/模块边界、文件数量、符号数量和跨模块依赖。

Package Diagrams candidate / high 0.1.0 · 34aad0bffa2f / main

图的读法

技术复杂度分析

与业务复杂度的关联

治理建议

UML / 技术图

flowchart LR
  package_node["firmware"]
  dependency_1["boards"]
  package_node --> dependency_1
  dependency_2["apps/esp32_lvgl"]
  package_node --> dependency_2
  dependency_3["apps/linux_uconsole_gtk"]
  package_node --> dependency_3

覆盖范围

图内语义元素下钻

  1. firmware package

    firmware 是当前 Package Diagram 的中心工程边界，用来观察它自身规模、依赖方向和可下钻技术复杂度。

    技术角色
    技术组织边界：它把 firmware 下的文件、符号和跨模块关系聚合成一个可讨论的工程单元。
    为什么出现
    本地仓库证据在 firmware 下观察到足够文件、符号或跨模块关系，因此它值得被提升为软件结构模型中的 package 级入口。
    关系意义
    图中从 firmware 指向其它节点的箭头表示当前边界依赖外部 package/module；被其他模块依赖或调用 68 次、依赖或调用外部模块 23 次，用于判断它更像稳定复用边界还是编排/桥接边界。
    下钻意图
    下钻该节点可以继续查看 firmware 内的关键组件、结构协作切片、运行链路、部署节点和复杂度热点，从而理解这个工程边界如何承载功能变化。
    业务关联
    该节点不是业务故事本身，但组织/过程模型中落到 firmware 的 Use Case 可以把这里作为技术承载边界引用。当前关联仍是 CANDIDATE。
    变更影响
    修改 firmware 的公共入口、依赖方向或目录边界，可能影响引用它的组件图、sequence 片段、部署配置和相关业务故事的验证路径。
    置信度
    high

    证据

    • package scope: firmware
    • 模块路径：firmware
    • 文件数：33
    • 符号数：376
    • 被其他模块依赖或调用：68
    • 依赖或调用外部模块：23
    • firmware/c6_companion/CMakeLists.txt
    • firmware/c6_companion/components/tm_ble/CMakeLists.txt

    风险

    • 如果只把该节点当作目录名，会遗漏它作为稳定工程边界的职责判断。
    • 如果依赖外部模块的迹象持续增加，可能说明该边界承担过多编排或桥接职责。

    问题

    • 当前仓库证据尚未把该 package 明确 Trace 到某个 Use Case；因此业务关联保持候选。
  2. boards package

    boards 是 firmware 当前观察到的外部技术边界依赖；它说明当前模块不是孤立实现，而是需要借助另一组工程能力完成职责。

    技术角色
    跨模块技术依赖边界：当前 package 需要另一个 package/module 提供能力、契约、配置或运行支撑。
    为什么出现
    本地仓库证据在 firmware 与 boards 之间观察到跨模块事实关系，因此该依赖被放入 Package Diagram，而不是只藏在代码 import/call 里。
    关系意义
    firmware -> boards 表示本地仓库证据观察到跨模块关系；它解释技术依赖方向，但不直接证明业务流程。
    下钻意图
    下钻 boards 可以查看它自己的 Package Diagram，再继续进入其组件、结构、sequence 或热点，判断当前依赖究竟落在入口、运行时、工具注册、模型适配还是基础设施边界。
    业务关联
    firmware 如果承载用户可见能力，那么对 boards 的依赖可能是该能力的运行机制、扩展点或治理约束。该业务关联需要由组织/过程模型的 Use Case 证据确认。
    变更影响
    修改 boards 的公共接口、路径或运行方式，可能让 firmware 的调用链、打包入口、agent 工作流或 UI 行为发生连锁变化。
    置信度
    high

    证据

    • dependency edge: firmware -> boards
    • boards/cardputerzero/board_facts.h
    • boards/cardputerzero/BOARD.md
    • boards/gat562_mesh_evb_pro.json
    • boards/gat562_mesh_evb_pro/board_facts.h
    • boards/gat562_mesh_evb_pro/BOARD.md
    • boards/gat562_mesh_evb_pro/include/boards/gat562_mesh_evb_pro/board_profile.h
    • boards/gat562_mesh_evb_pro/include/boards/gat562_mesh_evb_pro/gat562_board.h

    风险

    • 跨模块依赖只能证明技术关系，不能直接证明业务关系。
    • 如果该依赖只是因为实现方便而存在，未来变更可能形成边界漂移或隐式公共工具箱。

    问题

    • 当前证据尚未证明 firmware 依赖 boards 与某个 Use Case、runtime command 或配置决策直接相关。
    • 当前依赖方向按仓库事实记录为候选，尚未发现架构决策文档证明它是稳定边界。
  3. apps/esp32_lvgl package

    apps/esp32_lvgl 是 firmware 当前观察到的外部技术边界依赖；它说明当前模块不是孤立实现，而是需要借助另一组工程能力完成职责。

    技术角色
    跨模块技术依赖边界：当前 package 需要另一个 package/module 提供能力、契约、配置或运行支撑。
    为什么出现
    本地仓库证据在 firmware 与 apps/esp32_lvgl 之间观察到跨模块事实关系，因此该依赖被放入 Package Diagram，而不是只藏在代码 import/call 里。
    关系意义
    firmware -> apps/esp32_lvgl 表示本地仓库证据观察到跨模块关系；它解释技术依赖方向，但不直接证明业务流程。
    下钻意图
    下钻 apps/esp32_lvgl 可以查看它自己的 Package Diagram，再继续进入其组件、结构、sequence 或热点，判断当前依赖究竟落在入口、运行时、工具注册、模型适配还是基础设施边界。
    业务关联
    firmware 如果承载用户可见能力，那么对 apps/esp32_lvgl 的依赖可能是该能力的运行机制、扩展点或治理约束。该业务关联需要由组织/过程模型的 Use Case 证据确认。
    变更影响
    修改 apps/esp32_lvgl 的公共接口、路径或运行方式，可能让 firmware 的调用链、打包入口、agent 工作流或 UI 行为发生连锁变化。
    置信度
    high

    证据

    • dependency edge: firmware -> apps/esp32_lvgl
    • apps/esp32_lvgl/APP_SHELL_MANIFEST.md
    • apps/esp32_lvgl/CMakeLists.txt
    • apps/esp32_lvgl/library.json
    • apps/esp32_lvgl/README.md
    • apps/esp32_lvgl/src/esp32_lvgl_app_shell.cpp
    • apps/esp32_lvgl/src/esp32_lvgl_app_shell.h
    • apps/esp32_lvgl/src/esp32_lvgl_arduino_app_registry.cpp

    风险

    • 跨模块依赖只能证明技术关系，不能直接证明业务关系。
    • 如果该依赖只是因为实现方便而存在，未来变更可能形成边界漂移或隐式公共工具箱。

    问题

    • 当前证据尚未证明 firmware 依赖 apps/esp32_lvgl 与某个 Use Case、runtime command 或配置决策直接相关。
    • 当前依赖方向按仓库事实记录为候选，尚未发现架构决策文档证明它是稳定边界。
  4. apps/linux_uconsole_gtk package

    apps/linux_uconsole_gtk 是 firmware 当前观察到的外部技术边界依赖；它说明当前模块不是孤立实现，而是需要借助另一组工程能力完成职责。

    技术角色
    跨模块技术依赖边界：当前 package 需要另一个 package/module 提供能力、契约、配置或运行支撑。
    为什么出现
    本地仓库证据在 firmware 与 apps/linux_uconsole_gtk 之间观察到跨模块事实关系，因此该依赖被放入 Package Diagram，而不是只藏在代码 import/call 里。
    关系意义
    firmware -> apps/linux_uconsole_gtk 表示本地仓库证据观察到跨模块关系；它解释技术依赖方向，但不直接证明业务流程。
    下钻意图
    下钻 apps/linux_uconsole_gtk 可以查看它自己的 Package Diagram，再继续进入其组件、结构、sequence 或热点，判断当前依赖究竟落在入口、运行时、工具注册、模型适配还是基础设施边界。
    业务关联
    firmware 如果承载用户可见能力，那么对 apps/linux_uconsole_gtk 的依赖可能是该能力的运行机制、扩展点或治理约束。该业务关联需要由组织/过程模型的 Use Case 证据确认。
    变更影响
    修改 apps/linux_uconsole_gtk 的公共接口、路径或运行方式，可能让 firmware 的调用链、打包入口、agent 工作流或 UI 行为发生连锁变化。
    置信度
    high

    证据

    • dependency edge: firmware -> apps/linux_uconsole_gtk
    • apps/linux_uconsole_gtk/APP_SHELL_MANIFEST.md
    • apps/linux_uconsole_gtk/CMakeLists.txt
    • apps/linux_uconsole_gtk/packaging/trailmate-uconsole.desktop
    • apps/linux_uconsole_gtk/packaging/trailmate-uconsole.png
    • apps/linux_uconsole_gtk/README.md
    • apps/linux_uconsole_gtk/src/linux_uconsole_gtk_app_shell.cpp
    • apps/linux_uconsole_gtk/src/linux_uconsole_gtk_app_shell.h

    风险

    • 跨模块依赖只能证明技术关系，不能直接证明业务关系。
    • 如果该依赖只是因为实现方便而存在，未来变更可能形成边界漂移或隐式公共工具箱。

    问题

    • 当前证据尚未证明 firmware 依赖 apps/linux_uconsole_gtk 与某个 Use Case、runtime command 或配置决策直接相关。
    • 当前依赖方向按仓库事实记录为候选，尚未发现架构决策文档证明它是稳定边界。

可下钻 UML

服务对象：main component · contains

打开 服务对象：main 是为了确认 firmware 内部哪一个具体对象承担入口、编排、适配、契约或共享职责。重点查看代码锚点 firmware/c6_companion/tests/test_tm_services_functional.cpp，以及它的被引用/调用关系和对外依赖/调用关系是否意味着变更会扩散。

function 位于 firmware/c6_companion/tests/test_tm_services_functional.cpp#L97，协调多个外部对象或能力，用于解释技术协作和变更影响面。
界面组件：tm_services_record_error component · contains

打开 界面组件：tm_services_record_error 是为了确认 firmware 内部哪一个具体对象承担入口、编排、适配、契约或共享职责。重点查看代码锚点 firmware/c6_companion/components/tm_services/tm_services.c，以及它的被引用/调用关系和对外依赖/调用关系是否意味着变更会扩散。

function 位于 firmware/c6_companion/components/tm_services/tm_services.c#L471，被多个对象复用或依赖，用于解释技术协作和变更影响面。

证据

问题