# 融媒体词典数据

此目录 (curriculum/dictionary/) 包含融媒体词典的源数据，会在应用启动时自动导入 MongoDB。

## 数据结构

```
curriculum/dictionary/
├── dict-26/                    # 国际中文-新HSK词典 (11095 词)
│   ├── meta.yml               # 词典元数据
│   └── words/                 # 词汇文件目录
│       ├── vocab-26-10000.md
│       ├── vocab-26-10001.md
│       └── ...
├── dict-27/                    # 预科中文-YKK词典 (1635 词)
├── dict-33/                    # ...
├── dict-34/
├── dict-36/
├── dict-45/
├── dict-46/
├── dict-47/
└── dict-48/
```

## 词典列表

| 词典ID | 名称 | 词汇量 | 状态 |
|--------|------|--------|------|
| dict-26 | 国际中文-新HSK词典 | 11,095 | ✅ |
| dict-27 | 预科中文-YKK词典 | 1,635 | ✅ |
| dict-33 | ... | ... | ✅ |
| ... | ... | ... | ... |

## 自动迁移机制

应用启动时会自动检查 MongoDB 中的词典数据：

1. **首次启动**：检测到无数据，自动导入所有词典
2. **后续启动**：检测到数据已存在，跳过导入（加快启动速度）
3. **强制重导**：设置环境变量 `FORCE_MONGODB_MIGRATIONS=true` 重新导入

## 环境变量配置

```bash
# MongoDB 连接配置
MONGODB_URL=mongodb://localhost:27017
MONGODB_DB_NAME=baizor

# 认证配置（如果 MongoDB 需要）
MONGODB_USERNAME=lucky
MONGODB_PASSWORD=mq123456

# 迁移控制
SKIP_MONGODB_MIGRATIONS=true     # 跳过自动导入
FORCE_MONGODB_MIGRATIONS=true    # 强制重新导入（会清空数据）
```

## 手动操作

### 查看迁移状态

```bash
cd /path/to/project
python scripts/import_dictionaries.py --info
```

或调用 API（需要管理员权限）：

```bash
curl -H "Authorization: Bearer <token>" \
  http://localhost:8080/api/v1/dictionary/admin/migration-status
```

### 手动触发导入

```bash
# 普通导入（仅当数据不存在时）
python scripts/import_dictionaries.py

# 强制重新导入（清空并重新导入）
python scripts/import_dictionaries.py --force

# 查看统计
python scripts/import_dictionaries.py --stats
```

或通过 API（需要管理员权限）：

```bash
# 触发迁移
curl -X POST -H "Authorization: Bearer <token>" \
  http://localhost:8080/api/v1/dictionary/admin/run-migration

# 强制重新导入
curl -X POST -H "Authorization: Bearer <token>" \
  "http://localhost:8080/api/v1/dictionary/admin/run-migration?force=true"
```

## 词汇文件格式

每个词汇文件是 Markdown 格式，包含 YAML frontmatter：

```markdown
---
id: vocab-26-10000
word: 未经
type: vocabulary
dictionary:
  id: dict-26
  name: 国际中文-新HSK词典
pinyin: wèijīng
difficulty: '9'
translations:
  english: Not
  french: 'Sans '
  portuguese: 'Sem '
  spanish: 'Sin '
properties: fuci
media:
  audio: https://...
  image: https://...
---

# --sentences--

## vs-17895
**sentence**: 幽默大师林语堂先生...
**audio**: [https://...](https://...)
```

## 部署方式（重要）

### 方式一：Docker Volume 挂载（推荐）

数据文件**不打包**进 Docker 镜像，而是通过 Volume 挂载到容器外：

```yaml
# docker-compose.dictionary.yaml
services:
  backend:
    volumes:
      # 主机路径:容器路径:ro (只读)
      - ./backend/open_webui/migrations/curriculum/dictionary:/app/dictionary-data:ro
    environment:
      - DICTIONARY_DATA_PATH=/app/dictionary-data
```

**优点：**
- 镜像体积小（不包含数据文件）
- 更新数据无需重新构建镜像
- 数据与代码分离，符合最佳实践
- 可随时修改词汇文件并重启生效

**启动命令：**
```bash
docker-compose -f docker-compose.dictionary.yaml up -d
```

### 方式二：打包进镜像（简单但不推荐）

如果不配置 `DICTIONARY_DATA_PATH`，默认使用相对路径：
```bash
# 会打包 curriculum/dictionary/ 到镜像中
docker build -t chat-lanhc .
```

**缺点：**
- 镜像体积大 (+50~100MB)
- 每次数据更新都要重新构建镜像
- 生产环境不灵活

### .dockerignore 配置

已添加 `.dockerignore` 排除数据文件：
```
backend/open_webui/migrations/curriculum/
```

## 注意事项

1. **不要直接修改**此目录下的文件，修改后需要重新导入
2. 数据导入是幂等的（可以重复执行，不会重复数据）
3. 导入大量数据时可能需要几分钟时间
4. 建议在生产环境首次部署后检查数据完整性
5. **推荐使用 Volume 方式部署**，方便后续更新