Initial commit

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

scripts/era2/era2-keypoint.md

@@ -0,0 +1,199 @@
+# 二期（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位…
+
+信息密度和说服力显著提升。