# 备考通｜开发需求说明

版本：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 的接口。

推荐配置：

```text
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、领域层或消息系统：

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

```text
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 天作答记录计算：

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

### 4.4 计划与打卡

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

### 4.5 模考

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

### 4.6 要闻

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

### 4.7 AI 讲解

后端从环境变量读取：

```text
AI_BASE_URL=
AI_API_KEY=
AI_MODEL=
```

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

## 5. 数据文件与字段

```text
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`：

```json
{
  "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`，成功响应返回业务数据，失败响应格式为：

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

核心接口：

```text
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 参数：

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

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

## 9. 验收标准

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