AI音乐 PRD

文档信息

项目	内容
产品名称	PMForge - AI音乐
文档版本	v2.0
创建日期	2026-09-24
最后更新	2026-09-24
文档状态	评审中
优先级	P1

一、功能概述

1.1 功能定位

AI音乐是 PMForge AI 模块的核心子模块之一，为用户提供基于大模型的音乐生成能力。

通俗理解：把 AI 音乐模块想象成一间"自助录音棚"。你走进录音棚，不需要会乐器、不需要懂乐理，只要告诉录音师"我想要一首欢快的流行歌，主题是毕业季的青春回忆"，或者直接把写好的歌词递给他，1-2 分钟后一首完整的歌曲就制作好了。你还可以让录音师帮你写歌词、换风格、调时长，最终下载 MP3 带走。后台管理端则是"录音棚控制室"，管理员可以接入不同的录音师（Suno 等服务商）、监控每首歌的制作进度、审核发布作品、查看运营数据。

模块集成 Suno 等主流 AI 音乐生成服务商，支持歌词模式（输入歌词生成带演唱的歌曲）和描述模式（输入文字描述生成纯音乐/配乐）两种创作方式，涵盖流行、摇滚、古典、电子等多种风格。同时提供 AI 辅助歌词生成、在线试听、作品下载等完整音乐创作体验。基于 Spring AI 框架实现，统一调度音乐生成模型资源。

1.2 目标用户与使用频率

用户类型	使用场景	预计使用频率
C端音乐爱好者	用 AI 创作个人音乐作品、生成背景音乐	每周 2-5 次
内容创作者	为视频/播客生成配乐、BGM	每周 3-8 次
研学导师	为研学课程生成主题音乐、教学配乐	每周 1-3 次
教育工作者	生成教学辅助音乐、儿歌、互动音乐	每周 2-4 次
平台运营人员	管理音乐任务、审核作品、运营统计	每日
系统管理员	配置音乐服务商、监控资源消耗	每周 1-2 次

1.3 业务价值

价值维度	具体收益	衡量指标
零门槛创作	用户无需音乐基础，文字描述即可生成专业级音乐	用户首次生成成功率 ≥ 90%
多风格覆盖	流行、摇滚、古典、电子、民谣、爵士等 20+ 风格	风格选择使用率 ≥ 70%
AI 歌词辅助	降低歌词创作难度，从主题到完整歌词一键生成	歌词辅助使用占比 ≥ 30%
在线试听体验	内置播放器，生成后即时试听，支持歌词同步	试听转化率 ≥ 85%
作品管理闭环	管理个人音乐库，支持下载和分享	用户作品留存率 ≥ 60%
精细化运营	任务监控、作品管理、消耗统计等运营工具	任务失败率 ≤ 5%
可扩展架构	基于 Spring AI 统一抽象层，快速接入新服务商	新服务商接入周期 ≤ 3 天

1.4 功能范围

功能分类	后台管理端	前台用户端
音乐模型管理（CRUD）	✅	❌
音乐任务管理	✅	✅（仅本人）
音乐作品管理	✅	✅（仅本人）
音乐统计	✅	❌
AI 音乐生成（歌词/描述）	❌	✅
音乐风格选择	❌	✅
AI 辅助歌词生成	❌	✅
音乐在线播放	❌	✅
我的音乐（管理/下载）	❌	✅

二、用户场景

2.1 用户角色

角色	描述	核心诉求
音乐爱好者小李	AI 音乐使用者，喜欢用 AI 创作个性音乐	简单快速生成喜欢的音乐、管理个人音乐库
视频博主小王	视频/播客创作者，经常需要 BGM	为视频生成匹配的配乐，风格多样、时长可控
研学导师张老师	课程内容创作者，需要教学配乐	生成课程主题音乐，氛围与内容匹配
运营人员小陈	平台运营管理者	监控任务状态、管理作品、查看统计
系统管理员小赵	技术管理者	配置服务商、监控资源消耗、保障稳定

2.2 使用场景

场景1：音乐爱好者小李用歌词生成一首流行歌曲

角色：音乐爱好者小李
前置条件：小李已登录，账户余额 200 Token
操作流程：
1. 小李进入"AI 音乐"页面，选择"歌词模式"
2. 点击"AI 写歌词"，输入主题"毕业季，对青春的不舍和对未来的期待"
3. 选择歌词风格"抒情"、结构"主歌+副歌"、语言"中文"
4. AI 生成完整歌词，小李微调了副歌部分
5. 选择音乐风格"流行"，时长 180 秒，含人声
6. 点击"生成"，系统扣减 50 Token
7. 等待约 90 秒，4 个版本的歌曲生成完成
8. 自动播放第一首试听，小李切换到第二首觉得最好
9. 点击"保存到我的音乐"
期望结果：歌曲音质清晰、风格匹配、歌词演唱自然
验收标准：
1. AI 歌词生成在 30 秒内返回，歌词结构完整（含主歌+副歌）
2. 音乐生成在 5 分钟内完成，4 个版本均为可播放的 MP3
3. 生成完成后 2 秒内自动开始播放
4. 保存到"我的音乐"后可随时播放和下载
5. Token 扣减金额与模型配置一致（50 Token）

场景2：视频博主小王为 Vlog 生成背景音乐

