From 25cccd4372f963adca4451661f574eb2d84c47a4 Mon Sep 17 00:00:00 2001 From: Codex Date: Sun, 11 Oct 2026 13:34:56 +0800 Subject: [PATCH] docs: define unified local postgraduate workbench --- .gitignore | 10 ++++++ docs/design.md | 45 ++++++++++++++++++++++++ docs/implementation-plan.md | 69 +++++++++++++++++++++++++++++++++++++ docs/progress.md | 12 +++++++ frontend/package.json | 10 ++++++ frontend/tsconfig.json | 2 ++ frontend/vite.config.ts | 4 +++ pyproject.toml | 29 ++++++++++++++++ tests/test_data.py | 66 +++++++++++++++++++++++++++++++++++ 9 files changed, 247 insertions(+) create mode 100644 .gitignore create mode 100644 docs/design.md create mode 100644 docs/implementation-plan.md create mode 100644 docs/progress.md create mode 100644 frontend/package.json create mode 100644 frontend/tsconfig.json create mode 100644 frontend/vite.config.ts create mode 100644 pyproject.toml create mode 100644 tests/test_data.py diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..04fbfb5 --- /dev/null +++ b/.gitignore @@ -0,0 +1,10 @@ +.venv/ +.runtime/ +__pycache__/ +*.pyc +.pytest_cache/ +frontend/node_modules/ +frontend/dist/ +frontend/*.tsbuildinfo +.superpowers/ + diff --git a/docs/design.md b/docs/design.md new file mode 100644 index 0000000..cd6500a --- /dev/null +++ b/docs/design.md @@ -0,0 +1,45 @@ +# 考研数据工作台设计 + +日期:2026-10-11 + +## 用户目标与已确定的约束 + +用户要求创建独立项目,综合本地 `F:\@Other\yam` 与 `F:\@Other\yzw` 的功能,带图形界面,并连接 `C:\Users\Jayson\Desktop\proxy_pool`。用户选择本地网页界面。目标是同一工作台完成全国招生目录采集、分数线补充、筛选、收藏、对比、历史查看、导入导出和代理池管理。 + +独立目录:`F:\@Other\kaoyan-studio`。原项目存在用户修改,均作为只读参考。代理池现有 manage.ps1 / HTTP API 可直接使用,不修改服务配置。 + +## 方案选择 + +采用 Python FastAPI 后端、SQLite、本地 React + TypeScript 网页。比沿用 Tauri 更适合用户选择的浏览器界面;比启动两个原程序更容易统一年份、数据来源与代理路由。新实现参考两项目的接口与解析规则,保留来源和授权说明,运行不依赖原项目目录。 + +## 数据与采集 + +- 研招目录按省份→院校→专业→研究方向分页采集,每种四门考试组合单独保存。包含学位、学习方式、导师、考试方式和专项计划。 +- 历年分数线与招生计划接入掌上考研接口。分数线区分专业、一级学科、门类,保存原文、来源、时间、年份和匹配粒度;不将参考线变成专业线。 +- 专业清单预置本地 YAM 的目录快照。院校种子仅用于索引和选校,不生成招生计划或分数线。 +- 目录年份显式选择;发现来源页面年份与选择不一致时阻止写入。无法验证年份时记录验证状态并在界面提示。 +- 招生人数保留原文;只有明确专业口径或明确数字字段能结构化为数值。未知、方向级、学院级人数不能被重复累加成学校总计划。 +- SQLite 唯一键包括年份、学校、专业、院系、方向、学习方式、考试组合、专项计划。历史数据与来源不同的计划保持独立。 +- 任务运行在后台线程。支持暂停、恢复、取消;按完成的学校/专业保存断点和已完成工作单元,重启后可恢复。限流退避;失败记为可重试状态,不宣称完整成功。 + +## 代理与登录 + +- 所有研招登录、目录与掌上考研请求共用代理路由。支持直连、代理优先、仅代理,以及备用代理。 +- 使用代理池 /get/?type=https、/all/?type=https、/count/ 接口。网络失败隔离当前代理并换用其他;手动切换不删除健康代理。 +- 无代理时,代理优先模式明确显示直连,严格模式停止请求。429/业务限流采用退避,不把限流当成代理损坏。 +- 提供代理池状态、列表、启动服务、停止受管理服务和切换代理。服务管理复用原 manage.ps1,通过参数数组启动隐藏后台进程。 +- 支持 Cookie 输入、账号密码登录和打开受控浏览器由用户手动登录。登录必须验证业务接口,不能仅凭 HTTP 200。 +- Cookie 保存在项目运行目录并在 Windows 用 DPAPI 加密;密码只用于本次登录,配置和日志不保存。服务仅监听 127.0.0.1,拒绝来自其他网页的跨源写请求。 + +## 界面 + +侧栏:概览、院校工作区、采集任务、代理池、设置与登录。工作区提供关键词、省份、专业代码、院校层级、学位、学习方式、科目、年份和收藏筛选,分页表格,详情抽屉、年度趋势、2–6 项比较与导出。未知值显示“未公开”,来源标签与分数线口径始终可见。 + +## 导入与导出 + +支持 yzw CSV / Excel、YAM JSON 快照与 SQLite(只读)导入,年份不可凭当前日期猜测。CSV / Excel / JSON 导出使用当前筛选条件;导出不包含凭据。CSV 与 Excel 防止公式注入。 + +## 验证与交付 + +测试覆盖分页、多个考试组合、人数口径、跨年去重、分数线粒度、代理严格模式和实际路由、登录验证、任务恢复、上传导出与敏感字段。前端进行类型检查、生产构建及本机 Edge 浏览器操作验证。交付启动/停止脚本、完整源码与中文使用说明,启动后直接访问本地地址。真实研招登录及大规模抓取由用户在界面发起。 + diff --git a/docs/implementation-plan.md b/docs/implementation-plan.md new file mode 100644 index 0000000..8f5ff46 --- /dev/null +++ b/docs/implementation-plan.md @@ -0,0 +1,69 @@ +# 考研数据工作台 Implementation Plan + +**Goal:** 用本地网页将全国研招目录、历年考情与现有代理池连接成独立可运行软件。 +**Architecture:** Python FastAPI + SQLite + React/TypeScript。采集器共用代理、凭据与后台任务服务,数据层统一年份与来源,原仓库只读。 +**Spec:** docs/design.md +**Execution:** 当前会话直接实现,各组件按测试先行验证,完成后安排独立代码审查。 + +## Global Constraints + +- 项目位于 F:\@Other\kaoyan-studio;不修改两个原项目与代理池源码。 +- 本地网页;默认监听 127.0.0.1:8765。Python >=3.12,Node >=22。 +- 本机数据存 .runtime;凭据不可写入 Git、日志或导出。 +- 代理策略显式;人数和分数线未知值不得造数;招生年份不得凭抓取年份猜测。 + +## Review Focus + +1. 同一专业多个科目组合或方向,跨年导入不覆盖历史。 +2. 代理池为空、失效与 429 限流走不同分支,严格模式无直连。 +3. 专业、学科、门类线以及不同学院不能在表格/图表中混为同一指标。 +4. 暂停、重启、失败恢复不会漏掉尚未完成的工作单元。 +5. CSV 缺年、乱码、公式内容、空字段与上传大文件须有可理解结果。 + +## Task 1: 数据解析与存储 + +Files: studio/domain.py, studio/database.py, tests/test_data.py +Interfaces: normalize_catalog(item,year,school,major)->list[dict]; Database.upsert_catalog(records); query_catalog(filters); upsert_scores(records); history(record_id). +- [ ] 写并运行多科目组合、明确人数、跨年保留、收藏与分数线粒度测试,确认实现缺失导致失败。 +- [ ] 实现数据模型与 SQLite,运行 tests/test_data.py,再运行整个 suite。 +- [ ] 保存进度并提交。 + +## Task 2: 网络、代理与凭据 + +Files: studio/settings.py, studio/network.py, studio/auth.py, tests/test_network.py +Interfaces: SettingsStore.read/update; ProxyRouter.resolve/rotate/status; Transport.request; AuthService.cookie/login/browser/check. +- [ ] 写并运行代理路由、严格模式、切换、限流、凭据不泄露测试。 +- [ ] 实现上述接口并通过全部测试。 +- [ ] 保存进度并提交。 + +## Task 3: 数据源与可恢复任务 + +Files: studio/connectors.py, studio/jobs.py, tests/test_collectors.py +Interfaces: CatalogClient.pages; ScoreClient.score_lines/plans; JobManager.start/pause/resume/cancel/list. +- [ ] 写并运行真实响应结构下的分页、登录业务失败、学校精确匹配、分数线优先级、任务恢复测试。 +- [ ] 实现研招与掌上考研采集器、后台任务、断点与日志,运行 suite。 +- [ ] 保存进度并提交。 + +## Task 4: API 与文件互通 + +Files: studio/imports.py, studio/api.py, studio/__main__.py, tests/test_api.py +Interfaces: create_app(data_dir)->FastAPI; /api/catalog,/api/jobs,/api/proxy,/api/auth,/api/settings,/api/import,/api/export. +- [ ] 写并运行上传、过滤、跨源请求、机密字段、数据导出与公式处理测试。 +- [ ] 实现 API、CSV/Excel/JSON/YAM SQLite 导入导出,运行 suite。 +- [ ] 保存进度并提交。 + +## Task 5: 网页工作台 + +Files: frontend/src/*, frontend/index.html +- [ ] 实现导航、数据查询、详情/趋势、收藏/对比、任务控制、登录、代理管理、设置、上传导出。 +- [ ] 前端逻辑测试与类型检查;构建必须退出 0。 +- [ ] 用本地 Edge 与测试数据库验证导入→筛选→收藏→对比→导出,以及任务和代理页面。 +- [ ] 保存进度并提交。 + +## Task 6: 本地启动与交付 + +Files: start.ps1, stop.ps1, 启动工作台.cmd, README.md, THIRD_PARTY_NOTICES.md +- [ ] 验证独立虚拟环境、启动重复调用、进程身份校验与 HTTP 健康检查。 +- [ ] 独立审查;修复影响功能的问题并运行必要回归。 +- [ ] 完整 suite、生产构建、实际启动与本地服务检查;交付源码压缩包和使用说明。 + diff --git a/docs/progress.md b/docs/progress.md new file mode 100644 index 0000000..118f65a --- /dev/null +++ b/docs/progress.md @@ -0,0 +1,12 @@ +# 开发进度 — docs/implementation-plan.md + +用户已明确要求创建项目,并选择本地网页;依照会话授权直接推进开发。 +原目录检查:YAM 无本地修改;yzw 有本地修改;代理池运行中。新独立仓库隔离开发,不修改以上目录。 +Pre-flight:数据库/任务/网络/API 的数据接口按设计共享。图形界面通过 HTTP 使用这些接口,不依赖原项目环境。 +Task 1: pending +Task 2: pending +Task 3: pending +Task 4: pending +Task 5: pending +Task 6: pending + diff --git a/frontend/package.json b/frontend/package.json new file mode 100644 index 0000000..1282784 --- /dev/null +++ b/frontend/package.json @@ -0,0 +1,10 @@ +{ + "name": "kaoyan-studio-ui", + "version": "1.0.0", + "private": true, + "type": "module", + "scripts": {"dev": "vite --host 127.0.0.1", "build": "tsc --noEmit && vite build", "test": "vitest run"}, + "dependencies": {"react": "^19.3.0", "react-dom": "^19.3.0", "lucide-react": "^0.577.0"}, + "devDependencies": {"@types/react": "^19", "@types/react-dom": "^19", "@vitejs/plugin-react": "^6", "typescript": "^6", "vite": "^8.3.4", "vitest": "^4"} +} + diff --git a/frontend/tsconfig.json b/frontend/tsconfig.json new file mode 100644 index 0000000..45800b3 --- /dev/null +++ b/frontend/tsconfig.json @@ -0,0 +1,2 @@ +{"compilerOptions":{"target":"ES2022","lib":["ES2022","DOM","DOM.Iterable"],"module":"ESNext","moduleResolution":"bundler","jsx":"react-jsx","strict":true,"skipLibCheck":true,"noEmit":true,"allowImportingTsExtensions":true},"include":["src","vite.config.ts"]} + diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts new file mode 100644 index 0000000..604d67a --- /dev/null +++ b/frontend/vite.config.ts @@ -0,0 +1,4 @@ +import { defineConfig } from 'vite'; +import react from '@vitejs/plugin-react'; +export default defineConfig({plugins:[react()],server:{proxy:{'/api':'http://127.0.0.1:8765'}},build:{sourcemap:false}}); + diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..20183f4 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,29 @@ +[project] +name = "kaoyan-studio" +version = "1.0.0" +description = "本地考研招生目录、历年分数线与代理池工作台" +requires-python = ">=3.12" +dependencies = [ + "fastapi>=0.115,<1", + "uvicorn>=0.34,<1", + "requests>=2.32,<3", + "beautifulsoup4>=4.13,<5", + "openpyxl>=3.1,<4", + "python-multipart>=0.0.20,<1", + "playwright>=1.50,<2", +] + +[project.optional-dependencies] +dev = ["pytest>=8,<10", "httpx>=0.28,<1"] + +[build-system] +requires = ["setuptools>=75"] +build-backend = "setuptools.build_meta" + +[tool.setuptools.packages.find] +include = ["studio*"] + +[tool.pytest.ini_options] +testpaths = ["tests"] +pythonpath = ["."] + diff --git a/tests/test_data.py b/tests/test_data.py new file mode 100644 index 0000000..08be994 --- /dev/null +++ b/tests/test_data.py @@ -0,0 +1,66 @@ +from pathlib import Path + +from studio.domain import normalize_catalog, parse_quota, select_score_lines +from studio.database import Database + + +def raw_catalog(): + return { + "dwdm": "10001", "dwmc": "北京大学", "szss": "北京", + "zydm": "081200", "zymc": "计算机科学与技术", "xwlxmc": "学术学位", + "yxsdm": "001", "yxsmc": "计算机学院", "yjfxdm": "01", "yjfxmc": "人工智能", + "xxfs": "1", "ksfsmc": "全国统考", "nzsrsstr": "专业:6(不含推免)", + "kskmz": [ + {"km1Vo": {"kskmmc": "101思想政治理论"}, "km2Vo": {"kskmmc": "201英语(一)"}, "km3Vo": {"kskmmc": "301数学(一)"}, "km4Vo": {"kskmmc": "408计算机学科专业基础"}}, + {"km1Vo": {"kskmmc": "101思想政治理论"}, "km2Vo": {"kskmmc": "203日语"}, "km3Vo": {"kskmmc": "301数学(一)"}, "km4Vo": {"kskmmc": "408计算机学科专业基础"}}, + ], + } + + +def test_distinct_exam_combinations_are_preserved(): + records = normalize_catalog(raw_catalog(), 2027) + assert len(records) == 2 + assert records[0]["subjects"][1] == "201英语(一)" + assert records[1]["subjects"][1] == "203日语" + assert records[0]["record_key"] != records[1]["record_key"] + + +def test_ambiguous_quota_is_not_converted_to_major_total(): + assert parse_quota("专业:6(不含推免)") == (6, "major") + assert parse_quota("学院:100(含推免80)") == (None, "college") + assert parse_quota("研究方向:6") == (None, "direction") + assert parse_quota("拟招人数待定") == (None, "unknown") + assert parse_quota("专业:0(不含推免)") == (0, "major") + + +def test_history_is_preserved_across_years_and_reruns(tmp_path: Path): + db = Database(tmp_path / "studio.db") + db.upsert_catalog(normalize_catalog(raw_catalog(), 2026)) + db.upsert_catalog(normalize_catalog(raw_catalog(), 2027)) + db.upsert_catalog(normalize_catalog(raw_catalog(), 2027)) + assert db.query_catalog({})["total"] == 4 + result = db.query_catalog({"year": 2027, "subject": "203"}) + assert result["total"] == 1 + rid = result["items"][0]["id"] + db.favorite(rid, True) + assert db.query_catalog({"favorites": True})["total"] == 1 + + +def test_score_line_match_does_not_promote_category_to_major(): + rows = [{"code": "08", "total": "300"}, {"code": "0812", "total": "310"}, {"code": "081200", "total": "320"}] + scores = select_score_lines(rows, "081200", "10001", "北京大学", 2026) + assert len(scores) == 1 + assert scores[0]["total"] == 320 + assert scores[0]["scope"] == "major" + fallback = select_score_lines(rows[:1], "081200", "10001", "北京大学", 2025)[0] + assert fallback["scope"] == "category" + assert fallback["raw_code"] == "08" + + +def test_same_year_different_college_lines_are_not_attached_arbitrarily(tmp_path: Path): + db = Database(tmp_path / "studio.db") + db.upsert_catalog(normalize_catalog(raw_catalog(), 2026)) + rows = [{"code": "081200", "total": "350", "depart_id": "999", "depart_name": "其他学院"}] + db.upsert_scores(select_score_lines(rows, "081200", "10001", "北京大学", 2026)) + assert db.query_catalog({"year": 2026})["items"][0]["score_total"] is None +