# CLAUDE.md — 恭学教育

## 项目定位

恭学教育是基于 RuoYi-Vue-Pro 的教育 SaaS 平台，后端技术栈为 Spring Boot 4、MyBatis-Plus、PostgreSQL、Redis。

主要开发入口：

- `yudao-module-education/`：教育业务模块
- `yudao-server/`：应用启动模块，默认端口 `48080`
- `sql/postgresql/`：PostgreSQL 初始化与历史 SQL
- `tools/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：

```text
/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 放在所属模块：

```text
<module>/src/main/resources/db/migration/<module>/
```

已在共享环境执行的 migration 是不可变发布历史。数据库修复通过更高版本的向前 migration 完成，生产环境保持 `clean-disabled: true`。

## 验证

按改动范围执行最小充分验证。后端主链路至少运行：

```bash
git diff --check
mvn -pl yudao-server -am -DskipTests clean compile
```

涉及行为变化时运行对应模块的聚焦测试；涉及数据库 migration 时还要确认脚本被打包到模块的 `target/classes/db/migration/`。只有实际执行过 PostgreSQL migration，才能报告数据库迁移成功；否则明确说明仅完成静态检查或编译验证。