lofyerandfactory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
71db82393a
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
200 lines
9.2 KiB
Markdown
200 lines
9.2 KiB
Markdown
# 二期（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位…
|
||
|
||
信息密度和说服力显著提升。
|