项目概览

参考工程是一套 面向 IoT SaaS 的模块化 Go 后端基础，而不是「只有几条路由的 demo」。

它把启动、配置、鉴权、模块装配、存储、迁移、文档、测试、SDK、模拟器与 smoke 流程串在同一仓库里。

核心设计

• 同一套业务代码可以跑成模块化单体，也可以在边界清晰后按需抽出模块服务
• 模块之间通过 libs/contracts 协作，而不是互相 import 对方内部包
• 实现强调 简单、显式、性能优先

默认生产形态是 模块化单体（modular monolith）：

• 一个进程承载完整产品路径
• 模块边界仍然清晰
• 部署与运维更简单

一句话：先稳住模块边界，真有隔离/扩展压力再拆服务。

设计原则

原则	含义
Simple first	优先直接、可读的实现
Explicit first	避免隐藏装配与过深抽象
Performance first	减少不必要分配、反射与中间层
Boundary first	业务服务不得直接互相 import
Small changes first	没有明确理由不做大范围重构

技术硬约束（务必遵守）

用途	使用	不要用
HTTP	pkg.gostartkit.com/web	gin / chi / echo / fiber 作为主路由
应用启动	pkg.gostartkit.com/cmd	自造一套 bootstrap 框架
业务逻辑位置	services/*/application、services/*/domain	把业务堆在 HTTP handler 里

规则摘要：

• 路由、handler、中间件、HTTP 服务启动走 web
• main.go 通过 cmd 做生命周期管理
• 不要为了「再包一层」而包装框架

当前能力范围（概览）

参考仓库已覆盖（随版本演进，以该仓库 README 为准），例如：

• 用户认证、会话、邮箱验证、密码重置
• 组织、成员、邀请、计划与权限
• 设备开通、凭证、生命周期、配置、车队视图
• 遥测接入与原始/最新/汇总读模型
• 告警、事件、通知
• 命令下发、设备拉取与确认
• 厂商集成、任务、审计、自动化、设备孪生等

版本策略概念：

• v1.x：基础能力 + 产品增强
• v2.x：预留给架构级变更

详见参考仓库 docs/versioning.md。

本教程怎么对应仓库

本站文档	仓库中的对应物
架构与目录	README.md、docs/architecture.md
模块形态	services/*、libs/contracts、libs/platform
本地运行	Makefile：run-monolith、migrate、smoke
配置	.env.example、docs/config.md
API	docs/api.md、docs/openapi/
部署	docs/deployment.md、scripts/release.sh

下一步：环境准备。