# 二期数据处理脚本

## 数据概况

| 项目 | 一期 | 二期 |
|------|------|------|
| 区域 | 仅长宁区 | **13个区** |
| 学校数 | 9所 | **176~177所** |
| 基础信息表 | 277行 | 5,557行 |
| 课程实施情况表 | 5,506行 / 128题 | 145,484行 / **103题** |
| 学科课程实施情况表 | 25,006行 / 131题 | **1,348,513行** / 87~131题 |

### 一期 vs 二期 关键差异

1. **格式不同**：一期是3张扁平Excel，二期是原始平台导出（每题一个Sheet + 15个学科独立文件）
2. **题目数量**：课程实施表少了25题（128→103），学科表按学科不同题数也不同
3. **学校名称**：一期用简称（"延安中学"），二期用全称（"上海市延安中学"）
4. **长宁区**：二期只有8所（缺少"市三女中"），一期有9所
5. **字段ID覆盖**：
   - 课程实施表：共有275个，一期独有74个，二期独有62个
   - 学科表字段名称：共有713个，一期独有150个，二期独有53个

## 脚本说明

### `01_etl_transform.py` — ETL转换

将二期原始数据转换为与一期相同列结构的3张扁平表（parquet格式）。

```bash
cd report-admin
python3 scripts/era2/01_etl_transform.py
```

**输入**：`二期/[整理前] 二期_课程实施+教材使用情况表/` 下的17个xlsx文件
**输出**：`data/era2/` 下的3个parquet文件 + etl_meta.json

- `era2_基础信息表.parquet` — 列与一期完全一致
- `era2_课程实施情况表.parquet` — 列与一期完全一致
- `era2_学科课程实施情况表.parquet` — 列与一期完全一致
- `etl_meta.json` — 元信息（学校列表、区域列表等）

> ⚠️ 学科表有135万行，超过Excel行数上限(1,048,576)，因此使用parquet格式

### `02_verify_data.py` — 数据验证

对比一期和二期的列名、字段ID、学校名称等。

```bash
cd report-admin
python3 scripts/era2/02_verify_data.py
```

## 完整脚本列表

| 脚本 | 功能 | 用法 |
|------|------|------|
| `01_etl_transform.py` | 原始格式 → 扁平表 parquet | `python3 scripts/era2/01_etl_transform.py` |
| `02_verify_data.py` | 验证 ETL + 一期对比 | `python3 scripts/era2/02_verify_data.py` |
| `03_test_pipeline.py` | 完整 Pipeline 测试（不调 LLM） | `python3 scripts/era2/03_test_pipeline.py --district 长宁区` |
| `04_generate_report.py` | 单校报告生成 | `python3 scripts/era2/04_generate_report.py --school 延安中学` |
| `05_batch_generate.py` | 批量报告生成 | `python3 scripts/era2/05_batch_generate.py --district 长宁区` |
| `config_era2.py` | 二期配置（路径、学校映射等） | 被其他脚本导入 |
| `data_engine_era2.py` | 二期数据引擎（兼容一期接口） | 被其他脚本导入 |

### 关键参数

- `--district 长宁区` — 只分析长宁区8所学校（默认）
- `--district all` — 分析全部13个区176所学校
- `--enable-llm` — 启用 LLM 文字生成（**会产生 API 费用**）
- `--school 延安中学` — 指定学校（支持简称）
- `--list-schools` — 列出可用学校

### 运行示例

```bash
cd report-admin

# 1. ETL（只需运行一次）
python3 scripts/era2/01_etl_transform.py

# 2. 测试 pipeline（长宁区）
python3 scripts/era2/03_test_pipeline.py --district 长宁区

# 3. 全市 pipeline
python3 scripts/era2/03_test_pipeline.py --district all

# 4. 生成延安中学报告（不调LLM）
python3 scripts/era2/04_generate_report.py --school 延安中学

# 5. 批量生成长宁区全部报告（不调LLM）
python3 scripts/era2/05_batch_generate.py --district 长宁区

# 6. 启用LLM生成（⚠️ 会产生费用）
python3 scripts/era2/04_generate_report.py --school 延安中学 --enable-llm
```

## 后续优化方向

1. **学校名称映射扩展**：目前只配了长宁区8所学校的全称→简称映射，全市176所需补充
2. **学校类型信息补充**：办学性质、学校等级、特色类型等（一期在 config 手工配了9所）
3. **题号映射精细核对**：确认二期103题与一期128题的对应关系，优化赋分覆盖率
4. **赋分规则适配**：基于字段ID的赋分规则大部分可复用，但部分新增/缺失字段需处理
5. **全市对照基准**：二期有176所学校，PCA和标准化终于有统计意义，可做真正的全市对照