1.8 KiB
1.8 KiB
ADR-0001：Monorepo 与技术栈选型
- 日期：2026-07-27
- 状态：已接受
背景
第一波要同时出前端控制台、控制平面、Host Agent 三个可交付物，团队规模是 1-2 人。
决定
单仓库（monorepo），三个可独立部署的单元：apps/console、services/control-plane、
services/host-agent。技术栈按方案 §6.1：Next.js + FastAPI + PostgreSQL。
开发态零外部依赖：SQLite 替 Postgres、进程内 asyncio 替 Redis、
本地目录替 MinIO。三者都在接口后面，docker-compose.yml 给出生产形态。
理由
- 1-2 人团队用多仓库，跨仓改一个接口要开三个 PR，纯损耗。
- 控制平面与 Agent 的 HTTP 契约会在接第一个客户时频繁改。同仓库能一次改完、 一次跑通端到端测试。
- 开发态零依赖是为了降低启动摩擦：这台机器上没有 Docker，客户现场的
Windows 测试主机上也大概率装不了 Docker。能
python -m直接跑起来的东西， 在实验室里活得久。 - Python 3.9 兼容：客户测试主机的 Python 版本不可控，Agent 必须往低了兼容。
所以全仓库用
Optional[X]而不是X | None，用List[X]而不是list[X]。
代价
- SQLite 与 Postgres 有行为差异（并发写、JSON 查询、事务隔离）。 缓解：ORM 层不用任何方言特有类型；CI 后续要在 Postgres 上再跑一遍测试。
- monorepo 在团队超过 5 人后会需要更强的 CI 分区。届时再拆。
什么时候推翻
- 团队 >5 人且前后端分离开发节奏明显不同步 → 拆仓。
- Agent 需要单文件分发到无 Python 环境的 Windows → 把 Agent 用 Go 重写 （方案 §6.1 已经把这条写成演进建议）。届时 HTTP 契约不变，只换实现语言。