#贡献指南

#代码规范

#语言

• GraalVM JDK 21 源码/目标
• 使用现代 Java 特性（记录类、密封类、模式匹配等）
• 公开标识符和 REST 契约使用英文
• 代码注释可以使用英文或中文

#Lombok

• DTO 和实体使用 @Data、@Getter、@Setter
• 例外：带有 @Id 且通过 CrudRepository.update() 操作的实体必须使用显式 getter/setter
• 使用 @Slf4j 进行日志记录

#控制器

• 使用 @Controller("/_matrix/...") 注解
• 大多数端点使用 @Secured(SecurityRule.IS_ANONYMOUS) 以确保 Matrix 兼容性
• 仅管理员端点使用 @Secured(SecurityRule.IS_AUTHENTICATED)
• 通过 BaseException 和 BaseErrorEnum 返回正确的 Matrix 错误响应
• 避免返回没有 body 的裸 HttpResponse.ok() 或 HttpResponse.serverError()

#服务

• 优先使用构造函数注入而非字段注入
• 业务逻辑错误通过 BaseException 抛出（由 MatrixExceptionHandler 处理）
• 使用 @Inject 进行依赖注入

#仓储

• 扩展 Micronaut Data 接口
• 使用 @JdbcRepository(dialect = Dialect.H2) 注解
• 遵循 Micronaut Data 命名约定进行查询推导

#实体

• 使用 @MappedEntity 和显式表名
• 主键使用 @Id
• 避免在通过 CrudRepository 进行 CRUD 操作的实体上使用 Lombok @Getter/@Setter

#错误处理

• 在 BaseErrorEnum 中定义错误码
• 业务逻辑错误通过 BaseException 抛出
• MatrixExceptionHandler 将异常转换为 Matrix 错误格式

#提交消息

遵循约定式提交：

feat(p5): implement federation core compliance (FED-01~06)
fix(e2ee): add event_id to to-device events in sync response
docs: update STATUS.md with verification results
test: add P5 federation integration tests

#Pull Request 流程

1. 从 main 创建功能分支
2. 实现更改并添加测试
3. 运行 mvn test — 所有测试必须通过
4. 如果添加了新功能，更新 docs/plan/STATUS.md
5. 提交 PR 并清晰描述更改

#本地运行

mvn compile        # 编译
mvn test           # 运行测试
mvn exec:java      # 启动服务器

#项目状态

所有阶段 P0–P5 已完成。详见路线图。