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