# 教材 Excel 导入模板 - 表头说明

## 📋 表头定义

### 基本信息

| 字段名 | 中文名 | 是否必填 | 说明 | 示例值 |
|--------|--------|----------|------|--------|
| series_id | 教材系列ID | 必填 | 对应教材系列的ID | 1 |
| stage | 学段 | 必填 | primary(小学)、junior(初中)、senior(高中) | junior |
| grade | 年级 | 必填 | 小学1-6、初中7-9、高中10-12 | 7 |
| semester | 学期 | 必填 | 1(上册)、2(下册) | 1 |

### 学制信息（小学、初中）

| 字段名 | 中文名 | 是否必填 | 说明 | 示例值 |
|--------|--------|----------|------|--------|
| schooling_system | 学制 | 选填 | 63(六三学制)、54(五四学制) | 63 |

### 高中教材特有字段

| 字段名 | 中文名 | 是否必填 | 说明 | 示例值 |
|--------|--------|----------|------|--------|
| naming_scheme | 命名体系 | 选填 | new(新体系)、old(旧体系) | new |
| track | 版本 | 选填 | A(A版)、B(B版) | A |
| module_type | 模块类型 | 选填 | compulsory(必修)、selective_compulsory(选择性必修)、elective(选修) | compulsory |
| volume_no | 册次 | 选填 | 数字，如：1、2、3 | 1 |
| legacy_code | 旧体系编码 | 选填 | 旧体系的编码，如：必修1、选修1-1 | 必修1 |

### 课程标准信息

| 字段名 | 中文名 | 是否必填 | 说明 | 示例值 |
|--------|--------|----------|------|--------|
| curriculum_standard_year | 课标年代 | 选填 | 义务教育：2011/2022，高中：2017 | 2022 |
| curriculum_revision_year | 修订年份 | 选填 | 高中：2020 | 2020 |
| approval_year | 审定年份 | 选填 | 教材审定通过的年份 | 2024 |
| edition_label | 版次标识 | 选填 | 如：2024秋版、修订版 | 2024秋版 |

### 教材标识

| 字段名 | 中文名 | 是否必填 | 说明 | 示例值 |
|--------|--------|----------|------|--------|
| isbn | ISBN | 选填 | 教材的ISBN号 | 978-7-123-45678-9 |
| cover_path | 封面图片 | 选填 | 封面图片URL或本地路径 | https://... |

### 教材标题

| 字段名 | 中文名 | 是否必填 | 说明 | 示例值 |
|--------|--------|----------|------|--------|
| official_title | 官方书名 | 选填 | 教材的官方正式名称 | 人教版数学七年级上册 |
| display_title | 展示名称 | 选填 | 站内显示的名称 | 人教版数学（2024版） |
| aliases | 别名 | 选填 | JSON格式的别名数组 | ["人教数学", "PEP数学"] |

### 状态信息

| 字段名 | 中文名 | 是否必填 | 说明 | 示例值 |
|--------|--------|----------|------|--------|
| status | 状态 | 必填 | draft(草稿)、published(已发布)、archived(已归档) | draft |
| meta | 扩展信息 | 选填 | JSON格式的扩展信息 | {"note": "测试数据"} |

---

## 📝 Excel 模板示例

### 模板 A：初中教材

```
series_id | stage | grade | semester | schooling_system | official_title | display_title | isbn | approval_year | status
1 | junior | 7 | 1 | 63 | 人教版数学七年级上册 | 人教版数学（2024版） | 978-7-123-45678-9 | 2024 | draft
1 | junior | 7 | 2 | 63 | 人教版数学七年级下册 | 人教版数学（2024版） | 978-7-123-45679-6 | 2024 | draft
2 | junior | 8 | 1 | 63 | 北师大版数学八年级上册 | 北师大版数学（2024版） | 978-7-123-45680-2 | 2024 | draft
```

### 模板 B：高中教材

```
series_id | stage | grade | naming_scheme | track | module_type | volume_no | official_title | display_title | isbn | status
1 | senior | 10 | new | A | compulsory | 1 | 人教版数学必修第一册 | 人教版数学A版（2024版） | 978-7-123-45681-9 | draft
1 | senior | 10 | new | A | compulsory | 2 | 人教版数学必修第二册 | 人教版数学A版（2024版） | 978-7-123-45682-6 | draft
1 | senior | 11 | new | A | selective_compulsory | 3 | 人教版数学选择性必修第一册 | 人教版数学A版（2024版） | 978-7-123-45683-3 | draft
```

