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
+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、生产构建、实际启动与本地服务检查;交付源码压缩包和使用说明。