TrueGrowth/specs/009-media-library/spec.md

Feature Specification: 素材管理库 (Media Library)

Feature Branch: 009-media-library Created: 2025-12-11 Status: Draft Input: User description: "目前需要新增一个 素材管理 功能， 分析项目，然后目前该功能能够对应可以生成 ai 图片,视频 等 ,可以上传图片等资源,然后现在 是一个 前端项目,目前没有涉及后端,用的是 react 框架 ,然后对应有一版参考样式：注意只之用提取素材管理部分，也就是 Media Library 部分的功能 和样式 ，对应的参考代码在 /Users/gongchengtu/code/github/asset-manager 这个路径下。然后需要注意本项目中，ai生成的图片/视频的进入这个素材库 的对应处理方案，本地上传的图片、生成的图片、视频皆是素材,就是目前有一个ai 生图 和生视频的画板，里面有个选择参考图片，然后目前是默认点击后是直接打开本地项目夹进行图片资源选择，然后现在我要增加一个选择，也就是当前的素材库的选择，当用户点击素材库 的时候,会打开素材管理库 , 可以便捷选择 已有素材,同时 也有选择本地文件的功能。请你帮我设计和开发，然后说明文档 用中文概括描写"

Clarifications

Session 2025-12-11

• Q: 素材库访问入口 (Access Points) - 用户如何打开素材库进行浏览和管理？ → A: 仅通过AI生成对话框访问。素材库没有独立的主界面入口，只能在AI生图/生视频对话框中点击"选择参考图"时打开。
• Q: 删除确认机制 (Delete Confirmation) - 用户删除素材时需要什么样的确认机制？ → A: 弹出确认对话框。用户点击删除按钮后，显示确认对话框警告删除操作不可撤销，用户需要在对话框中确认才能完成删除。
• Q: 存储空间监控 (Storage Monitoring) - 如何向用户显示和管理浏览器存储空间使用情况？ → A: 显示容量指示器和警告。在素材库界面底部显示存储空间使用进度条，当使用量达到80%时显示警告提示用户清理空间。

User Scenarios & Testing (mandatory)

用户场景 1 - 浏览和管理已有素材 (Priority: P1)

作为画板用户，我需要能够查看和管理我的所有素材（包括AI生成的图片/视频和本地上传的文件），以便我可以复用之前的创作内容，而不需要重复生成或上传。用户通过AI生成对话框中的"选择参考图"功能访问素材库。

此优先级的原因: 这是素材管理的核心功能，用户必须能够看到和访问自己的素材库才能进行后续的选择和管理操作。这是最基础的价值交付。

独立测试: 可以通过在AI生成对话框中点击"选择参考图"按钮打开素材库界面，验证能够显示所有历史素材（AI生成和本地上传的图片/视频），并支持基本的浏览和分类查看功能。

验收场景:

1. Given 用户已经通过AI生成了3张图片和1个视频，When 用户在AI生成对话框中打开素材库，Then 应该能看到这4个素材按时间倒序排列显示
2. Given 用户在素材库中，When 用户点击"类型"筛选器选择"图片"，Then 只显示图片类型的素材
3. Given 用户在素材库中，When 用户点击"来源"筛选器选择"AI生成"，Then 只显示AI生成的素材
4. Given 用户选中一个素材，When 用户查看右侧检查面板，Then 应该显示素材的详细信息（名称、类型、来源、创建时间、预览图）
5. Given 用户在素材库中有20个素材，When 用户在搜索框输入素材名称的关键词，Then 只显示匹配搜索关键词的素材

---

用户场景 2 - 从素材库选择参考图片用于AI生成 (Priority: P1)

作为AI生图/生视频的用户，我需要在生成时从素材库中快速选择已有的图片作为参考图，而不是每次都从本地文件夹中寻找，以便提高创作效率。

此优先级的原因: 这是本功能的主要业务价值 - 打通素材库与AI生成流程，让用户可以复用已有素材。这直接解决了用户的痛点（每次都要从本地选择文件）。

独立测试: 可以通过在AI生图/生视频对话框中点击选择参考图按钮，验证能够打开素材库选择界面，选中素材后能够正确应用到生成参数中。

验收场景:

