gaokao-volunteer-system/docs/API.md

API参考

本文档提供给开发者使用的API参考。

---

🎯 规范检查器 API

GaokaoSpecCheckerV2 类

用于检查志愿方案的规范性。

构造函数

from spec_checker_v2 import GaokaoSpecCheckerV2

checker = GaokaoSpecCheckerV2(province=None)

参数:

• province (str, 可选): 省份名称，如"湖南"、"浙江"。如果未指定，会自动检测。

方法

auto_detect_and_check(text)

自动检测省份并检查方案。

参数:

• text (str): 志愿方案文本

返回值:

• str: 检查报告（Markdown格式）

示例:

checker = GaokaoSpecCheckerV2()
report = checker.auto_detect_and_check("我是湖南考生，578分...")
print(report)

check_volunteer_unit(text)

检查志愿单位是否正确。

检测条件:

• 省份模式为"院校专业组"时，应使用"院校专业组"而非"学校"
• 省份模式为"专业+学校"时，不应使用"组内服从"

check_volunteer_count(text)

检查志愿数量是否合规。

检测条件:

• 是否超过本省最大志愿数
• 是否填满建议志愿数

check_majors_per_group(text)

检查每组专业数。

检测条件:

• 院校专业组模式：每组最多6个
• 专业+学校模式：每组1个

check_adjustment_rule(text)

检查调剂规则。

检测条件:

• 调剂范围是否符合本省模式
• 是否提到"组内专业"

---

🗺️ 省份规则 API

PROVINCE_RULES 字典

包含27个省份的志愿填报规则。

from spec_checker_v2 import PROVINCE_RULES

# 获取湖南规则
hunan_rule = PROVINCE_RULES["湖南"]

print(hunan_rule["mode"])              # "院校专业组"
print(hunan_rule["max_volunteers"])    # 45
print(hunan_rule["adjustment_scope"])  # "组内专业"

规则字段

字段	类型	说明	示例
mode	str	志愿模式	"院校专业组" / "专业+学校" / "传统"
max_volunteers	int	最大志愿数	45
max_majors_per_group	int	每组专业数	6
has_adjustment	bool	是否有调剂	True
adjustment_scope	str	调剂范围	"组内专业" / "全部专业" / "无"
retrieval_rule	str	检索规则	"分数优先、遵循志愿、一次投档"
collection_count	int	征集次数	2
subject_mode	str	选科模式	"3+1+2" / "3+3" / "传统"
official_url	str	官方网址	"http://jyt.hunan.gov.cn/"
exam_subject_total	int	总分	750

---

🔍 省份检测 API

detect_province(text)

从文本中自动检测省份。

from spec_checker_v2 import detect_province

province = detect_province("我是湖南考生...")
print(province)  # "湖南"

province = detect_province("浙江省，620分")
print(province)  # "浙江"

支持检测形式:

• 全称："湖南"、"浙江省"
• 简称："湘"、"浙"

---

🔤 错误模式 API

错误分类

🔴 致命错误

{
    "rule": "错误名称（省份）",
    "description": "问题描述",
    "fix": "修正建议"
}

检测函数: _check_volunteer_unit()

🟡 严重错误

{
    "rule": "错误名称",
    "description": "问题描述",
    "fix": "修正建议"
}

检测函数: _check_data_accuracy()

🟢 一般警告

{
    "rule": "警告名称",
    "description": "建议描述",
    "fix": "补充建议"
}

检测函数: _check_risk_disclosure()

---

📝 报告生成 API

检查报告格式

检查器返回的Markdown格式报告：

╔══════════════════════════════════════════════════════════════════╗
║ ✅ 志愿方案规范检查报告 ║
╠══════════════════════════════════════════════════════════════════╣
║ 检测省份：湖南 ║
║ 志愿模式：院校专业组 ║
║ ...
╚══════════════════════════════════════════════════════════════════╝

🔴 【致命错误】
└──────────────────────────────────────────────────────────────────────

1. 错误名称
   ❌ 问题：...
   ✅ 修正：...

🟡 【严重错误】
└──────────────────────────────────────────────────────────────────────

1. 错误名称
   ⚠️ 问题：...
   🔧 修正：...

🟢 【一般警告】
└──────────────────────────────────────────────────────────────────────

1. 警告名称
   💡 建议：...
   📌 做法：...

---

🧪 测试 API

test_hunan_bad_plan()

测试湖南错误版方案检测能力。

预期: 检测出1个致命错误（"45个学校"）

test_hunan_good_plan()

测试湖南修正版方案合规性。

预期: 通过基础检查

test_zhejiang_wrong_mode()

测试浙江模式错误检测。

预期: 检测出E005模式错误

---

🔧 扩展开发

添加新省份

# 在 PROVINCE_RULES 中添加
PROVINCE_RULES["新省份"] = {
    "mode": "院校专业组",  # 或 "专业+学校" / "传统"
    "batch": "本科批",     # 或 "本科一批" / "普通批"
    "max_volunteers": 45,
    "max_majors_per_group": 6,
    "has_adjustment": True,
    "adjustment_scope": "组内专业",
    "retrieval_rule": "分数优先、遵循志愿、一次投档",
    "collection_count": 2,
    "subject_mode": "3+1+2",  # 或 "3+3" / "传统"
    "official_url": "http://...",  # 官方网址
    "exam_subject_total": 750,
}

添加新错误检测

# 在 GaokaoSpecCheckerV2 类中添加方法

def _check_new_error(self, text):
    """检查新错误类型"""
    error_pattern = r'错误正则'
    if re.search(error_pattern, text):
        self.errors["fatal"].append({
            "rule": "新错误名称",
            "description": "问题描述",
            "fix": "修正建议"
        })

---

📦 导入路径

从项目根目录

import sys
sys.path.insert(0, '/home/long/project/gaokao-volunteer-system/skills/gaokao-spec-checker/scripts')

from spec_checker_v2 import GaokaoSpecCheckerV2, PROVINCE_RULES, detect_province

从Skill目录

# 相对路径（在Skill内使用）
from scripts.spec_checker_v2 import GaokaoSpecCheckerV2

---

🎨 输出格式

返回类型

所有API返回标准的Python数据类型：

• str: Markdown格式的检查报告
• dict: 省份规则配置
• list: 错误列表
• bool: 检测结果

---

📞 更多信息

• 完整实现: skills/gaokao-spec-checker/scripts/spec_checker_v2.py
• 规则文档: rules/provinces.md
• 错误模式: rules/errors/ERRORS.md

---

版本: v2.0
最后更新: 2026-06-11