report-admin/scoring_engine_documentation.md

# 二期赋分引擎完整计算方法文档

> 自动生成于 2026-03-22，基于 `scoring_engine_era2.py`、`stats_engine_era2.py`、`config_era2.py`

---

## 一、总体数据流

```
原始问卷项 (B表=课程实施情况表, C表=学科课程实施情况表)
    ↓
_score_*() 方法：提取字段 → 赋分 → 输出 List[float]（每个学科/条目一个分值）
    ↓
每个学校得到 Dict[子维度名, List[float]]（20个子维度的原始分列表）
    ↓
compute_dimension_scores():
    对每个子维度：raw_score = nanmean(list)  → 得到每校一个标量
    全市所有学校的该子维度标量 → standardize_scores() → 标准化分
    ↓
compute_dimension_aggregates():
    维度分 = mean(该维度下所有子维度的标准化分)
    总体得分 = mean(7个维度分)
    ↓
compute_levels():
    对每个子维度标准化分 → determine_level() → 水平1/2/3/4
```

## 二、标准化方法 (stats_engine_era2.py)

### standardize_scores()
```python
标准化分 = (raw - mean) / std * PCA_STD + PCA_MEAN
```
- `raw`: 全市所有学校该子维度的原始均值数组
- `mean`: 全市 nanmean
- `std`: 全市 nanstd(ddof=1)（样本标准差）
- `PCA_MEAN = 50`, `PCA_STD = 10`
- 若 std=0 或样本<2，全部赋值 PCA_MEAN(50)

**本质：z-score 线性变换到 均值50、标准差10 的分布。**

### pca_compose()（仅在多列合成时使用）
- 用 StandardScaler 对多列标准化
- 做 PCA 取第一主成分
- 若loadings总和<0则翻转
- 最后再做 standardize_scores()
- **注意：当前20个子维度的 compute_dimension_scores() 并不使用 pca_compose()，而是直接 standardize_scores()。PCA仅作为可选工具。**

### determine_level()
基于 LEVEL_THRESHOLDS 配置的断点：
- score > level4 → 水平4
- score > level3 → 水平3
- score > level2 → 水平2
- 否则 → 水平1

### 维度聚合
- **维度分** = 该维度下所有子维度标准化分的 **算术平均**（等权）
- **总体得分** = 7个维度分的 **算术平均**（等权）

### 聚类
- KMeans(n_clusters=2) 在区内学校的维度分上做
- 分为"较好"和"待提升"两组

---

## 三、20个子维度详细计算方法

### 维度一：课程领导力

---

#### 1. 国家标准遵循

| 属性 | 值 |
|---|---|
| **数据源** | C表（学科课程实施情况表）via `get_weekly_hours()` |
| **字段** | 学科必修课周课时、学科选择性必修课周课时、学科类选修课周课时 |
| **赋分方式** | 按课程类型分三项打分 |
| **聚合** | 输出 scores 列表（3项），最终 nanmean → 1个标量 |

**详细逻辑：**
1. **必修**：统计9门考试科目（语数英物化生历地政）各学科周课时是否>0。
   - 9门全部开设 → 2.0
   - ≥6门开设 → 1.0
   - <6门 → 0.0
2. **选必**：全部学科选必课时总和 > 0 → 1.0，否则 0.0
3. **选修**：全部学科选修课时总和 > 0 → 1.0，否则 0.0
4. 若无数据 → 默认 [1.0]

**水平阈值（标准化分）：** >57=水平4, >53.5=水平3, >43=水平2, ≤43=水平1

---

#### 2. 课程结构建设

| 属性 | 值 |
|---|---|
| **数据源** | C表（周课时）+ B表（课程实施情况表） |
| **字段** | 周课时各学科占比 + 跨学科/综合主题/综合实践选修课门数 + 研究性学习数量/社会考察个数/志愿服务时长 |
| **赋分方式** | 连续值 |
| **聚合** | 输出 scores 列表（最多7项），最终 nanmean |

**详细逻辑：**
1. **均衡度**：各学科周课时占总课时比例 → 计算偏离均值的绝对偏差之和 `deviation`
   - `structure_score = max(0, 3 - deviation * 10)`
