Files
kaoyan/README.md
T

93 lines
9.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 研途 · 考研数据工作台
将 YAM 的择校工作区和历史考情能力,与 yzw 的全国目录采集、代理池和断点功能整合为独立的本地网页应用。
当前安装位置:`F:\@Other\kaoyan-studio`。原 YAM、yzw 和 proxy_pool 源码不作修改。
Debian 12 / MariaDB 服务器模式、HTTPS 访问与代理池后台运行见 [服务器部署说明](docs/debian-deployment.md)。服务器适配在 `feat/debian-server` 分支,Windows 继续默认使用 SQLite。设置页支持随机请求间隔上下限及按成功请求次数自动轮换代理。
## 启动
双击 **启动工作台.cmd**,浏览器打开 **http://127.0.0.1:8765**。窗口关闭后后台服务继续运行;双击 **停止工作台.cmd** 结束本项目服务。
本机已安装依赖并完成网页构建,可以直接启动。源码包包含已构建网页,复制到另一台 Windows 电脑后需要 Python 3.12+,首次运行会安装锁定的 Python 依赖。重新构建或修改网页需要 Node.js 22+;缺少网页构建时,脚本会安装前端依赖并构建。浏览器登录使用 Microsoft Edge。
在 PowerShell 中也可以运行:
```powershell
& 'F:\@Other\kaoyan-studio\start.ps1'
# 仅启动后台:start.ps1 -NoBrowser
# 改端口:start.ps1 -Port 8768
```
## 第一次采集
1. 在「代理 IP 池」刷新,查看池内 HTTPS 候选和当前路由。默认连接 `http://127.0.0.1:5010`;服务目录为 `C:\Users\Jayson\Desktop\proxy_pool`。
2. 在「设置与登录」选择网络策略。优先代理在池为空时允许直连;严格代理没有可用 IP 时等待处理。备用代理每行一个 `IP:端口`。代理池存在候选并不保证该 IP 对所有目标网站可用,连接失败会切换并隔离。
3. 点击「打开登录窗口」,在独立 Edge 窗口完成学信网登录和验证码。工作台会同步研招目录登录会话、验证第二页访问权限,再加密保存 Cookie。也可粘贴已登录研招网的 Cookie 请求头,或使用账号密码登录。点击「验证目录访问」会重新同步并检查权限。
4. 在「采集任务」选择内容、目录年份、地区、专业和院校关键词。建议先按一个地区、一个专业或一所院校验证,再创建全国任务。专业代码可以从内置目录选择,也可直接输入 6 位代码。
5. 查看任务日志。暂停可继续;需要登录、代理或限流解除时,处理后点击恢复;取消保留已有数据。关闭或重启服务会保留可恢复断点。
任务会保存本次采集的院校和专业列表分页,登录恢复或服务重启后复用,并一次加载已完成单元。界面显示当前核对的院校和正在请求的页数。修复前创建的任务首次恢复仍需建立列表缓存;新建任务会获取新列表。研究方向和登录验证保持实时请求,异常分页不会写入缓存。
研招网目录第一页可匿名返回,包括部分研究方向;不能用第一页判断登录成功。工作台访问研招目录的登录入口,将已有学信网 Cookie 同步到目录会话,再验证需要登录的第二页。采集开始/恢复时自动完成此检查;途中遇到登录提示,只同步一次并重试原页,失败后保留断点并提示重新登录。验证码仍需在浏览器人工完成,限流和网络失败会单独提示。登录卡片会持续更新状态;切换网络出口后需要重新验证,原 Cookie 保留。
分页使用接口返回的下一页位置和实际页大小。研招网可能将每页条数限制为 10,程序按实际位置继续,避免请求较大页时遗漏记录。目录采集先核对研招页面配置中的年份,避免将当前目录标为历史年份。
## 数据查询
「院校工作区」支持院校/专业/院系关键词、年份、省份、专业代码、学习方式、学位类型、院校层次、科目、院系、方向、人数及参考线筛选和排序。可收藏候选、勾选 2–6 条记录对比,点击院校名查看来源、分数线和计划历史。
每条记录按 **年份 + 院校 + 院系 + 专业 + 方向 + 考试方式 + 科目组合 + 来源** 保存。不同年份、方向及可选科目组合独立保留,相同记录重新采集时更新。人数保留原文:明确「专业」人数可用于筛选;学院、方向、范围或待定口径不会被转换成专业总人数。不同方向和科目组合可能重复展示同一专业人数,不能累加。
历史分数线区分专业线、学科参考线和门类参考线,匹配院系后才展示;专项计划线独立保留在详情,不作为普通计划的参考线。表格显示不晚于目录年的最近匹配线,空字段显示「未提供」。历年图表按口径、院系、备注和来源分开,不将门类线标为专业线。
985/211 是历史工程参考名单。双一流优先采用数据源标识,同时补充已知的 2022 年名单;名单来源见 `data/school_levels.json`。学校更名、新名单或未识别名称可能需要更新参考元数据。
内置 2,255 条专业目录条目和 460 所院校公开索引,来自 YAM 的公共数据文件。**索引并不代表已经采集招生详情**;首次安装的目录和分数线数据库为空。全国采集不限定于这些索引,通过研招网查询全部 31 个省级地区的招生单位。
## 原项目数据互通
在工作区点击「导入数据」:
| 格式 | 用途 | 年份规则 |
| --- | --- | --- |
| yzw CSV | 原 `export_major_csv.py` 输出的全部字段 | 原文件无年,必须填写实际招生年份 |
| YAM SQLite | Python 数据库中的 schools/departments、score_lines、admission_plans | 无年份目录须填写;历史分数/计划保留文件年份 |
| YAM JSON 种子 | `data/seeds/yan_zhao_*_all_regions.json` | 只有学校列表时仅导入索引;有方向详情时须提供年份 |
| 工作台 JSON | 完整目录和分数线快照 | 保留各条记录年份 |
| CSV / XLSX | 工作台导出,或包含相应机器字段/中文表头的数据 | 优先文件年份,否则须明确填写 |
支持 UTF-8 / UTF-8 BOM / GB18030 CSV。一次最多 100 MB、30 万条。导入只读取所选文件,不打开原软件环境或修改源文件;SQLite 使用只读模式。其他版本 YAM 表结构不同的数据库,请从原软件导出兼容文件再导入。
可将当前筛选结果导出 CSV、Excel 或完整 JSON。表格导出保留院系/方向代码和字段口径,回导不会凭空增加同一记录。JSON 同时保留相关学校专业的历史分数线;凭据不进入导出。CSV/Excel 对可能被表格软件当作公式的文本加保护前缀。
全量导出按 200 条分批读取,CSV/JSON 流式下载,Excel 使用写入模式和临时文件;同一实例一次只执行一个导出,重复请求返回 429。下载结束或中断后清理临时资源。导出期间新增的记录留待下次导出;导出不是事务一致性备份。大于 100 MB 的文件仍受导入上限限制,可按地区等条件分别导出;完整数据库备份按服务器部署说明操作。
历史采集在招生目录阶段完成后开始,按院校和年份复用全校分数线,每次最多缓存 8 份,历史计划继续逐专业获取。接口直接返回的数组按完整结果处理,带分页信息的结果按实际数量继续;不完整的响应不会被写成成功断点。数据、保存计数和完成断点在同一数据库事务中提交。
## 本地数据与开发
所有运行数据位于项目 `.runtime`:`studio.db` 保存目录、分数、收藏、任务和断点;`settings.json` 保存非机密配置;`chsi-cookie.enc` 由当前 Windows 用户的 DPAPI 加密。密码不持久化,接口不返回 Cookie。备份数据库时先停止工作台,再复制 `.runtime`;恢复加密 Cookie 需要原 Windows 用户环境,否则重新登录即可。
服务默认仅监听 `127.0.0.1`,拒绝非本机 Host 和跨来源写入。代理池设置页使用现有 `manage.ps1` 控制本机服务;工作台停止脚本只结束自己管理且进程身份匹配的服务,不停止代理池。
代理池页分别显示 API、抓取与检测、Redis 的状态。重复启动会复用已运行的服务;检查状态不改变当前代理或隔离列表。工作台优先使用已安装的 PowerShell 7.3+ 运行代理池脚本,并统一输出为 UTF-8。后台启动的输出通过文件收集,避免等待服务关闭才能返回。原代理池文件保持不变。
如果现有 API 和调度器由管理员启动,普通权限工作台仍可使用代理、查询状态和复用服务,页面会显示「管理员权限运行」及停止命令,并禁用普通权限下的停止按钮。如需改为网页直接管理:在管理员 PowerShell 中执行页面显示的停止命令,然后回到普通权限工作台点击「启动」。外部 Redis 服务会继续保留。PID 无效或进程入口不匹配时,工作台显示具体原因,禁止操作该进程。
Python 命令引号的版本兼容性参见 [PowerShell 官方参数解析说明](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.5#passing-arguments-that-contain-quote-characters)。
```powershell
# 后端行为测试
.\.venv\Scripts\python.exe -m pytest -q
# 前端逻辑测试及生产构建
cd frontend
npm.cmd test
npm.cmd run build
```
浏览器验收使用独立的测试数据库,运行方式及结果见 `docs/verification.md`。没有真人登录的自动验收不能替代账号登录后的全国采集验证。
项目结构:`studio/` 为网络、数据源、存储和 API;`frontend/src/` 为 React 网页;`data/` 为公开参考元数据;`tests/` 为后端行为测试。来源与许可证见 `THIRD_PARTY_NOTICES.md`。