角色：视频博主小王
前置条件：小王已登录，需要一段 60 秒的旅行 Vlog 配乐
操作流程：
1. 小王进入"AI 音乐"页面，选择"描述模式"
2. 输入描述"阳光沙滩、轻松愉快的旅行 Vlog 配乐"
3. 选择风格"电子/轻快"，时长 60 秒，纯音乐（无人声）
4. 点击"生成"，系统扣减 30 Token
5. 等待约 60 秒，生成完成
6. 试听后满意，下载 MP3 文件用于视频剪辑
期望结果：音乐氛围与旅行主题匹配，时长精准 60 秒
验收标准：
1. 描述模式下生成的音乐无人声，为纯配乐
2. 音频时长与设定值（60 秒）偏差不超过 ±5 秒
3. 下载的 MP3 文件可正常播放，码率 ≥ 128kbps
4. 每首音乐每天下载次数不超过 10 次

场景3：研学导师张老师为课程生成主题配乐

角色：研学导师张老师
前置条件：张老师已登录，需要为"太空探索"主题课程生成背景音乐
操作流程：
1. 张老师进入"AI 音乐"，选择"描述模式"
2. 输入描述"宇宙太空、神秘、宏大、科幻感"
3. 选择风格"电子/氛围"，情绪"平静"
4. 分别生成 30 秒和 60 秒两个版本
5. 试听后选择 60 秒版本，下载用于课件
期望结果：音乐氛围与太空主题匹配，可用于教学场景
验收标准：
1. 生成的音乐风格与"电子/氛围"匹配，具有科幻感
2. 两次生成分别消耗对应 Token，账单记录清晰
3. 下载的文件包含完整音频，无截断或杂音
4. 作品自动保存在"我的音乐"中

场景4：运营人员小陈管理音乐任务和统计

角色：运营人员小陈
前置条件：小陈具有"ai:music:task:list"和"ai:music:statistics:view"权限
操作流程：
1. 小陈进入后台"AI 音乐 → 任务管理"
2. 查看今日生成任务列表，发现 3 个任务失败
3. 查看详情，失败原因为"API 配额用尽"
4. 联系管理员补充配额后，对 3 个失败任务执行"重试"
5. 进入统计页面，查看本月 Token 消耗趋势和风格分布
6. 导出任务列表 Excel 报表
期望结果：失败任务可重试成功，统计数据准确
验收标准：
1. 任务列表支持按用户、模型、状态、时间范围筛选
2. 失败任务重试后状态变更为"处理中"，成功后自动更新结果
3. 统计数据延迟不超过 5 分钟
4. 导出的 Excel 包含任务 ID、用户、模型、状态、耗时、Token 消耗等完整字段

场景5：用户管理个人音乐库

角色：音乐爱好者小李
前置条件：小李已生成 20 首音乐作品
操作流程：
1. 小李进入"我的音乐"
2. 查看所有作品，按风格筛选"流行"类
3. 在线播放喜欢的音乐，查看歌词
4. 下载高音质版本到本地
5. 删除 2 首不满意的作品
6. 查看存储使用情况（已用 18/100 首）
期望结果：管理方便、播放流畅、下载便捷
验收标准：
1. 列表按时间倒序展示，支持风格和时间范围筛选
2. 播放器支持播放/暂停/进度拖拽/音量调节
3. 删除为逻辑删除，30 天内可恢复
4. 存储空间达到 80%（80 首）时显示提醒

三、功能需求

3.1 音乐模型管理（后台管理端）

描述

管理平台接入的 AI 音乐生成服务商和模型，主要支持 Suno 等服务商。支持配置模型参数、API 接入信息、启用/禁用、排序等。

页面原型：模型管理列表页

操作流程

管理员进入"AI 音乐 → 模型管理"页面
查看当前已接入的所有音乐模型列表
点击"新增模型"填写模型基本信息
配置 API Key、API 地址、并发限制、每分钟消耗 Token 数、支持的最大时长等
保存后可进行"连通性测试"
支持对模型进行启用/禁用、排序、编辑、删除操作

业务规则

规则	说明	设计原因
单服务商多模型	每个服务商可配置多个模型版本	同一服务商不同版本效果不同，用户可按需选择
唯一默认模型	同一时间仅允许一个模型作为默认模型	用户未选择时自动使用默认模型，避免歧义
禁用不影响在途任务	模型禁用后，用户端不可选择，已提交任务不受影响	已在处理的任务不应因配置变更而中断
API Key 加密存储	API Key 等敏感信息 AES-256 加密存储	防止数据库泄露导致密钥外泄
连通性测试限时	连通性测试需在 10 秒内返回结果	快速验证配置正确性，避免长时间阻塞管理员操作

接口列表

接口名称	请求方式	接口路径	说明
查询模型分页列表	GET	/admin-api/ai/music/model/list	支持按服务商、状态筛选
查询模型详情	GET	/admin-api/ai/music/model/	获取单个模型配置详情
新增模型	POST	/admin-api/ai/music/model/create	创建新的音乐模型配置
修改模型	PUT	/admin-api/ai/music/model/update	更新模型配置信息
删除模型	DELETE	/admin-api/ai/music/model/delete/	逻辑删除模型配置
启用/禁用模型	PUT	/admin-api/ai/music/model/status/	切换模型启用状态
模型连通性测试	POST	/admin-api/ai/music/model/test/	测试模型 API 连通性
获取模型下拉列表	GET	/admin-api/ai/music/model/options	用于前端下拉选择

3.2 音乐任务管理（后台管理端）

描述

