# 图像翻译模块初始化脚本使用说明

## 脚本功能

`init_image_translation.py` 脚本用于初始化图像翻译模块的数据库环境，包括：

1. **创建数据表**：执行 `add_image_translation_table.sql` 创建 `image_translation` 表及相关索引
2. **插入模型配置**：在 `model` 和 `model_price` 表中添加 `qwen-mt-image` 模型配置
3. **插入百宝箱应用**：在 `toolbox_apps` 表中添加图像翻译应用入口
4. **验证数据完整性**：检查所有数据是否正确插入

## 使用前提

1. 已安装 Python 3.7+
2. 已安装依赖包：`psycopg2-binary`, `python-dotenv`
3. 已配置 `backend/.env` 文件中的数据库连接信息
4. 数据库中已存在 `aigcspace` schema

## 执行步骤

### 1. 进入后端目录

```bash
cd backend
```

### 2. 安装依赖（如果尚未安装）

```bash
pip install psycopg2-binary python-dotenv
```

### 3. 执行迁移脚本

```bash
python scripts/init_image_translation.py
```

## 执行流程

脚本执行时会显示详细的进度信息：

```
============================================================
图像翻译模块数据库迁移脚本
============================================================

📁 找到迁移文件:
   - add_image_translation_table.sql

🔌 连接数据库...
   Host: localhost
   Port: 5432
   Database: aigcspace
   User: postgres
✓ 数据库连接成功

🚀 开始执行迁移...

[1/3] 创建数据表...
✓ 执行成功: add_image_translation_table.sql

[2/3] 插入模型配置...
✓ 模型 qwen-mt-image 插入成功 (ID: 123)
✓ 模型价格配置插入成功（每张图片 0.02 元）

[3/3] 插入百宝箱应用...
✓ 百宝箱应用 qwen-image-translate 插入成功 (ID: 456)

✓ 所有迁移执行成功

📊 数据验证:
   ✓ image_translation 表: 已创建
   ✓ 模型配置: qwen-mt-image (ID: 123, 价格: 0.02元/张)
   ✓ 百宝箱应用: 通义千问图像翻译 [New] (版本: 1.0.0, 状态: active)
   ✓ 索引数量: 4
      - idx_image_translation_user_id
      - idx_image_translation_task_id
      - idx_image_translation_created_at
      - idx_image_translation_status

============================================================
✅ 图像翻译模块数据库迁移完成！
============================================================

💡 下一步:
   1. 重启后端服务: cd backend && python main.py
   2. 访问百宝箱: http://localhost:5173/toolbox
   3. 点击「通义千问图像翻译」卡片的「立即使用」按钮
   4. 开始使用图像翻译功能
```

## 幂等性保证

脚本具有幂等性，可以安全地多次执行：

- 如果表已存在，不会重复创建
- 如果模型配置已存在，不会重复插入
- 如果百宝箱应用已存在，不会重复插入

## 错误处理

如果执行过程中出现错误：

1. 脚本会自动回滚所有更改
2. 显示详细的错误信息
3. 返回非零退出码

常见错误及解决方案：

### 数据库连接失败

```
❌ 数据库连接失败: FATAL: password authentication failed
```

**解决方案**：检查 `.env` 文件中的数据库连接信息是否正确

### 表已存在

如果表已存在但需要重新创建，请先手动删除：

```sql
DROP TABLE IF EXISTS aigcspace.image_translation CASCADE;
```

### 外键约束错误

如果 `model` 或 `toolbox_apps` 表不存在，需要先执行相关的迁移脚本。

## 验证安装

执行完成后，可以通过以下 SQL 验证：

```sql
-- 检查表是否创建
SELECT * FROM aigcspace.image_translation LIMIT 1;

-- 检查模型配置
SELECT m.title, mp.output_price 
FROM aigcspace.model m
LEFT JOIN aigcspace.model_price mp ON m.id = mp.model_id
WHERE m.title = 'qwen-mt-image';

-- 检查百宝箱应用
SELECT app_key, name, category, status 
FROM aigcspace.toolbox_apps 
WHERE app_key = 'qwen-image-translate';
```

## 回滚

如需回滚，执行以下 SQL：

```sql
-- 删除百宝箱应用
DELETE FROM aigcspace.toolbox_apps WHERE app_key = 'qwen-image-translate';

-- 删除模型价格配置
DELETE FROM aigcspace.model_price 
WHERE model_id = (SELECT id FROM aigcspace.model WHERE title = 'qwen-mt-image');

-- 删除模型配置
DELETE FROM aigcspace.model WHERE title = 'qwen-mt-image';

-- 删除表
DROP TABLE IF EXISTS aigcspace.image_translation CASCADE;
```

## 相关文件

- `backend/scripts/init_image_translation.py` - 初始化脚本
- `backend/migrations/add_image_translation_table.sql` - 表创建SQL
- `backend/.env` - 数据库连接配置
- `backend/app/models/image_translation.py` - ORM模型
- `backend/app/routers/image_translation_router.py` - API路由

## 技术支持

如遇到问题，请检查：

1. Python 版本是否 >= 3.7
2. 依赖包是否正确安装
3. 数据库连接信息是否正确
4. 数据库用户是否有足够权限
5. `aigcspace` schema 是否存在