640 lines
40 KiB
Markdown
640 lines
40 KiB
Markdown
# 备考中枢 · 系统架构设计
|
||
|
||
> 版本：v2.0 · 2026-08-26
|
||
> 角色：首席架构师 高见远
|
||
> 范围：仅架构设计。不含业务代码、不含设计规范、不含 PRD（均已存在）。
|
||
> 依据：用户已拍板选型（Express + Vue3 + Vite + 本地 JSON 文件 + 全 TypeScript 禁 any）作为**不可推翻基线**；本文件在此基线上做工程化落地与可行性确证。
|
||
|
||
---
|
||
|
||
## 一、设计目标与核心结论
|
||
|
||
「备考中枢」是**个人单用户、自用型**公务员备考数据中枢。移动优先（碎片双峰早 7-9 / 晚 19:30-22:30 为主战场），桌面兼顾整块时间模考与复盘导出。非 SaaS、非多租户、无社区、不办大规模模考、不做原生 App。
|
||
|
||
**产品核心闭环**：录入题库 → 分模块刷题 → 答错自动进错题本 → 打错因标签 → 考点×错因归因 →（AI 二期增强）→ 数据中枢聚合。
|
||
|
||
### 核心结论速览
|
||
|
||
| 项 | 结论 |
|
||
|---|---|
|
||
| 分层数 | 3 层（Handler 层 / Service 层 / 数据访问 + 领域类型层），依赖只向下 |
|
||
| 组织方式 | 垂直切片：一个资源 = 一个 route 文件（内含 handler）+ 一个 service 文件；请求校验、调 service、组装响应集中在 route handler |
|
||
| 实体数 | 8 个领域实体（Question / AnswerRecord / WrongQuestion / MockExam / ShenLunEssay / StudyTask / StatsSnapshot / AppSettings） |
|
||
| 关键工程化亮点 | **单一契约源（zod + zod-openapi）**：领域类型由 `z.infer` 自动生成、OpenAPI 契约由 `zod-openapi` 自动反推、请求校验用同一 zod schema，三者同步；本地 JSON 数据层采用「zod 运行时校验 + 临时文件原子 rename + 写队列串行」三重防护，保证数据资产永不损坏；全链路 0 any |
|
||
| 最大风险 | 统计聚合的 O(n) 全量扫描与 JSON 文件体积随作答记录增长 |
|
||
| 结论 | Express + 本地 JSON 对「个人单用户」场景**完全可行**，仅统计聚合与大文件写入需要防护策略（详见 §九 风险），不需更换存储或架构 |
|
||
|
||
---
|
||
|
||
## 二、版本锚定（技术选型确证）
|
||
|
||
> 依据 npm registry / 官方发布信息（2026-08-26 联网核实）。以下为**当前最新稳定线**；若实际安装版本不同，以锁定后 `package.json` 为准，**禁止按通用印象写 API**。
|
||
|
||
| 技术 | 版本锚定 | 说明 |
|
||
|---|---|---|
|
||
| Node.js | **24.x（LTS / Krypton）** | 生产应使用 Active/Maintenance LTS。Node 26 为 Current（未进入 Active LTS），不用于生产。Express 5 要求 Node ≥ 18，24 LTS 满足且有余量。 |
|
||
| Express | **5.2.x** | Express 5 已是 npm `latest` 默认线（3/2025 切换），v4 已进入 Maintenance（EOL 不早于 2026-10-01）。要求 Node ≥ 18。 |
|
||
| Vue | **3.5.x** | 官方 create-vue 脚手架默认 3.5.x（Vapor Mode 为 3.6 RC，不启用）。 |
|
||
| Vite | **6.x** | Vue 3.5 脚手架默认构建工具；Node ≥ 18。若安装为 Vite 7 亦可，不强制。 |
|
||
| TypeScript | **5.8.x** | 配合 strict 模式 + `any` 全禁。 |
|
||
| zod | **4.x（当前稳定线）** | 运行时校验 + 类型收窄，是「从 JSON 文件读数据 + 无 any」的硬依赖。`z.infer` 产出具名类型。 |
|
||
| @asteasolutions/zod-to-openapi | **8.x（配合 zod 4）** | 单一契约源的核心：从 zod schema 自动反推 OpenAPI 3.0/3.1 契约，无需手写 `openapi.yaml`。若项目锁定 zod 3.x，其匹配线为 `v7.3.4`（本项目不采用）。 |
|
||
| @types/express | 匹配 Express 5.x | 装 5.x 对应类型定义。 |
|
||
| pnpm | 10+ | monorepo workspace 包管理器。 |
|
||
| 包格式 | ESM | 统一 ES Module（Express 5 原生支持 import）。 |
|
||
|
||
**zod-openapi 用法要点**（mainstream，已联网确认）：
|
||
|
||
- 入口（`app.ts`）调用一次 `extendZodWithOpenApi(z)`，使所有 zod 类型获得 `.openapi()` 元数据扩展。
|
||
- 用 `OpenAPIRegistry.register(name, schema)` 把 zod schema 注册为 `components/schemas` 的具名组件；用 `registerPath({ method, path, request, responses })` 注册端点。
|
||
- `OpenApiGeneratorV3` 或 `V31` 的 `generateDocument()` 一次性产出完整 OpenAPI 文档；`generateComponents()` 只产出 `components` 段。
|
||
- 同一份 zod schema 同时驱动三处：**请求运行时校验**（`schema.parse(raw)`）、**TS 类型**（`z.infer`）、**OpenAPI 契约**（`generateDocument`），三者永不失同步。
|
||
- 前端据此契约：用 `orval` / `@hey-api/openapi-ts` 生成 TS 请求/响应类型与 fetch 封装（见 `packages/web/src/types/`），或直接复用 `packages/shared` 的 `z.infer` 类型。
|
||
- **规避 zod 4 的查询参数坑**：query 参数一律是字符串，需用 `z.coerce.number()` / `z.coerce.boolean()` 做显式强转，否则 `?page=2` 会因类型不符而校验失败。
|
||
- **规避校验结果丢失**：校验后必须把 `parsed` 结果写回 `req.body`（或注入 handler 局部变量），不要继续读原始 `req.body`，否则 defaults/coercions 不生效。
|
||
- **规避契约漂移**：在 dev 中间件中对出站响应做一次 schema 校验，把「返回值与契约不一致」在开发期就暴露。
|
||
|
||
> **版本锚定回写**：执行 Phase 2 安装后，须把 `package.json` / `pnpm-lock.yaml` 中的精确版本回写本文件「版本锚定」表，使规格与实现同步（见 `spec-as-contract`：版本锚定必须按实际安装写）。
|
||
|
||
---
|
||
|
||
## 三、Express + 本地 JSON 数据层：取舍正反评估
|
||
|
||
> 这是架构的关键约束。数据存储明确选定 JSON 文件（非 SQLite）。以下为对个人工具的**合理性论证**与**代价及规避策略**，作为 ADR-003 的正文依据。
|
||
|
||
### 3.1 为什么对个人工具合理（正面）
|
||
|
||
| 维度 | 说明 |
|
||
|---|---|
|
||
| 单机低运维 | 自用工具，无多实例、无并发在线用户。JSON 文件天然零安装、零连接串、零迁移脚本。Docker 起一个容器即用。 |
|
||
| 数据资产可读可迁移 | 数据是纯文件，用户可 `cat`/`jq` 直接读、可 git 跟踪、可一键备份到网盘/移动硬盘，跨设备迁移无锁定成本。对「备考数据是个人长期资产」这个心智高度契合。 |
|
||
| 无需 DB 部署 | 个人场景开 PostgreSQL 属杀鸡用牛刀；JSON + 内存聚合足够覆盖单用户数据量级。 |
|
||
| 开发速度快 | 无 ORM 映射、无迁移脚本、无连接池，`data/store.ts` 直接用 `fs` 读写，MVP 工作量最小。 |
|
||
| DevOps 极简 | Docker volume 挂载数据目录即持久化；备份即拷贝目录。 |
|
||
|
||
### 3.2 代价与规避策略（必须正视，不能回避）
|
||
|
||
| 代价 | 具体风险 | 规避策略 |
|
||
|---|---|---|
|
||
| 并发写 | 两个请求同时写同一文件导致覆盖或损坏 | **写队列串行**：单进程内所有写操作走一个 Promise 队列（互斥），逐个执行，杜绝交错写。 |
|
||
| 写入非原子 | 进程崩溃时写一半，文件损坏 | **临时文件 + rename 原子替换**：先写 `.tmp`，再 `fs.rename` 替换（同文件系统内 rename 原子）。 |
|
||
| 无事务 | 跨实体操作（如「错答 → 入错题本 + 增量统计」）任一步失败会导致数据不一致 | **单文件原子写 + 分解最小写单元**：每个实体独立文件，单文件内操作原子；跨实体的组合操作用「先写主实体、失败补偿 → 统计用内存快照重算」策略，统计始终可重建，不追求强一致。 |
|
||
| 体积增长 | 作答记录 file 随刷题量增长，全量读入内存成本上升 | **惰性加载 + 实体分文件**：仅按需读入某实体；作答记录达到阈值后做**归档分片**（按月切分 answer-records-YYYY-MM.json），增量统计在内存聚合。 |
|
||
| 无事务/一致性 | 统计与明细可能短暂不一致 | 统计采用「**内存聚合 + 快照持久化**」，明细写时同步更新内存聚合，快照定期落盘；明细永远可信，统计可随时由明细重新计算。 |
|
||
| 正文检索 | JSON 无索引，全文过滤为 O(n) | 单用户量级 O(n) 内存扫描足够（k 万条/秒级）；仅对高频过滤字段（module/status/日期）做**内存字段索引**（Map 缓存），避免全量遍历。 |
|
||
|
||
**结论**：Express + 本地 JSON 对「个人单用户备考工具」是**成本最低、数据资产感最强**的合理取舍；其并发/事务/体积三类代价均有明确规避策略，**不需要**升级到 SQLite 或 PostgreSQL（若未来数据量剧增或需多设备协作，再以 ADR 追加迁移，不影响本期闭环）。
|
||
|
||
---
|
||
|
||
## 四、垂直切片 3 层架构（ASCII 图）
|
||
|
||
本架构采用**垂直切片**组织方式，而非按层堆放大目录。一个资源被「纵向切透」——从 HTTP 入口到数据落盘端到端归属一个切片，切片内按职责分为三层，层与层之间**依赖只向下**。
|
||
|
||
```
|
||
┌────────────────────────────────────────────────────────────────────────────┐
|
||
│ Handler 层 · 垂直切片入口 │
|
||
│ routes/*.routes.ts │
|
||
│ · 路由注册 + zod 请求校验（schema.parse → parsed） │
|
||
│ · 调用对应 service │
|
||
│ · 组装统一响应 ApiResponse<T>（成功/失败） │
|
||
│ middlewares/ error / not-found / request-log │
|
||
└──────────────────────────┬─────────────────────────────────────────────────┘
|
||
│ 仅依赖 ↓（import）
|
||
┌──────────────────────────▼─────────────────────────────────────────────────┐
|
||
│ Service 层 │
|
||
│ services/*.service.ts │
|
||
│ · 跨实体业务逻辑（抽题 / 判定 / 错题入本 / 增量聚合 / 备份还原） │
|
||
│ · 用例编排、事务性组合、调用 data/store │
|
||
│ · 不 import req/res、不返回 HTTP 响应，只返回业务结果 / 抛业务异常 │
|
||
│ · authN（单用户：简单口令校验） │
|
||
└──────────────────────────┬─────────────────────────────────────────────────┘
|
||
│ 仅依赖 ↓（import）
|
||
┌──────────────────────────▼─────────────────────────────────────────────────┐
|
||
│ 数据访问 + 领域类型层 │
|
||
│ data/store.ts JsonStore 单例：读 JSON(zod 校验) + 写队列 + 原子写 │
|
||
│ data/file-map.ts APP_DATA_DIR 解析、文件命名 │
|
||
│ packages/shared/schemas/ zod schema（领域类型由 z.infer 产出，单一契约源） │
|
||
│ packages/shared/api/response.ts ApiResponse<T> 泛型 │
|
||
│ utils/ 纯工具函数（id / 日期 / 聚合，无业务无副作用） │
|
||
└──────────────────────────┬─────────────────────────────────────────────────┘
|
||
│
|
||
┌──────────────────────────▼─────────────────────────────────────────────────┐
|
||
│ 基础设施 Infrastructure │
|
||
│ 文件系统（数据目录） · 环境变量（config） · Docker volume 挂载点 │
|
||
└────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
> **AI 扩展位（二期，本期只留壳不实现）**：位于 Service 层，`services/ai/` 目录占位 + `providers/` 抽象接口；通过 Feature Flag 控制，见 §十。
|
||
|
||
**垂直切片 vs 横向堆叠的本质区分**：横向堆叠会把一个资源拆成 `routes + controllers + validators + services + repositories + stores` 六处，改一个接口字段要在多个目录间跳动；垂直切片把「路由 + 校验 + 编排 + 组装响应」收拢进一个 route 文件，跨实体复杂业务集中在对应 service 文件，数据存取合并进 `data/`，改一个接口往往只需动**一个 route 文件 + 一个 service 文件**。跨切片的实体业务（如答错同时写 answer-record、wrong-question 并增量更新统计）由 service 层统一承载，这是 service 层在本架构内的真实价值所在。
|
||
|
||
---
|
||
|
||
## 五、可执行目录结构与分包
|
||
|
||
### 5.1 Monorepo 布局（ADR-005）
|
||
|
||
采用 **pnpm workspace** 单仓多包，`apps/server` + `apps/web` + `packages/shared`。类型契约与 zod schema 在 `shared`，前后端共用，避免复制粘贴导致「同一模型多处定义漂移」。
|
||
|
||
```
|
||
gwy-exam/
|
||
├── pnpm-workspace.yaml
|
||
├── package.json # 仅脚本 + workspace 包管理器，不装业务依赖
|
||
├── tsconfig.base.json # 共享 TS 编译基座（strict / noImplicitAny / exact...）
|
||
├── .env.example # APP_DATA_DIR / PORT 等示例
|
||
├── Dockerfile
|
||
├── docker-compose.yml # server + volume 挂载数据目录
|
||
├── apps/
|
||
│ ├── server/ # Express 5 + TS + ESM
|
||
│ │ ├── package.json
|
||
│ │ ├── tsconfig.json
|
||
│ │ ├── src/
|
||
│ │ │ ├── app.ts # 入口：只装配（extendZodWithOpenApi + 挂中间件+路由+错误处理+启动），0 业务
|
||
│ │ │ ├── server.ts # 可选：监听与优雅关闭，仍只装配
|
||
│ │ │ ├── config/
|
||
│ │ │ │ ├── env.ts # 环境变量读取 + zod 校验，输出强类型 config
|
||
│ │ │ │ └── app-config.ts
|
||
│ │ │ ├── routes/ # 垂直切片入口：路由 + handler（校验 + 调 service + 组装响应）
|
||
│ │ │ │ ├── index.ts # 路由聚合（/api/v1）+ openapi 契约生成
|
||
│ │ │ │ ├── questions.routes.ts
|
||
│ │ │ │ ├── practice.routes.ts
|
||
│ │ │ │ ├── wrong-questions.routes.ts
|
||
│ │ │ │ ├── mock-exams.routes.ts
|
||
│ │ │ │ ├── shenlun.routes.ts
|
||
│ │ │ │ ├── tasks.routes.ts
|
||
│ │ │ │ ├── stats.routes.ts
|
||
│ │ │ │ ├── settings.routes.ts
|
||
│ │ │ │ └── data.routes.ts # 数据资产：导出 / 备份 / 还原
|
||
│ │ │ ├── services/ # 跨实体业务用例（不 import req/res）
|
||
│ │ │ │ ├── question.service.ts
|
||
│ │ │ │ ├── practice.service.ts # 抽题 + 判定 + 错题入本 + 统计增量
|
||
│ │ │ │ ├── wrong-question.service.ts
|
||
│ │ │ │ ├── mock-exam.service.ts
|
||
│ │ │ │ ├── shenlun.service.ts
|
||
│ │ │ │ ├── task.service.ts
|
||
│ │ │ │ ├── stats.service.ts # 内存聚合 + 快照
|
||
│ │ │ │ ├── settings.service.ts
|
||
│ │ │ │ ├── data-asset.service.ts # 导出/备份/还原
|
||
│ │ │ │ └── ai/ # 二期占位（详见 §十）
|
||
│ │ │ │ └── providers/ # provider 接口 + 空实现
|
||
│ │ │ ├── data/ # JSON 数据层核心（§六）
|
||
│ │ │ │ ├── store.ts # JsonStore 单例：写队列 + 原子写 + 惰性缓存 + zod 校验
|
||
│ │ │ │ └── file-map.ts # APP_DATA_DIR 解析、file 命名
|
||
│ │ │ ├── middlewares/
|
||
│ │ │ │ ├── error.middleware.ts
|
||
│ │ │ │ ├── not-found.middleware.ts
|
||
│ │ │ │ └── response-validate.middleware.ts # dev：出站响应 zod 校验
|
||
│ │ │ ├── errors/
|
||
│ │ │ │ ├── app-error.ts # 错误类型联合 + 错误码
|
||
│ │ │ │ └── error-codes.ts
|
||
│ │ │ └── utils/
|
||
│ │ │ ├── id.ts # crypto.randomUUID()
|
||
│ │ │ └── date.ts # ISO 时间 / 日粒度 key
|
||
│ │ └── data/ # 运行时数据目录（gitignore，APP_DATA_DIR 默认指向）
|
||
│ │ └── tests/ # 单元测试（service / data）
|
||
│ ├── web/ # Vue3 + Vite + TS
|
||
│ │ ├── package.json
|
||
│ │ ├── tsconfig.json
|
||
│ │ ├── vite.config.ts
|
||
│ │ ├── src/
|
||
│ │ │ ├── main.ts
|
||
│ │ │ ├── App.vue
|
||
│ │ │ ├── router/ # Vue Router 4 配置
|
||
│ │ │ ├── views/ # 页面组件（按产品页面分包）
|
||
│ │ │ │ ├── dashboard/ # 数据中枢
|
||
│ │ │ │ ├── question-entry/ # 题库录入
|
||
│ │ │ │ ├── practice/ # 刷题中心（刷题态/错题态/申论态）
|
||
│ │ │ │ ├── mock-exam/ # 模考分析
|
||
│ │ │ │ ├── task/ # 备考计划
|
||
│ │ │ │ ├── news/ # 要闻
|
||
│ │ │ │ └── settings/ # 设置
|
||
│ │ │ ├── components/ # 通用组件（按需拆分 + 单文件 ≤ 300 行）
|
||
│ │ │ ├── composables/ # 组合式函数（useQuestions / useStats 等）
|
||
│ │ │ ├── stores/ # Pinia
|
||
│ │ │ ├── services/ # API 封装（fetch 统一封装 + ApiResponse<T> 解析）
|
||
│ │ │ │ └── api-client.ts
|
||
│ │ │ ├── types/ # 由 openapi 契约生成的 TS 类型（orval/@hey-api）或复用 shared z.infer
|
||
│ │ │ ├── styles/ # 设计 token（来自设计规范 CSS 变量）
|
||
│ │ │ └── mocks/ # MSW Mock（依 openapi 契约生成）
|
||
│ │ └── public/
|
||
└── packages/
|
||
└── shared/ # 前后端共享：单一契约源（zod schema + z.infer 类型 + 常量）
|
||
├── package.json
|
||
├── tsconfig.json
|
||
├── src/
|
||
│ ├── schemas/ # zod schema = 领域类型 + 数据 schema + 请求 schema（单一契约源）
|
||
│ │ ├── question.schema.ts
|
||
│ │ ├── practice.schema.ts
|
||
│ │ ├── wrong-question.schema.ts
|
||
│ │ ├── mock-exam.schema.ts
|
||
│ │ ├── shenlun.schema.ts
|
||
│ │ ├── task.schema.ts
|
||
│ │ ├── stats.schema.ts
|
||
│ │ ├── settings.schema.ts
|
||
│ │ └── index.ts # 统一导出 + z.infer 具名类型
|
||
│ ├── api/response.ts # ApiResponse<T> 泛型
|
||
│ ├── api/error-codes.ts # 错误码联合
|
||
│ └── constants.ts # 模块中文名映射等
|
||
└── index.ts
|
||
```
|
||
|
||
### 5.2 文件组织硬规则（对照 `code-organization.md` §4，出现即不合格）
|
||
|
||
| # | 规则 | 本项目落地 |
|
||
|---|---|---|
|
||
| 1 | 单文件 ≤ 300 行 | route/service/schema 每文件一个；超限按子功能拆文件，不拆函数凑数 |
|
||
| 2 | 单一职责 | route handler 只编排 + 组装响应；service 只业务；`data/` 只存取 |
|
||
| 3 | 按资源分包 | 每资源 = route + service +（可选）schema 切片；`data/` 与 `packages/shared/schemas` 横跨复用 |
|
||
| 4 | 入口只装配 | `app.ts` 只挂中间件 + 路由 + 错误处理 + 启动，0 业务逻辑 |
|
||
| 5 | 业务不进路由处理器 | route handler 内只做 zod 校验 + 调 service + 组装响应，跨实体逻辑全部下沉 service |
|
||
| 6 | 依赖只向下、不反向、不跨层 | route→service→data；service 不 import req/res；跨切片走对方 service 接口 |
|
||
| 7 | utils 纯净 | `utils/` 只放纯函数（id / 日期 / 聚合），无业务无副作用 |
|
||
| 8 | 类型/schema 由 zod 单一契约源产出 | 领域类型用 `z.infer`，openapi 契约用 `zod-openapi` 自动生成，均不自维护另一份定义 |
|
||
|
||
**门禁命令**（Phase 2 交付前执行）：
|
||
|
||
```bash
|
||
# 超 300 行即退回
|
||
find apps -name '*.ts' -o -name '*.vue' | xargs wc -l | sort -rn | awk '$1>300 && $2!="total" {print "OVER LIMIT:", $0}'
|
||
# 入口是否含业务（应只装配，行数 < 100）
|
||
wc -l apps/server/src/app.ts
|
||
```
|
||
|
||
---
|
||
|
||
## 六、本地 JSON 数据层核心设计（本架构重点）
|
||
|
||
### 6.1 数据目录可配置
|
||
|
||
- 环境变量 `APP_DATA_DIR`，默认 `./data`（相对于 `apps/server` 运行目录）。
|
||
- 通过 `config/env.ts` 用 zod 读取并校验，输出强类型 `AppConfig`（非 any）。
|
||
- **Docker 挂载**：`docker-compose.yml` 将宿主机目录挂载到容器的 `APP_DATA_DIR`，实现持久化与宿主机备份。
|
||
|
||
```
|
||
数据目录（${APP_DATA_DIR}/）
|
||
├── questions.json # 题库
|
||
├── answer-records.json # 作答记录（刷题历史，驱动统计）
|
||
├── answer-records-2026-08.json # 归档分片（可选，达阈值后按月切）
|
||
├── wrong-questions.json # 错题本
|
||
├── mock-exams.json # 模考记录
|
||
├── shenlun.json # 申论写作/文章
|
||
├── tasks.json # 备考计划任务
|
||
├── stats.json # 统计聚合快照
|
||
├── settings.json # 偏好设置
|
||
└── meta.json # 数据 schema 版本 + 最后写时间（数据资产元信息）
|
||
```
|
||
|
||
> `.gitignore` 应忽略整个 `data/`（数据是用户资产，不入 git；但允许用户自行 git 跟踪做版本备份）。
|
||
|
||
### 6.2 数据文件顶层索引结构
|
||
|
||
每个实体文件采用**顶层索引 + items 数组**结构（用索引 id→index 便于 O(1) 查找，items 为有序记录）：
|
||
|
||
```jsonc
|
||
// questions.json
|
||
{
|
||
"version": 1, // schema 版本
|
||
"updatedAt": "2026-08-26T12:00:00.000Z",
|
||
"index": { "<question-id>": 0, "<question-id>": 1 }, // id → items 下标
|
||
"items": [ /* Question[] 全量 */ ]
|
||
}
|
||
```
|
||
|
||
### 6.3 数据形状（由 zod schema 定义，`z.infer` 产出具名类型，0 any）
|
||
|
||
> **单一契约源**：领域类型不手写 interface，全部由 `packages/shared/src/schemas/*.schema.ts` 的 zod schema 经 `z.infer` 产出。数据文件读入用同一 schema 校验，openapi 契约由同一 schema 反推，三者同一来源，永不漂移。
|
||
|
||
以下以 `packages/shared/src/schemas/question.schema.ts` 为例（示意，完整见 params.md）：
|
||
|
||
```ts
|
||
import { z } from 'zod';
|
||
|
||
export const SubjectKeySchema = z.enum(['xingce', 'shenlun']);
|
||
export const ModuleKeySchema = z.enum([
|
||
'xingce-shuli', 'xingce-panduan', 'xingce-yanyu',
|
||
'xingce-changshi', 'xingce-ziliao',
|
||
'shenlun-zhuizong', 'shenlun-zonghe', 'shenlun-shenlun',
|
||
]);
|
||
export const QuestionTypeSchema = z.enum(['single', 'multiple', 'judge', 'blank', 'essay']);
|
||
|
||
export const QuestionSchema = z.object({
|
||
id: z.string().uuid(),
|
||
subject: SubjectKeySchema,
|
||
module: ModuleKeySchema,
|
||
type: QuestionTypeSchema,
|
||
stem: z.string().min(1),
|
||
options: z.array(z.string()).optional(),
|
||
answer: z.union([z.string(), z.array(z.string())]),
|
||
analysis: z.string().optional(),
|
||
source: z.string().optional(),
|
||
difficulty: z.number().int().min(1).max(5).optional(),
|
||
tags: z.array(z.string()).default([]),
|
||
createdAt: z.string().datetime(),
|
||
updatedAt: z.string().datetime(),
|
||
aiExplanation: z.string().optional(),
|
||
aiConfidence: z.number().min(0).max(1).optional(),
|
||
}).openapi('Question'); // 注册为 openapi components/schemas/Question
|
||
|
||
export type SubjectKey = z.infer<typeof SubjectKeySchema>;
|
||
export type ModuleKey = z.infer<typeof ModuleKeySchema>;
|
||
export type QuestionType = z.infer<typeof QuestionTypeSchema>;
|
||
export type Question = z.infer<typeof QuestionSchema>;
|
||
```
|
||
|
||
其余 7 个实体（AnswerRecord / WrongQuestion / MockExam / ShenLunEssay / StudyTask / StatsSnapshot / AppSettings）以同样方式定义，枚举与字段见 `params.md`。
|
||
|
||
> `z.infer` 直接产出具名类型，**全文件无 any**。请求体 schema（Create/Update）与数据 schema 同文件或同目录定义，均转交给 zod-openapi 注册端点。
|
||
|
||
### 6.4 原子写入策略（保证数据不损坏）
|
||
|
||
核心在 `data/store.ts` 的 `JsonFileStore` 单例，四个防线：
|
||
|
||
#### (1) 临时文件 + rename 原子替换
|
||
|
||
```ts
|
||
async atomicWrite(data: JsonFile<T>): Promise<void> {
|
||
const dir = dirname(this.filePath);
|
||
await mkdir(dir, { recursive: true });
|
||
const tmp = join(dir, `.${basename(this.filePath)}.tmp`);
|
||
await writeFile(tmp, JSON.stringify(data, null, 2), 'utf8');
|
||
await rename(tmp, this.filePath); // 同文件系统内 rename 原子，进程崩溃不会留下半写文件
|
||
}
|
||
```
|
||
|
||
> 先写 `.tmp` 再 rename，保证任何时候磁盘上要么是旧完整文件，要么是新完整文件，绝无「写一半」的中间态。
|
||
|
||
#### (2) 写队列 / 互斥锁（防并发写坏）
|
||
|
||
```ts
|
||
private enqueue<TResult>(task: () => Promise<TResult>): Promise<TResult> {
|
||
const run = this.queue.then(task);
|
||
this.queue = run.catch(() => undefined); // 队尾吞错，保持链条存活
|
||
return run;
|
||
}
|
||
|
||
async save(): Promise<void> {
|
||
await this.enqueue(() => this.atomicWrite(this.currentData));
|
||
}
|
||
```
|
||
|
||
> 单进程内所有写操作串行入队、逐个执行，杜绝两个请求同时 rename 导致写覆盖或损坏。这是 JSON 数据层最关键的一道防线。
|
||
|
||
#### (3) 读入 zod 校验（不可信输入收窄）
|
||
|
||
```ts
|
||
function parseWith<T>(schema: ZodType<T>, raw: unknown): T {
|
||
return schema.parse(raw); // 返回类型为 T，天然收窄，无 any
|
||
}
|
||
```
|
||
|
||
> 数据来自本地 JSON 文件——文件是可变外部输入（可能被手工编辑、被旧版本程序写过、Docker 挂载来源不可控）。读入后必须过 zod schema，把「未知 JSON」收窄为「强类型实体」，这是「从文件读数据 + 无 any」的关键。
|
||
|
||
#### (4) 可选防抖批写
|
||
|
||
刷题高频写（每道题作答一次写 disk）时，用**防抖合并**（如 500ms 内多次写合并为一次落盘）+ **内存立即生效**，降低磁盘 IO：
|
||
|
||
```ts
|
||
private scheduleFlush(data: JsonFile<T>): void {
|
||
this.currentData = data;
|
||
clearTimeout(this.debounceTimer);
|
||
this.debounceTimer = setTimeout(() => this.save(), this.flushInterval);
|
||
}
|
||
```
|
||
|
||
### 6.5 Id 生成与时间字段
|
||
|
||
- **Id**：`crypto.randomUUID()`（Node 内置，全局唯一，无需自增/碰撞处理）。
|
||
- **时间字段**：所有实体必有 `createdAt` / `updatedAt`（ISO 8601，`new Date().toISOString()`）；写入时 service 统一设置 `updatedAt`。
|
||
- **时间工具**：`utils/date.ts` 提供 `toDateKey(iso): string`（yyyy-MM-dd，用于 stats/周报聚合）。
|
||
|
||
### 6.6 数据资产：导出 / 备份 / 还原（接口预留）
|
||
|
||
数据是「个人长期资产」，架构层预留**一键导出/备份/还原**能力（本期仅接口，Phase 2 实现）：
|
||
|
||
| 能力 | 接口 | 说明 |
|
||
|---|---|---|
|
||
| 导出 JSON | `POST /api/v1/data/export` | 把全部实体打包为一个 `gwy-exam-backup-{date}.json`，含 schema 版本 |
|
||
| 导出 CSV | `GET /api/v1/data/export?entity=questions` | 按实体导出 CSV（错题本/题库→可被 Excel 打开） |
|
||
| 备份 | `POST /api/v1/data/backup` | 复制 `APP_DATA_DIR` 到备份子目录（或输出压缩流） |
|
||
| 还原 | `POST /api/v1/data/restore` | 读入备份文件，通过 zod 校验后再原子写回各实体文件（先写临时，成功后整体替换） |
|
||
|
||
> **还原安全性**：备份内容是不可信输入，必须逐实体过 zod schema 校验后再落地；还原前先对当前数据做一次自动备份，坏备份不覆盖好数据。
|
||
|
||
---
|
||
|
||
## 七、无 any 的工程化约束（评审铁律）
|
||
|
||
### 7.1 tsconfig（strict 全家桶）
|
||
|
||
`tsconfig.base.json` 开满严格选项，**从类型系统层面严禁 any**：
|
||
|
||
```jsonc
|
||
{
|
||
"compilerOptions": {
|
||
"target": "ES2022",
|
||
"module": "NodeNext", // ESM
|
||
"moduleResolution": "NodeNext",
|
||
"strict": true,
|
||
"noImplicitAny": true, // 显式禁止 any
|
||
"noImplicitThis": true,
|
||
"alwaysStrict": true,
|
||
"strictNullChecks": true,
|
||
"strictFunctionTypes": true,
|
||
"strictPropertyInitialization": true,
|
||
"exactOptionalPropertyTypes": true, // 可选属性必须显式 undefined，杜绝隐式
|
||
"useUnknownInCatchVariables": true, // catch 变量为 unknown，须窄化
|
||
"noUncheckedIndexedAccess": true, // 对象索引访问可能为 undefined
|
||
"noImplicitReturns": true,
|
||
"noFallthroughCasesInSwitch": true,
|
||
"noUnusedLocals": true,
|
||
"noUnusedParameters": true,
|
||
"esModuleInterop": true,
|
||
"forceConsistentCasingInFileNames": true,
|
||
"skipLibCheck": true,
|
||
"declaration": true,
|
||
"outDir": "dist"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7.2 单一契约源：zod schema 驱动类型 + 契约 + 校验
|
||
|
||
- **领域类型**：由 `packages/shared/src/schemas/*.schema.ts` 的 zod schema 经 `z.infer` 产出，前后端共用，0 any。不手写 interface，避免「手写类型 vs zod schema」两处漂移。
|
||
- **OpenAPI 契约**：由 `zod-openapi` 从同一批 zod schema 自动反推生成（见 §二），前端据此生成 TS 类型 + MSW Mock，无需手写维护 `openapi.yaml`。
|
||
- **请求校验**：route handler 用同一 zod schema `parse(raw)`，获得收窄后的强类型输入。
|
||
|
||
三者**同源于 zod schema**，改一个字段只需改 schema 一处，类型与契约自动跟随。
|
||
|
||
### 7.3 统一响应类型与请求校验
|
||
|
||
- **统一响应类型** `ApiResponse<T>`（泛型，0 any）：
|
||
|
||
```ts
|
||
export interface ApiSuccess<T> {
|
||
code: 0;
|
||
data: T;
|
||
message?: string;
|
||
}
|
||
export interface ApiFailure {
|
||
code: number; // 非 0 错误码
|
||
data: null;
|
||
message: string; // 人类可读
|
||
}
|
||
export type ApiResponse<T> = ApiSuccess<T> | ApiFailure;
|
||
```
|
||
|
||
- **请求校验**：route handler 内以 zod 校验 body / query / params，`parsed` 结果注入局部变量（勿再读原始 req 对象）：
|
||
|
||
```ts
|
||
const body = QuestionCreateSchema.parse(req.body); // 收窄为强类型
|
||
const list = await questionService.create(body);
|
||
res.status(201).json({ code: 0, data: list });
|
||
```
|
||
|
||
### 7.4 错误类型联合（不用 any / 尽量不用 unknown）
|
||
|
||
- **应用错误**：`AppError` 带 `code` 与 `message`，错误码为联合类型（见 `error-codes.ts`）。
|
||
- **catch 变量为 unknown**：用窄化守卫，不用 `any` 强转：
|
||
|
||
```ts
|
||
function toAppError(err: unknown): AppError {
|
||
if (err instanceof AppError) return err;
|
||
return new AppError('INTERNAL_ERROR', 'internal server error');
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 八、API 骨架（RESTful，`/api/v1/`）
|
||
|
||
统一响应 `ApiResponse<T>`（见 §7.3），分页见 `{ items, total, page, limit, hasMore }`。完整契约由 `zod-openapi` 自动生成（见 `openapi.yaml`，Phase 2 前端据其生成类型 + MSW Mock）。
|
||
|
||
### 8.1 资源模块清单与方法示例
|
||
|
||
| 资源 | 端点 | 方法示例 |
|
||
|---|---|---|
|
||
| 题库 questions | `GET/POST /questions` `GET/PATCH/DELETE /questions/:id` | 列表、详情、创建、改、删；`POST /questions/import` 导入真题；`GET /questions/export` 导出 |
|
||
| 刷题 practice | `POST /practice/draw` `POST /practice/submit` | 抽题（按模块/错题优先/随机）；提交作答并判定 |
|
||
| 错题本 wrong-questions | `GET /wrong-questions` `GET/PATCH /wrong-questions/:id` | 打错因标签；`POST /wrong-questions/:id/resolve` 移除；复习 |
|
||
| 模考 mock-exams | `GET/POST /mock-exams` `GET/PATCH/DELETE /mock-exams/:id` | 记录与分模块分析 |
|
||
| 申论 shenlun | `GET /shenlun` `POST /shenlun` `PATCH /shenlun/:id` | 写作与自评 |
|
||
| 计划 tasks | `GET/POST /tasks` `PATCH /tasks/:id` | 备考计划、打卡、完成 |
|
||
| 统计 stats | `GET /stats/overview` `GET /stats/daily` `GET /stats/module` `GET /stats/monthly-report` | 数据中枢聚合（内存聚合） |
|
||
| 设置 settings | `GET /settings` `PATCH /settings` | 偏好（含 AI 开关） |
|
||
| 数据资产 data | `POST /data/export` `GET /data/export?entity=questions` `POST /data/backup` `POST /data/restore` | 导出/备份/还原（预留） |
|
||
|
||
### 8.2 REST 语义说明
|
||
|
||
> 数据底层是 JSON 文件，但 **API 仍用 REST semantic**（资源化 + HTTP 动词 + 版本号），前端据此生成 TS 类型、后端按契约实现。REST 语义与存储介质无关。
|
||
|
||
---
|
||
|
||
## 九、可行性验证与风险
|
||
|
||
### 9.1 核心闭环在 Express + 本地 JSON 下的可行性
|
||
|
||
| 场景 | 可行性 | 说明 / 防护 |
|
||
|---|---|---|
|
||
| 录入题库 | 完全可行 | 每道题一次写；写队列串行 + 原子写保护 |
|
||
| 分模块刷题（抽题） | 完全可行 | 抽题 = 读内存 items + 按 module/错题优先过滤（字段索引），O(1)~O(n) |
|
||
| 答错自动进错题本 | 完全可行 | Submit → 判定 wrong → 写 answer-record + 写 wrong-question（两个文件，各一次原子写） |
|
||
| 打错因标签 | 完全可行 | 更新 wrong-question，一次写 |
|
||
| 模考录入 | 完全可行 | 一次写 mock-exam + 可选写 answer-record |
|
||
| 统计聚合 | **需防护（可行）** | 见 9.2：用内存聚合，勿每次全量扫描文件 |
|
||
|
||
### 9.2 性能边界与防护（重点）
|
||
|
||
| 风险 | 边界 | 防护策略 |
|
||
|---|---|---|
|
||
| 统计 O(n) 全量扫描 | 每次请求若遍历全部 answer-record，随量增线性变慢 | **内存聚合 + 快照**：`stats.service` 在内存维护日/模块/错因聚合 Map，`AnswerRecord` 写入时同步增量更新；`StatsSnapshot` 定期落盘；查询返回快照/内存，不再全文件扫描。 |
|
||
| JSON 文件读入内存 | answer-record 达数万条时加载变慢 | **惰性加载**：仅按需读实体；作答记录超阈值做**归档分片**（按月切 `answer-records-YYYY-MM.json`），历史聚合走快照。 |
|
||
| 高频写磁盘 IO | 刷题高峰每道题一次落盘 | **防抖批写**（500ms 合并）+ 内存立即生效。 |
|
||
| 单文件过大 | 文件越大 rename 越慢 | 实体分文件（每个实体独立）+ 归档分片，单文件控制在合理量级。 |
|
||
|
||
**量级估算**：单用户年刷题 1-2 万道，answer-record 年增 1-2 万条 → 全年约 2-4 万条 JSON（每条几百字节，约存 10-20MB），单文件读入 + 内存聚合均在毫秒级，个人场景完全无压力。**无需更换存储**。
|
||
|
||
### 9.3 结论：不可行判定
|
||
|
||
- 对本产品既定功能（录入/刷题/错题本/模考/申论/计划/统计），**没有任何一项是「完全不可行」**。
|
||
- 仅「统计聚合」与「大文件写入」是**「当前栈成本高 + 有替代方案」**——替代方案即 §9.2 的内存聚合 + 归档分片，属**本期架构自带防护**，不需换 DB。
|
||
- 若未来出现**多设备实时协作 / 数据超百万条 / 需要复杂关系查询**，届时再以 ADR 追加迁移 SQLite/PostgreSQL，本期不预留迁移负担。
|
||
|
||
---
|
||
|
||
## 十、AI 扩展位（二期 P1，本期只留壳不实现）
|
||
|
||
AI 整体在二期，本期架构只为 AI **预留扩展位**，不做任何 AI 实现。
|
||
|
||
### 10.1 架构预留点
|
||
|
||
| 项 | 预留方式 | 位置 |
|
||
|---|---|---|
|
||
| 模块占位 | `services/ai/` 目录 + `providers/` 空实现 | `apps/server/src/services/ai/providers/` |
|
||
| Provider 抽象 | `AiProvider` 接口（`explainQuestion` / `giveFeedback` / `ask`），内置空实现 `NoopProvider` | 同上 |
|
||
| 数据字段预留 | `Question.aiExplanation / aiConfidence`、`ShenLunEssay.aiFeedback` 等字段已在 zod schema 中预留（本期可 undefined，但不实现产生逻辑） | `packages/shared/src/schemas/` |
|
||
| API 命名空间 | 预留 `/api/v1/ai/*`（本期不挂路由，由 Feature Flag 控制，见 §10.2） | `routes/` |
|
||
| 异步解耦 | AI 调用设计为非阻塞（返回 `pending` 任务 id，后续轮询），不阻塞主流程 | service 层约定 |
|
||
|
||
### 10.2 Feature Flag（AI 灰度/总开关）
|
||
|
||
AI 二期功能用轻量 Feature Flag 控制，避免全量上线风险（不引入第三方服务）：
|
||
|
||
```ts
|
||
// settings AppSettings.aiEnabled 作为总开关；后端 checkAIFeature(key) 判定
|
||
interface AiFeatureGate {
|
||
enabled: boolean; // 全局
|
||
rollout?: number; // 0-100（可扩展）
|
||
}
|
||
// 若 aiEnabled=false 或 gate 未开，/api/v1/ai/* 返回 404 FEATURE_DISABLED
|
||
```
|
||
|
||
> 本期 `aiEnabled` 恒为 `false`，`/api/v1/ai/*` 不挂路由、返回未启用错误码。Phase 2 实现 AI 时才打开。
|
||
|
||
---
|
||
|
||
## 十一、技术约束清单（汇总，写入 params.md）
|
||
|
||
- 语言：全 TypeScript，**全程禁止 any**。
|
||
- 后端：Express 5.x + Node 24 LTS + ESM。
|
||
- 前端：Vue 3.5 + Vite 6 + TS 5.8 + Vue Router 4 + Pinia。
|
||
- 数据层：本地 JSON 文件（可配置 `APP_DATA_DIR`，Docker volume 挂载），zod 运行时校验，临时文件 + rename 原子写 + 写队列。
|
||
- **单一契约源**：领域类型由 `z.infer` 产出，OpenAPI 契约由 `zod-openapi` 自动生成，请求校验用同一 zod schema，三者同源同步。
|
||
- 类型契约：`packages/shared` 共享 zod schema + `ApiResponse<T>` + 错误码。
|
||
- 版本锚定：Node 24 LTS / Express 5.2 / Vue 3.5 / Vite 6 / TS 5.8 / zod 4.x / @asteasolutions/zod-to-openapi 8.x（安装后回写精确版本）。
|
||
- 图标：前端图标 **由设计/架构阶段锁定一套 SVG 图标库并全局统一，不混用**；架构文档与 API 文档**不出现 emoji**、不采用紫色→粉色渐变、无空洞占位文案。
|
||
|
||
---
|
||
|
||
## 十二、机器可读产出物清单
|
||
|
||
| 文件 | 说明 |
|
||
|---|---|
|
||
| `architecture.md` | 本文件（核心架构） |
|
||
| `openapi.yaml` | OpenAPI 3.0 契约（由 zod-openapi 自动生成；前端据此生成 TS 类型 + MSW Mock） |
|
||
| `decisions/ADR-001.md` | Express 5 选型 |
|
||
| `decisions/ADR-002.md` | Vue3 + Vite 选型 |
|
||
| `decisions/ADR-003.md` | 本地 JSON 文件数据层选型 |
|
||
| `decisions/ADR-004.md` | 全 TS strict + zod 运行时校验（单一契约源） |
|
||
| `decisions/ADR-005.md` | monorepo 布局（pnpm workspace） |
|
||
| `decisions/ADR-006.md` | 垂直切片 + 单一契约源（zod + zod-openapi） |
|
||
| `params.md` | 技术约束清单 + 各资源数据结构说明 |
|
||
|
||
---
|
||
|
||
## 十三、端到端验证步骤（Phase 2 收尾用）
|
||
|
||
**改一个字段的完整链路（以修改题目 `stem` 的校验规则为例）**：
|
||
修改 `packages/shared/src/schemas/question.schema.ts` 中 `QuestionSchema`（或 `QuestionCreateSchema`）的 `stem` 校验 → 重新触发 `zod-openapi` 生成契约 → 前端 `orval`/`@hey-api` 据此重新生成 TS 类型 → route handler 用同一 schema 校验、类型与契约已自动跟随。**只需改 schema 一处，类型与契约自动同步。**
|
||
|
||
1. `pnpm install` → 核对 `package.json` 版本与 §二 锚定表一致。
|
||
2. `pnpm --filter <server> build` 通过（tsc strict 全家桶，无 any 报错）。
|
||
3. `pnpm --filter <server> dev` 启动，`curl /api/v1/settings` 返回 `{code:0,data:{...}}`。
|
||
4. 走核心闭环：`POST /questions`（录入 1 题）→ `POST /practice/submit`（答错）→ `GET /wrong-questions` 见该题 → `PATCH /wrong-questions/:id` 打错因标签 → `GET /stats/overview` 见聚合。
|
||
5. 数据写后 `cat ${APP_DATA_DIR}/questions.json` 校验为合法 JSON（原子写未损坏）。
|
||
6. 门禁：`find apps -name '*.ts' | xargs wc -l` 最大文件 ≤ 300；`app.ts` < 100 行。
|
||
|
||
---
|
||
|
||
*（文档无 emoji、无紫粉渐变、无占位文案。数据形状全部由 zod schema 定义并经 z.infer 产出类型，无 any。）*
|