# 二期（Era2）全市数据升级 — 关键点说明

> 更新日期：2026-03-18
> 
> 本文档用于向领导解释：为什么需要接入全市数据、接入后能带来什么价值、技术上需要注意哪些关键点。

---

## 一、背景：当前方案的局限

二期报告生成系统目前使用的数据来自**原始平台导出**（17个Excel分学科文件，经ETL合并），覆盖 **13个区、176所学校**。但存在三个核心局限：

### 1. "区均值恒等于50分"问题

当前系统对每个区**独立做标准化**（PCA + Z-score → 均值50，标准差10），导致：

- 任何一个区的"区均值"永远精确等于**50.00分**
- 校长看到的"高于区均值X分"只能反映**区内相对位置**，无法回答"我们区在全市什么水平？"
- 强区和弱区的50分含金量完全不同，但报告无法体现

### 2. 缺失学校类型信息

原始导出数据中**没有**学校类型字段（市实验性示范性高中、区实验性示范性高中、公办普通高中、民办高中、特色高中等），导致：

- 报告中"同类学校均值"被迫等于区均值，丧失了对标参考价值
- LLM分析文字无法给出针对性的定位建议（如"作为市实验性示范性高中，应在全市发挥引领作用"）
- 缺少A/B/C/D/T类学校的分类对比

### 3. 缺失3个区的数据

原始导出覆盖13个区、176所学校，缺少**嘉定区（11校）、普陀区（13校）、浦东新区（57校）**的数据，合计缺失约81所学校。

---

## 二、全市数据带来的价值

邱老师提供的全市数据（3个Excel文件）覆盖 **16个区、266所学校**，与当前数据相比：

### 价值1：全市统一基准线 ⭐⭐⭐

用全市266所学校做标准化基准后：

| 对比项 | 当前方案 | 升级后 |
|--------|----------|--------|
| 标准化基准 | 区内自己 → 区均值恒=50 | 全市266校 → 区均值有差异 |
| 杨浦区均值 | 50.00（数学定义） | 可能 52-55（反映杨浦在全市偏上） |
| 报告价值 | 只能看区内排名 | 能看到全市坐标、区域定位 |
| 校长体感 | "高于均值8分"——均值是什么？ | "高于全市均值8分"——清晰有力 |

### 价值2：学校类型对标 ⭐⭐⭐

全市数据自带每所学校的完整元数据：

| 字段 | 示例 | 报告中的用途 |
|------|------|-------------|
| 学校类型 | 市实验性示范性高中 | "同类学校均值"计算、LLM定位建议 |
| 学校类型编号 | A类/B类/C类/D类/T类 | 五类学校分组对比 |
| 学校性质 | 公办/民办 | 办学性质维度分析 |
| 所处地区 | 城区/城市郊区 | 城郊差异分析 |
| 学校特色 | 科技类/艺术类/人文类 | 特色学校的个性化建议 |

**升级后的报告示例**：
> 贵校课程实施总体得分58.75分，高于**杨浦区均值（53.2分）** 5.55分，高于**全市同类学校（市实验性示范性高中，74所）均值（54.8分）** 3.95分，在杨浦区14所学校中排名第1位。

### 价值3：覆盖完整16区 ⭐⭐

| 对比项 | 当前方案 | 升级后 |
|--------|----------|--------|
| 覆盖区域 | 13个区 | **16个区**（+嘉定、普陀、浦东新区） |
| 学校数量 | 176所 | **266所** |
| 浦东新区 | ❌ 缺失 | ✅ 57所（最大区） |

### 价值4：恢复被削弱的维度 ⭐⭐

全市数据比当前parquet **多出102个字段**，其中包括之前因原始导出格式问题被标记为"二期删除"的关键字段：

| 恢复的字段 | 归属维度 | 影响 |
|-----------|---------|------|
| `信息化平台功能_*`（18个） | 环境支持 | 该子维度从"降级评分"恢复为完整评分 |
| `管理业务的信息化应用_*`（2个） | 课程迭代优化 | 该子维度从仅1个评分项恢复到3+个 |
| `教学业务的信息化应用_*`（4个） | 课程迭代优化 | 同上 |
| `已完成的网络课程门数`（1个） | 课程迭代优化 | 同上 |
| 德育、劳动周、选课走班等（约75个） | 多个维度 | 增加评分区分度 |

> ⚠️ 唯一仍缺失的字段：`信息技术与教学融合的认识_*`（教学方式创新维度），已用`教学信息化应用程度_*`替代，不受影响。

---

## 三、技术实施方案

### 架构决策：在现有era2代码上扩展，不复制新分支

**原因**：赋分引擎、渲染引擎、模板、LLM引擎完全复用，只改数据加载层和统计基准层。复制会导致两套几乎相同的代码，后续维护成本翻倍。

### 改动范围

