89 lines
3.8 KiB
Markdown
89 lines
3.8 KiB
Markdown
# 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，才能报告数据库迁移成功；否则明确说明仅完成静态检查或编译验证。
|