2. **校本课程**（3个字段，各自独立）：
   - 跨学科选修课门数: `min(v/5, 3.0)`
   - 综合主题选修课门数: `min(v/5, 3.0)`
   - 综合实践选修课门数: `min(v/5, 3.0)`
3. **综合实践**（3个字段，各自独立）：
   - 三年应完成的研究性学习数量: `min(v/10, 3.0)`
   - 三年社会考察个数: `min(v/10, 3.0)`
   - 三年志愿服务时长: `min(v/10, 3.0)`
4. 若无数据 → 默认 [1.0]

**水平阈值：** >55.5=水平4, >49=水平3, >45=水平2, ≤45=水平1

---

#### 3. 课程规范落实

| 属性 | 值 |
|---|---|
| **数据源** | B表 via `get_course_norms()` |
| **字段** | 含"建设规范文本"的字段 + 含"档案"的字段 |
| **赋分方式** | 二值计数→比例→缩放 |
| **聚合** | 输出 scores 列表（最多2项），最终 nanmean |

**详细逻辑：**
1. **规范文本**：统计所有"建设规范文本"字段，有值非空/非0的计2分 → `norm_score/norm_count * 2`
2. **档案**：
   - "已经建成并使用" = 1 → 得2分
   - "已经建成" = 1 → 得1分
   - → `archive_score/archive_count * 2`
3. 若无数据 → 默认 [1.0]

**水平阈值：** >58=水平4, >50=水平3, >44=水平2, ≤44=水平1

---

### 维度二：教学变革力

---

#### 4. 教学方式变革

| 属性 | 值 |
|---|---|
| **数据源** | C表（学科课程实施情况表） |
| **字段** | 含"认识程度/认识"、"落实程度/落实"、"体现形式"的字段 |
| **赋分方式** | Likert量表(1-4) + 二值计数 |
| **聚合** | 每学科内部 mean → 15学科各一个分 → 全部进入 scores → nanmean |

**详细逻辑（每学科）：**
1. 匹配"认识程度/认识"的字段 → `_score_likert(value, scale=4)`：提取数字1-4
2. 匹配"落实程度/落实"的字段 → `_score_likert(value, scale=4)`
3. 匹配"体现形式"的字段 → 统计值为"1"的数量 → `min(form_count, 6)`
4. 每学科取 `np.mean(sub_scores)`
5. 若无数据 → 默认 [2.0]

**水平阈值：** >54=水平4, >49=水平3, >45=水平2, ≤45=水平1

---

#### 5. 作业设计与管理变革

| 属性 | 值 |
|---|---|
| **数据源** | C表 |
| **字段** | 实践类/表现类/跨学科/团队合作类作业_未布置；作业属性标注_*；回家作业时长控制_*；作业批改范围_* |
| **赋分方式** | 二值→分级 + 计数 |
| **聚合** | 每学科 mean → 15学科各一个分 → nanmean |

**详细逻辑（每学科）：**
1. **4种创新作业布置**（[ERA2-FIX-04/05/06/07]）：
   - 若 `{前缀}_未布置` == "1" → 0.0
   - 否则：统计该前缀下非"未布置/案例"子字段值为"1"的数量 `type_count`
   - 得分 = `min(1.0 + type_count * 0.2, 2.0)`
   - 默认（无字段）→ 1.0
2. **作业属性标注**：值为"1"的属性数量 `attr_count` → `min(attr_count, 5)`
3. **作业管理**（4个字段互斥打分）：
   - 回家作业时长控制_学校控制 → 3
   - 回家作业时长控制_教研组负责 → 2
   - 作业批改范围_全部批改 → 3
   - 作业批改范围_全部教材练习 → 1 [ERA2-FIX-03]
4. 每学科 `np.mean(sub_scores)`
5. 若无数据 → 默认 [1.5]

**水平阈值：** >54=水平4, >49=水平3, >45=水平2, ≤45=水平1

---

### 维度三：学生发展指导力

---

#### 6. 学科发展的个性化辅导

| 属性 | 值 |
|---|---|
| **数据源** | C表 |
| **字段** | 个别辅导时长_* + 个别辅导实施方式_* |
| **赋分方式** | 分类赋值（ordinal） |
| **聚合** | 15学科×2项（时长+方式） → scores 列表 → nanmean |

