Coding Standards

编码规范

1. 先遵循自动化格式

仓库已配置 Spotless + ktfmt，风格以工具结果为准：

./gradlew spotlessApply
./gradlew spotlessCheck

不要手写与 ktfmt 冲突的格式规则。

2. 模块边界约定

• 跨端 DTO / API 封装 -> shared
• 跨平台 UI 与状态 -> composeApp
• 平台壳层（Android/iOS）保持轻量，不承载共享业务逻辑
• 网关编排与上游适配 -> server

3. 接口与错误处理约定

• 服务端路由优先使用统一错误返回 respondError(...)
• 不要静默吞掉异常；要明确映射错误码
• 上游调用需要超时预算时，复用 withUpstreamDeadline(...)

4. 认证相关约定

• 认证模型是 “JWT + refresh token + 服务端会话”，不要按纯无状态 JWT 假设编码。
• 涉及会话恢复/失效时，优先复用 SessionManager 现有能力。

5. 注释与可读性

• 公共接口/复杂逻辑优先写 KDoc。
• 注释应解释职责和约束，不要复述语句字面意思。
• 注释语言保持与所在文件现有风格一致（本仓库以中文为主，部分文件英文可保留一致性）。

6. 变更一致性

改动以下内容时，必须联动检查三层：

1. shared（DTO/API）
2. server（路由/实现）
3. composeApp（消费逻辑）

7. 测试最低要求

• 新增后端接口：补 route/service 测试
• 新增 shared API：补 commonTest（MockEngine）
• 关键状态改动：补 compose ViewModel 测试