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

156 lines
7.6 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.
# shiguang_warehouse
本仓库用于管理 [shiguangschedule](https://github.com/XingHeYuZhuan/shiguangschedule) 的适配脚本,供软件拉取和测试。
> [!important]
> **为避免代码出现问题,`main` 分支已启用分支保护,需要先合并到 `pending` 分支等待分支同步。**
## 仓库结构
```
shiguang_warehouse/
├───.github/
│ ├───workflows/
│ │ ├───build-index.yml # 生成 Protobuf 数据索引
│ │ └───...
│ └───...
├───index/
│ └───root_index.yaml # 整个适配器仓库的根索引文件
├───resources/ # 资源目录
│ ├───CUST/ # 学校目录
│ │ ├───adapters.yaml # 配置信息
│ │ └───cust.js # 适配脚本
│ ├───GLOBAL_TOOLS/ # 通用工具
│ │ ├───adapters.yaml
│ │ ├───school.js # 组件测试脚本
│ │ └───...
│ └───...
├───proto/
| └───school_index.proto #索引模板文件 可使用protoc等工具编译为其他平台代码用于解析仓库索引
└───...
```
## root_index.yaml 字段说明
**每个条目需包含以下字段:**
| 字段名 | 类型 | 说明 |
| ----------------- | --------- | -------------------------- |
| `id` | `string` | 唯一标识(拼音或缩写,如果可以更建议使用域名)<br>一般来说我们建议教务使用全大写,工具使用全小写 |
| `name` | `string` | 中文名称 |
| `initial` | `string` | 名称首字母(用于排序) |
| `resource_folder` | `string` | 资源文件夹名称(建议和 `id` 保持一致)|
**示例:**
```yaml
schools: #固定字段
- id: "GLOBAL_TOOLS"
name: "通用工具与服务"
initial: "T"
resource_folder: "GLOBAL_TOOLS"
- id: "CUST"
name: "长春理工大学"
initial: "C"
resource_folder: "CUST"
```
> [!note]
> 新增学校/工具时,先在 `root_index.yaml` 添加条目,再在 `resources/` 下创建与 `resource_folder` 字段一致的文件夹,放入 `adapters.yaml` 和适配脚本。**未登记的学校/工具无法提交适配文件。**
## adapters.yaml 配置说明
**每个适配器配置应包含以下字段(YAML格式,字段全部必填):**
| 字段名 | 类型 | 说明 |
| --------------- | ------- | --------------------------------------------- |
| adapter_id | string | 唯一标识(建议用拼音或英文缩写),个人建议使用学校 id 加序号的形式 |
| adapter_name | string | 中文名称 |
| category | string | 分类:`BACHELOR_AND_ASSOCIATE`(本科/专科)、`POSTGRADUATE`(研究生)、`GENERAL_TOOL`(通用工具) |
| asset_js_path | string | 适配脚本的**相对路径**(如 `school.js`) |
| import_url | string | 系统登录URL(教务系统适配器必填,工具可为空) |
| maintainer | string | 维护者信息(如姓名或 GitHub 用户名) |
| description | string | 简要说明(如适配用途、备注等) |
**示例:**
```yaml
adapters: #固定字段
- adapter_id: "GENERAL_TOOL_01" # id加上序号
adapter_name: "组件测试"
category: "GENERAL_TOOL"
asset_js_path: "school.js" #相对路径
import_url: ""
maintainer: "星河欲转"
description: "这是一个空网站,用于组件测试与演示模式"
```
> [!important]
> - 请严格按照上述字段填写,不要添加或减少字段。
> - `import_url` 一定要是登录页面。
> - `asset_js_path` 填写对应学校的适配脚本**相对路径**。
> - `maintainer` 填写维护者信息,便于后续沟通和维护。
## 开发流程
```
Fork 本仓库 → 在 index/root_index.yaml 文件中登记 → 在 resources 目录创建学校文件夹 → 创建 adapters.yaml 和适配脚本 → 推送到自己仓库并充分测试 → 提交 PR 到上游 pending 分支等待合并
```
### 添加适配代码
> [!note]
> 在**不更新索引**的情况下,修改任何 yaml 文件是没有作用的(任何对于 yaml 文件的修改都需要编译索引才能应用),所以才提供了 asset_js_path: `test.js` 占位,用于在不更新索引的情况下测试适配代码
- Fork 仓库之后,建议测试代码不要在自己的主分支测试哦,可以在仓库再开一个测试分支,测试完成可以一次将正确的代码提交到主分支,这样你的提交历史就不会充斥错误的提交历史
- 仓库更改数据结构后索引需要编译,软件只接收编译过的索引文件。所以如果要测试适配代码,建议创建 `resources\GLOBAL_TOOLS\test.js` 文件写入适配代码
- **注意提交 PR 请不要把测试的 `test.js` 也提交上去哦!!**
```yaml
- adapter_id: "GENERAL_TOOL_02"
adapter_name: "适配代码测试"
category: "GENERAL_TOOL"
asset_js_path: "test.js"
import_url: ""
maintainer: "星河欲转"
description: "空网站以及不存在适配代码,用于在不更新索引的情况下给开发者进行适配的软件测试"
```
## 关于仓库索引
当前仓库下面的固定孤立分支index-pb-release承担存放索引的功能
school_index.pb文件存放了适配仓库里面的所有yaml文件的信息,因此软件仅需要拉取该索引文件和resources资源目录下面的所有*.js文件
`scripts\build_data.py`代码负责编译出school_index.pb文件
> 当前索引协议版本:v2
> [!tip]
> 如需更新索引,可自行了解仓库的 CI 配置(不建议测试适配时还更新索引)
### 软件测试
开发者需要在"更多"页面点击图标5次打开开发者功能,在软件的“我的-更多-更新仓库”中选择**自定义仓库或私有仓库**,来拉取并更新自己的仓库代码进行实际测试,完成 Beta 阶段适配验证。
从2.x版本开始不在维护两个版本,开发者功能已合并至正式版本,在"更多"页面点击图标5次打开开发者功能
### 提交 PR
测试通过后,提交 Pull Request,等待审核合并。
## 社区公约
本项目基于 MIT 协议开源,致力于教务系统的适配与维护。为保障项目的良性流转,请在参与或使用本项目时遵守以下约定:
1. 贡献与署名
我们感谢所有贡献者的无私分享,每一份适配代码都值得被尊重。在引用或二次开发时,请保留原始开发者的贡献记录(如 Git 提交历史)。这既是对他人劳动的认可,也是社区协作的基础。任何抹除或篡改记录的行为,均不符合社区规范。
2. 分支与免责声明
- **适用范围**:本项目主要维护工作集中于官方仓库及官方分支。
- **非官方项目**:任何脱离官方管理的第三方分支或衍生项目,其所有行为均与本项目官方无关。
- **责任界定**:若第三方项目存在代码滥用、违规适配或分发不当,由此产生的一切后果均由该项目维护者自行承担。**本项目及无辜的原始贡献者不承担任何连带责任**。
## 注意事项
- 请确保 `adapters.yaml` 信息准确完整,符合规范要求。
- 每次提交适配代码或索引信息后,建议自测通过再提交 PR。
## 更多链接
- **[如何适配教务](https://github.com/XingHeYuZhuan/shiguangschedule/wiki)**
- **[浏览器测试插件](https://github.com/XingHeYuZhuan/shiguang_Tester)**
---
如有问题或建议,欢迎提交 Issue 或 PR。