Files
kaoyan/docs/implementation-plan.md
T

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