Design: Style Designer Tab

Architecture Overview

┌──────────────────────────────────────┐
│    ImageGeneratorWindow (Main)       │
│                                      │
│  ┌────────────────────────────────┐ │
│  │      QTabWidget                │ │
│  │  ┌──────────┬──────────┬────┐ │ │
│  │  │ 图片生成  │ 款式设计  │历史│ │ │
│  │  └──────────┴──────────┴────┘ │ │
│  └────────────────────────────────┘ │
└──────────────────────────────────────┘

款式设计 Tab 内部结构：
┌────────────────────────────────────┐
│  StyleDesignerTab (QWidget)        │
│  ┌──────────────────────────────┐  │
│  │  7个元素表单区域              │  │
│  │  - ComboBox (下拉选择)       │  │
│  │  - 添加/删除按钮             │  │
│  └──────────────────────────────┘  │
│  ┌──────────────────────────────┐  │
│  │  Prompt 预览区               │  │
│  └──────────────────────────────┘  │
│  ┌──────────────────────────────┐  │
│  │  生成按钮 + 设置             │  │
│  └──────────────────────────────┘  │
│  ┌──────────────────────────────┐  │
│  │  结果展示区                  │  │
│  └──────────────────────────────┘  │
└────────────────────────────────────┘

Data Structures

1. Jewelry Library Configuration

文件：jewelry_library.json

结构（纯中文，大幅简化）：

{
  "主石": [
    "椭圆形黑发晶",
    "圆形莫桑石",
    "祖母绿形红宝石",
    "梨形蓝宝石"
  ],
  "金属": [
    "14K黄金",
    "18K玫瑰金",
    "14K白金",
    "铂金(PT950)"
  ],
  "花头形式": [
    "花卉风格光环",
    "经典圆形光环",
    "复古风格米粒边光环"
  ],
  "戒臂结构": [
    "扭转戒臂",
    "分裂戒臂",
    "刀刃戒臂"
  ],
  "戒臂处理": [
    "雕刻镂空花丝工艺",
    "密钉镶戒臂",
    "抛光平滑戒臂"
  ],
  "特殊元素": [
    "凯尔特结图案",
    "装饰艺术几何元素",
    "自然风格叶子图案"
  ],
  "辅石镶嵌": [
    "密钉镶",
    "微密钉镶",
    "槽镶"
  ]
}

默认词库：

• 代码中内置默认词库常量 DEFAULT_JEWELRY_LIBRARY（纯中文）
• 首次运行时创建配置文件
• 每个字段的选项都支持：添加、删除、恢复默认

2. Design Form State

@dataclass
class StyleDesignForm:
    center_stone: str = ""      # 主石
    metal: str = ""              # 金属
    halo_style: str = ""         # 花头形式
    shank_structure: str = ""    # 戒臂结构
    shank_treatment: str = ""    # 戒臂处理
    special_motifs: str = ""     # 特殊元素
    accent_setting: str = ""     # 辅石镶嵌

Core Components

1. JewelryLibraryManager

职责：管理词库的加载、保存、增删改

class JewelryLibraryManager:
    def __init__(self, config_path: Path):
        self.config_path = config_path
        self.library = self.load_library()

    def load_library(self) -> dict:
        """加载词库，不存在则创建默认词库"""

    def save_library(self):
        """保存词库到配置文件"""

    def add_item(self, category: str, value: str, label_cn: str):
        """添加词库项"""

    def remove_item(self, category: str, value: str):
        """删除词库项"""

    def reset_to_default(self):
        """恢复默认词库"""

2. PromptAssembler

职责：组装中文 prompt 字符串

class PromptAssembler:
    BASE_TEMPLATE = """一款高端精品珠宝戒指设计，主石为{主石}，镶嵌于{金属}中。
    戒头采用{花头形式}围绕主石。
    戒臂采用{戒臂结构}设计，表面处理为{戒臂处理}。
    风格元素包括{特殊元素}。
    辅石采用{辅石镶嵌}增加光彩。
    高端珠宝渲染，干净的摄影棚光线，精准的金属抛光，强调宝石清晰度，不要出现手部。"""

    @staticmethod
    def assemble(form: Dict[str, str]) -> str:
        """智能组装 prompt，处理空值"""
        # 逻辑：
        # 1. 如果"主石"为空，调整句式（改为"一款高端精品珠宝戒指设计，镶嵌于{金属}中..."）
        # 2. 其他空字段直接移除对应句段
        # 3. 返回清理后的 prompt