管理所有用户发起的音乐生成任务，包括任务列表查询、任务详情查看、任务状态管理、异常任务处理等。

操作流程

管理员进入"AI 音乐 → 任务管理"页面
查看任务列表，支持按用户、模型、状态、时间范围筛选
点击任务查看详情，包括歌词/描述、风格参数、生成结果、耗时等
对异常任务可执行"重试"或"取消"操作
可查看任务处理时间线

任务状态机

音乐任务状态机

业务规则

规则	说明	设计原因
超时自动失败	超过 5 分钟未返回结果自动标记失败	音乐生成通常 1-2 分钟，5 分钟已是宽限
超时退还 Token	超时失败后自动退还已扣减的 Token	非用户原因导致的失败不应由用户承担
失败可手动重试	失败任务支持手动重试	API 临时故障恢复后，运营可重新触发
参数完整保留	任务参数以 JSON 格式存储完整请求信息	便于问题排查和重试时使用原始参数
租户数据隔离	支持按租户隔离数据	多租户环境下数据安全性保障

接口列表

接口名称	请求方式	接口路径	说明
查询任务分页列表	GET	/admin-api/ai/music/task/list	支持多维度筛选
查询任务详情	GET	/admin-api/ai/music/task/	获取任务完整信息
取消任务	PUT	/admin-api/ai/music/task/cancel/	取消进行中的任务
重试任务	PUT	/admin-api/ai/music/task/retry/	重新处理失败的任务
删除任务	DELETE	/admin-api/ai/music/task/delete/	逻辑删除任务记录
导出任务列表	GET	/admin-api/ai/music/task/export	导出 Excel 报表
查询任务统计	GET	/admin-api/ai/music/task/statistics	任务数量、成功率统计

3.3 音乐作品管理（后台管理端）

描述

管理平台内所有 AI 生成的音乐作品，支持作品审核、分类管理、推荐管理等。

操作流程

管理员进入"AI 音乐 → 作品管理"页面
查看作品列表，支持按用户、风格、状态、时间筛选
对用户发布的作品进行审核（通过/驳回）
管理作品分类（风格分类维护）
对优质作品标记推荐

作品审核状态机

音乐作品状态机

业务规则

规则	说明	设计原因
默认仅本人可见	用户自主生成的作品默认仅本人可见	保护用户隐私，发布需主动操作
发布需审核	用户发布到社区的作品需经审核	防止违规内容在社区传播
驳回需填原因	驳回作品需填写原因，通知用户	用户可据此修改后重新发布
违规可下架	违规作品可下架处理	已发布内容事后发现违规时的处置手段
作品包含完整信息	作品包含音频文件、歌词文本、元数据	保证作品展示的完整性

接口列表

