liyy/gwy-exam
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
gwy-exam/deliverables/architecture/params.md
liyy 1601508900 init: 添加架构文档
2026-08-26 16:20:55 +08:00

8.5 KiB
Raw Blame History

备考中枢 · 技术约束清单与数据结构说明（params.md）

版本：v2.0 · 2026-08-26 用途：供前端 / 后端 / 测试开发阶段引用，与 architecture.md / openapi.yaml / decisions/ 互为契约。 组织方式：垂直切片（Handler 层 / Service 层 / 数据访问 + 领域类型层），单一契约源（zod + zod-openapi）。

一、技术栈与硬约束（必读铁律）

项 约束
语言 全 TypeScript，全程禁止 any（评审铁律，违反即退回）
后端 Express 5.x + Node.js 24 LTS + ESM
前端 Vue 3.5 + Vite 6 + TS 5.8 + Vue Router 4 + Pinia
数据层 本地 JSON 文件（APP_DATA_DIR，Docker volume 挂载）
数据校验 zod 运行时校验（读 JSON 必过，无 any）
单一契约源 领域类型由 zod z.infer 产出；OpenAPI 契约由 zod-openapi 自动生成；请求校验用同一 zod schema —— 三者同源同步
版本锚定 Node 24 LTS / Express 5.2 / Vue 3.5 / Vite 6 / TS 5.8 / zod 4.x / @asteasolutions/zod-to-openapi 8.x（安装后回写精确版）
包管理 pnpm 10+（monorepo workspace）
包格式 ESM（Express 5 原生支持 import）
响应格式 统一 ApiResponse<T>（code=0 成功，code!=0 失败）
API 版本 所有端点 /api/v1/ 前缀
图标 前端图标由设计/架构阶段锁定一套 SVG 图标库并全局统一，不混用；API/架构文档不出现 emoji
视觉 禁止紫色→粉色渐变方案
文案 禁止空洞占位文案
单文件 单文件 ≤ 300 行，单一职责，入口只装配零业务，依赖只向下

二、数据目录（APP_DATA_DIR）

环境变量 APP_DATA_DIR，默认 ./data。Docker volume 挂载。

${APP_DATA_DIR}/
├── questions.json               # 题库
├── answer-records.json          # 作答记录
├── answer-records-YYYY-MM.json  # 归档分片（阈值后按月切）
├── wrong-questions.json         # 错题本
├── mock-exams.json              # 模考记录
├── shenlun.json                 # 申论
├── tasks.json                   # 备考计划
├── stats.json                   # 统计快照
├── settings.json                # 偏好设置
└── meta.json                    # schema 版本 + 最后写时间

顶层索引结构（通用）

{
  "version": 1,
  "updatedAt": "2026-08-26T12:00:00.000Z",
  "index": { "<id>": 0 },
  "items": []
}

原子写入约定

  • 写 .tmp 后 fs.rename 原子替换（同文件系统 rename 原子）。
  • 单进程内所有写走一个 Promise 队列（互斥），逐个执行。
  • 高频写用防抖批写（< 500ms 合并），内存立即生效。
  • 读入文件必过 zod schema 校验（不可信输入收窄为强类型实体）。

三、领域实体清单（8 个）

