# Inbox Modules

本文档描述当前 `inbox/` 的真实模块边界和最近一次收口后的职责落点。

## 总原则

- 业务入口只有一个：HTTP
- 启动命令只有两个：`server` 和 `api`
- 程序装配只留在入口层，不把 service 组装散落到业务 handler
- app 层按用例职责划分，store 层按聚合划分，不按页面或临时调用方划分

## 当前模块

### 1. 启动层

| 模块 | 路径 | 职责 |
| --- | --- | --- |
| 程序入口 | `cmd/inbox/` | CLI 入口与最终 wiring |
| CLI 壳层 | `internal/cli/` | 识别 `server` 与 `api` 命令 |
| HTTP client | `internal/client/` | 通用 HTTP 请求封装 |
| AI CLI 封装 | `internal/clientcmd/` | 面向 AI 的 `api` 命令封装 |
| Server 启动器 | `internal/servercmd/` | 解析 flag，产出启动配置并启动 HTTP 服务 |
| Server 组装 | `internal/inboxserver/` | 生产路径上的 store / service / handler composition root |

### 2. 基础与领域层

| 模块 | 路径 | 职责 |
| --- | --- | --- |
| 基础能力 | `internal/base/` | `timeutil`、`slug`、`idgen`、`httpx` |
| 领域模型 | `internal/domain/` | `role`、`skill`、`topic`、`message`、`workflow`、`merge`、`docspec`、`workspace`、`lane`、`task`、`taskgraph` |

### 3. 应用层

| 模块 | 路径 | 职责 |
| --- | --- | --- |
| roles | `internal/app/roles/` | 角色配置管理与技能绑定 |
| runtimeconfig | `internal/app/runtimeconfig/` | workspace 维度的运行时角色解析 |
| skills | `internal/app/skills/` | 技能管理 |
| topics | `internal/app/topics/` | topic、message、确认/停止 相关用例 |
| lanes | `internal/app/lanes/` | lane CRUD 与启动/停止 |
| tasks | `internal/app/tasks/` | task CRUD 与依赖写入 |
| taskexec | `internal/app/taskexec/` | lane 内 task 认领、执行完成、topic 收口 |
| leaderloop | `internal/app/leaderloop/` | leader delivery 轮询、规划执行、图谱落库 |
| workflowrun | `internal/app/workflowrun/` | workflow run 与日志用例 |
| workspaces | `internal/app/workspaces/` | project/workspace catalog CRUD 与 resolve |
| workspacelifecycle | `internal/app/workspacelifecycle/` | workspace runtime inspect / provision / ensure |
| workspaceprovision | `internal/app/workspaceprovision/` | provision 过程编排 |
| workspaceruntime | `internal/app/workspaceruntime/` | worktree / binary / container runtime 生命周期 |
| systemfs | `internal/app/systemfs/` | 系统目录浏览与创建 |
| dashboard | `internal/app/dashboard/` | dashboard 读模型与聚合视图 |

### 4. 传输层

| 模块 | 路径 | 职责 |
| --- | --- | --- |
| HTTP API | `internal/httpapi/` | `/api/v2/*` handler，只做 transport 解析、调用 app service、写响应 |

### 5. 持久化层

| 模块 | 路径 | 职责 |
| --- | --- | --- |
| SQLite store | `internal/store/sqlite/` | schema、migration、repository 实现 |

当前 store 已按聚合拆分主要文件：

- `projects_workspaces.go`：project / workspace 持久化
- `topics_documents.go`：topic 持久化
- `messages.go`：message 与 delivery 持久化
- `workflow_runs_store.go`：workflow run 与 log 持久化
- `chains_store.go`、`tasks_store.go`：lane / task 持久化
- `task_graph_versions.go`：task graph version 持久化
- `roles_store.go`、`skills_store.go`：配置类持久化
- `taskexec_store.go`：task execution 认领与完成写入

## 已删除或收口的旧边界

以下形态已经不再保留：

- 顶层 `inbox/*.go` facade 包装层
- handler 中直接做 filesystem 业务
- handler 中直接做 patch merge 规则
- `roles` 包里的 runtime role resolve 适配层
- `dashboard_queries.go` / `entities.go` 这种跨多个聚合的大一统 store 文件

如果后续继续扩展 `inbox`，优先遵守现有边界，不再恢复“按页面切 repo”或“transport 里做业务编排”的旧模式。