**详细逻辑（每学科）：**
1. **辅导时长**（互斥取first-match）[ERA2-FIX-01/02]：
   - 个别辅导时长_每周2h+ → 4
   - 个别辅导时长_每周1~2h → 3
   - 个别辅导时长_每周1h- → 2
   - 个别辅导时长_几乎无 → 1
2. **辅导方式**（互斥取first-match）：
   - 分散辅导 → 3
   - 分组统一辅导 → 2
   - 班级统一辅导 → 1
3. 若无数据 → 默认 [2.0]

**水平阈值：** >60=水平4, >50=水平3, >46=水平2, ≤46=水平1

---

#### 7. 学生生涯发展指导

| 属性 | 值 |
|---|---|
| **数据源** | B表 |
| **字段** | 生涯指导实施方式_*；完成生涯指导的学生占比_*；生涯指导教师构成_*；生涯指导的校外/校内资源支持程度 |
| **赋分方式** | 分类赋值 + `_score_resource_level()` |
| **聚合** | 所有项进入 scores 列表 → nanmean |

**详细逻辑：**
1. **实施方式**（累加，非互斥）：
   - 专设课程 → 3
   - 社会考察和志愿服务 → 2
2. **覆盖率**：90%+ → 4，否则 → 2
3. **教师构成**（互斥 first-match）：
   - 本校和外聘结合 → 4
   - 本校为主 → 3
4. **资源支持**（2项，各用 `_score_resource_level()`）：提取数字1-3，或模糊匹配"足够"→3/"一些"→2/"没有"→1
5. 若无数据 → 默认 [2.0]

**水平阈值：** >56=水平4, >50=水平3, >42=水平2, ≤42=水平1

---

### 维度四：教师发展支持力

---

#### 8. 培训支持

| 属性 | 值 |
|---|---|
| **数据源** | C表 |
| **字段** | 提供外校培训的教师人数、区域培训指导人数 |
| **赋分方式** | 连续值截断 `min(v, 5)` |
| **聚合** | 15学科×2字段 → scores → nanmean |

**详细逻辑（每学科）：**
- 提供外校培训的教师人数 → `min(float(v), 5)`
- 区域培训指导人数 → `min(float(v), 5)`
- 若无数据 → 默认 [1.0]

**水平阈值：** >51=水平4, >49=水平3, >47.5=水平2, ≤47.5=水平1

---

#### 9. 教研支持

| 属性 | 值 |
|---|---|
| **数据源** | C表 |
| **字段** | 学科教研组每学期活动次数、平均每次活动时长、工作计划_有、校级/区域展示次数_*、成果发表次数_* |
| **赋分方式** | 连续值变换 + 二值 + 次数分级 |
| **聚合** | 15学科多项 → scores → nanmean |

**详细逻辑（每学科）：**
1. **活动次数**：`min(v/3, 4)` （即每学期3次=1分，12次以上=4分）
2. **活动时长**：`min(v/30, 4)` （即30分钟=1分，120分钟以上=4分）
3. **教研计划**：学科教研工作计划_有 == "1" → 2
4. **展示/发表**（[ERA2-FIX-08/09/10]，3个前缀各自独立）：
   - 从 `{前缀}次数_0/1/2/3/4/5以上` 找选中项
   - 0次 → 不给分
   - 1-2次 → 2
   - 3-4次 → 3
   - 5次以上 → 4
5. 若无数据 → 默认 [1.0]

**水平阈值：** >55=水平4, >50=水平3, >47=水平2, ≤47=水平1

---

#### 10. 项目支持

| 属性 | 值 |
|---|---|
| **数据源** | C表 + B表 |
| **字段** | （C表）学科承担的市级/区级/校级教改项目个数；（B表）学校负责/参与的市级/区级教改项目个数、校级教改项目个数 |
| **赋分方式** | 连续值截断 `min(v, 5)` |
| **聚合** | 所有项 → scores → nanmean |

**详细逻辑：**
1. **学科层面（C表）**：15学科 × 3字段（市/区/校级），每个 `min(float(v), 5)`
2. **学校层面（B表）**：5字段（学校负责市级/参与市级/负责区级/参与区级/校级），每个 `min(float(v), 5)`
3. 若无数据 → 默认 [0.5]

