xiaoxia-saas/docs/saas-project-structure-spec.md

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

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

原则：

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

---

1. 顶层结构建议

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 都更顺