# 正方教务导入说明 星课表只内置一份正方适配脚本,不连接外部学校仓库。 脚本路径: ``` shared/src/commonMain/composeResources/files/zhengfang.js ``` 运行时通过 Compose Resources 读取: ```kotlin Res.readBytes("files/zhengfang.js").decodeToString() ``` ## 1. 用户路径 1. 我的 → 课表导入/导出 → 正方教务导入(`Destination.WebView()`)。 2. 地址栏输入正方登录 URL(或从空白页开始输入)。 3. 登录后进入 **学生课表查询**,选择学年学期并查询。 4. 点「执行导入」,选择目标课表。 5. 脚本确认对话框 → 抓取 → `saveImportedCourses` → 覆盖写入 → `notifyTaskCompletion` 回到周课表。 ## 2. 页面要求 脚本会: 1. `fetch` 当前页 HTML,内容需包含「课表查询」。 2. 读取 `#shcPDF` 的 `data-type`:`list` 或网格。 3. 列表找 `#kblist_table`,网格找 `#kbgrid_table_0`。 4. 使用 **jQuery**(`window.jQuery`)。没有 jQuery 会直接失败。 网格解析 `parserTbale()`(函数名沿用历史拼写):遍历 `#kbgrid_table_0 td.td_wrap` 下的 `.timetable_con`。 列表解析 `parserList()`:按星期 `tbody` 扫行。 能解析的字段:课程名、星期、节次区间、周次(含 `1-16`、`1-16(单)`、逗号分隔)、教师、地点(取空白分隔的最后一段)。课程名会去掉 `●★○`。 周次规则: - `n-m` 闭区间 - `(单)` 只保留奇数周,`(双)` 只保留偶数周 - 多段用逗号 ## 3. JS Bridge 页面注入后可用: | 对象 | 方法 | 行为 | |---|---|---| | `shiguangBridge` | `showToast(message)` | 短提示 | | `shiguangBridge` | `notifyTaskCompletion()` | Native 结束导入并返回课表 | | `shiguangBridgePromise` | `showAlert(title, content, confirm)` | 确认框,Promise\ | | `shiguangBridgePromise` | `showPrompt(...)` | 输入框,可带 JS 校验函数名 | | `shiguangBridgePromise` | `showSingleSelection(title, items, defaultIndex)` | 单选 | | `shiguangBridgePromise` | `saveImportedCourses(coursesJsonString)` | 保存课程数组 | | `shiguangBridgePromise` | `saveCourseConfig(configJsonString)` | 保存学期配置(正方脚本目前未调用) | | `shiguangBridgePromise` | `savePresetTimeSlots(timeSlotsJsonString)` | 保存节次(正方脚本目前未调用) | 兼容别名:`AndroidBridge`、`AndroidBridgePromise`。 Native 回调: ```javascript window._shiguangNativeCallback(callbackId, isSuccess, result) ``` 消息 JSON: ```json { "action": "saveImportedCourses", "callbackId": "cb_1_...", "payload": "{\"coursesJsonString\":\"[...]\"}" } ``` `payload` 本身是再包一层的 JSON 字符串。Android 用 `JavascriptInterface` 的 `postMessage` 收到后交给 `WebBridgeHandler.onMessageReceived`。 ## 4. 写入规则 `saveImportedCourses` 解析为 `List`,调用: ```kotlin courseConversionRepository.importCoursesFromList(tableId, list) ``` - 必须已经选过目标课表,否则失败。 - **删除该课表全部旧课程** 再插入。 - 每条生成新 UUID。 - 按课程名分配颜色池下标。 - 正方脚本 **不导入节次时刻和开学日期**。导入后请在「自定义时间段」「设置开学日期」里按学校作息补全,否则小组件和提醒的钟点可能不准。 ## 5. 改脚本时注意 - 正方不同学校皮肤可能改 class 名。改选择器前用真机打开该校课表查询页看 DOM。 - 脚本末尾直接 `runImportFlow()`,每次 `executeScript` 都会跑完整流程。 - 不要在脚本里写死学校 URL;URL 由用户输入。 - 解析结果必须是 Bridge 能 decode 的数组:至少含 `name, day, weeks, teacher, position, startSection, endSection`。 - 保持依赖 jQuery 的前提,或同时改成原生 DOM——当前实现明确检查 jQuery。 ## 6. Native 侧相关文件 | 文件 | 职责 | |---|---| | `ui/schoolselection/web/WebViewScreen.kt` | 地址栏、导入按钮、读 js、选课表 | | `WebBridgeProtocol.kt` | 注入脚本、消息数据类 | | `WebBridgeHandler.kt` | action 路由、写库 | | `WebDialogHost.kt` | Alert / Prompt / 单选 Compose 弹窗 | | `WebView.android.kt` | WebView 创建、JS 接口、桌面 UA | | `AndroidWebConstants.kt` | 桌面 UA 等 | | `WebViewRequestInterceptor.kt` | 请求拦截(如有) | `isDesktopMode` 切换 UA,部分正方在「电脑模式」才能看到完整课表。 Release 混淆注意:`NativeBridge.postMessage` 必须能被 JS 调到,见 [构建与发布 · ProGuard](构建与发布.md)。