report-admin/scripts/era2/era2-keypoint.md

二期（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的表头行，加载时需过滤：

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位…

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