架构与目录

系统定位

该仓库是 IoT SaaS 后端的「内核」：

• 默认路径：模块化单体（运维简单、边界清晰）
• 可选路径：在真实压力出现时，按模块抽出服务（业务逻辑不复制一份）

v1 优先：可运维、可预期性能、清晰边界，而不是最大化分布式。

仓库布局（核心）

cmd/
  monolith/                 # 推荐入口：完整产品路径
services/
  auth/ organization/ device/ telemetry/ ...
libs/
  platform/                 # 配置、HTTP 集成、DB、权限、事件、迁移等
  contracts/                # 跨模块 DTO、接口、错误 —— 稳定边界
deploy/
  migrations/               # SQL 迁移
docs/                       # 架构 / API / 部署等英文文档
sdk/                        # 设备侧 Go SDK 等
examples/                   # simulator、quickstart
scripts/                    # smoke、release、边界检查等

业务模块列表会随产品增长（如 alert、automation、twin、vendorplatform、jobs…），以仓库 README.md 为准。

运行时形态

模块化单体（推荐）

• 入口：cmd/monolith
• 默认地址：:8080（以配置为准）
• 同一进程内：HTTP、可选 MQTT、调度/任务分发等

make run-monolith

按模块拆服务

架构保留 services/*/cmd 抽取边界，但仅当文档标明该模块已接线完整时才可独立跑。
未接线的 make run-{module} 应直接失败，避免「健康检查是绿、业务全错」的假启动。
完整路径请用 make run-monolith。详见仓库 docs/service-modes.md。

平面（Planes）直觉

不必一次记全模块名，可先记住职责平面：

平面	大致职责	示例模块
控制面	登录用户 API、组织内状态变更	auth、organization、device、alert…
数据面	遥测语义与读模型	telemetry
传输面	外部协议适配进业务语义	mqtt、vendorplatform
状态同步	期望/上报/收敛	twin
自动化	规则、执行、护栏	automation、alert 联动
通知	面向用户的通知编排	notifications
集成	出站 webhook 等	integration

依赖方向要点：

• 传输/厂商适配可以依赖 contracts / platform，业务服务不得反向依赖 mqtt/vendor 具体实现
• 跨模块复用优先走 contracts 与注入，禁止 services/a import services/b 内部包

请求与装配直觉

Monolith 启动时大致：

1. pkg.gostartkit.com/cmd 解析子命令（serve / migrate …）
2. 加载配置（platform.LoadServeConfig 等）
3. 组装依赖图（DB、权限、各模块 Runtime）
4. 各模块 RegisterRuntime 挂路由
5. 监听 HTTP，并按配置启动后台 worker

入口示例（概念，以仓库源码为准）：

func main() {
    app := cmd.NewApp("monolith")
    app.AddCommands(cmdServe(), cmdMigrate(), /* ... */)
    cmd.Main(app)
}

架构检查清单

• 新业务是否放在 services/{module} 而不是塞进无关模块
• 跨模块是否只依赖 libs/contracts（或平台注入）
• HTTP 是否只用 pkg.gostartkit.com/web 注册路由
• 是否避免无必要的中间层与反射

下一步：模块怎么写。