AOS/skills/gaokao-fetch-volunteers/reference.md

智能推荐志愿表 API 速查

两阶段调用流程

fetch_volunteers.py 默认先调批次接口，再调志愿推荐接口：

1. 批次列表 GET /zp/volunteer/batch/list?province=山东&classify=综合&score=651
2. 志愿推荐 POST /zp/volunteer/intelligenceVolunteer（请求体中的 batch、volunteerType 来自第 1 步选中项）

classify 取值：文科、理科、物理、历史、综合，按省份与选科模式填写（见下文）。

批次选中规则：精确批次名 → 按 gradeType/本科批·专科批过滤 → 在达线批次中取控制线最高者。

解析结果 parsed.json 含 batch_resolution 字段，记录批次来源与可选项。

批次列表接口

项	值
路径	GET /zp/volunteer/batch/list
参数	province、classify、score；京沪津另加 gradeType
响应	{ status, message, result: [{ batch, score, gradeType, type, ... }] }

result[].type 对应志愿接口的 volunteerType（如 MAJOR_GROUP）。gradeType 仅用于筛选批次；仅京沪津才写入志愿请求体。

志愿推荐接口

项	值
路径	POST /zp/volunteer/intelligenceVolunteer
Content-Type	application/json
认证	无（公网 skill-test 接口）
默认 BASE_URL	https://publicapi.chatglm.cn/chatglm_public/skill-test
完整地址	{BASE_URL}/zp/volunteer/intelligenceVolunteer

请求体字段

字段	类型	必填	说明
province	string	✓	高考省份
classify	string	✓	文科/理科/物理/历史/综合
score	integer	✓	高考成绩
batch	string	✓	填报批次（可由 batch/list 自动解析）
subjects	string | null	模式相关	逗号分隔选科
gradeType	string | null	京沪津	本科 / 专科
rank	integer | null		位次
universitys	string | null		心仪高校，, 分隔；来自 student.preferred_universities
provinces	string | null		省份意向；来自 preferred_provinces 或由 preferred_cities 推导
tags	string | null		院校属性意向；来自 preferred_tags（如 985,211）
majorClass	string | null		专业类意向；来自 preferred_major_classes
universityNum	integer		推荐院校数，默认 30
majorNum	integer		每组专业数，默认 6
isAdjust	boolean		是否调剂
volunteerType	string		ACADEMY_GROUP / ACADEMY_MAJOR / MAJOR_GROUP
returnUniversityNum	integer		已填志愿数
intentionNum	integer		已填意向数

省份与选科模式（实测规律）

老高考（仅新疆）

字段	值
classify	文科 或 理科（二选一，不能填物理/历史/综合）
subjects	不传或 null（不要传字符串 "null"）
gradeType	不传
score	必传（新疆无一分一段表，仅传 rank 无法反查分数）

3+1+2（23 省）

广东,江苏,河北,湖北,湖南,福建,辽宁,重庆,甘肃,黑龙江,吉林,安徽,江西,贵州,广西,云南,内蒙古,四川,宁夏,山西,河南,陕西,青海

字段	值
classify	物理 或 历史（对应 3+1+2 首选科目）
subjects	完整三科，逗号分隔：首选科目,再选1,再选2。须包含与 classify 一致的首选科目，不能只传两门再选

例：classify=物理，subjects=物理,化学,生物（✓）；subjects=化学,生物（✗ 缺少物理）

再选科目仅限：化学、生物、政治、地理。 | gradeType | 不传 |

3+3（6 省）

上海,北京,天津,山东,浙江,海南

字段	值
classify	固定 综合
subjects	三科逗号分隔；浙江可选 技术
gradeType	仅京沪津需要：本科 / 专科

满分差异：山东/浙江 750；海南 900；上海本科 660；北京/天津本科 750；京沪津专科语数外 450。

京沪津 gradeType 规则

批次接口 batch/list 与志愿接口均需传 gradeType：

GET .../batch/list?province=北京&classify=综合&score=650&gradeType=本科

未填时脚本按以下规则推断：batch=专科批 → 专科；score≤450 → 专科；否则 → 本科。

场景	subjects	gradeType
北京本科	物理,化学,生物	本科
北京专科	字符串 "null"（API 要求，非 JSON null）	专科
浙江/山东/海南	三科组合	不传

西藏

测试环境平台未接入，任意 classify 均返回 status=500，非参数错误。脚本会在校验阶段直接提示不支持。

常见踩坑（批次接口）

现象	原因	处理
status=0 但 result=[]	classify 与省份模式不匹配（如山东传 物理）	按上表改 classify
志愿接口 500（山东等）	误传 gradeType	仅京沪津传，其他省移除
志愿接口 500（山东等）	缺少 subjects 或只有两门	3+1+2 须传完整三科（含物理/历史）
志愿接口 500（新疆）	subjects 为字符串 "null"	不传 subjects 字段
北京专科 500	subjects 为 JSON null 或省略	改为字符串 "null"

scripts/province_config.py 封装了上述校验与参数规范化；scripts/test_batch_api.py 可批量回归 31 省。

批次静态兜底（batch/list 失败时）

省份	batch
天津	本科批A段
浙江	普通类一段
山东	普通类一段
四川、云南	本科批B段
甘肃	本科批
宁夏	本科批B段
新疆	本科一批
西藏	测试环境暂不支持（2222010 高考省份错误）

响应结构

公网 skill-test 接口返回 { status, message, result }（status=0 为成功），脚本会自动转换为统一格式。

{
  "status": 0,
  "message": "success",
  "result": {
    "province": "...",
    "schoolList": [
      {
        "universityName": "",
        "universityCode": "",
        "universityMajorGroup": "",
        "enrollProbability": 20,
        "type": "CHONG",
        "majorList": [ { "majorName": "", "claim": "", "type": "CHONG" } ]
      }
    ]
  }
}

旧版接口格式 { code, msg, body }（code=200）同样兼容。

type 枚举：CHONG 冲、WEN 稳、BAO 保、NAN 难、YI 易。

score / parityScore 常为 JSON 字符串，如 [{"2025":"660,2153,60"}]（分,位次,计划数）。