**水平阈值：** >56.5=水平4, >50=水平3, >44=水平2, ≤44=水平1

---

### 维度五：教育质量评估力

---

#### 11. 科学评价观

| 属性 | 值 |
|---|---|
| **数据源** | C表 |
| **字段** | 含"作业评价关注点"、"课堂表现评价关注点"、"学科实践活动评价关注点"的字段 |
| **赋分方式** | 关注点计数 → 连续值 |
| **聚合** | 15学科各一分 → scores → nanmean |

**详细逻辑（每学科）：**
- 匹配3类关注点字段，统计值为"1"的总数 `focus_count`
- 得分 = `min(focus_count / 3, 4)` （每3个关注点=1分，最高4分）
- 若无数据 → 默认 [2.0]

**水平阈值：** >57=水平4, >50=水平3, >43=水平2, ≤43=水平1

---

#### 12. 学业质量评估

| 属性 | 值 |
|---|---|
| **数据源** | C表 |
| **字段** | 作业评价工具_*；课堂表现评价工具_*；学期考试分析_*；表现性评价应用程度_* |
| **赋分方式** | 分类赋值（互斥first-match） |
| **聚合** | 15学科×3组选项 → scores → nanmean |

**详细逻辑（每学科）：**
1. **评价工具**（互斥）：
   - 作业评价工具_已经建成并使用 → 2
   - 课堂表现评价工具_已经建成并使用 → 2
   - 作业评价工具_已经建成尚未使用 → 1
   - 作业评价工具_尚未建成和使用 → 0
2. **考试分析**（互斥）：
   - 执行分析并存档 → 3
   - 执行分析，不要求存档 → 2
   - 教师自己决定 → 1
3. **表现性评价应用**（互斥）：
   - 经常/总是 → 4
   - 有时 → 3
   - 从不 → 1
4. 若无数据 → 默认 [2.0]

**水平阈值：** >54=水平4, >46=水平3, >41=水平2, ≤41=水平1

---

#### 13. 综合素质评估

| 属性 | 值 |
|---|---|
| **数据源** | B表 |
| **字段** | 综评评价体系_*；综评信息化实现_*；综评结果使用/综评应用_* |
| **赋分方式** | 分类赋值 + 计数 |
| **聚合** | 所有项 → scores → nanmean |

**详细逻辑：**
1. **评价体系**（互斥）：
   - 已经建成并使用 → 3
   - 已经建成尚未使用 → 2
   - 未建成 → 1
   - 不准备建设 → 0
2. **信息化实现**（互斥）：
   - 自建平台支持 → 2
   - 借助第三方平台支持 → 1
3. **结果使用**：匹配"综评结果使用/综评应用"的字段，值为"1"的数量 → `min(use_count, 6)`
4. 若无数据 → 默认 [1.0]

**水平阈值：** >58.5=水平4, >50=水平3, >39=水平2, ≤39=水平1

---

#### 14. 实践活动评估

| 属性 | 值 |
|---|---|
| **数据源** | B表 + C表 |
| **字段** | 研究性学习评价工具_*；社会考察评价工具_*；学科实践活动工具_* |
| **赋分方式** | 分类赋值（互斥） |
| **聚合** | 所有项 → scores → nanmean |

**详细逻辑：**
1. **研究性学习评价工具**（B表，互斥）：
   - 已经建成并使用 → 2
   - 尚未建成和使用 → 0
2. **社会考察评价工具**（B表，互斥）：
   - 已经建成并使用 → 2
   - 尚未建成和使用 → 0
3. **学科实践活动工具**（C表，仅取前5学科，互斥）：
   - 已经建成并使用 → 2
   - 已经建成尚未使用 → 1
   - 尚未建成和使用 → 0
4. 若无数据 → 默认 [1.0]

**水平阈值：** >50=水平4, >46.5=水平3, >43=水平2, ≤43=水平1

---

### 维度六：教育条件保障力

---

#### 15. 区域推进