1. Given 用户在AI生图对话框中，When 用户点击"选择参考图"按钮，Then 应该弹出选择来源的菜单（"从素材库选择" 和 "从本地文件选择"）
2. Given 用户选择了"从素材库选择"选项，When 选择操作完成，Then 应该打开素材库弹窗并且只显示图片类型的素材
3. Given 用户在素材库弹窗中，When 用户双击某个图片素材或点击"使用到画板"按钮，Then 该素材应该被应用为参考图，弹窗关闭，并在AI生成界面显示该参考图
4. Given 用户在素材库弹窗中，When 用户点击"选择本地文件"按钮，Then 应该打开系统文件选择对话框，用户可以从本地上传新图片
5. Given 用户在AI生视频对话框中选择参考图，When 打开素材库，Then 只应该显示图片类型的素材（视频不能作为参考图）

---

用户场景 3 - 上传新素材到素材库 (Priority: P2)

作为用户，我需要能够直接向素材库上传本地的图片和视频文件，以便统一管理我的所有素材资源。

此优先级的原因: 这是素材库的重要功能，但优先级低于查看和选择功能。用户可以通过AI生成界面间接上传（场景2中的"选择本地文件"），但直接在素材库上传能提供更好的体验。

独立测试: 可以通过打开素材库，点击上传按钮或拖拽文件到界面，验证文件能够成功添加到素材库并正确显示。

验收场景:

1. Given 用户在素材库界面，When 用户点击"上传"按钮并选择本地图片文件，Then 该文件应该被添加到素材库，标记为"本地上传"来源
2. Given 用户在素材库界面，When 用户从桌面拖拽一个图片文件到素材库区域，Then 该文件应该被上传并添加到素材库
3. Given 用户拖拽文件到素材库区域，When 拖拽进行中，Then 应该显示拖放区域的视觉提示
4. Given 用户上传了一个文件，When 上传完成，Then 新素材应该出现在素材列表的最前面（最新创建）

---

用户场景 4 - 管理素材（重命名、删除、下载） (Priority: P2)

作为用户，我需要能够对素材进行基本的管理操作（重命名、删除、下载），以便保持素材库的整洁和组织性。

此优先级的原因: 这些是素材管理的辅助功能，对于用户体验很重要，但不影响核心的查看和选择流程。

独立测试: 可以通过选中素材，验证能够成功执行重命名、删除和下载操作，并且操作结果正确反映在素材库中。

验收场景:

1. Given 用户选中了一个素材，When 用户点击名称旁边的编辑按钮并输入新名称，Then 素材名称应该被更新
2. Given 用户选中了一个素材，When 用户点击"删除"按钮，Then 应该弹出确认对话框，提示"删除后无法恢复，确认删除该素材？"
3. Given 用户在删除确认对话框中，When 用户点击"确认"按钮，Then 该素材应该从素材库中移除
4. Given 用户在删除确认对话框中，When 用户点击"取消"按钮，Then 对话框关闭，素材保留不被删除
5. Given 用户选中了一个素材，When 用户点击"下载"按钮，Then 该素材文件应该被下载到用户的本地设备
6. Given 用户在AI生成对话框中已经使用了某个素材作为参考图，When 该素材在素材库中被删除，Then AI生成对话框中的参考图仍然可以使用（因为已经加载）

---

用户场景 5 - AI生成的内容自动进入素材库 (Priority: P1)

作为用户，当我使用AI生成图片或视频时，生成的内容应该自动保存到素材库中，以便我后续可以复用这些内容。

此优先级的原因: 这是素材库与现有AI生成功能集成的关键，确保用户不会丢失生成的内容，并且能够积累素材资产。这是P1因为它是素材库价值的基础。

独立测试: 可以通过执行AI生成任务，验证生成成功后的图片/视频能够自动出现在素材库中，并标记为"AI生成"来源。

验收场景:

1. Given 用户通过AI生图功能成功生成了一张图片，When 生成完成，Then 该图片应该自动添加到素材库，来源标记为"AI生成"
2. Given 用户通过AI生视频功能成功生成了一个视频，When 生成完成，Then 该视频应该自动添加到素材库，来源标记为"AI生成"
3. Given 用户生成的图片名称为空或使用默认名称，When 添加到素材库，Then 应该使用生成时的提示词前20个字符作为名称，或使用"AI图片-日期时间"格式
4. Given AI生成任务失败，When 任务失败，Then 不应该在素材库中创建素材条目
5. Given 用户的素材库中已有100个素材，When 新的AI生成内容添加，Then 应该正常添加（不设置数量限制，但需要考虑浏览器存储限制）

---

边界情况

