更多

环境准备

• Node.js 20+ 与 npm — 前端构建和开发服务器。
• Rust stable（建议 1.78+） — Tauri 2.x 桌面后端需要 Rust 编译环境。
• Android SDK / NDK — 构建 Android 版本时需要（通过 Android Studio 安装最便捷）。
• macOS + Xcode 15+ — 构建 iOS 版本时需要。
• Git — 版本管理。

快速开始

# 1. 克隆仓库
git clone https://github.com/RollRoll520/Mini-HBUT.git
cd Mini-HBUT

# 2. 安装客户端依赖（客户端位于 apps/client/）
cd apps/client
npm install

# 3. 启动开发模式（前端 + Tauri 桌面端）
npm run tauri dev

# 4. 仅启动前端开发（用于 Web 模式调试）
npm run dev

# 5. 构建桌面端
npm run tauri build

# 6. 构建 Android 端
npm run tauri android build

# 7. 构建 iOS 端（macOS only）
npm run tauri ios build

目录结构速览

Mini-HBUT/（仓库根）
├── apps/client/                  # 客户端（Vue 前端 + Tauri/Capacitor）
│   ├── src/                      #   Vue 前端
│   │   ├── components/           #     业务组件（30+）
│   │   ├── utils/                #     工具函数
│   │   │   └── axios_adapter.js  #     HTTP 适配层
│   │   ├── platform/             #     平台桥接
│   │   └── config/               #     UI 配置
│   ├── src-tauri/
│   │   └── src/
│   │       ├── lib.rs            #     Tauri Commands 入口
│   │       ├── http_client/      #     网络请求模块
│   │       ├── http_server.rs    #     HTTP Bridge
│   │       └── db.rs             #     SQLite
│   ├── android/                  #   Capacitor Android
│   └── ios/                      #   Capacitor iOS
└── cloudflare/worker/            #   云同步 Worker

新增功能流程

1. 在 apps/client/src-tauri/src/（如 modules、http_client）新增 Rust 业务逻辑。
2. 在 apps/client/src-tauri/src/lib.rs 中注册 Tauri Command。
3. 前端通过 axios_adapter.js 新增 /v2 API 映射。
4. 在 apps/client/src/components/ 中添加或修改 Vue 组件。
5. 补充缓存策略、降级逻辑和错误处理路径。

质量与安全规范

Mini-HBUT 的 HTTP Bridge（127.0.0.1:4399）可以被 NoneBot、脚本或其他程序调用， 实现自动通知、定时查询等自动化能力。

接入方式

Bridge 固定监听本机；除健康检查外，外部程序必须配置并发送 HBUT_BRIDGE_TOKEN。

常用接口

GET  /health          — 检查 Bridge 是否在线
POST /login           — 触发登录
POST /sync_grades     — 获取最新成绩
POST /sync_schedule   — 获取课表
POST /fetch_exams     — 获取考试安排
POST /fetch_ranking   — 获取绩点排名

NoneBot 调用示例

import os
import httpx
from nonebot import on_command

cmd = on_command("成绩")
token = os.environ["HBUT_BRIDGE_TOKEN"]

@cmd.handle()
async def handle():
    headers = {"Authorization": f"Bearer {token}"}
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            "http://127.0.0.1:4399/sync_grades",
            headers=headers,
        )
        resp.raise_for_status()
        data = resp.json()
        await cmd.finish(f"课程数: {len(data.get('data', {}).get('grades', []))}")

cURL 调用示例

# 检查服务状态
curl http://127.0.0.1:4399/health

# 受保护接口：应用启动前需配置同值 HBUT_BRIDGE_TOKEN
curl -X POST http://127.0.0.1:4399/sync_grades   -H "Authorization: Bearer $HBUT_BRIDGE_TOKEN"

curl -X POST http://127.0.0.1:4399/sync_schedule   -H "Authorization: Bearer $HBUT_BRIDGE_TOKEN"

安全与限频

• Bridge 固定监听 127.0.0.1，不接受局域网或公网绑定。
• 除 /health 和只读嵌入资源外，脚本必须携带 HBUT_BRIDGE_TOKEN。
• 缓存 API 还会按接口要求校验 JWT scope。
• 高频任务建议加本地缓存，避免触发登录频率限制。

Mini-HBUT 是开源项目，欢迎任何形式的贡献！无论是提交 Bug 报告、功能建议，还是代码贡献。

如何贡献

1. Fork 仓库：在 GitHub 上 Fork Mini-HBUT 仓库到你的账号。
2. 创建分支：基于 main 分支创建你的功能分支（feature/你的功能名）。
3. 开发测试：完成开发后确保功能正常运行，并通过基本测试。
4. 提交 PR：向主仓库的 main 分支发起 Pull Request。
5. 代码审查：等待维护者审查，可能需要根据反馈修改。

贡献方式

提交规范

# Commit Message 格式
<type>(<scope>): <subject>

# 示例
feat(grade): 添加成绩趋势图表
fix(login): 修复验证码识别失败重试
docs(readme): 更新安装说明
style(schedule): 优化课表卡片布局
refactor(api): 重构缓存管理模块

简单来说：

• 可以：自由使用、修改、分发本软件。
• 要求：修改后的衍生作品也需要使用 GPL v3 协议发布源代码。
• 禁止：将本软件闭源后用于商业分发。

这意味着你可以自由使用 Mini-HBUT 的代码来学习和开发，但如果你基于它创建了新项目并分发， 你需要以相同的开源协议发布你的源代码。

Mini-HBUT 的开发离不开以下开源项目和服务：

感谢所有为 Mini-HBUT 提交过代码、报告过问题、提出过建议的贡献者们。