math_cms/教材导入模板-表头说明.md

教材 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