3.8 KiB
CLAUDE.md — 恭学教育
项目定位
恭学教育是基于 RuoYi-Vue-Pro 的教育 SaaS 平台，后端技术栈为 Spring Boot 4、MyBatis-Plus、PostgreSQL、Redis。
主要开发入口：
yudao-module-education/：教育业务模块yudao-server/：应用启动模块，默认端口48080sql/postgresql/：PostgreSQL 初始化与历史 SQLtools/education-student-harness/：学生端 Playwright E2E 测试
分支、工作区状态、运行中的容器和临时任务属于动态信息；执行任务时从 Git、配置文件和运行环境读取，不在本文档固化。
工作方式
Serena 优先
编码任务开始前调用 Serena initial_instructions 并激活项目。优先使用 Serena 完成符号检索、引用分析和结构化编辑；Serena 不可用或不适合时再使用通用文件与命令工具。互不依赖的查询或编辑应批量调用。
遵循现有代码
- 修改前检查工作区，保留用户已有的未提交修改。
- 代码风格、命名、注释密度和分层方式与相邻代码保持一致。
- 优先复用框架现有能力，避免为单一场景建立平行抽象。
- 只修改当前任务需要的文件；发现相邻问题时先判断是否影响本次交付。
Gitea 与仓库操作
项目托管在自建 Gitea。远程仓库、Issue 和 Pull Request 操作统一使用 tea CLI，不使用 GitHub CLI（gh）。执行创建或查看 Pull Request 等操作前，从当前 Git remote 与 tea 登录配置读取仓库和实例信息。
Skills
项目级 Skills 位于 .claude/skills/，已有规范索引见 .claude/skills/index.yaml。
数据库结构、索引、约束、数据回填、必要种子数据、基线或 Flyway 配置发生变化时，使用项目 Skill：
/flyway-postgresql
Flyway 的版本分配、接管策略、验证步骤以 .claude/skills/flyway-postgresql/SKILL.md 为唯一事实来源。
架构约束
Education 模块
yudao.education.catalog-mode控制目录数据源：SCALAR_READ：通过ScalarCatalogProvider访问 HTTP 数据源。JAVA_READ：通过JavaCatalogProvider直连 PostgreSQL。
QuestionCatalogServiceImpl返回前端前必须剥离答案与解析等敏感字段。- 题目不可见或数据源不可用时采用 fail-closed，不进行静默降级。
- 多租户业务 DO 继承
TenantBaseDO，由 MyBatis-Plus 注入tenant_id。
PostgreSQL
项目运行数据库为 PostgreSQL。Java 注解 SQL、MyBatis XML、测试 SQL 和运行配置均使用 PostgreSQL 方言。
- 主键：
BIGINT GENERATED BY DEFAULT AS IDENTITY。 - 时间：
TIMESTAMP，默认当前时间使用CURRENT_TIMESTAMP。 - 布尔：
BOOLEAN，按需使用NOT NULL DEFAULT false。 - 幂等插入：
ON CONFLICT ... DO NOTHING。 - Upsert：
ON CONFLICT (...) DO UPDATE SET ... EXCLUDED.column。 - 空值兜底：
COALESCE；时间格式化：TO_CHAR；日期字段提取：EXTRACT。 - 有界删除使用有序、限量的主键子查询或 CTE。
- DO 主键遵循项目既有的
@TableId、@KeySequence("{table}_seq")模式。
Flyway
运行时 migration 放在所属模块：
<module>/src/main/resources/db/migration/<module>/
已在共享环境执行的 migration 是不可变发布历史。数据库修复通过更高版本的向前 migration 完成，生产环境保持 clean-disabled: true。
验证
按改动范围执行最小充分验证。后端主链路至少运行：
git diff --check
mvn -pl yudao-server -am -DskipTests clean compile
涉及行为变化时运行对应模块的聚焦测试；涉及数据库 migration 时还要确认脚本被打包到模块的 target/classes/db/migration/。只有实际执行过 PostgreSQL migration，才能报告数据库迁移成功；否则明确说明仅完成静态检查或编译验证。