• 素材库中没有任何素材时，显示什么内容？（显示空状态提示，引导用户上传或生成素材）
• 用户上传的文件格式不支持（非图片/视频）时如何处理？（显示错误提示，只接受图片和视频格式）
• 用户上传的文件过大（如视频超过100MB）时如何处理？（显示警告，但仍然允许上传到浏览器存储）
• 浏览器存储空间不足时如何处理？（捕获存储错误，提示用户清理旧素材或下载后删除；同时在界面底部显示存储使用进度条，80%时主动警告）
• 用户在AI生成界面选择了参考图后又取消操作，素材库应该如何关闭？（点击关闭按钮或蒙层关闭素材库弹窗）
• 素材的缩略图加载失败时如何显示？（显示占位图标或默认图标）
• 用户快速连续生成多个AI内容时，素材库是否能够正确同步？（通过监听任务队列状态，确保所有成功的生成结果都能添加）
• 用户刷新页面后，素材库数据是否能够持久化？（使用IndexedDB持久化存储）
• 素材库弹窗在移动端如何显示？（响应式布局，在小屏幕上调整为单列布局，侧边栏可折叠）
• 用户删除素材后能否撤销？（当前版本不支持撤销，通过确认对话框防止误删除）

Requirements (mandatory)

Functional Requirements

• FR-001: 系统必须提供一个素材库弹窗组件，用于展示所有用户的素材（图片和视频）
• FR-001-A: 素材库弹窗只能通过AI生成对话框（AI生图/生视频）中的"选择参考图"功能打开，不提供独立的主界面入口
• FR-002: 系统必须支持按类型筛选素材（全部、图片、视频）
• FR-003: 系统必须支持按来源筛选素材（全部、本地上传、AI生成）
• FR-004: 系统必须支持通过名称搜索素材（实时搜索，不区分大小写）
• FR-005: 系统必须支持按日期排序素材（最新优先、最旧优先）和按名称排序（A-Z）
• FR-006: 系统必须在用户点击素材时显示详细信息（名称、类型、来源、创建时间、预览）
• FR-007: 系统必须支持用户重命名素材
• FR-008: 系统必须支持用户删除素材，删除前必须显示确认对话框警告操作不可撤销
• FR-009: 系统必须支持用户下载素材到本地设备
• FR-010: 系统必须支持用户通过点击按钮上传本地图片或视频文件
• FR-011: 系统必须支持用户通过拖拽方式上传本地文件到素材库
• FR-012: 系统必须在AI生图/生视频对话框的"选择参考图"功能中集成素材库选择选项
• FR-013: 当用户选择"从素材库选择"时，系统必须打开素材库弹窗并默认筛选为图片类型
• FR-014: 用户在素材库中双击素材或点击"使用到画板"按钮时，系统必须将该素材应用到AI生成参数中
• FR-015: 系统必须在AI生成任务成功完成时自动将生成的图片/视频添加到素材库
• FR-016: 自动添加的AI生成素材必须标记来源为"AI生成"，并使用合适的默认名称
• FR-017: 系统必须使用浏览器本地存储（IndexedDB）持久化素材数据
• FR-018: 系统必须显示素材库中的素材总数
• FR-019: 系统必须在素材上显示类型标识（图片图标或视频图标）
• FR-020: 系统必须在AI生成的素材上显示"AI"标识
• FR-021: 素材库界面必须支持响应式布局，在不同屏幕尺寸下可用
• FR-022: 系统必须在上传文件时验证文件类型（只接受图片和视频格式）
• FR-023: 系统必须在拖拽文件进入素材库区域时显示视觉反馈
• FR-024: 系统必须处理存储错误并向用户显示友好的错误提示
• FR-024-A: 系统必须在素材库界面底部显示浏览器存储空间使用进度条
• FR-024-B: 系统必须在存储空间使用量达到80%时显示警告消息，提示用户清理空间（删除或下载后删除旧素材）
• FR-025: 素材库弹窗必须提供关闭功能（点击关闭按钮或点击蒙层）

Key Entities

• 素材 (Asset): 代表用户的媒体资源

  • 唯一标识符 (id)
  • 类型 (type): IMAGE 或 VIDEO
  • 来源 (source): LOCAL（本地上传）或 AI_GENERATED（AI生成）
  • 存储位置 (url): Blob URL 用于浏览器中显示
  • 名称 (name): 用户可见的素材名称
  • 创建时间 (createdAt): 时间戳
  • MIME类型 (mimeType): 文件的媒体类型

