一键智能填报

接口概述

• 接口地址：POST /api/v1/volunteer/smart-match
• 接口说明：根据考生省份、批次、分数、位次、选科与志愿类型，自动生成冲稳保志愿表数据。
• Content-Type：application/json

本接口复刻旧版 /api/v2025-open/v1/volunteer/smart_match 逻辑，会读取省份志愿规则配置，并按 volunteerType 生成不同结构的志愿数据。

请求参数

参数名	类型	必填	默认值	说明
province	string	是	-	考生省份，如 江苏
batch	string	是	-	批次，如 本科批、专科批、普通类一段
rank_year	number / string	是	-	位次/推荐数据年份，如 2024
rank	number	否	0	考生位次
score	number	否	0	考生分数
is_key	number	否	0	旧版兼容字段
token	string	否	空字符串	缓存标识，响应中的 cache_zyb 为 cacheZyb:{token}
type	number	否	1	志愿策略类型：1 冲稳保、2 合理保守、3 标准均衡、4 激进冲刺
subject	string	否	综合	首选科目/科类，如 物理、历史、理科、文科、综合
xuanke	string	否	综合	选科字符串，多个用英文逗号分隔。为兼容旧版科类推导，3+1+2 省份建议包含首选科目，如 物理,化学,生物

batch 可参考动态批次接口：POST /api/v1/meta/batches。科目可参考动态科目接口：POST /api/v1/meta/subjects。

请求示例

{
  "province": "江苏",
  "batch": "本科批",
  "rank_year": 2024,
  "rank": 70814,
  "score": 500,
  "is_key": 0,
  "token": "demo-token-001",
  "type": 1,
  "subject": "物理",
  "xuanke": "物理,化学,生物"
}

响应参数

顶层字段

字段名	类型	说明
code	number	状态码，成功为 200
message	string	提示信息，成功为 获取成功
data	object	一键填报结果

data 字段

字段名	类型	说明
zyb_type	array	志愿策略类型列表，包含每种策略的冲稳保数量
zyb_data	object	当前策略生成的志愿表数据
zyb_rule	object	当前省份、批次、年份匹配到的志愿规则

zyb_type[] 字段

字段名	类型	说明
name	string	策略名称
type	number	策略类型
is_default	number	是否当前选中策略，1 是，0 否
rule	object	该策略下冲稳保数量
rule.chong	number	冲刺数量
rule.wen	number	稳妥数量
rule.bao	number	保底数量

zyb_data 字段

字段名	类型	说明
cache_zyb	string	缓存 key，格式为 cacheZyb:{token}
zyb_type	number	当前策略类型
zyb_id	number	旧版兼容字段，当前为 0
zybData	object	冲稳保志愿数据
zybData.chong	array	冲刺志愿列表
zybData.wen	array	稳妥志愿列表
zybData.bao	array	保底志愿列表

zybData.chong / wen / bao 列表项

字段名	类型	说明
sid	number	院校 ID
schoolName	string	院校名称
schoolCode	string / number	院校代码
index	number	排序索引
source	string	来源档位：chong、wen、bao
sg_name	string	专业组名称
f985	string / number	985 标识
f211	string / number	211 标识
nature_name	string	办学性质
dual_class_name	string	双一流信息
level_name	string	院校层次
zyList	array	专业列表
min_diff	number	专业最低位次与考生位次的最小差值

zyList[] 字段

字段名	类型	说明
zyId	number	专业 ID
zyName	string	专业名称
index	number	专业索引
source	string	来源档位
sg_name	string	专业组名称
sp_code	string	专业代码
luqu_rate	string	旧版固定字段，当前为 80%
min	number	专业最低分
min_section	number	专业最低位次
num	number	招生人数
length	string	学制
rating	number	专业评级
ranking	number	专业排名
diff	number	专业最低位次与考生位次差值

zyb_rule 字段

字段名	类型	说明
subjectsType	number	选科模式：2 为 3+1+2，3 为 3+3
batchName	string	配置匹配到的批次名
scoreMax	number	满分
volunteerType	number	志愿类型：1 一个志愿=一个学校多个专业；2 一个志愿=一个学校一个组多个专业；3 一个志愿=一个学校一个专业
volunteerNumMax	number	最大志愿数量
majorNumMax	number	每个志愿最大专业数量

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "zyb_type": [
      {
        "name": "冲稳保",
        "type": 1,
        "is_default": 1,
        "rule": {
          "chong": 10,
          "wen": 20,
          "bao": 10
        }
      }
    ],
    "zyb_data": {
      "cache_zyb": "cacheZyb:demo-token-001",
      "zyb_type": 1,
      "zyb_id": 0,
      "zybData": {
        "chong": [],
        "wen": [
          {
            "sid": 1061,
            "schoolName": "厦门理工学院",
            "schoolCode": "",
            "index": 16,
            "source": "wen",
            "sg_name": "(02)",
            "f985": "",
            "f211": "",
            "nature_name": "公办",
            "dual_class_name": "",
            "level_name": "普通本科",
            "zyList": [
              {
                "zyId": 16219,
                "zyName": "土木工程",
                "index": 0,
                "source": "wen",
                "sg_name": "(02)",
                "sp_code": "241312",
                "luqu_rate": "80%",
                "min": 547,
                "min_section": 78999,
                "num": 2,
                "length": "四年",
                "rating": 2,
                "ranking": 15,
                "diff": 8185
              }
            ],
            "min_diff": 8185
          }
        ],
        "bao": []
      }
    },
    "zyb_rule": {
      "subjectsType": 2,
      "batchName": "本科批",
      "scoreMax": 750,
      "volunteerType": 2,
      "volunteerNumMax": 40,
      "majorNumMax": 6
    }
  }
}

错误响应

{
  "code": 400,
  "message": "缺少必要参数：province、batch、rank_year",
  "data": {}
}

常见错误：

场景	message
缺少省份、批次或年份	缺少必要参数：province、batch、rank_year
type 不在 1-4 范围内	志愿类型不存在
省份批次没有匹配配置	{province}省暂无<{batch}>的志愿填报规则
没有可生成的冲稳保数据	{province}省{rank_year}年暂无<{subject}、{xuanke}>数据

curl 示例

curl -X POST http://localhost:3666/api/v1/volunteer/smart-match \
  -H 'Content-Type: application/json' \
  -d '{
    "province": "江苏",
    "batch": "本科批",
    "rank_year": 2024,
    "rank": 70814,
    "score": 500,
    "is_key": 0,
    "token": "demo-token-001",
    "type": 1,
    "subject": "物理",
    "xuanke": "物理,化学,生物"
  }'