空值处理逻辑：

• 主石 为空：改为 "一款高端精品珠宝戒指设计，镶嵌于{金属}中..."
• 其他字段为空：移除对应句段
• 如果多个连续字段为空，调整连接词（避免多余标点）

3. StyleDesignerTab (UI Component)

职责：款式设计 Tab 的 UI 容器

主要方法：

class StyleDesignerTab(QWidget):
    def __init__(self, library_manager: JewelryLibraryManager):
        self.library_manager = library_manager
        self.setup_ui()

    def setup_ui(self):
        """创建 UI 布局"""
        # 7个表单元素区域
        # Prompt 预览区
        # 生成设置区
        # 结果展示区

    def create_field_widget(self, category: str) -> QWidget:
        """创建单个字段的 UI 组件"""
        # ComboBox + 添加按钮 + 删除按钮

    def update_prompt_preview(self):
        """实时更新 prompt 预览"""

    def add_library_item(self, category: str):
        """添加词库项 UI（纯中文输入）"""

    def remove_library_item(self, category: str):
        """删除选中的词库项 UI"""

    def reset_library_for_category(self, category: str):
        """恢复单个字段的默认词库 UI"""

    def reset_all_library(self):
        """恢复所有字段的默认词库 UI"""

    def generate_image(self):
        """调用文生图 API"""

Implementation Strategy

Phase 1: 数据层

1. 定义 DEFAULT_JEWELRY_LIBRARY 常量
2. 实现 JewelryLibraryManager
3. 实现 PromptAssembler 的空值处理逻辑

Phase 2: UI 层

1. 创建 StyleDesignerTab 基础框架
2. 实现 7 个字段的表单 UI
3. 实现词库增删改 UI

Phase 3: 集成

1. 在 ImageGeneratorWindow.setup_ui() 中插入新 Tab
2. 连接 prompt 预览实时更新
3. 连接生成按钮到现有文生图 API

Phase 4: 测试

1. 测试空值组合场景
2. 测试词库增删改
3. 测试恢复默认词库

Key Design Decisions

1. 为什么使用纯中文而非中英文映射？

• 简洁性：Gemini 支持中文 prompt，无需翻译
• 用户友好：用户直接输入中文，零门槛
• 零维护成本：不需要维护中英文词典

2. 为什么使用 JSON 配置文件而非数据库？

• 简洁性：词库数据量小，JSON 足够
• 可移植性：配置文件易于备份和迁移
• 零依赖：不增加数据库依赖

3. 为什么在代码中内置默认词库？

• 兜底保障：配置文件损坏时仍可恢复
• 首次使用：新用户直接获得完整词库

4. Prompt 组装逻辑为何单独抽取？

• 可测试性：逻辑复杂，需独立单元测试
• 可维护性：未来可能优化 prompt 结构
• 复用性：可能用于其他珠宝设计场景

Trade-offs

决策	优点	缺点	结论
配置文件 vs 数据库	简单、轻量	不支持复杂查询	配置文件足够
实时预览 vs 按需生成	用户体验好	性能开销	实时预览，开销可忽略
硬编码词库 vs 动态加载	实现简单	不可扩展	动态加载（用户要求）

Security Considerations

• 无安全风险：不涉及网络请求、文件上传
• ️ 文件写入权限：需确保配置文件路径可写

Performance Considerations

• Prompt 组装：字符串操作，O(n)，可忽略
• 词库加载：仅在启动时加载一次
• UI 刷新：仅更新预览区域，不重绘整个窗口

Backward Compatibility

• 零破坏性：新增 Tab，不影响现有功能
• 配置文件独立：新增 jewelry_library.json，不修改现有 config.json

---

设计完成日期：2025-12-10