# Changelog - PreviewInfoPanel 重构与标签音色配置

**日期**: 2026-02-09
**类型**: 功能增强 (Refactor & Feat)
**模块**: 前端 - PreviewPanel

## 变更概述

重构 `PreviewInfoPanel` 组件，将单一详情页改为“详情 + 标签”双栏布局。并将角色的音色配置逻辑从角色详情移至标签（装扮）列表，实现了“不同装扮可配置不同音色”的需求。

## 技术实现

### 1. 数据结构扩展

- **文件**: `client/src/components/features/preview/types.ts`
- **变更**: 扩展 `ResourceTag` 接口，增加音色相关字段：
  ```typescript
  export interface ResourceTag {
    // ...
    voiceProvider?: string;
    voiceModelId?: string;
    voiceSampleUrl?: string; // 用于试听
  }
  ```

### 2. UI 重构 (PreviewInfoPanel)

- **文件**: `client/src/components/features/preview/PreviewInfoPanel.tsx`
- **布局调整**:
  - 使用 CSS Grid 实现双栏布局：左侧宽栏显示详细信息，右侧窄栏（380px）显示标签列表。
  - 移除了左侧 `renderCharacterFields` 中的音色配置区域。
- **功能增强**:
  - 在右侧标签列表中，针对 `character` 类型的资源，每个标签卡片增加音色配置区域。
  - 支持编辑模式下输入 `voiceModelId` 和 `voiceSampleUrl`。
  - 非编辑模式下显示音色 ID，并提供播放按钮（预留 `onVoicePlay` 接口）。

### 3. 逻辑更新

- **文件**: `client/src/components/features/preview/hooks/usePreviewActions.ts`
- **变更**: 更新 `handleUpdateTag` 函数，支持接收 `voiceConfig` 参数，并将音色信息保存到资源的 `metadata.tags` 中。
- **文件**: `client/src/components/features/preview/SingleViewPlayer.tsx`
- **变更**: 更新 `SingleViewPlayerProps` 接口，同步 `onUpdateTag` 的签名变更。

## 影响范围

- `PreviewInfoPanel` 组件结构完全改变。
- `ResourceTag` 数据结构变更（向下兼容，新增字段可选）。
- `SingleViewPlayer` 及其父组件（`PreviewPanel`）的 Props 传递。

## 后续计划

1.  **音色播放支持**: 当前 `onVoicePlay` 仅支持播放当前 Item 的默认音色。需升级 `useMediaPlayback` 以支持播放特定 Tag 的 `voiceSampleUrl`。
2.  **后端支持**: 确保后端 API 正确存储和返回 `metadata` 中的音色字段（目前前端已实现透传）。