### 模板 C：小学教材

```
series_id | stage | grade | semester | schooling_system | official_title | display_title | status
1 | primary | 1 | 1 | 63 | 人教版数学一年级上册 | 人教版数学（2024版） | draft
1 | primary | 1 | 2 | 63 | 人教版数学一年级下册 | 人教版数学（2024版） | draft
1 | primary | 2 | 1 | 63 | 人教版数学二年级上册 | 人教版数学（2024版） | draft
```

---

## ⚠️ 重要说明

### 1. 字段映射

- **学段值映射**：
  - `primary` → 小学
  - `junior` → 初中
  - `senior` → 高中

- **学制值映射**：
  - `63` → 六三学制（小学6年 + 初中3年）
  - `54` → 五四学制（小学5年 + 初中4年）

- **学期值映射**：
  - `1` → 上册
  - `2` → 下册

- **状态值映射**：
  - `draft` → 草稿
  - `published` → 已发布
  - `archived` → 已归档

### 2. 必填字段

创建教材时，以下字段**必须填写**：
- series_id（教材系列ID）
- stage（学段）
- grade（年级）
- semester（学期）
- status（状态）

### 3. 条件必填

- **小学/初中**：如果学段是 `primary` 或 `junior`，可以填写 `schooling_system`
- **高中**：如果学段是 `senior`，根据 `naming_scheme` 的值，可能需要填写：
  - 新体系（new）：`track`、`module_type`、`volume_no`
  - 旧体系（old）：`legacy_code`

### 4. 教材系列ID说明

在导入前，需要先创建教材系列，获取其ID。常见的系列ID：

| 系列ID | 系列名称 | 出版社 |
|--------|----------|--------|
| 1 | 人教版 | 人民教育出版社 |
| 2 | 北师大版 | 北京师范大学出版社 |
| 3 | 华东师大版 | 华东师范大学出版社 |

### 5. 别名和扩展信息格式

- **aliases（别名）**：JSON数组格式
  - 正确：`["人教数学", "PEP数学"]`
  - 错误：`人教数学, PEP数学`

- **meta（扩展信息）**：JSON对象格式
  - 正确：`{"note": "测试数据", "tags": ["数学", "初中"]}`
  - 错误：`note:测试数据`

### 6. 封面图片

- 可以是图片URL（推荐）
- 也可以是本地路径（需要先上传到服务器）
- 支持格式：JPG、PNG、WebP
- 推荐尺寸：400x600（2:3比例）
- 最大大小：5MB

### 7. 数据验证

导入时会进行以下验证：
- series_id 必须对应存在的教材系列
- stage 必须是有效的学段值
- grade 必须在学段范围内
- semester 必须是1或2
- JSON 格式必须正确
- 重复数据会被忽略

---

## 📊 Excel 文件要求

### 文件格式
- ✅ 支持：`.xlsx`、`.xls`
- ❌ 不支持：`.csv`、`.txt`

### 数据格式
- 第一行必须是表头（字段名）
- 从第二行开始是数据
- 不支持合并单元格
- 不支持公式

### 编码要求
- 使用 **UTF-8** 编码
- 确保中文显示正常

---

## 🚀 使用步骤

1. **准备数据**：按照表头说明填写Excel
2. **验证数据**：确保必填字段已填写，格式正确
3. **导入系统**：在 FilamentAdmin 中使用"Excel导入"功能
4. **检查结果**：导入后检查是否有错误记录
5. **修复错误**：如有错误，修正后重新导入

---

## 💡 最佳实践

### 1. 批量导入建议

- 每次导入不超过 500 条记录
- 先用小批量测试格式
- 准备好教材系列后再导入教材

### 2. 数据一致性

- 保持命名规范一致
- 统一使用相同的中文/英文标识
- 定期同步 MySQL 和 PostgreSQL 数据

### 3. 版本管理

- 使用 `edition_label` 标识不同版本
- 旧版本标记为 `archived`
- 新版本标记为 `published`

### 4. 封面管理

- 统一封面尺寸和格式
- 使用有意义的文件名
- 定期备份封面图片

---

**创建时间**：2025-12-16
**适用范围**：FilamentAdmin 教材管理系统
**版本**：v1.0