> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skrmir.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 分层架构设计

> AiOS 的 Interface / Usecase / Domain / Infrastructure 分层、依赖规则与运行态边界。

# 分层架构设计

## 适用对象

本页面向实现控制面、安装器、任务编排、审批与应用交付模块的开发者。

## 目标与范围

本页定义 AiOS 控制面的四层分层、依赖方向、运行态边界，以及“无状态服务、状态外置”的落地要求。

本页描述的是 **code-dependency view**。
如果你想理解系统在运行时的接入、控制与执行拓扑，请结合 [系统架构](/platform/architecture) 的 **runtime topology view** 一起阅读。

## 核心概念

### 1. Interface Layer

包含：

* HTTP API
* CLI
* Agent CLI
* 后续的任务进度流接口（SSE/WebSocket）

职责：协议转换、参数解析、错误映射、调用 usecase。

### 2. Usecase Layer

包含：

* 安装与 bootstrap 用例
* Deploy 用例
* DB 管理用例
* Approval 用例
* Task orchestration 用例

职责：串联业务流程，但不承载具体协议与基础设施细节。

### 3. Domain Layer

包含：

* Project / Environment / App / Deployment
* Task / Approval / Audit
* DBInstance / DBAccessPolicy

职责：承载领域模型、约束与状态语义。

### 4. Infrastructure Layer

包含：

* K3s/K8s 适配
* PostgreSQL / PgBouncer
* MinIO/S3
* Compose 解析与导入实现

职责：对接外部系统，不反向定义业务语义。

## 标准流程

### 依赖方向

允许的依赖方向：

`Interface -> Usecase -> Domain -> Infrastructure`

禁止：

* Interface 直接依赖具体 infra 实现
* Infrastructure 反向依赖 Interface
* 模块间随意穿透对方内部子包

### 运行态边界

* 控制面服务按无状态副本设计
* 权威状态放在 PostgreSQL / 对象存储
* 进程内状态只允许作为 bootstrap stub 或短生命周期缓存

## CLI 示例

```bash theme={null}
make test
make check-p0-contracts
```

## Web UI 路径

* 架构概念不会直接暴露为 UI 菜单，但会体现在平台设置、任务中心、审批中心与交付路径中。

## 常见问题 / 风险提示

* 如果一个模块需要长期保存业务状态，它不应依赖进程内 slice/map 作为权威来源。
* 如果一个接口要跨 Web/CLI/Agent 复用，它应优先落到 usecase 与统一服务端契约，而不是放在某个特定入口里。
* 当前代码骨架中的某些 stub 实现只是阶段性措施，不应反向影响正式架构。
* 不要把本页的代码依赖分层误读成运行时拓扑图；它们是两个互补视角。

## 相关页面

* [系统架构](/platform/architecture)
* [运维总览](/operations/index)