shiguang_warehouse

shiguang_warehouse

本仓库用于管理 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	唯一标识（拼音或缩写，如果可以更建议使用域名） 一般来说我们建议教务使用全大写，工具使用全小写
name	string	中文名称
initial	string	名称首字母（用于排序）
resource_folder	string	资源文件夹名称（建议和 id 保持一致）

示例：

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	简要说明（如适配用途、备注等）

示例：

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 分支等待合并

Fork 仓库

本仓库带有 lighthouse 标签，已在开发者版 APP 中关闭检查逻辑，请开发者对使用的仓库链接负责。

添加适配代码

[!note] 在不更新索引的情况下，修改任何 yaml 文件是没有作用的（任何对于 yaml 文件的修改都需要编译索引才能应用），所以才提供了 asset_js_path: test.js 占位，用于在不更新索引的情况下测试适配代码

• Fork 仓库之后，建议测试代码不要在自己的主分支测试哦，可以在仓库再开一个测试分支，测试完成可以一次将正确的代码提交到主分支，这样你的提交历史就不会充斥错误的提交历史
• 仓库更改数据结构后索引需要编译，软件只接收编译过的索引文件。所以如果要测试适配代码，建议创建 resources\GLOBAL_TOOLS\test.js 文件写入适配代码

• 注意提交 PR 请不要把测试的 test.js 也提交上去哦！！

  - adapter_id: "GENERAL_TOOL_02"
  adapter_name: "适配代码测试"
  category: "GENERAL_TOOL"
  asset_js_path: "test.js"
  import_url: ""
  maintainer: "星河欲转"
  description: "空网站以及不存在适配代码，用于在不更新索引的情况下给开发者进行适配的软件测试"    
  

[!tip] 如需更新索引，可自行了解仓库的 CI 配置（不建议测试适配时还更新索引）

软件测试

开发者需要安装开发者版 APP（红色图标），在软件的“我的-更多-更新仓库”中选择自定义仓库或私有仓库，来拉取并更新自己的仓库代码进行实际测试，完成 Beta 阶段适配验证。

提交 PR

测试通过后，提交 Pull Request，等待审核合并。

社区公约

本项目基于 MIT 协议开源，致力于教务系统的适配与维护。为保障项目的良性流转，请在参与或使用本项目时遵守以下约定：

1. 贡献与署名

我们感谢所有贡献者的无私分享，每一份适配代码都值得被尊重。在引用或二次开发时，请保留原始开发者的贡献记录（如 Git 提交历史）。这既是对他人劳动的认可，也是社区协作的基础。任何抹除或篡改记录的行为，均不符合社区规范。

1. 分支与免责声明
   • 适用范围：本项目主要维护工作集中于官方仓库及官方分支。
   • 非官方项目：任何脱离官方管理的第三方分支或衍生项目，其所有行为均与本项目官方无关。
   • 责任界定：若第三方项目存在代码滥用、违规适配或分发不当，由此产生的一切后果均由该项目维护者自行承担。本项目及无辜的原始贡献者不承担任何连带责任。

注意事项

• 请确保 adapters.yaml 信息准确完整，符合规范要求。
• 每次提交适配代码或索引信息后，建议自测通过再提交 PR。
• 仓库需保留 lighthouse 标签，否则软件无法识别为适配仓库。

更多链接

• 如何适配
  
• 浏览器测试插件

---

如有问题或建议，欢迎提交 Issue 或 PR。