Home

UBAA 开发 Wiki

这套文档面向 第一次进入仓库的开发者，目标是让你在阅读后可以直接开始改代码、跑服务、提 PR。

5 分钟上手

1. 复制配置：cp .env.sample .env
2. 本地联调时把 .env 中的 API_ENDPOINT 改为 http://127.0.0.1:5432
3. 启动 Redis，并确认 /health/ready 可用
4. 启动后端：./gradlew :server:run -Pdevelopment（Windows 用 gradlew.bat :server:run -Pdevelopment）
5. 启动桌面客户端：./gradlew :composeApp:run
6. 进入功能代码：
   • 客户端 UI：composeApp/src/commonMain/kotlin/cn/edu/ubaa
   • 共享契约/API/直连逻辑：shared/src/commonMain/kotlin/cn/edu/ubaa
   • 服务端：server/src/main/kotlin/cn/edu/ubaa

当前认证与会话主路径依赖 Redis（默认 redis://localhost:6379）。API_ENDPOINT 是构建时注入，改完要重建客户端。

推荐阅读路径

• 先跑起来： 快速开始 -> 配置说明
• 理解全局： 架构总览
• 按模块开发：
  • shared 模块指南
  • composeApp 模块指南
  • server 模块指南
• 接口与质量：
  • API 契约
  • 测试与质量
  • 编码规范
• 发布部署与排障：
  • 发布与部署
  • 常见问题

新功能开发最短路径

1. 在 shared 定义/调整 DTO、API 封装、Relay/Local backend。
2. 在 server 新增或调整路由、服务实现、上游客户端、指标和清理逻辑。
3. 在 composeApp 增加 ViewModel + Screen + 导航入口，必要时接入首页聚合。
4. 执行最小验证：./gradlew :server:test :shared:jvmTest :composeApp:jvmTest
5. 格式化与检查：./gradlew spotlessApply lint
6. 同步更新 API、模块、配置或排障文档。