2026-08-26 16:20:55 +08:00

40 KiB

Raw Blame History

备考中枢 · 系统架构设计

版本：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 交付前执行）：

# 超 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 为有序记录）：

// 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）：

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 原子替换

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) 写队列 / 互斥锁（防并发写坏）

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 校验（不可信输入收窄）

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：

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：

{
  "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）：

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 对象）：

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 强转：

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 控制，避免全量上线风险（不引入第三方服务）：

// 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 一处，类型与契约自动同步。

pnpm install → 核对 package.json 版本与 §二锚定表一致。
pnpm --filter <server> build 通过（tsc strict 全家桶，无 any 报错）。
pnpm --filter <server> dev 启动，curl /api/v1/settings 返回 {code:0,data:{...}}。
走核心闭环：POST /questions（录入 1 题）→ POST /practice/submit（答错）→ GET /wrong-questions 见该题 → PATCH /wrong-questions/:id 打错因标签 → GET /stats/overview 见聚合。
数据写后 cat ${APP_DATA_DIR}/questions.json 校验为合法 JSON（原子写未损坏）。
门禁：find apps -name '*.ts' | xargs wc -l 最大文件 ≤ 300；app.ts < 100 行。

（文档无 emoji、无紫粉渐变、无占位文案。数据形状全部由 zod schema 定义并经 z.infer 产出类型，无 any。）

40 KiB Raw Blame History Unescape Escape