• 素材库状态 (AssetStore): 管理所有素材的集合和操作

  • 素材列表 (assets): 所有素材的数组
  • 添加素材 (addAsset): 添加新素材到库中
  • 删除素材 (removeAsset): 从库中移除素材
  • 重命名素材 (renameAsset): 更新素材名称
  • 按类型获取 (getAssetsByType): 筛选特定类型的素材

• 筛选器状态 (FilterState): 控制素材库的显示筛选

  • 活动类型 (activeType): 当前选中的类型筛选器
  • 活动来源 (activeSource): 当前选中的来源筛选器
  • 搜索查询 (searchQuery): 搜索关键词
  • 排序方式 (sortBy): 排序规则

• 选择模式 (SelectionMode): 素材库的使用场景

  • 浏览模式: 用户打开素材库仅查看和管理素材
  • 选择模式: 从AI生成界面打开，需要选择素材作为参考图

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: 用户可以在3秒内从素材库中找到并选择所需的素材（通过搜索和筛选）
• SC-002: 用户从AI生成界面选择参考图的操作步骤从2步（打开文件选择器→选择文件）减少到2步（打开素材库→选择素材），但选择体验更流畅
• SC-003: 90%的AI生成内容能够自动保存到素材库并可在后续访问
• SC-004: 素材库支持存储至少100个素材而不影响界面响应速度（初始加载时间<2秒，筛选和搜索响应<500ms）
• SC-005: 用户上传素材的成功率达到95%以上（排除文件格式错误）
• SC-006: 素材库界面在桌面端（1920x1080）和移动端（375x667）都能正常使用
• SC-007: 用户能够在5秒内完成素材的重命名或删除操作
• SC-008: 素材数据在浏览器关闭后能够100%持久化保存（使用IndexedDB）
• SC-009: 从素材库选择参考图的用户使用率在功能上线后达到40%以上（相对于从本地选择）
• SC-010: 用户对素材库功能的满意度评分达到4.0/5.0以上

Assumptions (mandatory)

• 所有素材数据存储在浏览器的IndexedDB中，不涉及服务器端存储
• 用户使用现代浏览器（Chrome, Firefox, Safari, Edge最新版本），支持IndexedDB和Blob URL
• 素材文件以Blob形式存储在浏览器中，存储容量取决于浏览器限制（通常为50MB-500MB）
• AI生成的图片和视频已经由现有的生成服务处理，素材库只需要接收结果并存储
• 素材的缩略图使用原始文件的URL直接显示，不需要单独生成缩略图
• 用户不需要对素材进行高级编辑（如裁剪、旋转），只需要选择和使用
• 素材库的界面设计参考asset-manager项目的MediaLibraryModal组件风格
• 视频素材在网格视图中不会自动播放，只在选中后的检查面板中可以播放
• 素材库中的素材删除是永久性的，不提供回收站功能
• 用户的素材不会在不同设备或浏览器之间同步（纯本地存储）

Dependencies (mandatory)

• 依赖现有的IndexedDB存储服务或需要创建新的素材存储服务
• 依赖现有的AI图片生成服务 (generation-api-service.ts) 和视频生成服务 (video-api-service.ts)
• 依赖现有的任务队列服务 (task-queue-service.ts) 来监听AI生成任务的完成状态
• 依赖TDesign React UI组件库用于界面元素
• 依赖现有的AI生图对话框组件 (ai-image-generation.tsx) 和生视频对话框组件 (ai-video-generation.tsx)
• 可能依赖现有的media-cache-service.ts用于素材缓存管理
• 需要DrawnixContext支持素材库弹窗的打开/关闭状态管理

Out of Scope (mandatory)

• 素材的云端存储和跨设备同步
• 素材的高级编辑功能（裁剪、旋转、滤镜等）
• 素材的批量操作（批量删除、批量下载、批量重命名）
• 素材的文件夹/分类管理（标签、收藏夹等）
• 素材的版本历史管理
• 素材的共享功能（分享给其他用户）
• 素材的权限管理（公开/私有）
• 自动为视频生成缩略图（使用视频第一帧或中间帧）
• 素材的详细元数据编辑（描述、标签、评分等）
• 素材库的导出/导入功能（打包所有素材）
• 素材的使用统计（被引用次数、使用频率等）
• 自动素材清理建议（基于使用频率或年龄的智能清理推荐）