docs: define unified local postgraduate workbench

This commit is contained in:
Codex
2026-10-11 13:34:56 +08:00
commit 25cccd4372
9 changed files with 247 additions and 0 deletions
+45
View File
@@ -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 浏览器操作验证。交付启动/停止脚本、完整源码与中文使用说明,启动后直接访问本地地址。真实研招登录及大规模抓取由用户在界面发起。
+69
View File
@@ -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、生产构建、实际启动与本地服务检查;交付源码压缩包和使用说明。
+12
View File
@@ -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