| 属性 | 值 |
|---|---|
| **数据源** | B表 |
| **字段** | 区域工作会参与_*；区域推进措施_* |
| **赋分方式** | 分类赋值 + 计数 |
| **聚合** | 所有项 → scores → nanmean |

**详细逻辑：**
1. **会议频率**（互斥）：
   - 一月4次以上 → 7
   - 一月1次 → 5
   - 二月1次 → 3
   - 三月1次 → 1
2. **推进措施**：值为"1"的项数 → `min(measure_count, 5)`
3. 若无数据 → 默认 [2.0]

**水平阈值：** >59=水平4, >52=水平3, >40=水平2, ≤40=水平1

---

#### 16. 环境支持

| 属性 | 值 |
|---|---|
| **数据源** | B表 |
| **字段** | 场馆供给_*；专用教室供给_*；信息化平台功能_* |
| **赋分方式** | 分类赋值 + 计数 |
| **聚合** | 所有项 → scores → nanmean |

**详细逻辑：**
1. **场馆供给**（互斥）：
   - 能满足需要 → 3
   - 基本满足需要 → 2
   - 难以满足需要 → 1
2. **专用教室供给**（互斥）：
   - 能满足需要 → 3
   - 基本满足需要 → 2
3. **信息化平台功能**：统计 `信息化平台功能_*` 子字段值为"1"的数量 → `min(count/3, 5)` （18个子功能，每3个1分，最高5分）
4. 若无数据 → 默认 [2.0]

**水平阈值：** >56=水平4, >49.5=水平3, >41=水平2, ≤41=水平1

---

#### 17. 资源支持

| 属性 | 值 |
|---|---|
| **数据源** | C表 |
| **字段** | 必修课校内/校外资源支持程度；选择性必修课校内/校外资源支持程度；学科教研组总人数 |
| **赋分方式** | `_score_resource_level()` + 连续值 |
| **聚合** | 15学科×5字段 → scores → nanmean |

**详细逻辑（每学科）：**
1. **校内资源**（2字段）：`_score_resource_level()` → 提取数字1-3（足够=3, 一些=2, 没有=1）
2. **校外资源**（2字段）：同上
3. **师资**：学科教研组总人数 → `min(total/3, 4)`
4. 若无数据 → 默认 [2.0]

**`_score_resource_level()` 逻辑：** 尝试提取首个数字 → 成功则返回。否则模糊匹配"足够"/3→3, "一些"/2→2, "没有"/1→1

**水平阈值：** >57.5=水平4, >49=水平3, >42=水平2, ≤42=水平1

---

### 维度七：数字化赋能力

---

#### 18. 教学方式创新

| 属性 | 值 |
|---|---|
| **数据源** | C表 |
| **字段** | 教学信息化应用程度_*（[ERA2替代字段]）；信息化终端使用比例_* |
| **赋分方式** | 分类赋值（ordinal 1-4） |
| **聚合** | 15学科×2组选项 → scores → nanmean |

**详细逻辑（每学科）：**
1. **教学信息化应用程度**（互斥，替代一期"信息技术与教学融合的认识"）：
   - 师生用于全流程 → 4
   - 师生用于教学和评价 → 3
   - 师生用于教学 → 2
   - 教师用于教学 → 1
2. **信息化终端使用比例**（互斥）：
   - 80%+ → 4
   - 60~79% → 3
   - 30~59% → 2
   - 30%- → 1
3. 若无数据 → 默认 [2.0]

**水平阈值：** >54=水平4, >45=水平3, >40=水平2, ≤40=水平1

---

#### 19. 评价精准化与个性化

| 属性 | 值 |
|---|---|
| **数据源** | C表 + B表 |
| **字段** | （C表）学业评价信息化实现_*；（B表）学校信息系统对选课/排课支持程度 |
| **赋分方式** | 分类赋值 + `_score_resource_level()` |
| **聚合** | 15学科×1字段 + 2个学校字段 → scores → nanmean |

**详细逻辑：**
1. **学业评价信息化**（C表，每学科，互斥）：
   - 自建平台支持 → 3
   - 借助第三方平台支持 → 2
   - 没有平台支持 → 0
2. **信息系统支持**（B表，2字段）：
   - 学校信息系统对选课支持程度 → `_score_resource_level()`
   - 学校信息系统对排课支持程度 → `_score_resource_level()`
