# 交接:DIFrobot 数学组卷台(给「DIfrobot网站建设」)

截至 2026-07-26。本地已跑通、已验收,**尚未上线**。下面是网站化需要知道的全部事实。

---

## 一、这是什么

**DIFrobot数学组卷台** —— 老师按「教材 → 年级/册 → 章 → 专题」选题、加进试卷篮、预览、导出 Word/打印 PDF。

**44097 道题,5 套教材,1920 个专题节,零答案**(题面绝不含解析/答案,这是硬红线)。

| 教材 | 册/年级 | 专题节 |
|---|---:|---:|
| 一课一练(沪教配套) | 17 | 800 |
| 初中培优讲义(沪教版六上~九下) | 8 | 381 |
| 举一反三 | 6 | 357 |
| 动脑筋 | 6 | 222 |
| 胡小群课程(L1-2~L6) | 5 | 160 |

---

## 二、代码在哪,怎么跑

全部在 `~/Desktop/AI workspace/课程设计机器人/`。

```
组卷系统/
  组卷台.html              ← 139MB 单文件自包含前端(配图 base64 内嵌)
  组卷台AI助手.py           ← 本地服务(纯 stdlib,无第三方依赖),端口 8848
  启动组卷台AI助手.command   ← 双击启动
  topic_source.py          ← 专题源文件定位(预览/下载)
  split_topics.py          ← 把源资料拆成「一专题一文件」
  build_precut_map.py      ← 把组卷台专题节对到拆好的成品文件
  zujuan_v2.py             ← 初中培优讲义 → 组卷台 schema
  原书页/                   ← 动脑筋/举一反三 页图 + page_ranges.json
成果/胡小群题库/gen_组卷台.py  ← **正主生成器**(build 后拷到 组卷系统/)
源题文件/_专题拆分/            ← 2350 个专题级成品文件 + _索引.json + _组卷台映射.json
```

```bash
cd "组卷系统" && python3 组卷台AI助手.py     # → http://localhost:8848/组卷台.html
```

⚠ **`组卷台.html` 的正主是 `成果/胡小群题库/gen_组卷台.py` 生成的那份**,改前端要改生成器再 build 再拷过去,别直接改 `组卷系统/组卷台.html`。

---

## 三、后端接口(都在 `组卷台AI助手.py`)

| 方法 | 路径 | 作用 |
|---|---|---|
| GET | `/api/version` | 前后端版本握手(不一致页面出横幅提醒重启) |
| GET | `/api/topic?tb=&g=&cd=&src=&pg=` | **整个专题**的页图滚动预览页 |
| GET | `/api/topic/pdf?同上` | **整个专题**的源文件下载(PDF 或 docx) |
| GET | `/api/page?f=<相对路径>` | 单张页图(**有白名单防目录穿越**) |
| GET | `/api/source?title=&fmt=` | 初中培优讲义单个专题的源 docx |
| POST | `/api/similar` | 照一道题出 N 道同类题(DeepSeek) |
| POST | `/api/similar_batch` | 整页批量出题 |
| POST | `/api/export_docx` | 导出 Word(专题练习模板样式) |
| POST | `/api/report` | 老师点 🚩 报告问题 → `问题报告.jsonl` |

**DeepSeek key 在 `~/.deepseek_pro_key`,只在服务端读,不进前端/代码/git。** 上线要换成环境变量或密钥服务。

---

## 四、专题级源文件(刚做完,是你要找的「现成拆分方案」)

`源题文件/_专题拆分/` 里已经有 **2350 个「一专题一个文件」**,带 README.md:

- 新切 1040 个(一课一练 800 / 胡小群讲义 120 / 胡小群课后 L3~L6 120),用 **qpdf** 按页范围切,**34 秒、零 API 调用**
- 其余是硬链接(动脑筋/举一反三官方拆分版、初中一专题一 docx、胡小群 L7-L9),**不额外占盘**
- 新增磁盘约 **1.7 GB**

**`_组卷台映射.json`** 把组卷台的 1920 个专题节逐个对到成品文件,**1920/1920 全部对上**。
服务端 `/api/topic` 和 `/api/topic/pdf` 都先查这张表,**直接送成品、不再现切**。

**铁律:预览什么,下载就是什么** —— 两条路径必须用同一个页范围来源。全量回归 2040/2040 一致(胡小群的讲义/课后两个文件分别验)。

重跑:
```bash
python3 组卷系统/split_topics.py          # 全量,幂等
python3 组卷系统/build_precut_map.py      # 改过 组卷台.html 后要重跑
```

---

## 五、网站化要解决的几件事(我的判断)

1. **139MB 单页扛不住公网**。配图是 base64 内嵌进 html 的(FIG 43MB),题目数据 ~90MB。上线要拆:题库数据走接口分页/按专题懒加载,配图走静态资源 + CDN。
2. **页图和源 PDF 在本地磁盘,不在 html 里**。`_专题拆分/` 5GB、页图另有 16518 张。要么上对象存储,要么这部分功能只对内网开放。
3. **零答案是红线**。题面绝不含解析/答案。`/api/similar` 出的是题干、也不带答案。任何新接口都要守住。
4. **DeepSeek key 不能进前端**,现在靠本地服务端代理;上线后要有真正的鉴权(现在是 127.0.0.1 裸跑,无登录)。
5. **`/api/page` 的白名单**是防目录穿越的唯一屏障,改路径逻辑时别绕过它。
6. **老师反馈闭环**已有:🚩 报告问题 → `问题报告.jsonl`,上线可以直接接成工单。

---

## 六、想深挖的话

飞书项目记忆 docx:`CipIdMnQgoiAEuxnqddcgBXQnpb`(整个数学学习系统的完整技术档案,含所有踩过的坑)。
本目录 `源题文件/_专题拆分/README.md` 是拆分库的详细说明。

有具体问题可以直接问我(surface:2「数学课程设计机器人」)。