Ivan's Blog
项目实践

Mains Aegis

Mains Aegis 是 UPS / power-management 设备 mono-repo：它把硬件行为文档、ESP32-S3 固件、Web 管理界面、docs-site、前面板/音频预览工具和质量门禁放在同一个维护边界里。PRODUCT.md 明确把 Web 管理界面定义为面向多设备 UPS 的只读运维控制台，首要目标是让维护者快速判断设备健康、离线、后备供电和告警状态，而不是做可写控制台。

  • Device mono-repo
  • Web demo
  • Embedded device control plane
  • Project docs site

目录

技术栈

运行与交付

CI 工作流
  • ci.yml
  • dependency-review.yml
  • docs-pages.yml
  • firmware.yml
  • lint-pr-title.yml
能力标记
  • bun_lock
  • github_actions
  • package_json
JSON

Purpose

Mains Aegis 是 UPS / power-management 设备 mono-repo：它把硬件行为文档、ESP32-S3 固件、Web 管理界面、docs-site、前面板/音频预览工具和质量门禁放在同一个维护边界里。PRODUCT.md 明确把 Web 管理界面定义为面向多设备 UPS 的只读运维控制台，首要目标是让维护者快速判断设备健康、离线、后备供电和告警状态，而不是做可写控制台。

Taxonomy

  • Tags: Device mono-repo, Web demo, Embedded device control plane, Project docs site

Repository map

  • docs/ 是工程设计中心，包含 bms-design.md、charger-design.md、ups-output-design.md、power-monitoring-design.md、quality-gates.md 等硬件/固件/产品决策。
  • firmware/ 是 ESP32-S3 Rust firmware crate，firmware/Cargo.toml 暴露 main voltage selector、BMS diag、thermal protect test 等编译特性。
  • web/ 是 React/Vite TypeScript 管理界面，web/package.json 暴露 dev、preview、build、check。
  • docs-site/ 使用 Rspress 生成公开文档站；mcu-agentd.toml 让本仓库能被 MCU 管理工具直接识别。

Runtime and delivery

根 package.json 只负责 workspace 脚本和 commitlint；Web 运行通过 bun run web:dev 进入 web/，默认 WEB_PORT 可覆盖。PRODUCT.md 还要求测试示例与 direct-access demo path 复用正式 frontend 和正式 route，并允许 mock seed data 作为稳定交互输入。docs-site 通过 DOCS_PORT 覆盖端口，默认 50885。固件侧依赖 firmware/Cargo.toml 和 mcu-agentd.toml，后者声明 espflash、esp32s3、release ELF 和 selector cache。

Architecture notes

这个项目的架构重心是“文档先行的设备系统”。UPS 行为拆成 BMS、charger、output、audio、boot self-test、power monitoring 等文档，再由 firmware 和 web UI 分别落地。Web 首版只读是关键边界：PRODUCT.md 明确避免误触 UPS 状态；任何后续控制操作都应该先进入 specs 和 safety gate，而不是直接加到 React 页面。

Workflow and quality gates

.github/workflows/ci.yml、firmware.yml、docs-pages.yml、dependency-review.yml 和 lint-pr-title.yml 把固件、文档站、依赖审查和 PR 标题规则分开。docs/quality-gates.md 与 lefthook.yml 说明质量门禁是项目 contract 的一部分。

Reusable decisions

  • 复杂硬件项目用 docs/ 承载 current truth，比把设计散在 PR 里更可复用。
  • 只读运维 UI 先行，硬件控制写操作延后到安全模型清楚之后。
  • 根 mcu-agentd.toml 让固件操作可配置，减少每次 flashing 的口头约定。
  • Web demo 只接受复用正式前端与正式路由的 mock-seeded / read-only 演示路径，不把 docs-site 或普通 preview 误算成产品演示面。

Risks and open questions

  • Web UI 与 firmware/docs 的事实可能漂移；UI 声称的状态必须能追到设备 API 和设计文档。
  • 电源/电池/热保护相关改动需要硬件证据或仿真证据，不能只看 TypeScript build。

Evidence index

  • PRODUCT.md
  • docs/README.md
  • docs/quality-gates.md
  • docs/bms-design.md
  • docs/charger-design.md
  • docs/ups-output-design.md
  • firmware/Cargo.toml
  • web/package.json
  • docs-site/package.json
  • mcu-agentd.toml
  • .github/workflows/ci.yml
  • .github/workflows/firmware.yml

相关内容