3. 若无数据 → 默认 [1.5]

**水平阈值：** >60=水平4, >50=水平3, >40=水平2, ≤40=水平1

---

#### 20. 课程迭代优化

| 属性 | 值 |
|---|---|
| **数据源** | B表 |
| **字段** | 数据连通_*；管理业务的信息化应用_*；教学业务的信息化应用_*；已完成的网络课程门数 |
| **赋分方式** | 分类赋值 + 连续值 |
| **聚合** | 所有项 → scores → nanmean |

**详细逻辑：**
1. **数据连通**（互斥）：
   - 有数据能互通 → 3
   - 有数据不互通 → 1
   - 无意识（二期新增）→ 0
2. **管理业务信息化**（互斥）：
   - 绝大部分 → 3
   - 少数 → 1
3. **教学业务信息化**（互斥）：
   - 绝大部分 → 3
   - 少数 → 1
   - 几乎不用 → 0
   - 无系统支持 → 0
4. **网络课程**：`min(v/5, 4)` （每5门1分，最高4分）
5. 若无数据 → 默认 [1.5]

**水平阈值：** >55=水平4, >50=水平3, >45=水平2, ≤45=水平1

---

## 四、二期 vs 一期差异汇总（ERA2-FIX标记）

| FIX编号 | 子维度 | 变更内容 |
|---|---|---|
| ERA2-FIX-01 | 个性化辅导 | `个别辅导时长_每周>2h` → `个别辅导时长_每周2h+` |
| ERA2-FIX-02 | 个性化辅导 | `个别辅导时长_每周<1h` → `个别辅导时长_每周1h-` |
| ERA2-FIX-03 | 作业变革 | `作业批改范围_部分练习` → `作业批改范围_全部教材练习` |
| ERA2-FIX-04 | 作业变革 | `实践类作业_有布置` → 反推 `实践类作业_未布置 ≠ 1` |
| ERA2-FIX-05 | 作业变革 | `表现类作业_有布置` → 反推 `表现类作业_未布置 ≠ 1` |
| ERA2-FIX-06 | 作业变革 | `跨学科作业_有布置` → 反推 `跨学科作业_未布置 ≠ 1` |
| ERA2-FIX-07 | 作业变革 | `团队合作类作业_有布置` → 反推 `团队合作类作业_未布置 ≠ 1` |
| ERA2-FIX-08 | 教研支持 | `学科教研组校级展示_有` → `学科教研组校级展示次数_0/1/../5以上`（次数分级赋分） |
| ERA2-FIX-09 | 教研支持 | `学科教研组区域展示_有` → 同上 |
| ERA2-FIX-10 | 教研支持 | `学科教研组成果发表_有` → 同上 |
| C类-替代 | 教学方式创新 | `信息技术与教学融合的认识_*` → `教学信息化应用程度_*` |
| C类-恢复 | 环境支持 | `信息化平台功能_*` 在全市数据中已恢复 |
| C类-恢复 | 课程迭代优化 | `管理/教学业务信息化应用` + `已完成网络课程门数` 在全市数据中已恢复 |

---

## 五、辅助函数

### `_score_likert(value, scale=4, reverse=False)`
- 提取字符串首个整数
- reverse=True 时：`scale + 1 - v`
- 返回 float 或 None

### `_score_resource_level(value)`
- 提取首个整数 → 返回
- 否则模糊匹配：足够/3→3.0, 一些/2→2.0, 没有/1→1.0

### `_get_count_from_options(sub_df, prefix)`
- 从 `{prefix}_0/1/2/3/4/5以上` 找值为"1"的选项
- 返回对应整数（5以上=5）

---

## 六、关键计算参数

| 参数 | 值 | 用途 |
|---|---|---|
| PCA_MEAN | 50 | 标准化目标均值 |
| PCA_STD | 10 | 标准化目标标准差 |
| SUBJECTS | 15个学科 | 逐学科循环的学科列表 |
| 维度聚合 | 等权mean | 子维度→维度、维度→总分 |
| 标准化基准 | 全市所有学校 | standardize_scores用全市分布 |
| 聚类基准 | 区内学校 | KMeans用区内数据 |