Xiaoxia AI
b5a62ee9a3
- domain: User, Workspace, Project, AssetLibrary, Asset, IngestJob - ports: repository interfaces - application: use cases - adapters: in-memory - API: FastAPI 5 routes - worker: Celery ingest_asset - tests: 4 passing
248 lines
3.5 KiB
Markdown
248 lines
3.5 KiB
Markdown
# 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 都更顺
|