Files
2026-09-20 13:33:09 +08:00

117 lines
4.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 正方教务导入说明
星课表只内置一份正方适配脚本,不连接外部学校仓库。
脚本路径:
```
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\<boolean\> |
| `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<ImportCourseJsonModel>`,调用:
```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)。