API Contracts

API 契约

本文档按当前 server 路由实现和 shared/api 调用封装整理。除特别说明外，接口前缀为 /api/v1，请求/响应使用 kotlinx.serialization JSON。

认证模型

• 客户端通过 Bearer access token 调用受保护接口。
• access token 过期后，ApiClient 会用 /api/v1/auth/refresh 自动换新 token。
• JWT 不是唯一会话凭据：服务端还必须能从 Redis 恢复用户的上游 Cookie、会话元数据和客户端缓存。
• /api/v1/auth/status 和 /api/v1/auth/logout 虽然不在 Ktor authenticate {} 块内注册，但路由内部会读取并校验 Authorization 头。

匿名接口

方法	路径	说明
POST	/api/v1/auth/preload	预加载登录状态，Body: LoginPreloadRequest(clientId)
POST	/api/v1/auth/login	CAS/SSO 登录，Body: LoginRequest(username, password, captcha?, execution?, clientId)
POST	/api/v1/auth/login-stats	上报登录成功模式与连接模式，Body: LoginStatsReportRequest(username, successMode, connectionMode)
POST	/api/v1/auth/refresh	refresh token 换新 token 对，Body: TokenRefreshRequest(refreshToken)
GET	/api/v1/auth/captcha/{captchaId}	获取验证码图片
GET	/api/v1/app/version	客户端版本检查，Query: clientVersion

/api/v1/app/version 返回 AppVersionCheckResponse：

字段	说明
latestVersion	服务端认为的最新版本；未知时可能等于当前服务端版本或 unknown
status	UP_TO_DATE、UPDATE_AVAILABLE、UNKNOWN_LATEST_VERSION
updateAvailable	是否应提示客户端更新
downloadUrl	下载入口
releaseNotes	可选更新说明
serverVersion	兼容旧客户端的服务端版本字段
aligned	兼容旧客户端的“客户端是否与服务端版本一致”字段

UpdateService.checkUpdate() 只在 status == UPDATE_AVAILABLE 时返回响应；无更新、服务端不可达或响应异常时返回 null。

需有效会话的接口

认证与用户

方法	路径	说明
GET	/api/v1/auth/status	查询会话状态
POST	/api/v1/auth/logout	注销并失效服务端会话，尝试退出上游 SSO
GET	/api/v1/user/info	获取用户资料

课表、考试、成绩

方法	路径	参数
GET	/api/v1/schedule/terms	-
GET	/api/v1/schedule/weeks	termCode
GET	/api/v1/schedule/week	termCode, week
GET	/api/v1/schedule/today	-
GET	/api/v1/exam/list	termCode
GET	/api/v1/grade/list	termCode，返回 GradeData

BYKC

方法	路径	参数/说明
GET	/api/v1/bykc/profile	-
GET	/api/v1/bykc/courses	page, size, all
GET	/api/v1/bykc/courses/{courseId}	-
GET	/api/v1/bykc/courses/chosen	-
GET	/api/v1/bykc/statistics	-
POST	/api/v1/bykc/courses/{courseId}/select	报名
DELETE	/api/v1/bykc/courses/{courseId}/select	退选
POST	/api/v1/bykc/courses/{courseId}/sign	Body: BykcSignRequest

CGYY

方法	路径	参数/说明
GET	/api/v1/cgyy/sites	-
GET	/api/v1/cgyy/purpose-types	-
GET	/api/v1/cgyy/day-info	venueSiteId, date
POST	/api/v1/cgyy/reservations	Body: CgyyReservationSubmitRequest
GET	/api/v1/cgyy/orders	page, size
GET	/api/v1/cgyy/orders/{orderId}	-
POST	/api/v1/cgyy/orders/{orderId}/cancel	-
GET	/api/v1/cgyy/orders/lock-code	-

SPOC 与 Judge

域	方法	路径	参数/说明
SPOC	GET	/api/v1/spoc/assignments	作业摘要列表
SPOC	GET	/api/v1/spoc/assignments/{assignmentId}	作业详情
Judge	GET	/api/v1/judge/assignments	includeExpired，默认由客户端控制；返回 JudgeAssignmentsResponse
Judge	GET	/api/v1/judge/courses/{courseId}/assignments/{assignmentId}	单个作业详情
Judge	POST	/api/v1/judge/assignment-details	Body: JudgeAssignmentDetailsRequest(keys)，批量详情

Judge 列表是轻量摘要接口；大账号不要在初始列表请求中强制拉取所有详情。客户端列表先展示摘要，再按需加载详情或批量补充详情。

其他业务

域	方法	路径	参数/说明
Signin	GET	/api/v1/signin/today	-
Signin	POST	/api/v1/signin/do	Query: courseId
Classroom	GET	/api/v1/classroom/query	xqid, date
Evaluation	GET	/api/v1/evaluation/list	-
Evaluation	POST	/api/v1/evaluation/submit	Body: List<EvaluationCourse>
YGDK	GET	/api/v1/ygdk/overview	-
YGDK	GET	/api/v1/ygdk/records	page, size
YGDK	POST	/api/v1/ygdk/records	multipart，可含照片；无照片时服务端/直连实现会按业务逻辑补默认图

运维接口

方法	路径	说明
GET	/metrics	Prometheus 指标
GET	/health/live	进程存活
GET	/health/ready	Redis 就绪检查；Redis 不可用时返回 503
GET	/	简单问候文本，用于快速确认服务响应

错误响应

统一错误结构：

{
  "error": {
    "code": "invalid_request",
    "message": "..."
  }
}

常见错误码：

分类	错误码
通用/认证	invalid_request, invalid_token, invalid_refresh_token, invalid_credentials, unauthenticated, auth_upstream_timeout, unsupported_portal, missing_client_version, internal_server_error
课表/考试/成绩	schedule_error, exam_error, grade_error
SPOC/Judge	spoc_auth_failed, spoc_error, judge_auth_failed, judge_not_found, judge_error, judge_timeout
其他业务	classroom_query_failed, evaluation_error, ygdk_error, ygdk_timeout

客户端用户可读文案主要由 shared/src/commonMain/kotlin/cn/edu/ubaa/api/NetworkUtils.kt 映射。新增服务端错误码时，应同步补 shared 映射和测试。

与 shared 的映射

shared/src/commonMain/kotlin/cn/edu/ubaa/api 已覆盖当前主要域：

• 认证/用户：AuthApi.kt, TokenStore.kt, CredentialStore.kt, ConnectionRuntime.kt
• 教务：ScheduleApi.kt, GradeApi.kt, ClassroomApi.kt
• 业务功能：BykcApi.kt, CgyyApi.kt, SigninApi.kt, EvaluationService.kt, SpocApi.kt, JudgeApi.kt, YgdkApi.kt
• 版本与网络：UpdateService.kt, NetworkUtils.kt, ApiClient.kt

每个业务域通常有 Relay*Backend 和 Local*Backend 两套实现：SERVER_RELAY 走服务端接口，DIRECT / WEBVPN 在支持的平台上直接访问北航上游。