# ADR-0004：采用可拆分的模块化 Controller 架构

- 状态：Accepted
- 日期：2026-09-17

## 背景

Ayatori 将逐步提供任务执行、虚拟机、数据库、负载均衡、对象存储、托管 Kubernetes 和
人工操作等领域能力。这些能力拥有不同的生命周期、权限、网络位置和后端实现，若直接在
一个 controller 中相互调用并共享内部状态，后续接入新后端时容易形成代码耦合，也难以
独立扩缩容、发布和隔离故障。

另一方面，在首个领域能力完成前就拆分为多个独立服务，会立即引入镜像与部署管理、服务
间认证、版本兼容、分布式观测和故障处理成本，而这些成本尚未由真实运行需求证明。

Job 是首个领域对象。它既是最初的单次任务调度 API，也用于验证领域状态机与 Kubernetes
Job、OpenSandbox 和未来执行后端之间的适配边界。

## 决策

Ayatori 初期采用模块化单体：多个领域 controller 可以编译进同一个 controller manager，
但代码、API 所有权和依赖方向按照未来可独立部署的服务边界组织。

### 领域所有权

每个领域模块拥有自己的：

- CRD 与 API 版本；
- reconciler 和状态机；
- finalizer、conditions、删除及恢复语义；
- backend adapter contract；
- 领域测试。

初始领域包括但不限于 execution、compute、database、networking 和 human operations。领域
模块不得导入其他领域的内部实现，也不得直接修改其他领域所拥有对象的 spec 或 status。

### 跨领域协作

领域间的持久协作通过 Kubernetes API 对象、typed reference、owner reference 和
conditions 完成，而不是通过进程内 service 方法调用。

例如虚拟机完成创建后需要执行 provision，应创建或引用 Run 对象并观察其状态，而不是
直接调用 execution 模块的内部 Go API。更高层的资源组合由专门的领域对象或 GitOps 声明
完成，不引入统一包装所有底层能力的 Application controller。

该约束使 controller 即使暂时位于同一进程，其通信、失败和恢复行为仍与未来分进程部署
一致。

### Backend adapter

领域状态机只依赖本领域定义的最小 adapter contract，不依赖 Kubernetes Job、Crossplane、
OpenTofu、OpenSandbox 或具体厂商 SDK 类型。Adapter 负责：

- 幂等地确保期望外部资源存在；
- 观察并翻译外部状态；
- 执行取消、删除或 orphan 策略；
- 返回稳定的外部引用、能力和分类错误。

不同领域分别定义 adapter contract，不建立能包装所有资源类型的万能 Provider 接口。
后端不具备的能力必须显式报告，不通过虚假的统一语义隐藏差异。

Crossplane、OpenTofu 和 Ansible 等系统是可替换的 backend 实现或执行机制，不构成 Ayatori
面向用户的稳定 API。它们的 ProviderConfig、Workspace、playbook 等实现细节不得直接成为
领域 API 的必填契约。

### 共享代码

默认不建立跨领域的万能 service、repository 或 util 层。共享并非禁止，但必须来自已经
存在的真实重复，并同时满足：

1. 至少有两个真实调用者；
2. 重复的行为和语义一致，而不只是代码形状相似；
3. 调用方对其生命周期和预期演化方向一致；
4. 共享包不依赖任何具体领域的内部包。

适合共享的通常是机制，例如 conditions 操作、typed reference、重试退避、Secret 引用
读取、观测初始化和测试环境。领域状态机、资源策略、错误含义及后端选择不得为了消除少量
重复而抽取到共享层。

共享包使用表达具体职责的窄名称，初期保留在 `internal/shared/`。不建立内容持续膨胀的
通用 `util` 包，也不在实现稳定前承诺公共 Go API。

### 部署与拆分

controller manager 应支持按领域或 controller 集合选择性启用。初期可以使用一个二进制和
一个 Deployment；需要隔离时，优先使用同一制品部署为多个 Deployment。只有独立版本和
依赖关系成为真实需求后，才进一步拆分二进制或仓库。

出现下列任一情况时，应评估拆分部署：

- 需要独立扩缩容或显著不同的 reconcile 并发；
- 权限边界要求独立 ServiceAccount 与 RBAC；
- 后端只能从特定网络或节点访问；
- 沉重、不可信或冲突的 SDK 需要隔离；
- 一个领域的故障不应影响其他控制循环；
- 发布节奏或维护责任已经明确分离。

拆分不得改变领域 API，也不应将原本通过 API 对象完成的协作改为同步 RPC 链路。

## 结果

- 首个 Job 实现需要同时建立 execution 状态机和 adapter 边界，不能把 Kubernetes Job
  细节写入领域模型。
- 初期避免承担不必要的微服务运维成本，同时保留按权限、网络位置和故障域拆分的路径。
- Kubernetes API 成为领域间异步协作和恢复边界，领域 controller 必须正确处理最终一致性。
- 部分机械代码会有意保留重复，直到共享语义被至少两个真实实现证明。
- 代码评审需要检查跨领域 import、对象写入所有权和后端类型泄漏。
- 当 Job 同时拥有 Kubernetes Job 与 OpenSandbox adapter 后，应复审 adapter contract，确认
  它来自真实后端差异而非单一实现假设。