224 lines
9.7 KiB
Markdown
224 lines
9.7 KiB
Markdown
# LoveACE - 财大自动化工具
|
||
|
||
<div align="center">
|
||
|
||
<img src="https://cdn.apifox.com/app/project-icon/custom/20251011/e20b3227-13dd-4057-b1d3-dc821294d914.jpeg" alt="LoveACE Logo" width="120" height="120" />
|
||
|
||
**Make It Easy**
|
||
</div>
|
||
|
||
## 🚀 项目简介
|
||
|
||
LoveACE 是一个面向安徽财经大学的教务系统自动化工具，专为安徽财经大学各类系统设计。通过 RESTful API 接口，提供课表查询、成绩查询、积分查询、宿舍管理等功能，大幅简化学生的日常操作流程。
|
||
|
||
### ✨ 主要特性
|
||
|
||
- **🔐 安全认证**: 基于 Token 的用户认证系统，RSA 加密保护敏感信息
|
||
- **📚 教务集成**: 深度集成教务系统，支持成绩、课表、考试、培养方案、学业信息查询
|
||
- **💯 积分查询**: 爱安财系统集成，实时查询积分和明细
|
||
- **🏠 宿舍管理**: ISIM系统集成，支持电费查询和房间信息查询
|
||
- **🚀 高性能**: 基于 FastAPI 构建，支持异步处理和高并发
|
||
- **📊 中间件支持**: 请求处理时间监控、CORS 配置
|
||
- **🔒 数据安全**: RSA 加密存储敏感信息，保护用户隐私
|
||
|
||
### 🛠️ 技术栈
|
||
|
||
- **后端框架**: [FastAPI](https://fastapi.tiangolo.com/) - 现代、快速的 Python Web 框架
|
||
- **数据库**: [SQLAlchemy](https://sqlalchemy.org/) (异步) + [aiomysql](https://aiomysql.readthedocs.io/) - 强大的异步 ORM
|
||
- **HTTP客户端**: [httpx](https://www.python-httpx.org/) - 现代化的异步 HTTP 客户端
|
||
- **日志系统**: [richuru](https://github.com/GreyElaina/richuru) - rich + loguru 的完美结合
|
||
- **包管理**: [uv](https://github.com/astral-sh/uv) - 极速 Python 包管理器
|
||
- **加密工具**: [cryptography](https://cryptography.io/) - RSA 加密支持
|
||
- **数据解析**: [BeautifulSoup4](https://www.crummy.com/software/BeautifulSoup/) + [lxml](https://lxml.de/) - HTML 解析
|
||
|
||
## 📚 API 功能
|
||
|
||
### 认证模块 (`/auth`)
|
||
- **用户注册**: 创建新用户账号
|
||
- **用户登录**: 获取访问令牌
|
||
- **身份验证**: 验证当前用户身份和令牌有效性
|
||
|
||
### 教务系统 (`/jwc`)
|
||
- **成绩查询**: 查询学期成绩和历史成绩
|
||
- **课表查询**: 获取当前学期课程表
|
||
- **考试安排**: 查看考试时间和地点
|
||
- **培养方案**: 查询专业培养方案
|
||
- **学业信息**: 获取学生基本学业信息
|
||
- **学期信息**: 查询学期列表
|
||
|
||
### 爱安财系统 (`/aac`)
|
||
- **学分查询**: 查询总的爱安财学分
|
||
- **学分明细**: 获取爱安财学分明细
|
||
|
||
### 宿舍管理 (`/isim`)
|
||
- **电费查询**: 查询宿舍剩余电费
|
||
- **房间信息**: 获取宿舍房间详细信息
|
||
|
||
## 📚 文档
|
||
|
||
### API 文档
|
||
启动服务后，在 debug 模式下访问：
|
||
- **Swagger UI**: http://localhost:4500/docs
|
||
- **ReDoc**: http://localhost:4500/redoc
|
||
- **OpenAPI Schema**: http://localhost:4500/openapi.json
|
||
|
||
> **注意**: 生产环境下，文档接口默认关闭，需在配置文件中设置 `app.debug = true` 启用。
|
||
|
||
## 🏗️ 项目结构
|
||
|
||
```
|
||
LoveACE-V2/
|
||
├── 📁 loveace/ # 主应用目录
|
||
│ ├── 📁 config/ # 配置管理
|
||
│ │ ├── logger.py # 日志配置
|
||
│ │ ├── manager.py # 配置管理器
|
||
│ │ └── settings.py # 配置模型
|
||
│ ├── 📁 database/ # 数据库相关代码
|
||
│ │ ├── creator.py # 数据库会话管理
|
||
│ │ ├── base/ # 基础模型定义
|
||
│ │ ├── auth/ # 认证相关模型 (用户、令牌、登录、注册)
|
||
│ │ ├── aac/ # 爱安财积分票据模型
|
||
│ │ └── isim/ # 宿舍管理模型
|
||
│ ├── 📁 router/ # API路由定义
|
||
│ │ ├── dependencies/ # 路由依赖项 (认证、日志等)
|
||
│ │ ├── endpoint/ # API端点
|
||
│ │ │ ├── auth/ # 认证路由 (登录、注册、authme)
|
||
│ │ │ ├── jwc/ # 教务系统路由 (成绩、课表、考试、培养方案等)
|
||
│ │ │ ├── aac/ # 爱安财系统路由 (积分查询)
|
||
│ │ │ └── isim/ # 宿舍管理路由 (电费、房间信息)
|
||
│ │ └── schemas/ # 通用响应模型和错误处理
|
||
│ ├── 📁 service/ # 服务层
|
||
│ │ ├── model/ # 服务模型
|
||
│ │ └── remote/ # 远程服务
|
||
│ │ └── aufe/ # 安徽财经大学服务集成
|
||
│ ├── 📁 middleware/ # 中间件
|
||
│ │ └── process_time.py # 请求处理时间中间件
|
||
│ └── 📁 utils/ # 工具函数
|
||
│ ├── richuru_hook.py # Rich + Loguru 集成
|
||
│ └── rsa.py # RSA 加密工具
|
||
├── 📁 data/ # 数据文件
|
||
│ ├── isim_rooms.json # 宿舍房间数据
|
||
│ └── keys/ # RSA密钥对
|
||
├── 📁 logs/ # 日志文件目录
|
||
├── 📄 main.py # 应用入口文件
|
||
├── 📄 config.json # 配置文件
|
||
├── 📄 pyproject.toml # 项目依赖配置 (uv)
|
||
├── 📄 uv.lock # 依赖锁定文件
|
||
└── 📄 README.md # 项目说明文档
|
||
```
|
||
|
||
## 🤝 贡献
|
||
|
||
我们欢迎所有形式的贡献！
|
||
|
||
### 贡献方式
|
||
|
||
- 🐛 **Bug报告**: [创建Issue](https://github.com/LoveACE-Team/LoveACE/issues/new)
|
||
- 💡 **功能建议**: [发起Issue](https://github.com/LoveACE-Team/LoveACE/issues/new)
|
||
- 📝 **代码贡献**: 提交Pull Request
|
||
- 📖 **文档改进**: 帮助完善文档
|
||
|
||
### 开发指南
|
||
|
||
```bash
|
||
# 克隆项目
|
||
git clone https://github.com/LoveACE-Team/LoveACE.git
|
||
cd LoveACE
|
||
|
||
# 安装开发依赖
|
||
uv sync --group dev
|
||
|
||
# 代码格式化
|
||
black .
|
||
isort .
|
||
|
||
# 代码检查
|
||
ruff check .
|
||
```
|
||
|
||
## ⚖️ 免责声明
|
||
|
||
**重要提醒**: 本软件仅供学习、研究和个人非商业用途使用。
|
||
|
||
### 使用条款
|
||
|
||
- ✅ **开源性质**: 本软件为教育目的开发的开源项目，遵循 MIT 许可证
|
||
- 📚 **用途限制**: 仅限于学习交流、技术研究等非商业用途
|
||
- ⚠️ **合规使用**: 使用时请严格遵守学校相关规定、服务条款及您所在地的法律法规
|
||
- 🛡️ **账户安全**: 请妥善保管个人账户信息，不要与他人共享，避免账号泄露
|
||
- 🔒 **隐私保护**: 本软件不会主动收集、存储或泄露用户的个人信息
|
||
|
||
### 商业使用禁止
|
||
|
||
- ❌ **严禁商用**: 本软件不得用于任何形式的商业用途，包括但不限于：
|
||
- 收费服务或产品
|
||
- 商业广告和推广
|
||
- 未经授权的数据采集和销售
|
||
- ⚠️ **风险自负**: 任何未经授权的商业使用所产生的法律责任、经济损失、侵权纠纷及其他风险，均由商业使用者自行承担，与本软件作者及所有贡献者无关
|
||
|
||
### 免责条款
|
||
|
||
- 🚫 **后果免责**: 开发者及贡献者不对使用本软件造成的任何直接或间接后果负责，包括但不限于：
|
||
- 账号封禁或处罚
|
||
- 数据丢失或泄露
|
||
- 服务中断或错误
|
||
- 学业或经济损失
|
||
- 🔧 **无担保**: 本软件按"现状"提供，不提供任何明示或暗示的担保，包括但不限于适销性、特定用途适用性的担保
|
||
- 📋 **自行判断**: 用户应自行判断使用本软件的风险，并承担使用本软件的全部责任
|
||
|
||
### 接受条款
|
||
|
||
- 📜 **视为同意**: 下载、安装、使用本软件或对本软件进行任何形式的操作，即表示您已充分阅读、理解并同意接受本免责声明的所有条款
|
||
- ⛔ **不同意则停止**: 如果您不同意本免责声明的任何条款，请立即停止使用本软件并删除所有相关文件
|
||
|
||
## 📞 支持与联系
|
||
|
||
- 📧 **邮箱**: [sibuxiang@proton.me](mailto:sibuxiang@proton.me)
|
||
- 🐛 **Bug报告**: [GitHub Issues](https://github.com/LoveACE-Team/LoveACE/issues)
|
||
- 💬 **讨论交流**: [GitHub Discussions](https://github.com/LoveACE-Team/LoveACE/discussions)
|
||
|
||
## 📄 许可证
|
||
|
||
本项目采用 [MIT许可证](LICENSE) 开源。
|
||
|
||
**重要商业使用限制**: 本软件不得用于商业用途。任何未经授权的商业使用所产生的一切法律责任、经济损失及其他风险，均由商业使用者自行承担，与本软件作者及贡献者无关。
|
||
|
||
```bash
|
||
MIT License
|
||
|
||
Copyright (c) 2025 LoveACE Team
|
||
|
||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||
of this software and associated documentation files (the "Software"), to deal
|
||
in the Software without restriction, including without limitation the rights
|
||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||
copies of the Software, and to permit persons to whom the Software is
|
||
furnished to do so, subject to the following conditions:
|
||
|
||
COMMERCIAL USE RESTRICTION:
|
||
This software is NOT intended for commercial use. Any unauthorized commercial
|
||
use of this software is strictly prohibited. All legal liabilities, financial
|
||
losses, and other risks arising from unauthorized commercial use shall be
|
||
borne solely by the commercial user and are not the responsibility of the
|
||
software authors or contributors.
|
||
|
||
The above copyright notice and this permission notice shall be included in all
|
||
copies or substantial portions of the Software.
|
||
|
||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||
SOFTWARE.
|
||
```
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
**如果这个项目对你有帮助，请给它一个 ⭐️**
|
||
|
||
Made with ❤️ by [Sibuxiangx](https://github.com/Sibuxiangx)
|
||
|
||
</div> |