[new] new project

This commit is contained in:
2026-09-20 13:33:09 +08:00
commit ca6a52fb2d
997 changed files with 140250 additions and 0 deletions
+116
View File
@@ -0,0 +1,116 @@
# 正方教务导入说明
星课表只内置一份正方适配脚本,不连接外部学校仓库。
脚本路径:
```
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)。