| 文件 | 改动内容 | 影响 |
|------|---------|------|
| `08_etl_city_data.py` | **新建** — 将全市3个xlsx转为parquet | 一次性ETL |
| `config_era2.py` | 新增全市数据路径、自动构建`SCHOOL_TYPE_MAP`（266校） | 配置扩展 |
| `data_engine_era2.py` | 支持加载全市parquet；提供全市基准数据接口 | 接口扩展 |
| `stats_engine_era2.py` | 标准化基准改为全市；同类学校均值从全市同类型算 | 核心逻辑变化 |
| `04_generate_report.py` | 新增`--city-baseline`参数（默认开启） | 参数扩展 |
| `05_batch_generate.py` | 同上 | 参数扩展 |

赋分引擎、渲染引擎、LLM引擎、模板 → **零改动**。

---

## 四、需要注意的关键点

### 关键点1：学校名称映射

全市数据使用**简称**（如"同济一附"），当前系统使用**全称**（如"同济大学第一附属中学"）。

| 来源 | 杨浦区示例 |
|------|-----------|
| 全市数据 | 同济一附、复旦附中、交大附中、控江中学 |
| 当前系统 | 同济大学第一附属中学、复旦大学附属中学… |

**处理方案**：
- 统一使用全市数据的**简称**作为系统内部标识
- 报告标题使用全称（从A表或映射表获取），正文用简称
- 需构建266所学校的 简称↔全称 映射表

### 关键点2：学校数量差异

| 数据源 | 学校数 | 说明 |
|--------|:------:|------|
| A表（基础信息） | 270 | 含4所无课程数据的学校 |
| B表（课程实施） | 266 | 以此为准 |
| C表（学科课程） | 待确认 | 理论上应与B表一致 |
| 当前parquet | 176 | 原始导出不完整 |

差异原因：当前parquet来自原始平台导出（17个分学科文件），部分区的数据未被导出。全市数据是整合后的完整版。

> **建议**：以全市B表的266所学校为准。A表多出的4所（宝山世外、协和高中、金瑞学校、青浦协和）无课程数据，不参与赋分。

### 关键点3：字段差异处理

| 类别 | 数量 | 说明 |
|------|:----:|------|
| 全市与parquet共有字段 | 331 | 赋分引擎已适配 |
| 全市多出的字段 | 102 | 其中约25个可提升赋分精度，其余为新增题目 |
| parquet独有的字段 | 5 | 其中`nan`为脏数据，其余4个为极少数学校的特殊选项 |

**原则**：赋分引擎基于字段名称匹配，多出的字段不会报错（被忽略），但可以主动利用恢复的字段提升评分精度。

### 关键点4：B表中的表头行污染

全市B表的`所在区`列中混有一行值为`district`的表头行，加载时需过滤：
```python
df = df[df['所在区'] != 'district']
```

### 关键点5：标准化基准变化的影响

使用全市基准后，**所有已生成的报告得分都会变化**：

| 影响 | 说明 |
|------|------|
| 分数值变化 | 同一学校的得分可能从58.75→55.2或→62.3（取决于全市分布） |
| 排名逻辑不变 | 区内排名仍按区内学校比较 |
| 水平划分 | 阈值不变（仍用赋分整理表中的固定阈值），但学校可能跨水平 |
| LLM缓存 | 所有旧缓存失效，需重新生成（约50秒/校） |

> **建议**：全市基准上线后，需一次性重新生成所有已交付区域的报告。

### 关键点6：C表文件较大

`C全市数据_学科课程实施情况表_sh_sub7(全)(1).xlsx` 约44MB，包含全市15个学科×266校的数据。ETL转parquet后约10-15MB，后续读取速度不受影响。

---

## 五、实施步骤（预估）

| 步骤 | 工作量 | 说明 |
|------|--------|------|
| 1. 全市数据ETL（xlsx→parquet） | 30分钟 | 新建脚本，处理名称映射和表头清洗 |
| 2. 构建全量SCHOOL_TYPE_MAP | 15分钟 | 从A/B表提取266校元数据 |
| 3. 改造data_engine支持全市数据 | 30分钟 | 加载全市parquet，提供基准接口 |
| 4. 改造stats_engine标准化逻辑 | 45分钟 | 全市基准 + 同类学校均值 |
| 5. 恢复C类削弱字段的赋分 | 30分钟 | 环境支持、课程迭代优化维度 |
| 6. 测试验证 | 30分钟 | 对比前后得分变化，确认逻辑正确 |
| 7. 重新生成已交付区域报告 | ~60分钟 | 杨浦14校+宝山19校+长宁9校 |

**合计：约 3-4 小时**

---

## 六、预期效果对比

### 报告第一段（Before）
> 贵校课程实施总体得分为58.75分，高于**长宁区**均值（**50.00分**）8.75分，同时高于同类学校均值（**50.00分**）8.75分…

### 报告第一段（After）
> 贵校课程实施总体得分为XX.XX分，高于**杨浦区**均值（**XX.XX分**）X.XX分，高于**全市同类学校（市实验性示范性高中，74所）** 均值（**XX.XX分**）X.XX分。在杨浦区14所学校中排名第1位，在全市同类学校中排名第X位…

信息密度和说服力显著提升。