Module Shared

shared 模块指南

shared 是客户端与服务端的契约层，也是客户端基础设施层。composeApp 和 server 都依赖它；后端业务实现仍放在 server，但客户端的服务端中转、直连、WebVPN 分发都从这一层发起。

这一层负责什么

• 定义前后端共用 DTO
• 封装客户端 HTTP 调用和错误映射
• 根据连接模式选择 Relay*Backend 或 Local*Backend
• 管理 token、clientId、本地直连会话、Cookie、记住密码、功能筛选和表单草稿
• 提供更新检查、登录统计上报和通用网络错误文案
• 给 UI ViewModel 提供稳定的 Result<T> 风格 API

连接模式分发

核心文件是 api/ConnectionRuntime.kt 和 api/ApiFactory.kt。

模式	backend	说明
SERVER_RELAY	Relay*Backend	调用 UBAA 服务端 /api/v1/*
DIRECT	Local*Backend	直接访问北航上游
WEBVPN	Local*Backend + WebVPN URL 转写	通过北航 WebVPN 访问上游

平台可用性由 supportsLocalConnectionModes() 决定：Android、iOS、JVM 支持 DIRECT / WEBVPN；JS/Wasm 只支持 SERVER_RELAY。

切换连接模式会调用 ConnectionRuntime.resetSession()，清理 AuthTokensStore、ClientIdStore、LocalAuthSessionStore、LocalCookieStore、共享 ApiClient、本地上游 client、Judge 缓存、学期缓存，并关闭自动登录。开发时不要假设不同连接模式共享登录态。

目录清单

基础元信息

文件	作用
AppInfo.kt	暴露 BuildKonfig.VERSION，给 UI 和版本页使用
Greeting.kt	跨平台示例问候语，服务端根路径 / 会直接返回它
Platform.kt	expect/actual 平台名称与本地连接模式能力

API 基础设施

文件	作用
ApiClient.kt	统一 HttpClient，默认 BuildKonfig.API_ENDPOINT，Bearer token 自动刷新
ApiFactory.kt	连接模式到各业务 backend 的统一分发
ConnectionRuntime.kt	连接模式选择、持久化、切换和会话清理
NetworkUtils.kt	safeApiCall、ApiCallException、错误码到用户文案映射
ResettableSharedInstance.kt	可重置共享实例辅助
LoginStatsReporter.kt	登录成功模式和连接模式上报
UpdateService.kt	调用 /api/v1/app/version 做版本检查

认证与存储

文件	作用
AuthApi.kt	登录、预加载、状态、注销、用户信息调用封装
TokenStore.kt	AuthTokensStore、ClientIdStore，按连接模式分 scope 并兼容 legacy key
CredentialStore.kt	记住密码 / 自动登录开关与凭据存储
LocalConnectionAuth.kt	直连/WebVPN 登录、预加载、状态和用户信息逻辑
LocalAuthSessionStore / LocalCookieStore	位于 LocalConnectionAuth.kt 中，本地保存直连/WebVPN 上游会话与 Cookie
LocalWebVpnSupport.kt	WebVPN URL 转写与支持逻辑

业务 API

领域	Relay/API 文件	Local 文件
聚合旧门面	ApiService.kt	-
课表/考试	ScheduleApi.kt	LocalScheduleApi.kt
成绩	GradeApi.kt	LocalGradeApi.kt
博雅课程	BykcApi.kt, BykcCourseFilterStore.kt	LocalBykcApi.kt, LocalBykcCrypto.kt
研讨室预约	CgyyApi.kt, CgyyReservationFormStore.kt	LocalCgyyApi.kt, LocalCgyySigner.kt, LocalCgyyCaptchaSupport.kt
空教室	ClassroomApi.kt	LocalClassroomApi.kt
课堂签到	SigninApi.kt	LocalSigninApi.kt
SPOC	SpocApi.kt	LocalSpocApi.kt, LocalSpocSupport.kt
Judge/希冀	JudgeApi.kt	LocalJudgeApi.kt
评教	EvaluationService.kt	LocalEvaluationService.kt
阳光打卡	YgdkApi.kt	LocalYgdkApi.kt

平台能力

文件	作用
PlatformAesCbcNoPadding.kt, PlatformAesCfbNoPadding.kt, PlatformAesEcbPkcs5Padding.kt	各业务上游加解密所需 AES 能力
PlatformRsaPkcs1Encrypt.kt	BYKC 等上游加密请求
PlatformMd5Hex.kt	签名/摘要辅助
PlatformImageRasterDecoder.kt	CGYY 验证码等图片处理辅助

DTO 与仓储

文件	领域
model/dto/Auth.kt	登录、预加载、验证码、token 刷新、登录统计
model/dto/UserInfo.kt	用户个人信息、状态响应
model/dto/Schedule.kt	学期、周次、课表、今日课表
model/dto/Exam.kt	考试安排
model/dto/Grade.kt	成绩列表、学分、均分等
model/dto/Bykc.kt, BykcSerialization.kt	博雅课程、选课、签到、统计
model/dto/Cgyy.kt	研讨室场地、时段、订单、锁码、提交
model/dto/Classroom.kt	空教室查询
model/dto/Signin.kt	课堂签到列表与结果
model/dto/Spoc.kt	SPOC 作业摘要与详情
model/dto/Judge.kt	希冀课程、作业摘要、详情、批量详情
model/dto/Ygdk.kt	阳光打卡概览、记录、提交
model/evaluation/EvaluationModel.kt	评教任务、课程、进度、结果
repository/TermRepository.kt	学期列表内存缓存，避免重复拉取

关键运行时行为

• shared/build.gradle.kts 在构建时注入 BuildKonfig.API_ENDPOINT，无 .env 和环境变量时默认 https://ubaa.mofrp.top。
• .env.sample 当前给出的线上示例为 https://ubaa.mofrp.top:2021；本地联调要改为本地服务端地址并重建客户端。
• ApiClient 通过 Bearer 认证插件自动刷新 token，刷新接口是 /api/v1/auth/refresh。
• safeApiCall() 会把 401、422、网络超时和业务错误码统一转成 UI 可直接消费的异常/错误文本。
• AuthTokensStore 和 ClientIdStore 是连接模式隔离的；CredentialStore 是全局记住密码/自动登录设置。
• BykcCourseFilterStore 按用户保存课程筛选条件；CgyyReservationFormStore 保存研讨室预约表单草稿。
• TermRepository 运行期缓存学期列表；强刷用 forceRefresh = true。

业务实现提示

• Grade 直连访问 https://app.buaa.edu.cn/buaascore/wap/default/index，从 termCode 推导 year 和 xq，返回统一 GradeData。旧 BYXT 成绩 DTO 仍保留，但当前主路径是 BUAA Score。
• Judge 直连通过 judge.buaa.edu.cn 的课程列表、作业列表和详情链路聚合；列表支持 includeExpired，详情可用 JudgeAssignmentDetailKeyDto 批量补齐。
• SPOC/Judge 类作业列表不要在初始请求中强制拉取所有详情。大账号下应先展示摘要，再按需或后台渐进加载详情。
• 新增错误码必须同步 NetworkUtils.userFacingMessageForCode() 和相关测试，否则直连和中转模式的 UI 文案会分叉。

改动契约时的顺序

1. 先改 model/dto/
2. 再改 api/ 中的接口、Relay backend 和必要的 Local backend
3. 再同步 server 路由和返回体
4. 最后改 composeApp 的 ViewModel / Screen / 导航入口
5. 补 shared、server、composeApp 对应测试