架构与开发

技术栈

• Next.js 15 + React 19 + TypeScript，Tailwind CSS 设计令牌，motion 动效。
• Neon Postgres（Vercel 集成）存储用户数据；bcrypt + JWT Cookie 认证。
• CodeMirror 6 编辑器；three.js r186 本地托管，供沙箱通过 import map 加载。
• 部署在 Vercel，GitHub 推送 main 分支自动部署。

目录

• src/core：纯逻辑（主题、快捷键、i18n、markdown、高亮、搜索、用户数据校验），没有 DOM 依赖，全部单元测试覆盖。
• src/server：数据库、认证、与框架无关的请求处理器（Request → Response），用 PGlite（WASM 版 Postgres）做集成测试。
• src/client：数据源抽象（访客 localStorage / 账号 API 同一接口）、全局状态、快捷键分发。
• src/components：设计系统原语与页面组件。
• examples/<路径>/<slug>：每节课一个文件夹（meta.json + main.js）。
• public/sandbox.html：代码运行沙箱。

TDD 与质量

npm test 运行全部测试，包括：主题对比度、快捷键解析与冲突检测、中英文案键完全一致、组件中禁止硬编码中文、每节课的元数据与代码校验、API 与用户隔离测试。新增功能先写测试。

新增一节课

1. 在 examples/<路径>/ 下新建文件夹，写 meta.json 和 main.js。
2. npm test 校验格式、双语与导入规则。
3. node scripts/serve-dev.mjs 后用 python3 scripts/check_example.py <路径>/<slug> 在无头浏览器里运行并截图。

详细约定见仓库中的 docs/AUTHORING-EXAMPLES.md。