以下字段均由 packages/shared/src/schemas/*.schema.ts 的 zod schema 定义，类型经 z.infer 产出。表中字段为约定值（must-match），实际以 zod schema 为准。

实体 关键字段 说明
Question id, subject, module, type, stem, options, answer, analysis, source, difficulty, tags, createdAt/At 题目
AnswerRecord id, questionId, module, correctness, isWrong, userAnswer, wrongReasons, tookMs, source, practiceDate 作答记录（驱动统计）
WrongQuestion id, questionId, module, wrongReasons, wrongCount, lastWrongAt, reviewCount, status, note 错题本（错答自动入本）
MockExam id, title, examType, fullScore, score, rank, durationMin, moduleScores, moduleCorrectRate, examDate 模考
ShenLunEssay id, examId, topic, module, content, wordCount, durationMin, selfRating, aiFeedback 申论
StudyTask id, title, module, planDate, status, recurrence, targetCount, completedCount, note 备考任务
StatsSnapshot id, date, totalAnswered/Correct/Wrong, overallCorrectRate, practiceStreak, moduleStats, wrongByReason 统计聚合快照
AppSettings id('app'), targetScore, dailyQuestionTarget, dailyStudyMinutes, uiTheme, primaryColor, aiEnabled 偏好设置（单例）

枚举清单

  • 科目 SubjectKey：xingce | shenlun
  • 模块 ModuleKey：xingce-shuli | xingce-panduan | xingce-yanyu | xingce-changshi | xingce-ziliao | shenlun-zhuizong | shenlun-zonghe | shenlun-shenlun
  • 题型 QuestionType：single | multiple | judge | blank | essay
  • 判定 Correctness：correct | wrong | partial | blank
  • 错因 WrongReason：knowledge-gap | concept-confusion | careless | time-pressure | method-unfamiliar | calculation-error | reading-error
  • 错题状态 WrongQuestionStatus：open | resolved | mastered
  • 模考类型 ExamType：national | province | self
  • 任务状态 TaskStatus：todo | doing | done | skipped
  • 任务循环 TaskRecurrence：once | daily | weekly
  • 主题 uiTheme：light | dark（默认 light，深蓝主色，不采用紫粉渐变）

四、统一响应格式

// 成功
{ "code": 0, "data": { ... } }
// 失败
{ "code": 40001, "data": null, "message": "human readable" }

分页响应：

{ "code": 0, "data": { "items": [], "total": 100, "page": 1, "limit": 20, "hasMore": true } }

五、错误码约定

区段 含义
40001 请求参数错误（BadRequest）
42200 校验失败（ValidationError，zod）
40400 资源不存在（NotFound）
50000 内部错误（Internal）
50303 功能未启用（AI 二期 FEATURE_DISABLED）
40900 数据写入冲突（写队列拒绝，罕见）

错误码为联合类型（AppError），catch 变量用 unknown 窄化，禁止 any 强转。

六、垂直切片分包要点（对照 code-organization.md §3）

  • Handler 层（routes/*.routes.ts）：路由注册 + zod 请求校验（schema.parse，用收窄后结果）+ 调 service + 组装 ApiResponse<T>，端点变更只落在一个 route 文件。
  • Service 层（services/*.service.ts）：跨实体业务逻辑（抽题 / 判定 / 错题入本 / 增量聚合 / 备份还原），不 import req/res，不返回 HTTP 响应。
  • 数据访问 + 领域类型（data/ + packages/shared/src/schemas/）：data/store.ts（读 JSON + 原子写 + 写队列 + zod 校验）、data/file-map.ts；领域类型与请求校验均由 zod schema 单一契约源产出。
  • 前端：页面在 views/ 按产品页面分包（dashboard / question-entry / practice / mock-exam / task / news / settings）；组合式函数在 composables/；API 调用统一封装 services/api-client.ts，解析 ApiResponse<T>；类型由 openapi 契约生成（orval / @hey-api/openapi-ts）或复用 packages/shared 的 z.infer 类型。
  • 组件单文件 ≤ 300 行，单一职责。

七、单一契约源（zod + zod-openapi）

  • 领域类型：packages/shared/src/schemas/*.schema.ts 的 zod schema → z.infer 产出具名类型，前后端共用，0 any。
  • OpenAPI 契约：同一批 zod schema → zod-openapi（OpenAPIRegistry.register / registerPath + OpenApiGeneratorV3.generateDocument）自动生成 openapi.yaml。
  • 请求校验：route handler 用同一 schema schema.parse(raw)。
  • 改字段链路：改 packages/shared/src/schemas/x.schema.ts 一处 → 重新生成 openapi 契约 → 前端重新生成 TS 类型 → route handler 校验自动跟随。类型、契约、校验三者永不失同步。

八、AI 扩展位（二期预留，本期不实现）

  • apps/server/src/services/ai/providers/：AiProvider 接口 + NoopProvider 空实现。
  • Question.aiExplanation / aiConfidence、ShenLunEssay.aiFeedback 字段已在 zod schema 预留。
  • AppSettings.aiEnabled（恒 false），/api/v1/ai/* 本期不挂路由，返回 50303。

九、Phase 2 端到端验证步骤

  1. pnpm install → 核对版本与锚定表一致。
  2. pnpm --filter <server> build 通过（strict + 无 any）。
  3. pnpm --filter <server> dev → curl /api/v1/settings 返回 {code:0,data:{...}}。
  4. 核心闭环：POST /questions → 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 行。