Development Workflow

开发工作流

常用命令（按模块）

macOS/Linux 用 ./gradlew，Windows 用 gradlew.bat。

本地运行

目标	命令
后端	:server:run
后端（开发模式）	:server:run -Pdevelopment
桌面客户端	:composeApp:run
Web (Wasm)	:composeApp:wasmJsBrowserDevelopmentRun
Web (JS)	:composeApp:jsBrowserDevelopmentRun
Android 安装 Debug	:androidApp:installDebug

本地全栈联调推荐：

./gradlew :server:run -Pdevelopment
./gradlew :composeApp:wasmJsBrowserDevelopmentRun

Windows:

.\gradlew.bat :server:run -Pdevelopment
.\gradlew.bat :composeApp:wasmJsBrowserDevelopmentRun

同时确认 .env：

API_ENDPOINT=http://127.0.0.1:5432
CORS_ALLOWED_ORIGINS=http://localhost:8080

构建

目标	命令
后端	:server:build
shared	:shared:build
composeApp	:composeApp:build
Android Debug APK	:androidApp:assembleDebug
Server Fat JAR	:server:buildFatJar
Web Wasm 发布目录	:composeApp:wasmJsBrowserDistribution
Web JS 发布目录	:composeApp:jsBrowserDistribution

测试与质量

目标	命令
后端测试	:server:test
shared 测试	:shared:jvmTest
composeApp 测试	:composeApp:jvmTest
推荐组合	:server:test :shared:jvmTest :composeApp:jvmTest
格式检查	spotlessCheck
自动格式化	spotlessApply
Android Lint	lint
覆盖率报告	koverHtmlReport

新功能开发（端到端）

1. 先改契约（shared）
   • 新增/调整 DTO（model/dto）
   • 新增 API interface
   • 同步 Relay backend 和必要的 Local backend
2. 再改服务端（server）
   • 新增路由（*Routes.kt）
   • 新增服务逻辑（*Service.kt）和上游客户端（*Client.kt）
   • 复用统一错误返回与指标埋点模式
   • 缓存型服务要接入 Application.kt 清理和 gauge
3. 最后接 UI（composeApp）
   • ViewModel 组织状态与调用 API
   • Screen 渲染状态
   • MainAppScreen 挂导航入口、顶栏操作和必要的首页聚合
4. 补测试
   • shared API/DTO/Local backend 测试
   • server 路由/服务测试
   • composeApp ViewModel/展示规则测试
5. 同步文档
   • API、模块说明、配置、运行方式有变化时必须更新 docs

调试建议

• 登录/会话问题先看 server/logs/server.log 与 /health/ready。
• 多节点会话问题优先关注 Redis 连接、JWT_SECRET 和 INSTANCE_ID。
• 客户端地址错乱优先检查 BuildKonfig.API_ENDPOINT 是否重新构建生效。
• Web/Wasm 自动化测试如果 locator 点击不生效，优先怀疑 Compose canvas/hit-testing，尝试坐标点击。
• BYKC 上游结构变化可临时打开 BYKC_DEBUG_RAW_API_LOG 或 BYKC_DEBUG_PARSED_COURSE_LOG，排障结束后关闭。

提交前清单

1. 执行与改动相关的最小测试。
2. 对跨层改动执行推荐组合：./gradlew :server:test :shared:jvmTest :composeApp:jvmTest。
3. 执行 spotlessApply 后确认无额外格式噪音。
4. 检查 docs/API-Contracts.md、模块文档和配置文档是否需要同步。
5. 在脏工作区中只 stage 本次相关文件，避免混入无关改动。