design.md 3.59 KB

Raw Blame History Permalink



Design Document: Image History Management


Context

当前应用缺乏图片历史记录功能，用户生成图片后需要手动下载和管理。需要实现自动保存、管理和查看历史生成记录的功能，提升用户体验和工作效率。


Goals / Non-Goals

Goals:


自动保存所有生成的图片和相关元数据
提供直观的历史记录浏览界面
支持从历史记录快速重新加载图片
保持与现有功能的完全兼容


Non-Goals:


不实现云同步功能（纯本地存储）
不修改现有图片生成核心逻辑
不依赖外部数据库或复杂依赖


Decisions


1. 存储架构

Decision: 使用文件系统 + JSON索引的轻量级存储方案


Why: 避免引入重型数据库依赖，保持应用轻量化

Alternatives considered: SQLite数据库, Redis缓存, 文件系统-only方案

Chosen approach: /images/YYYYMMDDHHMMSS/ 目录结构 + 全局 history_index.json


2. 数据结构设计

Decision: 采用分层存储结构

/images/
├── history_index.json          # 全局索引文件
└── 20241201123456/             # 按时间戳的目录
    ├── metadata.json           # 该会话的元数据
    ├── generated.png           # 生成的图片
    ├── reference1.jpg          # 参考图片1
    └── reference2.jpg          # 参考图片2


3. UI集成方案

Decision: 在现有主界面添加"历史记录"标签页


Why: 保持界面一致性，最小化学习成本

Alternatives considered: 独立历史记录窗口, 侧边栏集成, 右键菜单


4. 性能优化策略

Decision: 延迟加载和缩略图缓存


历史记录列表只加载基本信息和缩略图
点击时才加载完整图片
实现缩略图缓存机制


Risks / Trade-offs


[磁盘空间使用] → 添加用户配置选项：最大历史记录数量限制

[大量历史记录性能] → 实现分页加载和虚拟滚动

[跨平台路径处理] → 使用 pathlib.Path 确保跨平台兼容性

[UI响应性] → 使用异步加载避免界面冻结


Migration Plan


Phase 1: 实现 HistoryManager 类和基础存储逻辑

Phase 2: 修改现有图片生成流程，添加自动保存

Phase 3: 开发历史记录界面和交互功能

Phase 4: 添加配置选项和性能优化


Rollback plan: 所有功能都是增量添加，移除新功能不会影响现有系统稳定性。


Open Questions


历史记录的默认数量上限应该是多少？
是否需要历史记录的搜索功能？
是否需要支持历史记录的导入/导出？
如何处理参考图片的版权和隐私问题？


Technical Architecture Details


HistoryManager Class Structure

class HistoryManager:
    def __init__(self, base_path: Path)
    def save_generation(self, image_bytes, prompt, references, params)
    def load_history_index(self) -> List[HistoryItem]
    def get_history_item(self, timestamp: str) -> HistoryItem
    def delete_history_item(self, timestamp: str) -> bool
    def cleanup_old_records(self, max_count: int)


Data Models

@dataclass
class HistoryItem:
    timestamp: str
    prompt: str
    generated_image_path: Path
    reference_image_paths: List[Path]
    aspect_ratio: str
    image_size: str
    model: str
    created_at: datetime


Integration Points


ImageGenerationWorker: 修改 on_image_generated 回调

ImageGeneratorWindow: 添加历史记录标签页和相关UI组件

Configuration: 扩展 config.json 添加历史记录相关配置