liyy/gwy-exam

Fork 0

liyy 86c906727b docs: 增加需求文档和开发计划

2026-08-27 17:58:10 +08:00

14 KiB

Raw Permalink Blame History

备考通｜开发需求说明

版本：v1.0 · 2026-08-27
定位：个人本地部署的公务员考试备考工具
依据：deliverables/prototype/ 原型图与 deliverables/design/ 设计规范

1. 项目边界

备考通服务单一用户，围绕行测备考形成“计划—刷题—错题复习—模考分析”的闭环，并提供时政要闻和申论入口。

本版本包含：

PC 与 Mobile 响应式界面。
行测内置演示题库、题目 JSON 导入与导出。
行测按模块刷题、计时、提交、结果和解析。
错题沉淀、间隔复习和错题详情。
学习计划、每日任务、周报复盘。
行测模考成绩录入、趋势与模块分析。
要闻列表、详情及 JSON/RSS/API/URL 导入入口。
AI 行测题目讲解，后端通过 OpenAI 兼容接口调用。
申论占位页，不实现写作编辑、批改和评分。

明确不包含：登录注册、权限系统、多用户、云同步、数据库、备份恢复、深色模式、行测以外的模考、完整申论系统。

2. 技术方案

2.1 技术栈

前端：Vue 3、Vite、TypeScript、Vue Router、Pinia、ECharts、Lucide Vue。
后端：Node.js、TypeScript、Fastify（Express 可替代，但项目内只选一种）。
存储：后端本地 data/*.json 文件。
校验：Zod。
AI：OpenAI 兼容的 Chat Completions 接口，Token 只在后端配置。

2.2 OpenAPI 约定

后端接口必须提供 OpenAPI 3.0 文档，作为前后端接口契约的唯一来源。接口仍采用语义化路径，不因引入 OpenAPI 改为传统 REST 资源风格。

Fastify 使用 @fastify/swagger 根据路由 schema 生成 OpenAPI 文档。
开发环境提供 /api/openapi.json，便于查看和调试。
前端使用 openapi-typescript 生成接口类型，使用 openapi-fetch 封装请求客户端。
生成文件放在 client/src/api/generated/，不手工修改，加入 .gitignore。
前端通过 pnpm api:generate（或项目选定的包管理器命令）从后端 OpenAPI 文档重新生成 API 文件。
dev 与 build 前执行生成检查；若 OpenAPI 文档无法获取或生成失败，命令应直接失败。
后端每个接口必须声明请求参数、请求体、成功响应和错误响应 schema；禁止出现只有实现没有 schema 的接口。

推荐配置：

server: @fastify/swagger + @fastify/swagger-ui
client: openapi-typescript + openapi-fetch
document: /api/openapi.json
generated: client/src/api/generated/

前端业务代码只调用生成后的 API 方法或类型，不直接在页面中写 fetch、URL 字符串和重复的请求类型。生成客户端统一处理基础 URL、JSON headers、错误响应和超时；AI Token 等敏感配置不进入 OpenAPI 文档或前端代码。

2.2 后端分层

后端保持三层，不引入 Repository、ORM、领域层或消息系统：

请求 → Handler → Service → JSON Store
                         ↘ AI / 导入解析器

server/
├── src/
│   ├── server.ts
│   ├── routes.ts
│   ├── handlers/       # 参数读取、调用 service、响应格式化
│   ├── services/       # 业务规则和统计计算
│   ├── data/
│   │   ├── store.ts    # readData / writeData / updateData
│   │   └── files.ts
│   ├── importers/      # JSON、RSS、API、URL 解析入口
│   ├── ai/             # AI 客户端与响应整理
│   ├── utils/          # id、日期、内容指纹
│   └── types/
└── data/

store.ts 负责 JSON 读写。所有写操作先写临时文件，再原子替换目标文件；不提供数据备份和恢复能力。

2.3 前端目录规划

前端按页面、业务组件、状态、接口、基础组件分离，页面组件负责组合，不直接承担数据计算和请求细节。

client/
└── src/
    ├── main.ts、App.vue
    ├── router/index.ts
    ├── api/
    │   ├── client.ts              # 生成客户端的统一配置
    │   ├── index.ts               # 对业务暴露 API
    │   └── generated/             # OpenAPI 自动生成，禁止手工修改
    ├── stores/                    # app、profile、practice
    ├── layouts/                   # Desktop、Mobile、Navigation
    ├── views/                     # 按 dashboard、practice、review、plan、mock、news、questions、profile、settings、essay 划分
    ├── components/
    │   ├── base/                  # Button、Card、Badge、Modal
    │   ├── feedback/              # Loading、Error、Toast、Confirm
    │   ├── charts/
    │   └── dashboard、practice、review、plan、mock、news、questions/
    ├── composables/               # useResponsive、useRequest、useToast
    ├── styles/                    # main、tokens、reset、responsive
    ├── types/view-models.ts       # 页面组合类型，不复制接口类型
    └── utils/                     # 格式化、日期、前端校验

目录规则：views 对应路由页面；components 放跨页面复用组件；stores 只保存跨页面共享状态；api/generated 只由 OpenAPI 脚本生成；页面不复制桌面和移动两套业务逻辑，通过 Layout、CSS 断点和少量条件渲染适配。

3. 页面与导航

3.1 PC 导航

左侧固定导航：数据中枢、刷题中心、模考分析、备考计划、要闻、我的、题库管理、设置。

3.2 Mobile 导航

底部 TabBar：首页、刷题、要闻、分析、我的。二级页面通过页面内返回按钮进入。

3.3 页面清单

页面	主要内容
数据中枢	备考数据卡、模考趋势、今日任务、掌握度、薄弱考点
刷题中心	行测模块、组卷时长、自定义组卷、错因分布、待复习入口
作答页	题干、选项、进度、计时、提交
结果页	得分、正确率、错题、标准解析、AI 讲解入口
AI 讲解	结论、分步解析、考点、常见错误、答案
错题本	待复习列表、模块/错因筛选、复习状态
错题详情	题目、用户答案、正确答案、解析、复习操作
申论占位	功能说明与后续入口，不保存写作内容
备考计划	今日/本周任务、完成状态、计划操作、周报入口
周报复盘	周学习时长、刷题数、正确率、薄弱模块、建议
模考分析	行测成绩趋势、目标分差、模块得分、模考记录
成绩录入	模考名称、日期、总分、五个行测模块分数、备注
要闻	分类列表、详情、导入入口
我的	学习档案、累计数据、成就
题库管理	题目列表、筛选、JSON 导入/导出、删除
设置	目标分、考试日期、每日提醒、刷题偏好、AI 配置状态

每个数据页面必须处理加载、空数据、错误和成功反馈四种状态；空状态需要给出下一步操作。

4. 业务规则

4.1 行测模块

固定模块：言语理解、数量关系、判断推理、资料分析、常识判断。题目支持单选题；每道题包含题干、A-D 选项、答案、解析、难度、标签和来源。

4.2 刷题会话

用户选择模块和 5/10/15 分钟时长，系统按模块随机组卷并创建会话。会话保存开始时间、题目顺序、答题记录和结束状态。提交后计算答对数、正确率、用时，并将答错题写入错题数据。

4.3 错题复习

错题首次答错当天可复习；复习答对后依次安排 +1 天、+3 天、+7 天，连续四次复习答对后标记已掌握；任意阶段答错则回到当天。用户可以手动标记待复习、复习中或已掌握。

模块掌握度默认使用最近 30 天作答记录计算：

正确作答数 ÷ 有效作答总数 × 100%

4.4 计划与打卡

任务包含日期、类型、模块、目标数量或时长、状态和备注。完成一道题、一次错题复习、一个计划任务或一次模考录入，均可计为当日学习行为。连续打卡按自然日计算，缺失一天即归零。

4.5 模考

只支持行测成绩，字段为名称、日期、总分、言语理解、数量关系、判断推理、资料分析、常识判断和备注。系统展示最近成绩、目标分差、较上次变化、趋势和模块对比。

4.6 要闻

内部统一字段：标题、分类、摘要、Markdown 正文、来源、发布时间、标签、导入来源。JSON 为首要维护方式，RSS、API、URL 仅需保留入口、请求结构和未配置提示，解析器可暂为空实现。

4.7 AI 讲解

后端从环境变量读取：

AI_BASE_URL=
AI_API_KEY=
AI_MODEL=

前端只传题目 ID、用户答案和请求类型。后端组装题干、选项、标准答案、解析和用户答案后请求 AI，并整理为摘要、步骤、考点、常见错误和答案。AI 超时或未配置时回退到题库解析并返回可识别的提示。

5. 数据文件与字段

data/
├── profile.json
├── settings.json
├── questions.json
├── practice-sessions.json
├── practice-records.json
├── wrong-questions.json
├── study-plans.json
├── mock-exams.json
└── news.json

5.1 题目导入格式

导入文件不提供 id：

{
  "version": "1.0",
  "questions": [
    {
      "type": "行测",
      "module": "数量关系",
      "subModule": "行程问题",
      "difficulty": "中等",
      "stem": "题干内容",
      "options": [
        { "key": "A", "text": "选项一" },
        { "key": "B", "text": "选项二" },
        { "key": "C", "text": "选项三" },
        { "key": "D", "text": "选项四" }
      ],
      "answer": "C",
      "analysis": "标准解析",
      "tags": ["相遇问题"],
      "source": "演示题库"
    }
  ]
}

导入流程：校验字段 → 规范化文本 → 使用题型、模块、题干、选项和答案计算内容指纹 → 跳过重复项 → 生成 UUID → 写入文件。导入结果返回总数、成功数、跳过数、失败数和逐条错误。

5.2 其他实体最小字段

profile：昵称、考试日期、目标分、备考开始日期。
settings：每日目标、提醒时间、AI 配置状态、刷题偏好。
practice-session：会话 ID、题目 ID 列表、模式、开始/结束时间、状态。
practice-record：题目 ID、会话 ID、用户答案、是否正确、耗时、作答时间。
wrong-question：题目 ID、错因、状态、复习次数、下次复习时间、更新时间。
study-plan：任务 ID、日期、类型、模块、目标、状态、备注。
mock-exam：模考字段、创建时间。
news：要闻字段及导入来源。

6. 语义化接口

接口统一前缀 /api，成功响应返回业务数据，失败响应格式为：

{ "error": { "code": "VALIDATION_ERROR", "message": "说明", "details": [] } }

核心接口：

GET  /api/dashboard/overview
GET  /api/dashboard/trends

GET  /api/practice/modules
POST /api/practice/start
GET  /api/practice/:sessionId/question
POST /api/practice/:sessionId/answer
POST /api/practice/:sessionId/finish

GET  /api/review/list
POST /api/review/:id/submit
POST /api/review/:id/mark-mastered

GET  /api/plans/today
GET  /api/plans/week
POST /api/plans/tasks
PATCH /api/plans/tasks/:id/toggle

GET  /api/mock-exams/analysis
POST /api/mock-exams/record

GET  /api/news/list
GET  /api/news/:id
POST /api/news/import/json
POST /api/news/import/rss
POST /api/news/import/api
POST /api/news/import/url

GET  /api/questions/list
POST /api/questions/import
GET  /api/questions/export
DELETE /api/questions/:id

POST /api/ai/explain-question
GET  /api/profile
PATCH /api/profile
GET  /api/settings
PATCH /api/settings

7. 前端实现约束

使用 Vue Router 管理页面；Pinia 只保存用户档案、设置、当前会话和必要的缓存，不把所有接口数据做成全局状态。
请求封装统一处理加载、错误和响应解包；页面不直接调用 fetch。
以设计 Token 为唯一颜色、字号、间距和圆角来源，沿用 deliverables/design/design-tokens.css。
PC 使用侧栏和多列卡片；小于 768px 切换为移动布局和底部 TabBar；移动端内容宽度、触控区域和安全边距遵循原型。
图表只展示可解释的真实数据；无数据时使用空状态，不绘制虚假趋势。
所有破坏性操作需要二次确认；导入操作必须显示结果摘要。

8. 运行与配置

前端和后端分别提供开发启动与生产构建命令。后端通过环境变量配置端口、数据目录和 AI 参数：

PORT=3000
DATA_DIR=./data
AI_BASE_URL=
AI_API_KEY=
AI_MODEL=

本地部署要求：首次启动自动创建数据目录并写入演示数据；数据文件不存在时使用空数组或默认档案，不因单个文件缺失导致服务崩溃。

9. 验收标准

PC 和 Mobile 均能完成首页浏览、开始刷题、提交答案、查看解析、进入错题复习和查看模考分析。
刷题结果会正确更新作答记录、正确率、错题和数据中枢统计。
错题能按规则进入下一次复习，并能手动标记已掌握。
题目 JSON 导入不要求 ID；后台自动生成 ID，重复题目被跳过并可追溯原因；可导出当前题库。
模考仅出现行测字段，录入后趋势和模块分析同步更新。
AI Token 配置后可完成一次真实讲解；未配置或失败时能回退到题库解析。
要闻 JSON 列表和详情可用，其他导入入口有明确的占位反馈。
页面具备空、加载、错误和成功反馈；刷新页面后数据仍从 JSON 文件恢复。
不存在登录、权限、数据库、备份恢复和多用户相关界面或接口。

14 KiB Raw Permalink Blame History Unescape Escape