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
6.8 KiB
SaaS 核心对象清单（第一版）
本文档定义新 SaaS 系统的核心业务对象。目标不是现在就把数据库字段写死，而是先把系统世界观定清楚，避免后续边开发边返工。
1. 设计原则
核心对象必须满足：
- 能覆盖当前桌面版的主要业务能力
- 能支撑未来多人协作和迭代
- 能清楚区分“谁拥有、谁使用、谁产生、谁消费”
- 不因为桌面版历史实现而被绑死
2. 顶层对象分组
新 SaaS 的核心对象建议分为 6 组：
- 用户与组织
- 工作空间与项目
- 素材与素材库
- 生成与任务
- 结果与发布
- 系统与运维
3. 用户与组织对象
3.1 User（用户）
代表系统中的登录使用者。
职责：
- 登录系统
- 创建项目
- 上传素材
- 发起生成
- 查看结果
- 管理自己的资源
后续待确认：
- 是否支持多个角色
- 是否支持子账号
- 是否支持团队成员
3.2 Team / Workspace（团队 / 工作空间）
如果未来不是纯个人 SaaS，就必须有这个对象。
职责：
- 隔离不同用户组的数据
- 承载成员、项目、素材库、任务
- 作为权限边界
当前建议：
- 先按“工作空间”概念设计
- 一期即使只支持单用户，也保留扩展位
3.3 Membership（成员关系）
表示用户属于哪个工作空间、具备什么权限。
职责：
- 权限控制
- 团队协作
- 后续审计与操作归属
4. 工作空间与项目对象
4.1 Project（项目）
新 SaaS 里最核心的业务容器之一。
职责：
- 承载一组素材、配音、策略、任务、生成结果
- 作为用户操作的主要上下文
为什么必须有：
桌面版很多逻辑都默认“当前工作台上下文”，SaaS 里必须把这个上下文对象化。
4.2 Folder / Collection（可选）
如果素材量很大，后续可能需要集合/文件夹逻辑。
一期建议：
- 不作为强制核心对象
- 预留二级组织能力即可
5. 素材与素材库对象
5.1 AssetLibrary（素材库）
素材库的统一抽象。
建议未来不要把“视频库”和“配音库”写成完全不同的两套模型，而是：
- 统一为
AssetLibrary - 通过
kind区分：videovoice- 后续可扩展
image/template/subtitle
职责：
- 组织素材
- 隔离不同项目/工作空间资源
- 提供筛选、统计、权限、归属能力
5.2 Asset（素材）
素材的统一抽象。
可能包括：
- 视频素材
- 图片素材
- 配音素材
- 背景音频
- 模板文件（未来）
关键属性层面未来要支持：
- 所属库
- 所属项目 / 工作空间
- 文件地址
- 文件元数据
- 分类结果
- 质量状态
- 风险标记
- 使用统计
5.3 AssetClassification（素材分类结果）
当前桌面版已经有成熟经验，这个对象未来应该独立表达。
职责：
- 记录素材分类结果
- 记录口播/场景/待复核等业务标签
- 作为生成策略选择依据
5.4 AssetDiagnosis（素材诊断结果）
用于表达素材准备度、缺口、建议。
职责：
- 给项目/素材库生成健康判断
- 给用户输出“缺什么、风险在哪里、建议怎么补”
6. 配音与策略对象
6.1 VoiceAsset（配音素材）
虽然可以作为 Asset 的一种，但业务上很重要，需要单独强调。
职责：
- 作为生成输入
- 支持试听、复核、重复检测、质量检查
6.2 GenerationStrategy（生成策略）
桌面版里已经存在生成策略概念，SaaS 里必须保留，而且要对象化。
职责：
- 定义生成模式
- 定义视频库/配音库选择方式
- 定义阈值、数量、规则
- 支持后续模板化与复用
6.3 StrategyTemplate（策略模板，可选）
如果未来要做更强复用，这个对象会非常有用。
职责：
- 保存可复用的生成策略
- 支持团队共享
7. 生成与任务对象
7.1 GenerationRequest（生成请求）
表示用户点击“开始生成”时提交的一次业务请求。
职责：
- 记录用户发起的意图
- 绑定项目、策略、素材范围、配置
7.2 GenerationTask（生成任务）
表示后台真正执行的一次任务。
职责：
- 追踪状态
- 分配 worker
- 记录进度
- 支持失败重试
- 支持日志与诊断
7.3 BatchTask（批量任务）
桌面版已经证明单个任务和批量任务不是一个复杂度级别，所以建议单独对象化。
职责：
- 管理一批生成候选
- 统计成功/失败/跳过
- 支持单候选失败隔离
7.4 TaskAttempt / TaskRun（任务执行记录）
如果未来要支持重试、回放、错误审计，这个对象很重要。
职责：
- 记录某个任务的第几次执行
- 记录失败原因、耗时、日志摘要
8. 结果与发布对象
8.1 GeneratedVideo（生成结果 / 成片）
表示最终产出的业务结果。
职责：
- 保存成片元信息
- 绑定来源任务
- 供下载、预览、发布、同步
8.2 ResultPackage（结果包，可选）
如果后续要把视频、封面、字幕、元信息打包下载，可以引入。
8.3 PublishRecord（发布记录，可选）
如果未来要做发布/分发到外部平台，这个对象需要提前预留。
9. 系统与运维对象
9.1 WorkerNode（执行节点）
SaaS 版里视频生成大概率不应该和 Web 请求进程混在一起，所以需要执行节点概念。
职责：
- 执行长任务
- 上报健康状态
- 接受任务分派
9.2 SyncJob（同步任务）
当前桌面版有云同步经验，SaaS 里如果有多存储、多节点、多结果归档，也会需要同步任务抽象。
9.3 AuditLog（审计日志）
职责：
- 记录谁在什么时候做了什么
- 支持排错、责任追踪、安全审计
9.4 SystemEvent / HealthCheck（系统事件 / 健康检查）
职责：
- 观测性
- 巡检
- 告警
10. 一期必须优先确认的对象
最先必须定死的是：
- User
- Workspace
- Project
- AssetLibrary
- Asset
- GenerationStrategy
- GenerationTask
- BatchTask
- GeneratedVideo
- WorkerNode
这 10 个对象决定了 SaaS 的主骨架。
11. 当前建议
一期推荐采用的对象骨架
- 用户
- 工作空间
- 项目
- 统一素材库
- 统一素材对象
- 生成策略
- 单任务 / 批量任务
- 成片结果
- Worker 节点
- 审计日志
暂时可后补的对象
- 套餐 / 支付
- 发布记录
- 模板市场
- 高级权限体系
- 更复杂的目录树/集合体系
12. 当前阶段结论
新 SaaS 项目最重要的不是“先建多少表”，而是先把对象世界观定清楚。
当前建议已经足够支持下一步：
- 继续定义核心流程
- 再根据对象和流程定技术栈
- 之后再设计数据库和 API