Quiz DSL 架构指南 (Architecture Guide)

欢迎来到 @quizerjs/dsl 核心规范库。作为 Quiz Architect，我将引导你理解本项目的灵魂——结构化评估语言 (Quiz DSL)。

0. 设计哲学

在 Quizer 体系中，数据高于一切。我们将评估逻辑抽象为平台无关的 JSON 模型，确保同一份测验可以在 Web、移动端、甚至命令行中以一致的逻辑运行。

• 模型驱动：UI 只是状态的投影，DSL 才是状态的源头。
• 类型安全：借助 TypeScript，我们在编译期捕获 90% 的模型错误。
• 严谨验证：运行时 Schema 验证确保数据的完整性。

1. 核心模型 (Core Models)

Quiz DSL (测验定义)

定义了一个测验的静态结构，包括标题、描述、设置、章节和题目。

import { QuizDSL } from '@quizerjs/dsl';

const myQuiz: QuizDSL = {
  version: '1.0.0',
  quiz: {
    id: 'quiz-001',
    title: '基础地理测试',
    questions: [
      {
        id: 'q-1',
        type: 'single_choice',
        text: '珠穆朗玛峰在哪个洲？',
        options: [
          { id: 'o1', text: '亚洲', isCorrect: true },
          { id: 'o2', text: '欧洲', isCorrect: false },
        ],
      },
    ],
  },
};

Result DSL (结果模型)

捕获一次测验旅程的完整数据，包括原始测验定义、用户答案、得分情况以及元数据。

• Scoring: 包含总分、百分比、通过状态。
• QuestionResults: 每道题的详细表现（耗时、正误、答案映射）。

2. API 使用手册

验证 (Validation)

在将 DSL 传递给支付或存储模块前，务必验证其合法性。

import { validateQuizDSL } from '@quizerjs/dsl';

const { valid, errors } = validateQuizDSL(myQuiz);
if (!valid) {
  console.error('DSL 格式错误:', errors);
}

解析与序列化 (Parsing & Serialization)

提供容错性解析和标准化序列化。

import { parseQuizDSL, serializeQuizDSL } from '@quizerjs/dsl';

// 从字符串解析
const parseResult = parseQuizDSL(jsonString);

// 序列化为标准化 JSON 字符串
const { data, success } = serializeQuizDSL(myQuiz, { indent: 2 });

3. 扩展 DSL

如果你需要添加新的题目类型或元数据字段：

1. 修改 types.ts: 添加新的 Question 子类型。
2. 更新 QuestionTypes: 在常量中注册新类型。
3. 更新 validator.ts: 为新类型编写验证逻辑。
4. 更新 schema.json: 确保 JSON Schema 同步更新，以支持非 TS 端的验证。

"一个定义良好的元模型是所有交互的灵魂。" —— Quentin "Quiz" Masterson