# KnowWhy Learning Map

`learning-map/` 是 KnowWhy 仓库中的独立家庭学习与知识图谱模块。它与现有视频制作并行，不改变 `production/`、`deliverables/` 或 `docs/` 中已经稳定的制作流程。

## 边界

- 教材 PDF 是章节、版本和页码的事实来源。
- 本模块只读取正式视频的相对路径，不修改视频、脚本、字幕或制作清单。
- 知识点可以没有视频；没有视频不影响学习计划和练习安排。
- 学习数据只能为未来视频选题提供参考，不能自动改变视频制作顺序。
- `os-taxonomy` 只提供“微知识点、前置关系、掌握证据”的组织思路。本模块不直接套用英美课程内容。
- 学生姓名、成绩和错题等个人数据不要提交到公共仓库；`progress/` 只保存格式说明和脱敏示例。

## 目录

```text
learning-map/
├── data/
│   ├── grade-N/                 # 各年级、各科目的教材知识点
│   ├── video-sources.json       # 成品目录和课次—知识点映射配置
│   └── video-links.json         # 可选的知识点—视频连接层
├── plans/                       # 家庭周计划模板和样例
├── progress/                    # 本地学习记录格式说明
├── schemas/                     # JSON Schema
├── mini-program/                # 原生微信小程序视频课程
└── scripts/validate.mjs         # 独立数据检查
```

## 数据原则

每个知识点包含：

- 稳定 ID 和教材定位；
- 一句话知识说明；
- 本图谱内部的前置知识；
- 尚未录入图谱的外部前置知识；
- 可观察的掌握证据；
- 常见误区；
- 基础、强化和迁移三层练习建议；
- 视频解释价值，而不是视频生产任务。

视频连接单独保存在 `data/video-links.json`。删除全部连接后，知识图谱仍然完整可用；视频生产目录也不依赖本模块。

## 当前试点

1. 湘教版数学八年级上册：55 个知识点，覆盖五章、综合实践与主要拓展，并连接 `deliverables/八年级上册数学/按教材顺序/` 中的全册成品视频。
2. 人教版数学三年级上册：35 个知识点，覆盖全部正式单元、“曹冲称象”“数字编码”综合实践和搭配问题，并连接 `deliverables/三年级上册数学/按教材顺序/` 中的 24 课、48 个成品视频。
3. 人教版物理八年级上册：37 个教材核验课程，覆盖导入和第1—6章，并连接 `deliverables/八年级上册物理/按教材顺序/` 中的 37 支核心理解片；当前仍待人工完整试听与物理复核。
4. 教科版科学三年级上册：24 个教材小节，覆盖天气、水、物体的运动3个单元，并连接24支核心理解片；当前仍待人工完整试听与科学复核。
5. 湘教版地理八年级上册：35 个教材核验课程，覆盖中国的疆域与人口、自然环境、自然资源和主要产业4章，并连接35支核心理解片；当前仍待人工完整试听与地理复核。

当前文件已经覆盖五册教材整学期的主要课时和知识主线。练习题仍以能力层级和题型建议表示，不复制教材原题，也不表示穷尽每一种变式。

## 年级与科目扩展

网站和小程序统一采用以下层级，不在页面代码中写死具体年级或科目：

```text
年级 → 科目 → 教材 → 章节 → 课程 → 视频版本（原理短片 / 完整讲解 / 核心理解片）
```

增加四年级、九年级、物理或其他科目时：

1. 在 `data/grade-N/` 增加符合 schema 的教材知识点 JSON；如已有标准生产课程清单，也可配置 `courseCatalog` 和 `datasetPath` 后运行 `sync-course-catalog-datasets.mjs` 生成。
2. 在 `data/video-sources.json` 增加一个视频来源，登记成品目录及 `lessonToTopic` 映射。
3. 依次运行 `sync-course-catalog-datasets.mjs`、`sync-deliverable-videos.mjs` 和 `build-mini-program-data.mjs`。
4. 网站会自动发现教材文件；小程序会自动生成对应的年级、科目、章节和课程入口。

课程 ID 使用“知识点 ID + 课次”，不同科目相同课次不会冲突；“下一课”只在同一年级、同一科目、同一本教材中跳转。

## 验证

在 KnowWhy 根目录运行：

```powershell
node learning-map/scripts/validate.mjs
```

检查内容包括：JSON 结构、知识点 ID、前置引用、循环依赖、视频映射和视频文件是否存在。验证脚本不会写入 `production/`。

## 查看知识点和生成周计划

列出全部或指定年级的知识点：

```powershell
node learning-map/scripts/list-topics.mjs
node learning-map/scripts/list-topics.mjs --grade 3
```

根据知识点生成家庭周计划：

```powershell
node learning-map/scripts/generate-week-plan.mjs `
  --topic math-g8-xj-u1-1-factorization-concept `
  --learner 八年级孩子 `
  --output learning-map/plans/generated/八年级_因式分解入门.md
```

生成器只允许写入 `learning-map/plans/`，不会写入视频生产目录。未指定 `--output` 时，计划只输出到终端。

生成整学期内容总览：

```powershell
node learning-map/scripts/generate-semester-overview.mjs
```

## 本地网页

成品视频更新后，先重新扫描并生成连接：

```powershell
node learning-map/scripts/sync-deliverable-videos.mjs
```

在 KnowWhy 根目录运行：

```powershell
node learning-map/scripts/serve-web.mjs
```

然后在浏览器打开：

```text
http://127.0.0.1:4173
```

网页支持由数据生成的年级切换、科目切换、章节筛选、关键词搜索、前置知识跳转、三级练习、视频播放和学习状态记录。状态只保存在当前浏览器的 `localStorage` 中，不修改知识数据，也不写入视频目录。

手机窄屏会自动进入孩子使用的“视频课程模式”：只列出有视频的课程，课程页优先显示一句话简介、播放器、学习反馈和下一课。PC 端仍显示完整知识地图。

微信小程序工程位于 `learning-map/mini-program/`，配置和正式发布前提参见其中的 `README.md`。