接口名称	请求方式	接口路径	说明
查询作品分页列表	GET	/admin-api/ai/music/work/list	支持多维度筛选
查询作品详情	GET	/admin-api/ai/music/work/	获取作品详情
审核作品	PUT	/admin-api/ai/music/work/audit/	通过或驳回
推荐作品	PUT	/admin-api/ai/music/work/recommend/	标记推荐
下架作品	PUT	/admin-api/ai/music/work/offline/	下架违规作品
删除作品	DELETE	/admin-api/ai/music/work/delete/	逻辑删除
风格分类管理	GET/POST/PUT/DELETE	/admin-api/ai/music/work/style/*	风格分类 CRUD

3.4 音乐统计（后台管理端）

描述

提供 AI 音乐模块的数据统计能力，包括生成次数、Token 消耗、用户排行、风格分布等。

页面原型：数据统计概览页

操作流程

管理员进入"AI 音乐 → 数据统计"页面
查看概览面板：今日生成数、本月 Token 消耗、活跃用户数、平均生成时长
查看趋势图：按天/周/月查看生成量和 Token 消耗趋势
查看风格分布饼图
查看用户消耗排行

业务规则

规则	说明	设计原因
近实时统计	统计数据延迟不超过 5 分钟	运营需要及时了解业务动态，但不要求秒级实时
租户维度	支持按租户维度统计	多租户运营各自查看各自数据
Token 关联扣减	Token 消耗需关联用户钱包扣减记录	确保消耗数据与财务数据一致
90 天明细保留	统计数据保留最近 90 天明细	平衡存储成本与运营分析需求

接口列表

接口名称	请求方式	接口路径	说明
获取概览数据	GET	/admin-api/ai/music/statistics/overview	今日/本周/本月概览
获取趋势数据	GET	/admin-api/ai/music/statistics/trend	按天/周/月趋势
获取风格分布	GET	/admin-api/ai/music/statistics/style-distribution	风格使用占比
获取用户排行	GET	/admin-api/ai/music/statistics/user-ranking	Token 消耗排行
获取模型使用分布	GET	/admin-api/ai/music/statistics/model-distribution	模型使用占比

3.5 AI 音乐生成（前台用户端）

描述

用户通过输入歌词或文字描述生成完整音乐作品。支持选择音乐风格、设置时长、选择模型等。

页面原型：AI 音乐创作页面

操作流程

用户进入"AI 音乐"页面
选择生成模式：
- 歌词模式：输入或 AI 生成歌词 → 选择风格 → 生成音乐
- 描述模式：输入音乐描述 → 选择风格 → 生成纯音乐/配乐
选择音乐风格（流行/摇滚/古典/电子/民谣/爵士/嘻哈/乡村等）
可选配置：
- 歌曲时长（30 秒/60 秒/120 秒/180 秒）
- 是否含人声（纯音乐/含人声）
- 语速（慢/中/快）
- 情绪（欢快/悲伤/激昂/平静）
选择音乐模型
点击"生成"按钮
系统扣减 Token → 创建任务 → 异步调用模型 API
页面显示生成进度
生成完成后自动播放试听
用户可"保存到我的音乐"、"下载"、"分享"

业务规则

规则	说明	设计原因
歌词长度上限	不超过 2000 字	Suno 等服务商有输入长度限制，超出会截断
描述长度上限	不超过 500 字	描述模式仅需风格/氛围关键词，无需长文本
余额前置校验	生成前校验用户 Token/余额是否充足	避免生成完成后无法扣减导致资损
超时自动退还	任务超时 5 分钟自动失败并退还 Token	非用户原因失败不应扣费
多版本生成	支持同一歌词/描述生成最多 4 个版本	给用户选择空间，提升满意度
自动播放	生成完成后自动进入在线播放	减少操作步骤，提升体验
描述模式无人声	描述模式默认生成纯音乐	描述模式用于配乐场景，通常不需要人声

接口列表

接口名称	请求方式	接口路径	说明
提交歌词生成任务	POST	/app-api/ai/music/generate/lyrics	通过歌词生成音乐
提交描述生成任务	POST	/app-api/ai/music/generate/describe	通过描述生成纯音乐
查询任务状态	GET	/app-api/ai/music/task/{taskId}/status	轮询任务进度
获取任务结果	GET	/app-api/ai/music/task/{taskId}/result	获取生成结果
获取可用模型列表	GET	/app-api/ai/music/models	用户端模型下拉
获取风格列表	GET	/app-api/ai/music/styles	可选风格列表
取消任务	PUT	/app-api/ai/music/task/{taskId}/cancel	取消排队中的任务

3.6 音乐风格选择（前台用户端）

描述

提供丰富的音乐风格预设，用户可快速选择适合的风格进行创作。支持风格预览和组合。

操作流程

在生成音乐前，用户点击"选择风格"
展示风格分类列表（按场景/情绪/流派分类）
点击风格卡片可预览该风格的示例音乐
选择一种风格作为主风格
可选配置风格强度（轻度/中度/强烈）
确认后风格参数将附加到生成请求中

预设风格分类

分类维度	预设选项
流派（genre）	流行、摇滚、古典、电子、民谣、爵士、嘻哈、乡村、R&B、金属、朋克
场景（scene）	办公、运动、睡眠、学习、聚会、冥想、旅行
情绪（mood）	欢快、悲伤、激昂、平静、浪漫、紧张、温馨

业务规则

规则	说明	设计原因
风格试听	每种风格提供 3-5 秒试听片段	用户可快速了解风格效果，降低选择成本
风格组合	支持主风格 + 副风格组合	满足用户对混合风格的需求（如"电子+古典"）
后台可配置	风格数据后台可配置和管理	运营可根据用户反馈调整风格库
风格强度	支持轻度/中度/强烈三档	控制风格特征在生成音乐中的明显程度

接口列表

接口名称	请求方式	接口路径	说明
获取风格分类列表	GET	/app-api/ai/music/style/categories	风格分类及子项
风格试听	GET	/app-api/ai/music/style/{id}/preview	获取风格试听片段
获取推荐风格	GET	/app-api/ai/music/style/recommend	根据描述推荐风格

3.7 AI 辅助歌词生成（前台用户端）

描述

利用 AI 大模型辅助用户创作歌词，输入主题/描述即可生成完整歌词，用户可在此基础上修改后用于音乐生成。

页面原型：AI 写歌词弹窗

操作流程

用户点击"AI 写歌词"按钮
输入歌词主题/描述，如"毕业季，对青春的不舍和对未来的期待"
选择歌词风格：抒情/励志/叙事/说唱/古风/童谣等
选择歌词结构：主歌+副歌（标准）/ 主歌+副歌+桥段 / 自由格式
选择歌词语言：中文/英文/中英混合
点击"生成歌词"
AI 生成完整歌词文本
用户可在线编辑修改
可重新生成（不满意时）
确认后"使用此歌词"进入音乐生成流程

业务规则

规则	说明	设计原因
主题描述上限	不超过 500 字	给 AI 足够上下文即可，过长反而影响生成质量
固定 Token 消耗	每次生成歌词消耗 10 Token	歌词生成使用对话模型，成本远低于音乐生成
可编辑可重新生成	生成结果可编辑、可重新生成	给用户充分调整空间
歌词长度上限	歌词最大长度不超过 2000 字	与音乐生成的输入限制一致
草稿上限	最多保存 10 条歌词草稿	避免存储膨胀，同时满足基本管理需求
共享对话模型配额	歌词生成使用对话模型，与 AI 对话模块共享配额	歌词生成本质是文本生成，复用对话模型资源

接口列表

接口名称	请求方式	接口路径	说明
AI 生成歌词	POST	/app-api/ai/music/lyrics/generate	调用大模型生成歌词
保存歌词草稿	POST	/app-api/ai/music/lyrics/draft	保存歌词草稿
查询歌词草稿列表	GET	/app-api/ai/music/lyrics/drafts	获取歌词草稿
删除歌词草稿	DELETE	/app-api/ai/music/lyrics/draft/	删除指定草稿

3.8 音乐播放（前台用户端）

描述

内置音乐播放器，支持用户在线试听已生成的音乐作品，提供播放控制、进度展示、音质切换等功能。

操作流程

音乐生成完成后自动进入播放状态
用户在"我的音乐"中点击作品卡片也可开始播放
播放器控制栏支持：播放/暂停、上一首/下一首、进度拖拽、音量调节
支持音质切换：标准（128kbps）/ 高品质（320kbps）
歌词同步显示（如有歌词文本）
播放列表模式：可连续播放多首

业务规则

规则	说明	设计原因
HTML5 Audio 实现	播放器基于 HTML5 Audio API	无需安装插件，跨浏览器兼容
MP3 主格式	支持 MP3 格式播放	兼容性最好的音频格式
音质切换	支持标准/高品质两种音质	不同网络环境下用户可灵活选择
后台播放	切换页面不中断播放	用户浏览其他页面时音乐不中断
移动端媒体会话	适配系统媒体会话（锁屏控制）	移动端用户体验，锁屏可控制播放
歌词同步	支持 LRC 格式歌词同步显示	增强音乐欣赏体验

接口列表

接口名称	请求方式	接口路径	说明
获取音频播放地址	GET	/app-api/ai/music/play/	获取音频文件 URL
获取歌词文本	GET	/app-api/ai/music/{id}/lyrics	获取歌词（LRC 格式）
切换音质	GET	/app-api/ai/music/play/{id}/	获取指定音质 URL

3.9 我的音乐（前台用户端）

描述

用户管理个人 AI 生成的所有音乐作品，支持列表查看、分类筛选、下载、删除等操作。

页面原型：我的音乐列表页

操作流程

用户进入"我的音乐"页面
查看所有已生成的音乐作品（按时间倒序）
支持按风格、时间范围、关键词筛选
对作品可执行操作：在线播放、下载、删除、查看详情
查看详情：歌词、风格参数、生成时间、消耗 Token 数
支持批量操作：批量下载、批量删除

业务规则

规则	说明	设计原因
默认仅本人可见	作品默认仅本人可见	保护用户隐私
下载频率限制	每首音乐最多下载 10 次/天	防止批量下载后传播，保护版权
MP3 格式下载	下载文件格式为 MP3	兼容性最好的音频格式
逻辑删除	删除为逻辑删除，保留 30 天可恢复	防止误删，提供恢复窗口
存储上限	单用户最多保存 100 首（可配置）	控制存储成本，同时满足大部分用户需求
存储预警	存储空间达到 80% 时提醒用户清理	提前告知，避免存满后无法保存

接口列表

接口名称	请求方式	接口路径	说明
查询我的音乐列表	GET	/app-api/ai/music/my/list	分页查询我的音乐
查询作品详情	GET	/app-api/ai/music/my/	查看作品详情
下载音乐	GET	/app-api/ai/music/my/{id}/download	下载音频文件
删除音乐	DELETE	/app-api/ai/music/my/	逻辑删除作品
批量删除	DELETE	/app-api/ai/music/my/batch	批量逻辑删除
查询存储使用情况	GET	/app-api/ai/music/my/storage	查看已用/总存储

四、非功能需求

4.1 性能需求

指标	要求	实现策略
任务提交响应时间	≤ 500ms	异步处理，提交仅创建任务记录不入队等待
任务状态查询响应时间	≤ 200ms	任务状态缓存到 Redis，减少数据库查询
音乐生成最大等待时间	5 分钟	超时自动失败，定时任务扫描超时任务
任务轮询间隔	5 秒	前端定时轮询，避免过于频繁请求
歌词生成响应时间	≤ 30 秒	调用对话模型生成，流式返回
音频播放起播时间	≤ 2 秒	CDN 加速音频文件分发
音乐下载速度	≥ 500KB/s	对象存储直链下载，不经过应用服务器
并发任务处理能力	单模型 ≥ 30 任务/分钟	消息队列削峰填谷，控制并发上限
统计报表生成时间	≤ 5 秒	预计算 + 缓存，定时汇总

4.2 安全需求

安全项	要求	实现方式
API Key 存储	AES-256 加密存储	使用框架统一加密组件，密钥从环境变量读取
音频内容安全	生成内容经安全审核	调用内容安全审核接口，拦截违规内容
歌词内容安全	输入歌词需经敏感词过滤	接入敏感词库，提交前校验
接口鉴权	所有接口需登录鉴权，管理接口需角色鉴权	Spring Security + RBAC 权限体系
数据隔离	多租户数据严格隔离	MyBatis Plus 租户插件自动注入 tenant_id
音频防盗链	音频 URL 带签名，有效期 2 小时	对象存储签名 URL，过期自动失效
频率限制	单用户每分钟最多提交 5 个音乐任务	Redis 滑动窗口限流
下载频率限制	单用户每首音乐每天最多下载 10 次	Redis 计数器，每日零点重置
敏感信息脱敏	日志中不打印 API Key 等敏感信息	日志脱敏过滤器
版权合规	生成内容标注"AI 生成"水印	音频元数据写入 AI 生成标记

4.3 可用性需求

指标	要求
服务可用率	≥ 99.5%
第三方 API 降级	Suno API 不可用时自动切换到备用模型
任务恢复	服务重启后未完成任务自动恢复处理
数据备份	音频文件每日增量备份

4.4 错误码定义

错误码	说明	处理建议
AI_MUSIC_001	用户 Token 余额不足	提示用户充值或领取积分
AI_MUSIC_002	歌词长度超过限制	提示用户精简歌词，显示当前字数和上限
AI_MUSIC_003	描述长度超过限制	提示用户精简描述
AI_MUSIC_004	音乐模型不可用	提示用户切换其他模型，通知管理员
AI_MUSIC_005	任务提交频率超限	提示用户稍后再试，显示剩余等待时间
AI_MUSIC_006	任务不存在或已过期	提示用户刷新列表
AI_MUSIC_007	下载次数已达上限	提示用户明天再下载
AI_MUSIC_008	存储空间已满	提示用户删除不需要的作品释放空间
AI_MUSIC_009	音频文件已过期	提示用户重新生成或联系管理员

五、数据设计

5.1 数据表概览

表名	说明	核心字段
ai_music_model	音乐模型配置表	provider, model_name, api_key, token_cost_per_minute, max_duration
ai_music_task	音乐任务表	user_id, task_type, prompt/lyrics, style, status, result_urls
ai_music	音乐作品表	user_id, task_id, title, audio_url, style, duration
ai_music_style	音乐风格表	category, name, label, preview_url
ai_music_lyrics_draft	歌词草稿表	user_id, title, content, theme, style

5.2 表关系

音乐表关系

5.3 缓存策略

缓存 Key	数据内容	过期时间	更新策略
ai:music:model:list	启用状态的模型列表	30 分钟	模型配置变更时主动失效
ai:music:model:default	默认模型配置	30 分钟	默认模型变更时主动失效
ai:music:task:status:	任务状态和进度	10 分钟	任务状态变更时更新
ai:music:style:list	启用的风格列表	1 小时	风格配置变更时主动失效
ai:music:rate:limit:	用户提交频率计数	1 分钟	滑动窗口自动过期

5.4 核心数据表结构

ai_music_task 音乐任务表

字段名	字段类型	是否必填	说明
id	BIGINT	是	主键 ID
user_id	BIGINT	是	用户 ID
provider	VARCHAR(50)	是	服务商标识（suno/udio 等）
model	VARCHAR(100)	是	模型名称
task_type	VARCHAR(30)	是	任务类型（lyrics/describe/lyrics_gen）
prompt	TEXT	否	文字描述（描述模式时使用）
lyrics	TEXT	否	歌词文本（歌词模式时使用）
style	VARCHAR(100)	否	音乐风格
sub_style	VARCHAR(100)	否	副风格
style_intensity	VARCHAR(20)	否	风格强度（light/medium/strong）
mood	VARCHAR(50)	否	情绪标签
duration	INT	否	目标时长（秒）
has_vocal	TINYINT	否	是否含人声（0 否 1 是）
tempo	VARCHAR(20)	否	语速（slow/medium/fast）
language	VARCHAR(20)	否	语言（zh/en/mixed）
generate_count	INT	否	生成数量（1-4）
result_urls	TEXT	否	生成结果音频 URL 列表（JSON 数组）
result_lyrics	TEXT	否	生成结果歌词文本
status	TINYINT	是	任务状态（0 待处理 1 处理中 2 已完成 3 失败 4 已取消）
progress	INT	否	进度百分比（0-100）
token_cost	INT	否	本次消耗 Token 数
error_message	VARCHAR(500)	否	失败原因
cost_time	INT	否	耗时（毫秒）
external_task_id	VARCHAR(200)	否	第三方平台任务 ID
params	JSON	否	扩展参数（JSON 格式）
creator	VARCHAR(64)	否	创建者
create_time	DATETIME	否	创建时间
updater	VARCHAR(64)	否	更新者
update_time	DATETIME	否	更新时间
deleted	BIT	否	是否删除（0 否 1 是）
tenant_id	BIGINT	否	租户 ID

ai_music 音乐作品表

字段名	字段类型	是否必填	说明
id	BIGINT	是	主键 ID
user_id	BIGINT	是	用户 ID
task_id	BIGINT	是	关联任务 ID
title	VARCHAR(200)	否	音乐标题
provider	VARCHAR(50)	是	服务商标识
model	VARCHAR(100)	是	模型名称
style	VARCHAR(100)	否	音乐风格
mood	VARCHAR(50)	否	情绪标签
lyrics	TEXT	否	歌词文本
audio_url	VARCHAR(1000)	是	音频文件 URL
audio_url_hq	VARCHAR(1000)	否	高品质音频 URL
cover_url	VARCHAR(1000)	否	封面图 URL
duration	INT	否	音频时长（秒）
file_size	BIGINT	否	文件大小（字节）
format	VARCHAR(20)	否	音频格式（mp3/wav）
sample_rate	INT	否	采样率（Hz）
bitrate	INT	否	比特率（kbps）
status	TINYINT	是	状态（0 正常 1 已删除）
download_count	INT	否	下载次数
play_count	INT	否	播放次数
is_published	TINYINT	否	是否发布到社区
audit_status	TINYINT	否	审核状态（0 待审核 1 通过 2 驳回）
params	JSON	否	生成参数快照
creator	VARCHAR(64)	否	创建者
create_time	DATETIME	否	创建时间
updater	VARCHAR(64)	否	更新者
update_time	DATETIME	否	更新时间
deleted	BIT	否	是否删除（0 否 1 是）
tenant_id	BIGINT	否	租户 ID

ai_music_style 音乐风格表

字段名	字段类型	是否必填	说明
id	BIGINT	是	主键 ID
category	VARCHAR(50)	是	分类（genre/scene/mood）
name	VARCHAR(100)	是	风格名称
label	VARCHAR(100)	是	显示名称
description	VARCHAR(500)	否	风格描述
icon	VARCHAR(200)	否	风格图标
preview_url	VARCHAR(1000)	否	试听片段 URL
sort	INT	否	排序值
status	TINYINT	是	状态（0 禁用 1 启用）
creator	VARCHAR(64)	否	创建者
create_time	DATETIME	否	创建时间
updater	VARCHAR(64)	否	更新者
update_time	DATETIME	否	更新时间
deleted	BIT	否	是否删除

ai_music_lyrics_draft 歌词草稿表

字段名	字段类型	是否必填	说明
id	BIGINT	是	主键 ID
user_id	BIGINT	是	用户 ID
title	VARCHAR(200)	否	草稿标题
content	TEXT	是	歌词内容
theme	VARCHAR(200)	否	主题描述
style	VARCHAR(50)	否	歌词风格
language	VARCHAR(20)	否	语言
creator	VARCHAR(64)	否	创建者
create_time	DATETIME	否	创建时间
updater	VARCHAR(64)	否	更新者
update_time	DATETIME	否	更新时间
deleted	BIT	否	是否删除

六、跨模块联动

6.1 联动关系总览

关联模块	联动方向	联动说明
AI 模型管理（07-01）	AI 音乐 → AI 模型管理	读取模型配置，统一模型调度
会员积分（05-02）	AI 音乐 → 会员积分	Token 扣减与充值
钱包管理（04-02）	AI 音乐 → 钱包管理	Token 购买与消费记录
AI 对话（07-01）	AI 音乐 → AI 对话	歌词生成复用对话模型
统计分析	AI 音乐 → 统计分析	生成数据汇入全局统计

6.2 详细联动设计

AI 音乐 ↔ AI 模型管理（07-01）

联动场景	触发条件	联动行为	数据流向
获取可用模型	用户进入创作页面	查询启用状态的音乐模型列表	AI 模型管理 → AI 音乐
模型配置变更	管理员修改模型参数	缓存失效，下次请求获取最新配置	AI 模型管理 → AI 音乐
模型连通性测试	管理员点击测试	调用模型 API 验证连通性	AI 模型管理 → 第三方 API

AI 音乐 ↔ 会员积分（05-02）

联动场景	触发条件	联动行为	数据流向
Token 扣减	用户提交音乐生成任务	扣减用户 Token 余额	AI 音乐 → 会员积分
Token 退还	任务超时/失败	退还已扣减的 Token	AI 音乐 → 会员积分
歌词生成扣减	用户生成歌词	扣减 10 Token（对话模型配额）	AI 音乐 → 会员积分
余额校验	用户点击生成	校验余额是否充足	AI 音乐 ← 会员积分

AI 音乐 ↔ 钱包管理（04-02）

联动场景	触发条件	联动行为	数据流向
消费记录	Token 扣减完成	写入钱包消费流水	AI 音乐 → 钱包管理
退还记录	Token 退还完成	写入钱包退还流水	AI 音乐 → 钱包管理

AI 音乐 → 统计分析

联动场景	触发条件	联动行为	数据流向
生成数据汇总	定时任务（每 5 分钟）	汇总生成次数、Token 消耗、风格分布	AI 音乐 → 统计分析
用户活跃度	用户完成音乐生成	更新用户活跃度指标	AI 音乐 → 统计分析

七、附录

7.1 名词解释

术语	说明	通俗理解
Suno	知名 AI 音乐生成服务商，支持文字/歌词生成完整音乐	音乐界的"AI 作曲家"，给它文字就能变出歌
Udio	AI 音乐生成服务商，提供高质量音乐生成能力	类似 Suno 的另一家"AI 作曲家"
歌词模式	用户提供歌词，AI 根据歌词内容生成配乐和演唱	你写词，AI 来谱曲+演唱
描述模式	用户用文字描述音乐风格/氛围，AI 生成纯音乐	你说"我要什么感觉"，AI 帮你做出来
风格（Style）	音乐流派特征，如流行、摇滚、电子等	就像选菜系——中餐、西餐、日料
情绪（Mood）	音乐的情感倾向，如欢快、悲伤、激昂	音乐给人的"感觉"——开心还是伤感
音质（Quality）	音频文件的采样精度，标准 128kbps / 高品质 320kbps	类似照片清晰度——标清 vs 高清
时长（Duration）	生成音乐的播放时长	这首歌有多长
Token	平台统一的 AI 资源计量单位	AI 服务的"话费"，用一次扣一点
LRC	歌词同步格式，包含时间戳的歌词文本	带时间轴的歌词，KTV 那种逐字显示效果
歌词草稿	用户编辑歌词时保存的临时版本	写歌词时的"草稿纸"，随时可以拿回来改
风格强度	风格特征在生成音乐中的明显程度（轻度/中度/强烈）	加多少"调味料"——清淡、适中、重口味
Spring AI	Spring 生态的 AI 集成框架	连接各种 AI 服务的"万能转接头"
音频防盗链	音频 URL 带签名，设置有效期	下载链接有时效，过期就不能用了
纯音乐	不含人声的音乐，仅由乐器演奏	没有歌手唱歌，只有乐器演奏
人声（Vocal）	音乐中包含的歌唱或说话声音	有歌手在唱歌

7.2 权限标识

权限标识	说明	所属角色
ai:music:model:list	查看音乐模型列表	系统管理员
ai:music:model:create	新增音乐模型	系统管理员
ai:music:model:update	修改音乐模型	系统管理员
ai:music:model:delete	删除音乐模型	系统管理员
ai:music:model:test	测试模型连通性	系统管理员
ai:music:task:list	查看音乐任务列表	运营人员、系统管理员
ai:music:task:cancel	取消音乐任务	运营人员
ai:music:task:retry	重试音乐任务	运营人员
ai:music:task:export	导出音乐任务	运营人员
ai:music:work:list	查看作品列表	运营人员
ai:music:work:audit	审核作品	运营人员
ai:music:work:recommend	推荐作品	运营人员
ai:music:work:offline	下架作品	运营人员
ai:music:style:list	查看风格列表	运营人员
ai:music:style:manage	管理风格配置	运营人员、系统管理员
ai:music:statistics:view	查看音乐统计	运营人员、系统管理员
ai:music:generate	使用 AI 音乐生成	所有登录用户
ai:music:lyrics:generate	使用 AI 歌词生成	所有登录用户
ai:music:my:list	查看我的音乐	所有登录用户
ai:music:my:download	下载音乐	所有登录用户

AI音乐 PRD ​

文档信息 ​

一、功能概述 ​

1.1 功能定位 ​

1.2 目标用户与使用频率 ​

1.3 业务价值 ​

1.4 功能范围 ​

二、用户场景 ​

2.1 用户角色 ​

2.2 使用场景 ​

场景1：音乐爱好者小李用歌词生成一首流行歌曲 ​

场景2：视频博主小王为 Vlog 生成背景音乐 ​

场景3：研学导师张老师为课程生成主题配乐 ​

场景4：运营人员小陈管理音乐任务和统计 ​

场景5：用户管理个人音乐库 ​

三、功能需求 ​

3.1 音乐模型管理（后台管理端） ​

描述 ​

操作流程 ​

业务规则 ​

接口列表 ​

3.2 音乐任务管理（后台管理端） ​

描述 ​

操作流程 ​

任务状态机 ​

业务规则 ​

接口列表 ​

3.3 音乐作品管理（后台管理端） ​

描述 ​

操作流程 ​

作品审核状态机 ​

业务规则 ​

接口列表 ​

3.4 音乐统计（后台管理端） ​

描述 ​

操作流程 ​

业务规则 ​

接口列表 ​

3.5 AI 音乐生成（前台用户端） ​

描述 ​

操作流程 ​

业务规则 ​

接口列表 ​

3.6 音乐风格选择（前台用户端） ​

描述 ​

操作流程 ​

预设风格分类 ​

业务规则 ​

接口列表 ​

3.7 AI 辅助歌词生成（前台用户端） ​

描述 ​

操作流程 ​

业务规则 ​

接口列表 ​

3.8 音乐播放（前台用户端） ​

描述 ​

操作流程 ​

业务规则 ​

接口列表 ​

3.9 我的音乐（前台用户端） ​

描述 ​

操作流程 ​

业务规则 ​

接口列表 ​

四、非功能需求 ​

4.1 性能需求 ​

4.2 安全需求 ​

4.3 可用性需求 ​

4.4 错误码定义 ​

五、数据设计 ​

5.1 数据表概览 ​

5.2 表关系 ​

5.3 缓存策略 ​

5.4 核心数据表结构 ​

ai_music_task 音乐任务表 ​

ai_music 音乐作品表 ​

ai_music_style 音乐风格表 ​

ai_music_lyrics_draft 歌词草稿表 ​

六、跨模块联动 ​

6.1 联动关系总览 ​

AI音乐 PRD

文档信息

一、功能概述

1.1 功能定位

1.2 目标用户与使用频率

1.3 业务价值

1.4 功能范围

二、用户场景

2.1 用户角色

2.2 使用场景

场景1：音乐爱好者小李用歌词生成一首流行歌曲

场景2：视频博主小王为 Vlog 生成背景音乐

场景3：研学导师张老师为课程生成主题配乐

场景4：运营人员小陈管理音乐任务和统计

场景5：用户管理个人音乐库

三、功能需求

3.1 音乐模型管理（后台管理端）

描述

操作流程

业务规则

接口列表

3.2 音乐任务管理（后台管理端）

描述

操作流程

任务状态机

业务规则

接口列表

3.3 音乐作品管理（后台管理端）

描述

操作流程

作品审核状态机

业务规则

接口列表

3.4 音乐统计（后台管理端）

描述

操作流程

业务规则

接口列表

3.5 AI 音乐生成（前台用户端）

描述

操作流程

业务规则

接口列表

3.6 音乐风格选择（前台用户端）

描述

操作流程

预设风格分类

业务规则

接口列表

3.7 AI 辅助歌词生成（前台用户端）

描述

操作流程

业务规则

接口列表

3.8 音乐播放（前台用户端）

描述

操作流程

业务规则

接口列表

3.9 我的音乐（前台用户端）

描述

操作流程

业务规则

接口列表

四、非功能需求

4.1 性能需求

4.2 安全需求

4.3 可用性需求

4.4 错误码定义

五、数据设计

5.1 数据表概览

5.2 表关系

5.3 缓存策略

5.4 核心数据表结构

ai_music_task 音乐任务表

ai_music 音乐作品表

ai_music_style 音乐风格表

ai_music_lyrics_draft 歌词草稿表

六、跨模块联动

6.1 联动关系总览