课堂积分系统是给任课老师使用的课堂正向激励工具。老师在课堂中点击学生即可奖励 5 积分，学生积分同步给班级加分，学生和班级都可以按照可配置兑换项消耗可用积分。
- 产品事实：产品定位、用户、约束和长期原则。
- 开发文档索引：建议阅读顺序和第一版硬约束。
- 项目当前状态：下次继续开发前先读的交接文档。
- 产品需求说明：第一版范围、用户场景和业务规则。
- 技术架构：技术栈、目录结构、权限、事务和部署策略。
- 部署指南：Vercel + Neon Postgres 的上线步骤。
- 数据模型：表结构、约束、索引和账本口径。
- API 设计：第一版 server API 契约。
- UI 与 SEO 规范：公开站、登录后应用、展示模式和 PWA 要求。
- 实施计划：阶段拆分和最小测试集合。
- 验收清单：开发完成后的逐项验收。
- 决策记录：已确认的产品和技术决策。
- 本地开发使用 PGlite，生产部署使用 Neon Postgres，数据库访问通过 Drizzle ORM 封装。
- 技术栈使用 Nuxt 4、Nuxt UI 和 Tailwind CSS。
- 教师账号密码登录，学生不登录。
- 登录后默认进入课堂页，课堂页移动端优先。
- 学生课堂奖励固定为 5 积分。
- 学生奖励同步给班级加 5 积分。
- 兑换扣可用积分，不扣累计积分。
- 按学期归档，旧学期只读。
- 归档班级不再出现在默认班级列表和学生兑换流程中。
- 积分以
ledger_entries汇总为准，不要只维护一个可覆盖余额字段。 - 所有写操作都要记录
teacher_id。 - 所有课堂奖励、兑换、撤销和作废都要写事件和账本。
- 旧学期禁止写操作。
- 已产生历史记录的数据不硬删除。
- 安装依赖：
npm install - 复制环境变量：
cp .env.example .env - 初始化数据库：
npm run db:setup - 启动开发服务器：
npm run dev
默认本地数据库为 .data/classroom-points.pglite。测试环境使用内存数据库，不会写入本地开发数据。
默认本地 seed 账号为 admin，密码为 admin123456。正式使用前请通过 .env 修改 SEED_ADMIN_PASSWORD 并重新执行 seed。
部署前执行：
npm run deploy:check该命令会依次运行单元测试、覆盖率、类型检查和生产构建。完整上线步骤见 部署指南。