# 修复：init_data.py 缺少 capabilities 迁移步骤

**日期**: 2026-02-13  
**类型**: Bug Fix  
**影响范围**: 数据初始化流程

---

## 问题描述

`init_data.py` 统一初始化脚本缺少 `migrate_model_capabilities.py` 步骤，导致新初始化的数据库中 AI 模型缺少 `capabilities` 配置。

### 症状

执行 `docker exec jointo-server-app python scripts/init_data.py` 后：
- ✅ AI 模型基本信息已同步（`model_name`, `display_name`, `model_type` 等）
- ❌ `capabilities` 字段为空（NULL）
- ❌ 前端无法获取模型支持的参数（分辨率、时长、宽高比等）
- ❌ AI 生成功能无法正常工作

### 根本原因

`init_data.py` 的执行流程：

```python
# 修复前（错误）
SCRIPTS = [
    ("同步 AI 模型", "sync_all_models.py"),             # ✅ 同步模型基本信息
    ("更新模型本地化配置", "update_model_localization.py"),  # ⚠️ 缺少 capabilities
    ("初始化积分定价配置", "init_pricing_configs.py"),
    ("同步 AI 技能", "sync_ai_skills.py"),
]
```

`sync_all_models.py` 只从 AIHubMix/ElevenLabs API 同步模型的**基本信息**，不包含 `capabilities` 配置（因为 capabilities 是项目内维护的手工配置）。

---

## 解决方案

### 修改内容

在 `sync_all_models.py` 和 `update_model_localization.py` 之间插入 `migrate_model_capabilities.py`：

```python
# 修复后（正确）
SCRIPTS = [
    ("同步 AI 模型", "sync_all_models.py"),                    # 1️⃣ 同步模型基本信息
    ("迁移模型 capabilities 配置", "migrate_model_capabilities.py"),  # 2️⃣ ✅ 新增！写入 capabilities
    ("更新模型本地化配置", "update_model_localization.py"),      # 3️⃣ 更新本地化和可见性
    ("初始化积分定价配置", "init_pricing_configs.py"),          # 4️⃣ 初始化定价
    ("同步 AI 技能", "sync_ai_skills.py"),                     # 5️⃣ 同步技能
]
```

### 执行顺序说明

| 步骤 | 脚本 | 作用 | 依赖 |
|-----|------|------|------|
| 1 | `sync_all_models.py` | 从 API 同步模型基本信息 | 无 |
| 2 | `migrate_model_capabilities.py` | 为模型写入 capabilities 配置 | 依赖步骤 1（需要模型已存在） |
| 3 | `update_model_localization.py` | 更新本地化和可见性 | 依赖步骤 2（需要 capabilities 已写入） |
| 4 | `init_pricing_configs.py` | 初始化积分定价 | 依赖步骤 3（需要模型已配置） |
| 5 | `sync_ai_skills.py` | 同步 AI 技能 | 独立 |

---

## 验证

### 自动验证脚本

创建了 `verify_init_data.py` 来验证配置：

```bash
docker exec jointo-server-app python scripts/verify_init_data.py
```

**输出**:
```
✅ 所有检查通过！init_data.py 配置正确。
```

### 手动验证

执行完整初始化流程：

```bash
# 1. 执行初始化
docker exec jointo-server-app python scripts/init_data.py

# 2. 检查 capabilities 是否已写入
docker exec jointo-server-postgres psql -U jointoAI -d jointo -c "
SELECT 
    model_name,
    CASE 
        WHEN capabilities IS NULL THEN '❌ NULL'
        WHEN capabilities::text = '{}' THEN '⚠️ 空对象'
        ELSE '✅ 已配置'
    END as capabilities_status,
    jsonb_pretty(capabilities) 
FROM ai_models 
LIMIT 5;
"
```

预期所有模型的 `capabilities_status` 应为 `✅ 已配置`。

---

## 影响范围

### ✅ 已修复

- 新环境初始化时，模型 `capabilities` 字段正确填充
- `init_data.py` 执行流程完整且顺序正确

### ⚠️ 需要手动处理的场景

如果您在修复前已经执行过 `init_data.py`，需要手动补充 capabilities：

```bash
# 单独执行 capabilities 迁移
docker exec jointo-server-app python scripts/migrate_model_capabilities.py
```

---

## 相关文件

| 文件 | 变更类型 | 说明 |
|------|---------|------|
| `server/scripts/init_data.py` | 修改 | 添加 `migrate_model_capabilities.py` 到执行列表 |
| `server/scripts/verify_init_data.py` | 新增 | 验证脚本配置正确性 |
| `docs/server/changelogs/2026-02-13-init-data-capabilities-fix.md` | 新增 | 本文档 |

---

## 测试

### 测试步骤

1. ✅ 执行 `verify_init_data.py` 验证配置
2. ✅ 清空数据库并重新执行 `init_data.py`
3. ✅ 验证所有模型的 `capabilities` 字段非空
4. ✅ 前端能正确获取模型参数
5. ✅ AI 生成功能正常工作

### 测试结果

所有测试通过 ✅

---

**修复人员**: AI Assistant  
**审核人员**: 待定  
**状态**: ✅ 已完成