8.3 KiB
备考通｜开发计划
版本：v1.0 · 2026-08-27
说明：这是最终版本的实施顺序，不代表功能分期；所有工作完成后才视为项目交付。
1. 执行方式
采用“基础设施先行、纵向功能闭环、最后统一验收”的顺序。每项工作必须同时具备代码、可运行结果和验证记录，避免只完成页面而没有接口或持久化。
执行约束：
- 后端接口 Schema 先于前端 API 生成。
- 数据模型先于业务 Service，业务 Service 先于页面联调。
- 每完成一个业务闭环，立即验证刷新后的 JSON 持久化结果。
- PC 与 Mobile 从第一张页面开始同步适配，不集中到末尾处理。
- 生成代码不手工修改，接口变更必须重新生成并检查差异。
2. 任务顺序
任务 01｜项目初始化与目录整理
工作：创建前后端目录、TypeScript 配置、包管理脚本、环境变量模板、基础 Git 忽略规则；按照需求文档拆分前端 api、stores、layouts、views、components、composables、styles、types 和 utils 目录；将已有散落代码移动到明确归属的位置，建立统一入口。
产出：前后端分别可以启动；前端目录结构与需求文档一致；开发、构建、类型检查命令可执行。
完成标准：新环境按 README 操作可以启动前后端；页面、样式、请求和状态没有继续堆在 App.vue 或单一目录；新增页面和功能都有明确放置位置；启动失败时有明确错误。
任务 02｜JSON Store 与演示数据
工作：实现 readData、writeData、updateData，建立数据文件路径常量和缺失文件初始化；录入演示题、用户档案、计划、模考和要闻数据。
产出：data/ 可独立运行；写入使用临时文件后原子替换。需要兼容开发/生产两套环境。
完成标准：服务重启后数据仍然存在；任一 JSON 文件缺失不会导致服务崩溃；非法 JSON 有可定位错误。
任务 03｜后端路由 Schema 与 OpenAPI
工作：注册 Fastify、统一错误处理、请求日志、Zod 校验；为每个业务接口补齐请求和响应 Schema；导出静态 OpenAPI 文档。
产出：/api/openapi.json、Swagger UI、错误响应格式、OpenAPI 导出脚本。
完成标准：所有已登记接口都出现在文档中；请求参数错误能返回统一错误；openapi:export 可重复执行。
任务 04｜前端 API 自动生成与基础视觉壳层
工作：接入 OpenAPI 代码生成；完善请求客户端、路由、Pinia 基础 store；落地设计 Token、全局布局、PC 侧栏和 Mobile TabBar。
产出：client/src/api/generated/；页面可在桌面和移动断点切换；统一加载、空数据、错误提示组件。
完成标准：前端业务代码不直接写 URL 和 fetch；修改后端 Schema 能重新生成类型；首页路由能通过真实接口加载。
任务 05｜数据中枢纵向闭环
工作：实现概览、趋势、掌握度、今日任务和薄弱考点接口及页面；接入统计计算。
产出：PC 数据看板和 Mobile 首页均使用同一份后端数据。
完成标准：存在演示数据时指标、图表和任务可见；清空数据时显示合理空状态；刷新后结果一致。
任务 06｜计划、个人中心、设置与要闻
工作：实现计划任务创建/切换、个人档案、设置修改、要闻列表/详情；接入 Markdown 渲染和 JSON 要闻数据。
产出：计划、个人、设置和要闻页面的接口、页面和持久化。
完成标准：任务状态变更能影响首页统计；设置刷新后保留；要闻详情支持 Markdown；RSS/API/URL 入口返回明确占位反馈。
任务 07｜题库管理与导入导出
工作：实现题目列表筛选、JSON 导入、内容指纹去重、后台 UUID 生成、导出和删除确认。
产出：题库管理页面、导入结果报告、导出文件。
完成标准：导入文件不含 ID 也能成功；重复题目被跳过；错误题目不影响有效题目导入；导出的数据可再次导入。
任务 08｜刷题与结果闭环
工作：实现模块选题、5/10/15 分钟组卷、自定义组卷、会话、计时、作答、提交、结果和标准解析。
产出：可从首页或刷题中心开始一套题并完成提交；记录写入 JSON。
完成标准：答案、正确率、耗时和完成状态准确；中途刷新按设计处理；提交后不能重复计入同一题。
任务 09｜错题复习闭环
工作：答错自动沉淀错题；实现待复习筛选、复习提交、+1/+3/+7 天安排、连续答对后标记掌握、再次答错回到当天。
产出：错题本、错题详情、复习操作和数据中枢联动。
完成标准：修改系统日期或使用测试时间可验证每个复习节点；复习结果影响掌握度和待复习数量。
任务 10｜模考分析
工作：实现行测模考录入、列表、趋势、模块分数、目标分差和较上次变化；补充无数据空状态。
产出：模考分析页和成绩录入页。
完成标准：只出现行测字段；至少两条记录能生成趋势；删除或修改记录后分析同步更新。
任务 11｜AI 讲解与申论占位
工作：实现 OpenAI 兼容客户端、Token 配置读取、结构化讲解、超时处理和题库解析回退；完成申论占位页面。
产出：AI 讲解接口、前端结果展示、未配置和失败提示。
完成标准：配置有效 Token 能完成一次讲解；未配置或超时不会阻塞刷题结果；Token 不出现在前端和日志中。
任务 12｜联调与异常收口
工作：逐接口联调；补齐空数据、非法导入、重复提交、文件写入失败、AI 失败和网络断开处理；统一按钮禁用和提示文案。
产出：接口检查清单、边界场景记录、修复提交。
完成标准：主要用户流程无未处理异常；所有错误都能被用户理解；服务端日志能定位问题但不泄露敏感配置。
任务 13｜原型视觉验收与响应式修正
工作：对照原型逐页校准尺寸、间距、字号、颜色、图标、卡片层级和交互状态；检查 390px 手机宽度、平板宽度和桌面宽度。
产出：视觉差异修复、页面截图检查记录。
完成标准：导航、主要卡片、按钮和核心数据层级与原型一致；无横向溢出；触控目标可操作。
任务 14｜交付整理
工作：整理 README、环境变量示例、启动命令、题库格式说明、AI 配置说明和数据目录说明；执行生产构建。
产出：可交付代码、运行文档、最终 OpenAPI 文件和验收清单。
完成标准：清空依赖缓存后可重新安装并构建；生产构建成功；文档中的命令与实际脚本一致。
3. 关键依赖关系
初始化
↓
JSON Store ───────┐
↓ │
数据模型/Schema │
↓ │
OpenAPI ─→ 前端 API 生成
↓ ↓
业务 Service ─→ 页面联调
↓
统计、错题、AI
↓
双端验收与交付
以下事项不得提前绕过依赖：
- 页面不得在接口未定时自行定义重复类型。
- 统计页面不得使用仅存在于前端的模拟计算。
- 错题复习必须基于真实作答记录，不能单独维护一套展示数字。
- AI 页面必须复用刷题结果中的题目和用户答案。
4. 每项任务的完成检查
完成一项任务前，按以下顺序检查：
- 启动前端并使用浏览器打开对应页面，在与原型图一致的视口尺寸下截图；将实现截图与对应原型逐项对比，记录布局、尺寸、间距、颜色、字体、图标和内容差异，修正明显偏差后再继续。
- 使用浏览器实际操作一遍本任务涉及的核心流程，确认页面反馈、路由跳转和数据变化符合预期。
- 正常流程是否可运行。
- 空数据是否可展示。
- 非法输入是否有反馈。
- 写入后重启服务是否仍然正确。
- PC 与 Mobile 是否都可操作。
- OpenAPI、生成 API 和实际实现是否一致。
- 是否引入了需求之外的抽象或依赖。
全部任务完成后，再执行一次从“首次启动 → 开始刷题 → 提交 → 错题复习 → 录入模考 → 查看数据中枢”的完整验收流程。