# SaaS 项目目录结构规范（第一版）

本文档定义新 SaaS 项目的目录结构和职责边界。

原则：

- 新旧隔离
- 前后端隔离
- 业务层和框架层隔离
- 目录一旦定下，后续新增功能必须按结构落位

---

## 1. 顶层结构建议

```text
saas/
  docs/
  apps/
    web/
    api/
    worker/
  packages/
    domain/
    application/
    ports/
    adapters/
    shared/
  infra/
    docker/
    nginx/
    scripts/
  tests/
    integration/
    e2e/
```

---

## 2. 目录职责

### 2.1 `docs/`

存放所有正式文档：

- PRD
- 架构文档
- 数据模型
- API 规范
- 发布说明
- 运维说明
- 里程碑和范围文档

规则：

- 文档必须是单一真相源
- 先改文档，再改实现

### 2.2 `apps/web/`

前端 Web 应用。

职责：

- 页面
- 路由
- 组件
- 页面状态绑定
- 调用后端 API

禁止：

- 在这里写核心业务规则
- 在这里写任务执行逻辑

### 2.3 `apps/api/`

后端 API 应用。

职责：

- 提供 HTTP API
- 鉴权
- 请求校验
- 调用 Application Use Cases

禁止：

- 把业务规则直接写在路由层
- 直接耦合底层外部实现

### 2.4 `apps/worker/`

后台任务执行应用。

职责：

- 执行素材分类任务
- 执行视频生成任务
- 执行同步和诊断任务

原则：

- Worker 只执行任务，不处理 Web 交互

### 2.5 `packages/domain/`

核心业务对象和值对象。

职责：

- User
- Workspace
- Project
- Asset
- AssetLibrary
- GenerationTask
- GeneratedVideo
- 业务规则

禁止：

- import Web 框架
- import 数据库驱动
- import UI 工具

### 2.6 `packages/application/`

用例层。

职责：

- 创建项目
- 上传素材
- 分类素材
- 发起生成
- 查询进度
- 获取结果

原则：

- 编排业务流程
- 通过 ports 调外部能力

### 2.7 `packages/ports/`

接口定义层。

职责：

- 仓储接口
- 存储接口
- 队列接口
- 通知接口
- 日志接口

原则：

- 不依赖具体实现

### 2.8 `packages/adapters/`

外部实现层。

职责：

- PostgreSQL 实现
- Redis / Celery 实现
- OSS / S3 实现
- 鉴权实现
- 日志实现

### 2.9 `packages/shared/`

共享的通用工具和基础类型。

职责：

- 通用配置
- 错误类型
- 公共 schema
- 公共常量

规则：

- 只放真正跨层复用的通用内容
- 禁止把业务逻辑偷塞进 shared

### 2.10 `infra/`

基础设施目录。

职责：

- Docker
- Nginx
- 启动脚本
- 本地开发环境脚本
- 部署脚本

### 2.11 `tests/`

测试目录。

建议拆分：

- `integration/`：前后端/数据库/队列联调测试
- `e2e/`：核心流程端到端测试

应用/包内部也可各自保留单元测试目录。

---

## 3. 模块新增规则

以后新增功能时，按这个顺序决定落点：

1. 是业务对象？放 `domain`
2. 是业务用例？放 `application`
3. 是接口定义？放 `ports`
4. 是外部实现？放 `adapters`
5. 是页面或交互？放 `apps/web`
6. 是 API 路由？放 `apps/api`
7. 是后台任务执行？放 `apps/worker`
8. 是部署与运行？放 `infra`

---

## 4. 禁止事项

- 禁止把旧桌面版目录结构照搬过来
- 禁止在 `web` / `api` 中直接写核心业务规则
- 禁止 `domain` 依赖数据库、Redis、OSS、框架
- 禁止 `shared` 成为大杂烩
- 禁止把临时脚本堆进项目根目录

---

## 5. 当前阶段结论

新 SaaS 项目必须从第一天就按这个结构起步。

这样做的价值是：

- 不会再回到单体混乱结构
- AI 工具更容易分工协作
- 后面扩功能、拆模块、加 worker 都更顺