ManyCourse 教务系统 API 接入与调用指南

1
data class School(
2
    val id: String,        // 稳定标识，持久化主键，全小写英文，如 "gzus"
3
    val name: String,      // 下拉里显示的中文全称
4
    val baseUrl: String,   // 根地址，必须 https、不带结尾斜杠
5
    val system: String = "", // 教务系统类型备注，只用于排查
6
) {
7
    val host: String       // 下拉副标题用，如 "jwxt.gzus.edu.cn"
8
}

1
interface SchoolApi {
2
    val school: School
3

4
    /** 登录参数是否已填好；预写的空壳返回 false */
5
    val configured: Boolean get() = true
6

7
    /** 异步登录；回调在工作线程，保证只回调一次 */
8
    fun login(account: String, password: String, callback: (LoginResult) -> Unit)
9
}

1
prepare()  ──▶  表单 POST { usernameField=账号, passwordField=encodePassword(密码), ...额外字段 }  ──▶  judge()

1
fun getAsync(url: String, headers: Map<String,String> = emptyMap(),
2
             callback: (Result<HttpResponse>) -> Unit)
3

4
fun postFormAsync(url: String, form: Map<String,String>, headers: Map<String,String> = emptyMap(),
5
                  callback: (Result<HttpResponse>) -> Unit)

1
fun getResponse(url: String, headers: Map<String,String> = emptyMap()): HttpResponse
2
fun postForm(url: String, form: Map<String,String>, headers: Map<String,String> = emptyMap()): HttpResponse

1
fun cookieValue(url: String, name: String): String?  // 取某个 Cookie 值（回填 csrftoken 时用）
2
fun cookiesFor(url: String): List<Cookie>
3
fun clearCookies()                                    // 换学校 / 退出登录

1
data class HttpResponse(
2
    val code: Int,
3
    val body: String,
4
    val location: String?,   // 重定向目标：登录成功的典型信号
5
    val finalUrl: String,    // 跟随重定向后的最终地址
6
) { val isRedirect: Boolean }

1
/** 裸 RSA（无填充）加密，返回小写十六进制 */
2
RsaCipher.encryptToHex(plain: String, modulusBase64: String, exponentBase64: String): String

1
private val apis: List<SchoolApi> = listOf(
2
    GzusApi(),
3
    NhjcxyApi(),
4
    XxxApi(),        // ← 加这里
5
)

1
class GzusApi : WebLoginSchoolApi() {
2

3
    private val root = "${school.baseUrl}/jwglxt"
4

5
    // TODO(接入): 路径与参数以抓包为准（登录后进课表页，F12 里找那条返回课表的请求）
6
    private val scheduleUrl get() = "$root/xskb/xskb_list.do?gnmkdm=N253508"
7

8
    /** 拉课表原始响应。调用前必须已经登录成功（会话在 http 里） */
9
    fun fetchScheduleRaw(callback: (Result<String>) -> Unit) {
10
        http.getAsync(scheduleUrl) { result ->
11
            callback(result.map { it.body })
12
        }
13
    }
14
}

1
val api = SchoolRegistry.apiOf(LoginSettings.selectedSchoolId.value) as? GzusApi
2

3
api?.fetchScheduleRaw { result ->
4
    // 回调在工作线程 → 切主线程再动 CourseRepository / View（见 §4.4）
5
    Handler(Looper.getMainLooper()).post {
6
        result.fold(
7
            onSuccess = { html -> /* 解析后写进 CourseRepository，见 §4.3 */ },
8
            onFailure = { showError(it.readableMessage()) },
9
        )
10
    }
11
}

1
interface SchoolApi {
2
    // ...
3
    /** 拉课表。默认未接入 —— 新学校不写这个方法也能编译 */
4
    fun fetchCourses(callback: (Result<List<Course>>) -> Unit) {
5
        callback(Result.failure(UnsupportedOperationException("${school.name} 尚未接入课表接口")))
6
    }
7
}

1
fun applyCourses(list: List<Course>) {
2
    CourseRepository.courses.clear()
3
    list.forEach {
4
        CourseRepository.add(
5
            name = it.name,
6
            teacher = it.teacher,
7
            room = it.room,
8
            weekday = it.weekday,
9
            startPeriod = it.startPeriod,
10
            periodCount = it.periodCount,
11
        )
12
    }
13
}

1
runOnUiThread { ... }                       // Activity 里最省事
2
view.post { ... }                           // 只有 View 引用时
3
Handler(Looper.getMainLooper()).post { }    // 非 Activity 上下文（仓库/工具类）

1
onFailure = { showError(it.readableMessage()) }