214 lines
9.3 KiB
Markdown
214 lines
9.3 KiB
Markdown
# Implementation Plan: 素材管理库 (Media Library)
|
||
|
||
**Branch**: `009-media-library` | **Date**: 2025-12-11 | **Spec**: [spec.md](./spec.md)
|
||
**Input**: Feature specification from `/specs/009-media-library/spec.md`
|
||
|
||
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
|
||
|
||
## Summary
|
||
|
||
实现一个素材管理库功能，允许用户通过AI生成对话框访问、浏览、管理和选择媒体素材（图片和视频）。素材库使用IndexedDB进行本地持久化存储，支持按类型和来源筛选、搜索、排序，以及重命名、删除和下载操作。AI生成的内容将自动添加到素材库中，用户可以从素材库中选择已有素材作为参考图，无需每次都从本地文件系统选择。
|
||
|
||
## Technical Context
|
||
|
||
**Language/Version**: TypeScript 5.x (strict mode), React 18.x
|
||
**Primary Dependencies**:
|
||
- TDesign React (UI components, light theme)
|
||
- Plait Framework (existing whiteboard core)
|
||
- localforage (IndexedDB wrapper for storage)
|
||
- RxJS (reactive state management)
|
||
- Vite (build tool)
|
||
|
||
**Storage**: IndexedDB (via localforage) for:
|
||
- Asset metadata and Blob URLs
|
||
- Asset data persistence across browser sessions
|
||
- Storage quota monitoring
|
||
|
||
**Testing**:
|
||
- React Testing Library (component tests)
|
||
- Jest (unit tests)
|
||
- Playwright (E2E tests for key flows)
|
||
|
||
**Target Platform**: Modern web browsers (Chrome, Firefox, Safari, Edge latest versions) supporting IndexedDB and Blob URLs
|
||
|
||
**Project Type**: Monorepo web application (Nx workspace)
|
||
|
||
**Performance Goals**:
|
||
- Initial load time < 2 seconds (for 100 assets)
|
||
- Filter/search response < 500ms
|
||
- Support至少 100 assets without degrading UI responsiveness
|
||
|
||
**Constraints**:
|
||
- No backend - pure frontend solution
|
||
- Browser storage limits (50MB-500MB depending on browser)
|
||
- Single file size limit: 500 lines (per constitution)
|
||
- Access only through AI generation dialogs (no standalone entry point)
|
||
|
||
**Scale/Scope**:
|
||
- ~5-8 React components (modal, sidebar, grid, inspector, upload)
|
||
- 1 Context provider for asset state management
|
||
- 1 IndexedDB storage service
|
||
- Integration with 2 existing AI generation dialogs (image, video)
|
||
- Integration with existing task queue service for auto-save
|
||
|
||
## Constitution Check
|
||
|
||
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
||
|
||
### ✅ PASS: Plugin Architecture
|
||
- **Requirement**: 每个功能都应该实现为遵循 `withXxx` 模式的可组合插件
|
||
- **Status**: ✅ PASS - 素材管理库不是编辑器插件，而是UI功能模块，使用React Context模式进行状态管理。不违反插件架构原则。
|
||
|
||
### ✅ PASS: File Size Constraint (500 lines)
|
||
- **Requirement**: 单个文件不得超过 500 行（硬性约束）
|
||
- **Status**: ✅ PASS - 计划将组件分解为多个小文件：
|
||
- MediaLibraryModal.tsx (主容器 < 150 lines)
|
||
- MediaLibraryGrid.tsx (网格视图 < 200 lines)
|
||
- MediaLibrarySidebar.tsx (筛选侧边栏 < 150 lines)
|
||
- MediaLibraryInspector.tsx (详情面板 < 200 lines)
|
||
- AssetContext.tsx (状态管理 < 150 lines)
|
||
- asset-storage-service.ts (存储服务 < 250 lines)
|
||
- 各种小型组件和工具函数
|
||
|
||
### ✅ PASS: TypeScript Strict Mode
|
||
- **Requirement**: TypeScript 严格模式是强制性的
|
||
- **Status**: ✅ PASS - 所有新代码将使用 TypeScript 5.x strict mode，定义完整的接口和类型
|
||
|
||
### ✅ PASS: TDesign React & Light Theme
|
||
- **Requirement**: 所有 UI 组件必须使用 TDesign React 并采用 light 主题
|
||
- **Status**: ✅ PASS - 将使用TDesign组件（Dialog, Button, Input, Tooltip）并配置light主题
|
||
|
||
### ✅ PASS: Performance Optimization
|
||
- **Requirement**: 为用户体验进行优化（React.memo, useCallback, useMemo）
|
||
- **Status**: ✅ PASS - 将应用优化策略：
|
||
- 网格项组件使用 React.memo
|
||
- 事件处理器使用 useCallback
|
||
- 筛选后的素材列表使用 useMemo
|
||
- 考虑虚拟化（如果资产数量增长）
|
||
|
||
### ✅ PASS: Security & Validation
|
||
- **Requirement**: 验证和清理所有用户输入，文件上传验证
|
||
- **Status**: ✅ PASS - 将实现：
|
||
- 文件类型验证（仅图片和视频）
|
||
- MIME类型检查
|
||
- 存储错误处理
|
||
- 无硬编码敏感信息
|
||
|
||
### ✅ PASS: Monorepo Structure
|
||
- **Requirement**: 在 Nx monorepo 中保持清晰的分离
|
||
- **Status**: ✅ PASS - 新代码将放置在 `packages/drawnix/src/` 下：
|
||
- `components/media-library/` - UI组件
|
||
- `services/asset-storage-service.ts` - 存储服务
|
||
- `types/asset.types.ts` - 类型定义
|
||
- `hooks/useAssets.ts` - 自定义hook
|
||
|
||
### ✅ PASS: Naming Conventions
|
||
- **Requirement**: 严格的文件和代码命名约定
|
||
- **Status**: ✅ PASS - 将遵循：
|
||
- 组件：PascalCase.tsx
|
||
- Hooks：camelCase.ts (useAssets.ts)
|
||
- 服务：kebab-case.ts (asset-storage-service.ts)
|
||
- 类型：kebab-case.types.ts (asset.types.ts)
|
||
|
||
### ✅ PASS: Component Structure
|
||
- **Requirement**: React组件遵循标准结构顺序
|
||
- **Status**: ✅ PASS - 所有组件将遵循：导入 → 类型 → 常量 → Hooks → 事件处理器 → 渲染
|
||
|
||
### ✅ PASS: Testing Requirements
|
||
- **Requirement**: 单元测试、组件测试、集成测试、E2E测试
|
||
- **Status**: ✅ PASS - 测试计划：
|
||
- 单元测试：asset-storage-service.ts
|
||
- 组件测试：所有React组件
|
||
- 集成测试：与AI生成对话框的集成
|
||
- E2E测试：完整的选择和上传流程
|
||
|
||
### ✅ PASS: CSS/SCSS Standards
|
||
- **Requirement**: 遵循 BEM 方法论
|
||
- **Status**: ✅ PASS - 将使用BEM命名，CSS变量优先
|
||
|
||
### ✅ PASS: Git Commit Convention
|
||
- **Requirement**: 遵循 Conventional Commits
|
||
- **Status**: ✅ PASS - 提交格式：`feat(media-library): <description>`
|
||
|
||
**GATE RESULT: ✅ ALL GATES PASSED - Proceed to Phase 0**
|
||
|
||
## Project Structure
|
||
|
||
### Documentation (this feature)
|
||
|
||
```text
|
||
specs/009-media-library/
|
||
├── spec.md # Feature specification
|
||
├── plan.md # This file (/speckit.plan command output)
|
||
├── research.md # Phase 0 output (技术决策和最佳实践)
|
||
├── data-model.md # Phase 1 output (数据模型定义)
|
||
├── quickstart.md # Phase 1 output (快速开始指南)
|
||
├── contracts/ # Phase 1 output (接口契约)
|
||
│ └── asset-store-api.md
|
||
└── tasks.md # Phase 2 output (/speckit.tasks command - NOT YET CREATED)
|
||
```
|
||
|
||
### Source Code (repository root)
|
||
|
||
```text
|
||
packages/drawnix/src/
|
||
├── components/
|
||
│ └── media-library/
|
||
│ ├── MediaLibraryModal.tsx # 主弹窗容器组件
|
||
│ ├── MediaLibraryModal.scss # 弹窗样式
|
||
│ ├── MediaLibraryGrid.tsx # 网格视图组件
|
||
│ ├── MediaLibraryGrid.scss # 网格样式
|
||
│ ├── MediaLibrarySidebar.tsx # 左侧筛选侧边栏
|
||
│ ├── MediaLibrarySidebar.scss # 侧边栏样式
|
||
│ ├── MediaLibraryInspector.tsx # 右侧详情面板
|
||
│ ├── MediaLibraryInspector.scss # 详情面板样式
|
||
│ ├── MediaLibraryEmpty.tsx # 空状态组件
|
||
│ ├── MediaLibraryStorageBar.tsx # 存储空间进度条
|
||
│ ├── AssetGridItem.tsx # 单个素材网格项
|
||
│ ├── AssetGridItem.scss # 网格项样式
|
||
│ └── index.ts # 导出
|
||
├── contexts/
|
||
│ └── AssetContext.tsx # 素材状态管理Context
|
||
├── services/
|
||
│ ├── asset-storage-service.ts # IndexedDB存储服务
|
||
│ └── asset-integration-service.ts # 与AI生成服务集成
|
||
├── hooks/
|
||
│ ├── useAssets.ts # 素材管理hook
|
||
│ └── useAssetSelection.ts # 素材选择hook
|
||
├── types/
|
||
│ └── asset.types.ts # 素材相关类型定义
|
||
├── utils/
|
||
│ ├── asset-utils.ts # 素材工具函数
|
||
│ └── storage-quota.ts # 存储配额工具
|
||
└── constants/
|
||
└── ASSET_CONSTANTS.ts # 素材相关常量
|
||
|
||
packages/drawnix/src/components/ttd-dialog/
|
||
├── ai-image-generation.tsx # [MODIFY] 集成素材库选择
|
||
└── ai-video-generation.tsx # [MODIFY] 集成素材库选择
|
||
|
||
tests/
|
||
└── media-library/
|
||
├── unit/
|
||
│ ├── asset-storage-service.spec.ts
|
||
│ ├── asset-utils.spec.ts
|
||
│ └── storage-quota.spec.ts
|
||
├── component/
|
||
│ ├── MediaLibraryModal.spec.tsx
|
||
│ ├── MediaLibraryGrid.spec.tsx
|
||
│ └── AssetGridItem.spec.tsx
|
||
├── integration/
|
||
│ └── ai-generation-integration.spec.tsx
|
||
└── e2e/
|
||
├── asset-upload.spec.ts
|
||
└── asset-selection.spec.ts
|
||
```
|
||
|
||
**Structure Decision**: 使用 monorepo 中的 `packages/drawnix` 包，遵循现有项目结构，将素材管理库功能作为独立模块添加到 `components/media-library/` 目录下。使用Context模式进行状态管理，与现有的服务层（`services/`）保持一致。组件将被分解为多个小文件以符合500行限制，每个组件负责单一职责（网格、侧边栏、详情面板等）。
|
||
|
||
## Complexity Tracking
|
||
|
||
> **No constitution violations - This section is empty**
|
||
|
||
所有宪章检查项均已通过，无需额外的复杂性理由说明。
|