⚒️ 重大重构 LoveACE V2
引入了 mongodb 对数据库进行了一定程度的数据加密 性能改善 代码简化 统一错误模型和响应 使用 apifox 作为文档
This commit is contained in:
@@ -1,200 +0,0 @@
|
||||
<template>
|
||||
<div ref="swaggerContainer" id="swagger-ui"></div>
|
||||
</template>
|
||||
|
||||
<script setup lang="ts">
|
||||
import { ref, onMounted, onUnmounted } from 'vue'
|
||||
|
||||
const swaggerContainer = ref<HTMLElement>()
|
||||
|
||||
onMounted(async () => {
|
||||
if (typeof window !== 'undefined') {
|
||||
try {
|
||||
// 加载CSS
|
||||
const link = document.createElement('link')
|
||||
link.rel = 'stylesheet'
|
||||
link.href = '/swagger-ui.css'
|
||||
document.head.appendChild(link)
|
||||
|
||||
// 加载SwaggerUI Bundle
|
||||
const bundleScript = document.createElement('script')
|
||||
bundleScript.src = '/swagger-ui-bundle.js'
|
||||
bundleScript.crossOrigin = 'anonymous'
|
||||
|
||||
// 加载Standalone Preset
|
||||
const presetScript = document.createElement('script')
|
||||
presetScript.src = '/swagger-ui-standalone-preset.js'
|
||||
presetScript.crossOrigin = 'anonymous'
|
||||
|
||||
// 等待两个脚本都加载完成
|
||||
let bundleLoaded = false
|
||||
let presetLoaded = false
|
||||
|
||||
const initSwagger = () => {
|
||||
if (bundleLoaded && presetLoaded) {
|
||||
// @ts-ignore
|
||||
window.ui = window.SwaggerUIBundle({
|
||||
url: '/openapi.json',
|
||||
dom_id: '#swagger-ui',
|
||||
deepLinking: true,
|
||||
presets: [
|
||||
// @ts-ignore
|
||||
SwaggerUIBundle.presets.apis,
|
||||
// @ts-ignore
|
||||
SwaggerUIStandalonePreset
|
||||
],
|
||||
plugins: [
|
||||
// @ts-ignore
|
||||
SwaggerUIBundle.plugins.DownloadUrl
|
||||
],
|
||||
layout: "StandaloneLayout",
|
||||
tryItOutEnabled: true,
|
||||
displayRequestDuration: true,
|
||||
showExtensions: true,
|
||||
showCommonExtensions: true,
|
||||
requestInterceptor: (request: any) => {
|
||||
// 可以在这里添加认证头或其他请求拦截
|
||||
console.log('请求拦截:', request)
|
||||
return request
|
||||
},
|
||||
responseInterceptor: (response: any) => {
|
||||
// 可以在这里处理响应
|
||||
console.log('响应拦截:', response)
|
||||
return response
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
bundleScript.onload = () => {
|
||||
bundleLoaded = true
|
||||
initSwagger()
|
||||
}
|
||||
|
||||
presetScript.onload = () => {
|
||||
presetLoaded = true
|
||||
initSwagger()
|
||||
}
|
||||
|
||||
bundleScript.onerror = () => {
|
||||
console.error('加载SwaggerUI Bundle失败')
|
||||
}
|
||||
|
||||
presetScript.onerror = () => {
|
||||
console.error('加载SwaggerUI Preset失败')
|
||||
}
|
||||
|
||||
document.head.appendChild(bundleScript)
|
||||
document.head.appendChild(presetScript)
|
||||
} catch (error) {
|
||||
console.error('加载SwaggerUI失败:', error)
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
onUnmounted(() => {
|
||||
// 清理动态添加的脚本和样式
|
||||
const bundleScripts = document.querySelectorAll('script[src*="swagger-ui-bundle"]')
|
||||
const presetScripts = document.querySelectorAll('script[src*="swagger-ui-standalone-preset"]')
|
||||
const links = document.querySelectorAll('link[href*="swagger-ui.css"]')
|
||||
|
||||
bundleScripts.forEach(script => script.remove())
|
||||
presetScripts.forEach(script => script.remove())
|
||||
links.forEach(link => link.remove())
|
||||
|
||||
// 清理全局变量
|
||||
if (typeof window !== 'undefined' && (window as any).ui) {
|
||||
delete (window as any).ui
|
||||
}
|
||||
})
|
||||
</script>
|
||||
|
||||
<style>
|
||||
/* SwaggerUI 容器样式 */
|
||||
#swagger-ui {
|
||||
font-family: var(--vp-font-family-base);
|
||||
width: 100%;
|
||||
min-height: 600px;
|
||||
}
|
||||
|
||||
/* 调整SwaggerUI的主题以匹配VitePress */
|
||||
#swagger-ui .swagger-ui .topbar {
|
||||
display: none !important;
|
||||
}
|
||||
|
||||
#swagger-ui .swagger-ui .info {
|
||||
margin: 0 0 20px 0;
|
||||
}
|
||||
|
||||
#swagger-ui .swagger-ui .scheme-container {
|
||||
background: var(--vp-c-bg-soft);
|
||||
border: 1px solid var(--vp-c-border);
|
||||
border-radius: 8px;
|
||||
padding: 10px;
|
||||
margin: 10px 0;
|
||||
}
|
||||
|
||||
#swagger-ui .swagger-ui .opblock {
|
||||
border: 1px solid var(--vp-c-border);
|
||||
border-radius: 8px;
|
||||
margin: 10px 0;
|
||||
background: var(--vp-c-bg);
|
||||
}
|
||||
|
||||
#swagger-ui .swagger-ui .opblock.opblock-post {
|
||||
border-color: var(--vp-c-green-2);
|
||||
background: var(--vp-c-green-soft);
|
||||
}
|
||||
|
||||
#swagger-ui .swagger-ui .opblock.opblock-get {
|
||||
border-color: var(--vp-c-blue-2);
|
||||
background: var(--vp-c-blue-soft);
|
||||
}
|
||||
|
||||
#swagger-ui .swagger-ui .opblock.opblock-put {
|
||||
border-color: var(--vp-c-yellow-2);
|
||||
background: var(--vp-c-yellow-soft);
|
||||
}
|
||||
|
||||
#swagger-ui .swagger-ui .opblock.opblock-delete {
|
||||
border-color: var(--vp-c-red-2);
|
||||
background: var(--vp-c-red-soft);
|
||||
}
|
||||
|
||||
#swagger-ui .swagger-ui .opblock-summary {
|
||||
padding: 10px 15px;
|
||||
}
|
||||
|
||||
#swagger-ui .swagger-ui .opblock-description-wrapper,
|
||||
#swagger-ui .swagger-ui .opblock-external-docs-wrapper,
|
||||
#swagger-ui .swagger-ui .opblock-title_normal {
|
||||
padding: 15px;
|
||||
background: var(--vp-c-bg-alt);
|
||||
border-radius: 4px;
|
||||
margin: 10px 0;
|
||||
}
|
||||
|
||||
/* 响应式设计 */
|
||||
@media (max-width: 768px) {
|
||||
#swagger-ui .swagger-ui {
|
||||
font-size: 14px;
|
||||
}
|
||||
|
||||
#swagger-ui .swagger-ui .opblock-summary {
|
||||
padding: 8px 10px;
|
||||
}
|
||||
}
|
||||
|
||||
/* 深色模式适配 */
|
||||
.dark #swagger-ui .swagger-ui {
|
||||
color-scheme: dark;
|
||||
}
|
||||
|
||||
.dark #swagger-ui .swagger-ui .opblock {
|
||||
background: var(--vp-c-bg-elv);
|
||||
}
|
||||
|
||||
.dark #swagger-ui .swagger-ui .scheme-container {
|
||||
background: var(--vp-c-bg-elv);
|
||||
}
|
||||
</style>
|
||||
@@ -1,75 +0,0 @@
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
title: 'LoveACE',
|
||||
description: '教务系统自动化工具',
|
||||
lang: 'zh-CN',
|
||||
|
||||
themeConfig: {
|
||||
logo: '/images/logo.jpg',
|
||||
|
||||
nav: [
|
||||
{ text: '首页', link: '/' },
|
||||
{ text: 'API文档', link: '/api/' },
|
||||
{ text: '配置', link: '/config' },
|
||||
{ text: '部署', link: '/deploy' },
|
||||
{ text: '贡献', link: '/contributing' }
|
||||
],
|
||||
|
||||
sidebar: {
|
||||
'/': [
|
||||
{
|
||||
text: '指南',
|
||||
items: [
|
||||
{ text: '介绍', link: '/' },
|
||||
{ text: '快速开始', link: '/getting-started' },
|
||||
{ text: '配置', link: '/config' },
|
||||
{ text: '部署指南', link: '/deploy' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'API文档',
|
||||
items: [
|
||||
{ text: 'API交互式文档', link: '/api/' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: '其他',
|
||||
items: [
|
||||
{ text: '贡献指南', link: '/contributing' },
|
||||
{ text: '免责声明', link: '/disclaimer' }
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
socialLinks: [
|
||||
{ icon: 'github', link: 'https://github.com/LoveACE-Team/LoveACE' }
|
||||
],
|
||||
|
||||
footer: {
|
||||
message: '基于 MIT 许可发布',
|
||||
copyright: 'Copyright © 2025 LoveACE'
|
||||
},
|
||||
|
||||
search: {
|
||||
provider: 'local'
|
||||
},
|
||||
|
||||
lastUpdated: {
|
||||
text: '最后更新于',
|
||||
formatOptions: {
|
||||
dateStyle: 'short',
|
||||
timeStyle: 'medium'
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
head: [
|
||||
['link', { rel: 'icon', href: '/images/logo.jpg' }]
|
||||
],
|
||||
|
||||
markdown: {
|
||||
lineNumbers: true
|
||||
}
|
||||
})
|
||||
@@ -1,29 +0,0 @@
|
||||
/* 自定义样式文件 */
|
||||
|
||||
/* 确保SwaggerUI容器有足够的高度 */
|
||||
.swagger-container {
|
||||
min-height: 600px;
|
||||
width: 100%;
|
||||
}
|
||||
|
||||
/* SwaggerUI组件的容器样式 */
|
||||
.api-docs-container {
|
||||
background: var(--vp-c-bg);
|
||||
border-radius: 8px;
|
||||
padding: 20px;
|
||||
margin: 20px 0;
|
||||
}
|
||||
|
||||
/* 为API文档页面添加特殊样式 */
|
||||
.api-page .content-container {
|
||||
max-width: none !important;
|
||||
padding: 0 !important;
|
||||
}
|
||||
|
||||
/* 响应式调整 */
|
||||
@media (max-width: 960px) {
|
||||
.api-docs-container {
|
||||
padding: 10px;
|
||||
margin: 10px 0;
|
||||
}
|
||||
}
|
||||
@@ -1,17 +0,0 @@
|
||||
import { h } from 'vue'
|
||||
import DefaultTheme from 'vitepress/theme'
|
||||
import SwaggerUI from '../components/SwaggerUI.vue'
|
||||
import './custom.css'
|
||||
|
||||
export default {
|
||||
extends: DefaultTheme,
|
||||
Layout: () => {
|
||||
return h(DefaultTheme.Layout, null, {
|
||||
// https://vitepress.dev/guide/extending-default-theme#layout-slots
|
||||
})
|
||||
},
|
||||
enhanceApp({ app, router, siteData }) {
|
||||
// 注册全局组件
|
||||
app.component('SwaggerUI', SwaggerUI)
|
||||
}
|
||||
}
|
||||
46
docs/API_DOCSTRING_GUIDELINE.md
Normal file
46
docs/API_DOCSTRING_GUIDELINE.md
Normal file
@@ -0,0 +1,46 @@
|
||||
## 注解使用指南
|
||||
|
||||
### 📝 写注解时的最佳实践
|
||||
|
||||
1. **保持一致性** - 所有注解使用统一的结构和 Emoji
|
||||
2. **包含场景** - 明确说明接口的应用场景
|
||||
3. **突出特性** - 使用 ✅ 标记主要功能
|
||||
4. **警告限制** - 使用 ⚠️ 标记重要限制条件
|
||||
5. **简明扼要** - 避免过长的描述，保持可读性
|
||||
|
||||
### 🎯 Emoji 参考表
|
||||
|
||||
| Emoji | 含义 | 用途 |
|
||||
|--------|------|------|
|
||||
| ✅ | 功能特性 | 列举该接口的主要优势 |
|
||||
| ⚠️ | 警告/限制 | 标记使用时需要注意的限制 |
|
||||
| 💡 | 建议/场景 | 列举应用场景或建议 |
|
||||
| 🔄 | 流程/步骤 | 表示流程或步骤 |
|
||||
| 🎁 | 返回值 | 描述返回值 |
|
||||
|
||||
```python
|
||||
"""
|
||||
[简明功能描述]
|
||||
|
||||
✅ 功能特性：
|
||||
- 功能 1
|
||||
- 功能 2
|
||||
- 功能 3
|
||||
|
||||
⚠️ 限制条件：（如需要）
|
||||
- 限制 1
|
||||
- 限制 2
|
||||
|
||||
💡 使用场景：
|
||||
- 场景 1
|
||||
- 场景 2
|
||||
- 场景 3
|
||||
|
||||
Args:
|
||||
param1: 参数说明
|
||||
param2: 参数说明
|
||||
|
||||
Returns:
|
||||
ResponseType: 返回值说明
|
||||
"""
|
||||
```
|
||||
326
docs/ISIM_API.md
326
docs/ISIM_API.md
@@ -1,326 +0,0 @@
|
||||
# ISIM 电费查询系统 API 文档
|
||||
|
||||
## 概述
|
||||
|
||||
ISIM（Integrated Student Information Management）电费查询系统是为安徽财经大学学生提供的后勤电费查询服务。通过该系统，学生可以：
|
||||
|
||||
- 选择和绑定宿舍房间
|
||||
- 查询电费余额和用电记录
|
||||
- 查看充值记录
|
||||
|
||||
## API 端点
|
||||
|
||||
### 认证
|
||||
|
||||
所有API都需要通过认证令牌（authme_token）进行身份验证。认证信息通过依赖注入自动处理。
|
||||
|
||||
### 房间选择器 API
|
||||
|
||||
#### 1. 获取楼栋列表
|
||||
|
||||
**POST** `/api/v1/isim/picker/building/get`
|
||||
|
||||
获取所有可选择的楼栋信息。
|
||||
|
||||
**响应示例：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "楼栋列表获取成功",
|
||||
"data": [
|
||||
{
|
||||
"code": "11",
|
||||
"name": "北苑11号学生公寓"
|
||||
},
|
||||
{
|
||||
"code": "12",
|
||||
"name": "北苑12号学生公寓"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. 设置楼栋并获取楼层列表
|
||||
|
||||
**POST** `/api/v1/isim/picker/building/set`
|
||||
|
||||
设置楼栋并获取对应的楼层列表。
|
||||
|
||||
**请求参数：**
|
||||
```json
|
||||
{
|
||||
"building_code": "11"
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "楼层列表获取成功",
|
||||
"data": [
|
||||
{
|
||||
"code": "010101",
|
||||
"name": "1-1层"
|
||||
},
|
||||
{
|
||||
"code": "010102",
|
||||
"name": "1-2层"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. 设置楼层并获取房间列表
|
||||
|
||||
**POST** `/api/v1/isim/picker/floor/set`
|
||||
|
||||
设置楼层并获取对应的房间列表。
|
||||
|
||||
**请求参数：**
|
||||
```json
|
||||
{
|
||||
"floor_code": "010101"
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "房间列表获取成功",
|
||||
"data": [
|
||||
{
|
||||
"code": "01",
|
||||
"name": "1-101"
|
||||
},
|
||||
{
|
||||
"code": "02",
|
||||
"name": "1-102"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 4. 绑定房间
|
||||
|
||||
**POST** `/api/v1/isim/picker/room/set`
|
||||
|
||||
绑定房间到用户账户。
|
||||
|
||||
**请求参数：**
|
||||
```json
|
||||
{
|
||||
"building_code": "11",
|
||||
"floor_code": "010101",
|
||||
"room_code": "01"
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "房间绑定成功",
|
||||
"data": {
|
||||
"building": {
|
||||
"code": "11",
|
||||
"name": "北苑11号学生公寓"
|
||||
},
|
||||
"floor": {
|
||||
"code": "010101",
|
||||
"name": "1-1层"
|
||||
},
|
||||
"room": {
|
||||
"code": "01",
|
||||
"name": "1-101"
|
||||
},
|
||||
"room_id": "01",
|
||||
"display_text": "北苑11号学生公寓/1-1层/1-101"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 电费查询 API
|
||||
|
||||
#### 5. 获取电费信息
|
||||
|
||||
**POST** `/api/v1/isim/electricity/info`
|
||||
|
||||
获取电费余额和用电记录信息。
|
||||
|
||||
**响应示例：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "电费信息获取成功",
|
||||
"data": {
|
||||
"balance": {
|
||||
"remaining_purchased": 815.30,
|
||||
"remaining_subsidy": 2198.01
|
||||
},
|
||||
"usage_records": [
|
||||
{
|
||||
"record_time": "2025-08-29 00:04:58",
|
||||
"usage_amount": 0.00,
|
||||
"meter_name": "1-101"
|
||||
},
|
||||
{
|
||||
"record_time": "2025-08-29 00:04:58",
|
||||
"usage_amount": 0.00,
|
||||
"meter_name": "1-101空调"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 6. 获取充值信息
|
||||
|
||||
**POST** `/api/v1/isim/payment/info`
|
||||
|
||||
获取电费余额和充值记录信息。
|
||||
|
||||
**响应示例：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "充值信息获取成功",
|
||||
"data": {
|
||||
"balance": {
|
||||
"remaining_purchased": 815.30,
|
||||
"remaining_subsidy": 2198.01
|
||||
},
|
||||
"payment_records": [
|
||||
{
|
||||
"payment_time": "2025-02-21 11:30:08",
|
||||
"amount": 71.29,
|
||||
"payment_type": "下发补助"
|
||||
},
|
||||
{
|
||||
"payment_time": "2024-09-01 15:52:40",
|
||||
"amount": 71.29,
|
||||
"payment_type": "下发补助"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 7. 检查房间绑定状态
|
||||
|
||||
**POST** `/api/v1/isim/room/binding/status`
|
||||
|
||||
检查用户是否已绑定宿舍房间。
|
||||
|
||||
**已绑定响应示例：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "用户已绑定宿舍房间",
|
||||
"data": {
|
||||
"is_bound": true,
|
||||
"binding_info": {
|
||||
"building": {
|
||||
"code": "35",
|
||||
"name": "西校荆苑5号学生公寓"
|
||||
},
|
||||
"floor": {
|
||||
"code": "3501",
|
||||
"name": "荆5-1层"
|
||||
},
|
||||
"room": {
|
||||
"code": "350116",
|
||||
"name": "J5-116"
|
||||
},
|
||||
"room_id": "350116",
|
||||
"display_text": "西校荆苑5号学生公寓/荆5-1层/J5-116"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**未绑定响应示例：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "用户未绑定宿舍房间",
|
||||
"data": {
|
||||
"is_bound": false,
|
||||
"binding_info": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
### 标准错误响应
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 1,
|
||||
"message": "错误描述信息"
|
||||
}
|
||||
```
|
||||
|
||||
### 认证错误响应
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 401,
|
||||
"message": "Cookie已失效或不在VPN/校园网环境，请重新登录"
|
||||
}
|
||||
```
|
||||
|
||||
### 常见错误代码
|
||||
|
||||
- `0`: 成功
|
||||
- `1`: 一般业务错误
|
||||
- `400`: 请求参数错误或未绑定房间
|
||||
- `401`: 认证失败
|
||||
- `500`: 服务器内部错误
|
||||
|
||||
### 特殊错误情况
|
||||
|
||||
#### 未绑定房间错误
|
||||
|
||||
当用户尝试查询电费或充值信息但未绑定房间时，会返回特定错误：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 400,
|
||||
"message": "请先绑定宿舍房间后再查询电费信息"
|
||||
}
|
||||
```
|
||||
|
||||
或
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 400,
|
||||
"message": "请先绑定宿舍房间后再查询充值信息"
|
||||
}
|
||||
```
|
||||
|
||||
## 使用流程
|
||||
|
||||
### 房间绑定流程
|
||||
1. **检查绑定状态**：调用房间绑定状态API检查是否已绑定
|
||||
2. **首次绑定**（如果未绑定）：
|
||||
- 调用楼栋列表API获取所有楼栋
|
||||
- 调用楼栋设置API获取楼层列表
|
||||
- 调用楼层设置API获取房间列表
|
||||
- 调用房间绑定API完成房间绑定
|
||||
|
||||
### 查询流程
|
||||
1. **确认绑定**：确保用户已绑定房间（必需）
|
||||
2. **查询信息**：调用电费信息或充值信息API获取数据
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 所有接口都需要有效的认证令牌
|
||||
- 数据实时从后勤系统获取，不会在数据库中缓存
|
||||
- 房间绑定信息会保存在数据库中以便下次使用
|
||||
- 系统需要VPN或校园网环境才能正常访问
|
||||
- **电费查询和充值查询需要先绑定房间**，否则会返回400错误
|
||||
- 访问`/go`端点会返回302重定向，系统会自动处理并提取JSESSIONID
|
||||
@@ -1,18 +0,0 @@
|
||||
---
|
||||
layout: page
|
||||
title: LoveACE API 文档
|
||||
description: 基于 OpenAPI 3.1 规范的交互式 API 文档
|
||||
---
|
||||
|
||||
<script setup>
|
||||
import { onMounted } from 'vue'
|
||||
|
||||
onMounted(() => {
|
||||
// 为当前页面添加特殊的CSS类，用于样式定制
|
||||
document.body.classList.add('api-page')
|
||||
})
|
||||
</script>
|
||||
|
||||
<div class="api-docs-container">
|
||||
<SwaggerUI />
|
||||
</div>
|
||||
232
docs/config.md
232
docs/config.md
@@ -1,232 +0,0 @@
|
||||
# 配置指南
|
||||
|
||||
LoveACE使用JSON格式的配置文件来管理各种设置。本文档详细介绍了所有可用的配置选项。
|
||||
|
||||
## 配置文件位置
|
||||
|
||||
配置文件应位于项目根目录下，命名为`config.json`。您可以从`config.example.json`复制并修改。
|
||||
|
||||
## 完整配置示例
|
||||
|
||||
```json
|
||||
{
|
||||
"database": {
|
||||
"url": "mysql+aiomysql://username:password@host:port/database",
|
||||
"echo": false,
|
||||
"pool_size": 10,
|
||||
"max_overflow": 20,
|
||||
"pool_timeout": 30,
|
||||
"pool_recycle": 3600
|
||||
},
|
||||
"aufe": {
|
||||
"default_timeout": 30,
|
||||
"max_retries": 3,
|
||||
"max_reconnect_retries": 2,
|
||||
"activity_timeout": 300,
|
||||
"monitor_interval": 60,
|
||||
"retry_base_delay": 1.0,
|
||||
"retry_max_delay": 60.0,
|
||||
"retry_exponential_base": 2.0,
|
||||
"uaap_base_url": "http://uaap-aufe-edu-cn.vpn2.aufe.edu.cn:8118/cas",
|
||||
"uaap_login_url": "http://uaap-aufe-edu-cn.vpn2.aufe.edu.cn:8118/cas/login?service=http%3A%2F%2Fjwcxk2.aufe.edu.cn%2Fj_spring_cas_security_check",
|
||||
"default_headers": {
|
||||
"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"
|
||||
}
|
||||
},
|
||||
"s3": {
|
||||
"access_key_id": "YOUR_ACCESS_KEY_ID",
|
||||
"secret_access_key": "YOUR_SECRET_ACCESS_KEY",
|
||||
"endpoint_url": null,
|
||||
"region_name": "us-east-1",
|
||||
"bucket_name": "YOUR_BUCKET_NAME",
|
||||
"use_ssl": true,
|
||||
"signature_version": "s3v4"
|
||||
},
|
||||
"log": {
|
||||
"level": "INFO",
|
||||
"format": "<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",
|
||||
"file_path": "logs/app.log",
|
||||
"rotation": "10 MB",
|
||||
"retention": "30 days",
|
||||
"compression": "zip",
|
||||
"backtrace": true,
|
||||
"diagnose": true,
|
||||
"console_output": true,
|
||||
"additional_loggers": [
|
||||
{
|
||||
"file_path": "logs/debug.log",
|
||||
"level": "DEBUG",
|
||||
"rotation": "10 MB"
|
||||
},
|
||||
{
|
||||
"file_path": "logs/error.log",
|
||||
"level": "ERROR",
|
||||
"rotation": "10 MB"
|
||||
}
|
||||
]
|
||||
},
|
||||
"app": {
|
||||
"title": "LoveAC API",
|
||||
"description": "LoveACAPI API",
|
||||
"version": "1.0.0",
|
||||
"debug": false,
|
||||
"cors_allow_origins": ["*"],
|
||||
"cors_allow_credentials": true,
|
||||
"cors_allow_methods": ["*"],
|
||||
"cors_allow_headers": ["*"],
|
||||
"host": "0.0.0.0",
|
||||
"port": 8000,
|
||||
"workers": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 配置项详解
|
||||
|
||||
### 数据库配置 (database)
|
||||
|
||||
| 参数 | 类型 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| `url` | string | - | 数据库连接URL，支持MySQL、SQLite等 |
|
||||
| `echo` | boolean | false | 是否打印SQL语句到日志 |
|
||||
| `pool_size` | integer | 10 | 连接池大小 |
|
||||
| `max_overflow` | integer | 20 | 连接池最大溢出数量 |
|
||||
| `pool_timeout` | integer | 30 | 获取连接超时时间（秒） |
|
||||
| `pool_recycle` | integer | 3600 | 连接回收时间（秒） |
|
||||
|
||||
#### 数据库URL格式
|
||||
|
||||
**MySQL**:
|
||||
```
|
||||
mysql+aiomysql://用户名:密码@主机:端口/数据库名
|
||||
```
|
||||
|
||||
**SQLite**:
|
||||
```
|
||||
sqlite+aiosqlite:///path/to/database.db
|
||||
```
|
||||
|
||||
### AUFE配置 (aufe)
|
||||
|
||||
安徽财经大学教务系统相关配置。
|
||||
|
||||
| 参数 | 类型 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| `default_timeout` | integer | 30 | 默认请求超时时间（秒） |
|
||||
| `max_retries` | integer | 3 | 最大重试次数 |
|
||||
| `max_reconnect_retries` | integer | 2 | 最大重连次数 |
|
||||
| `activity_timeout` | integer | 300 | 活动超时时间（秒） |
|
||||
| `monitor_interval` | integer | 60 | 监控间隔（秒） |
|
||||
| `retry_base_delay` | float | 1.0 | 重试基础延迟（秒） |
|
||||
| `retry_max_delay` | float | 60.0 | 重试最大延迟（秒） |
|
||||
| `retry_exponential_base` | float | 2.0 | 重试指数基数 |
|
||||
| `uaap_base_url` | string | - | UAAP基础URL |
|
||||
| `uaap_login_url` | string | - | UAAP登录URL |
|
||||
| `default_headers` | object | - | 默认HTTP请求头 |
|
||||
|
||||
### S3存储配置 (s3)
|
||||
|
||||
用于文件存储的S3兼容服务配置。
|
||||
|
||||
| 参数 | 类型 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| `access_key_id` | string | - | S3访问密钥ID |
|
||||
| `secret_access_key` | string | - | S3访问密钥 |
|
||||
| `endpoint_url` | string | null | 自定义端点URL（用于S3兼容服务） |
|
||||
| `region_name` | string | us-east-1 | 区域名称 |
|
||||
| `bucket_name` | string | - | 存储桶名称 |
|
||||
| `use_ssl` | boolean | true | 是否使用SSL |
|
||||
| `signature_version` | string | s3v4 | 签名版本 |
|
||||
|
||||
### 日志配置 (log)
|
||||
|
||||
| 参数 | 类型 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| `level` | string | INFO | 日志级别 |
|
||||
| `format` | string | - | 日志格式 |
|
||||
| `file_path` | string | logs/app.log | 主日志文件路径 |
|
||||
| `rotation` | string | 10 MB | 日志轮转大小 |
|
||||
| `retention` | string | 30 days | 日志保留时间 |
|
||||
| `compression` | string | zip | 压缩格式 |
|
||||
| `backtrace` | boolean | true | 是否包含回溯信息 |
|
||||
| `diagnose` | boolean | true | 是否包含诊断信息 |
|
||||
| `console_output` | boolean | true | 是否输出到控制台 |
|
||||
| `additional_loggers` | array | - | 额外的日志记录器配置 |
|
||||
|
||||
#### 日志级别
|
||||
|
||||
- `DEBUG`: 调试信息
|
||||
- `INFO`: 一般信息
|
||||
- `WARNING`: 警告信息
|
||||
- `ERROR`: 错误信息
|
||||
- `CRITICAL`: 严重错误
|
||||
|
||||
### 应用配置 (app)
|
||||
|
||||
| 参数 | 类型 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| `title` | string | LoveAC API | 应用标题 |
|
||||
| `description` | string | - | 应用描述 |
|
||||
| `version` | string | 1.0.0 | 应用版本 |
|
||||
| `debug` | boolean | false | 是否启用调试模式 |
|
||||
| `cors_allow_origins` | array | ["*"] | 允许的CORS源 |
|
||||
| `cors_allow_credentials` | boolean | true | 是否允许携带凭证 |
|
||||
| `cors_allow_methods` | array | ["*"] | 允许的HTTP方法 |
|
||||
| `cors_allow_headers` | array | ["*"] | 允许的HTTP头 |
|
||||
| `host` | string | 0.0.0.0 | 绑定主机 |
|
||||
| `port` | integer | 8000 | 绑定端口 |
|
||||
| `workers` | integer | 1 | 工作进程数 |
|
||||
|
||||
## 环境特定配置
|
||||
|
||||
### 开发环境
|
||||
|
||||
```json
|
||||
{
|
||||
"app": {
|
||||
"debug": true,
|
||||
"workers": 1
|
||||
},
|
||||
"log": {
|
||||
"level": "DEBUG",
|
||||
"console_output": true
|
||||
},
|
||||
"database": {
|
||||
"echo": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 生产环境
|
||||
|
||||
```json
|
||||
{
|
||||
"app": {
|
||||
"debug": false,
|
||||
"workers": 4,
|
||||
"cors_allow_origins": ["https://yourdomain.com"]
|
||||
},
|
||||
"log": {
|
||||
"level": "INFO",
|
||||
"console_output": false
|
||||
},
|
||||
"database": {
|
||||
"echo": false,
|
||||
"pool_size": 20
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 配置验证
|
||||
|
||||
启动应用时，系统会自动验证配置文件的格式和必需参数。如果配置有误，应用将无法启动并显示相应的错误信息。
|
||||
|
||||
## 动态配置
|
||||
|
||||
某些配置项支持运行时修改，无需重启服务：
|
||||
|
||||
- 日志级别
|
||||
- CORS设置
|
||||
- 部分AUFE配置
|
||||
|
||||
动态配置修改可通过管理API进行（需要管理员权限）。
|
||||
@@ -1,5 +0,0 @@
|
||||
# 贡献指南
|
||||
|
||||
感谢您对LoveACE项目的关注！我们欢迎所有形式的贡献，包括但不限于代码贡献、文档改进、问题报告和功能建议。
|
||||
|
||||
## In Progress
|
||||
@@ -1,5 +0,0 @@
|
||||
# 部署指南
|
||||
|
||||
本指南介绍如何在生产环境中部署LoveACE教务系统自动化工具。
|
||||
|
||||
## In Progress
|
||||
@@ -1,119 +0,0 @@
|
||||
# 免责声明
|
||||
|
||||
## 重要声明
|
||||
|
||||
**请在使用LoveACE（以下简称"本软件"）之前仔细阅读本免责声明。使用本软件即表示您已阅读、理解并同意接受本声明的所有条款。**
|
||||
|
||||
## 软件性质与用途
|
||||
|
||||
1. **教育目的**: 本软件是为教育和学习目的而开发的开源项目，旨在帮助学生简化教务系统操作流程。
|
||||
|
||||
2. **个人使用**: 本软件仅供个人学习和使用，不得用于任何商业目的。
|
||||
|
||||
3. **实验性质**: 本软件处于开发阶段，可能存在功能不完善、数据不准确等问题。
|
||||
|
||||
## 使用风险与责任
|
||||
|
||||
### 用户责任
|
||||
|
||||
1. **合规使用**: 用户有责任确保使用本软件的行为符合所在地区的法律法规以及学校的相关规定。
|
||||
|
||||
2. **账户安全**: 用户应妥善保管自己的账户信息，因账户信息泄露造成的损失由用户自行承担。
|
||||
|
||||
3. **数据备份**: 用户应自行备份重要数据，开发者不对数据丢失承担责任。
|
||||
|
||||
4. **风险评估**: 用户在使用本软件前应充分评估可能的风险，并自行决定是否使用。
|
||||
|
||||
### 开发者免责
|
||||
|
||||
1. **不保证性**: 开发者不保证本软件的功能完整性、准确性、可靠性或及时性。
|
||||
|
||||
2. **服务中断**: 开发者不对因软件故障、网络问题、服务器维护等原因导致的服务中断承担责任。
|
||||
|
||||
3. **数据损失**: 开发者不对使用本软件过程中可能出现的数据丢失、损坏或泄露承担责任。
|
||||
|
||||
4. **第三方影响**: 开发者不对因第三方服务（如学校教务系统）变更而导致的软件功能异常承担责任。
|
||||
|
||||
## 技术限制
|
||||
|
||||
1. **兼容性**: 本软件可能无法与所有系统环境兼容，用户应在支持的环境中使用。
|
||||
|
||||
2. **性能表现**: 软件的性能表现可能因硬件配置、网络环境等因素而有所差异。
|
||||
|
||||
3. **功能限制**: 本软件的功能可能受到目标系统的限制，某些功能可能无法正常使用。
|
||||
|
||||
## 隐私与数据安全
|
||||
|
||||
1. **数据收集**: 本软件可能收集必要的用户数据以提供服务，但不会收集与服务无关的个人信息。
|
||||
|
||||
2. **数据存储**: 用户数据存储在用户自行配置的数据库中，开发者不保存用户的敏感信息。
|
||||
|
||||
3. **数据传输**: 数据传输过程中可能存在被截获的风险，用户应采取适当的安全措施。
|
||||
|
||||
4. **第三方访问**: 开发者承诺不会主动向第三方泄露用户数据，但不能保证在所有情况下数据的绝对安全。
|
||||
|
||||
## 法律合规
|
||||
|
||||
1. **遵守法律**: 用户使用本软件时应遵守所在地区的相关法律法规。
|
||||
|
||||
2. **学校规定**: 用户应确保使用本软件的行为符合所在学校（此处指安徽财经大学）的规章制度（详阅最新版安徽财经大学本科生学生手册）。
|
||||
|
||||
3. **禁止行为**:
|
||||
- 不得使用本软件进行任何违法活动
|
||||
- 不得利用本软件进行恶意攻击或破坏行为
|
||||
- 不得将本软件用于商业目的
|
||||
- 不得传播或分享他人的账户信息
|
||||
|
||||
## 知识产权
|
||||
|
||||
1. **开源许可**: 本软件基于MIT许可证开源，用户应遵守相关许可条款。
|
||||
|
||||
2. **版权声明**: 本软件的版权归原作者所有，未经授权不得用于商业用途。
|
||||
|
||||
3. **商标权**: 涉及的第三方商标权归其所有者所有，本软件的使用不代表对这些商标的任何权利主张。
|
||||
|
||||
## 服务变更与终止
|
||||
|
||||
1. **功能变更**: 开发者保留随时修改、升级或终止软件功能的权利，恕不另行通知。
|
||||
|
||||
2. **服务终止**: 开发者可能因技术、法律或其他原因终止软件服务，用户应提前做好数据备份。
|
||||
|
||||
3. **协议更新**: 本免责声明可能随时更新，建议用户定期查看最新版本。
|
||||
|
||||
## 争议解决
|
||||
|
||||
1. **友好协商**: 因使用本软件产生的争议，双方应首先通过友好协商解决。
|
||||
|
||||
2. **法律途径**: 如协商无果，争议应按照开发者所在地的法律法规通过法律途径解决。
|
||||
|
||||
## 紧急情况处理
|
||||
|
||||
如果在使用过程中遇到以下情况，请立即停止使用：
|
||||
|
||||
1. 收到学校或相关部门的警告
|
||||
2. 发现账户异常或疑似被盗用
|
||||
3. 软件出现严重错误或异常行为
|
||||
4. 怀疑数据泄露或安全问题
|
||||
|
||||
## 联系方式
|
||||
|
||||
如果您对本免责声明有任何疑问，或在使用过程中遇到问题，请通过以下方式联系：
|
||||
|
||||
- **邮箱**: sibuxiang@proton.me
|
||||
- **GitHub Issues**: [https://github.com/LoveACE-Team/LoveACE/issues](https://github.com/LoveACE-Team/LoveACE/issues)
|
||||
|
||||
## 最终条款
|
||||
|
||||
1. **完整协议**: 本免责声明构成完整的协议，取代之前的所有口头或书面协议。
|
||||
|
||||
2. **协议效力**: 如本协议的任何条款被认定为无效或不可执行，其余条款仍然有效。
|
||||
|
||||
3. **生效时间**: 本免责声明自用户首次使用本软件时生效。
|
||||
|
||||
---
|
||||
|
||||
**最后更新时间**: 2025/8/3
|
||||
|
||||
**版本**: v1.0
|
||||
|
||||
**请注意**: 本免责声明可能会不定期更新，继续使用本软件即表示您接受更新后的条款。
|
||||
@@ -1,96 +0,0 @@
|
||||
# 快速开始
|
||||
|
||||
本指南将帮助您快速设置并运行LoveACE教务系统自动化工具。
|
||||
|
||||
## 前置条件
|
||||
|
||||
在开始之前，请确保您的系统已安装：
|
||||
|
||||
- **Python 3.12**
|
||||
- **PDM** (Python Dependency Manager)
|
||||
- **MySQL** 或其他支持的数据库
|
||||
|
||||
## 安装步骤
|
||||
|
||||
### 1. 克隆项目
|
||||
|
||||
```bash
|
||||
git clone https://github.com/LoveACE-Team/LoveACE.git
|
||||
cd LoveACE
|
||||
```
|
||||
|
||||
### 2. 安装依赖
|
||||
|
||||
使用PDM安装项目依赖：
|
||||
|
||||
```bash
|
||||
pdm install
|
||||
```
|
||||
|
||||
### 3. 配置环境
|
||||
|
||||
启动 App 生成配置文件并编辑：
|
||||
|
||||
```bash
|
||||
python main.py
|
||||
```
|
||||
|
||||
编辑`config.json`文件，配置以下关键参数：
|
||||
|
||||
```json
|
||||
{
|
||||
"database": {
|
||||
"url": "mysql+aiomysql://username:password@host:port/database"
|
||||
},
|
||||
"app": {
|
||||
"host": "0.0.0.0",
|
||||
"port": 8000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 初始化数据库
|
||||
|
||||
项目会在首次运行时自动创建数据库表结构。
|
||||
|
||||
### 5. 启动服务
|
||||
|
||||
```bash
|
||||
python main.py
|
||||
```
|
||||
|
||||
## 下一步
|
||||
|
||||
- 查看 [配置指南](/config) 了解详细配置选项
|
||||
- 阅读 [API文档](/api/) 了解可用接口
|
||||
- 参考 [部署指南](/deploy) 进行生产环境部署
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 数据库连接失败
|
||||
|
||||
检查`config.json`中的数据库配置是否正确，确保：
|
||||
- 数据库服务已启动
|
||||
- 用户名密码正确
|
||||
- 网络连接正常
|
||||
|
||||
### 端口被占用
|
||||
|
||||
如果8000端口被占用，可以在配置文件中修改端口：
|
||||
|
||||
```json
|
||||
{
|
||||
"app": {
|
||||
"port": 8080
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 依赖安装失败
|
||||
|
||||
确保使用Python 3.12，并尝试清理缓存：
|
||||
|
||||
```bash
|
||||
pdm cache clear
|
||||
pdm install
|
||||
```
|
||||
@@ -1,91 +0,0 @@
|
||||
---
|
||||
layout: home
|
||||
|
||||
hero:
|
||||
name: "LoveACE"
|
||||
text: "教务系统自动化工具"
|
||||
tagline: "简化学生教务操作，提高使用效率"
|
||||
image:
|
||||
src: /images/logo.jpg
|
||||
alt: LoveACE Logo
|
||||
actions:
|
||||
- theme: brand
|
||||
text: 快速开始
|
||||
link: /getting-started
|
||||
- theme: alt
|
||||
text: API文档
|
||||
link: /api/
|
||||
|
||||
features:
|
||||
- icon: 🔐
|
||||
title: 用户认证与授权
|
||||
details: 支持邀请码注册和用户登录，确保系统安全
|
||||
- icon: 📚
|
||||
title: 教务系统集成
|
||||
details: 学业信息查询、培养方案信息查询、课程列表查询
|
||||
- icon: ⭐
|
||||
title: 自动评教系统（开发中）
|
||||
details: 支持评教任务的初始化、开始、暂停、终止和状态查询
|
||||
- icon: 💯
|
||||
title: 爱安财系统
|
||||
details: 总分信息查询和分数明细列表查询
|
||||
- icon: 🚀
|
||||
title: 高性能架构
|
||||
details: 基于FastAPI和异步SQLAlchemy构建，支持高并发访问
|
||||
- icon: 📖
|
||||
title: 完整文档
|
||||
details: 提供详细的API文档、配置指南和部署教程
|
||||
---
|
||||
|
||||
## 技术栈
|
||||
|
||||
- **后端框架**: FastAPI
|
||||
- **数据库ORM**: SQLAlchemy (异步)
|
||||
- **HTTP客户端**: 基于aiohttp的自定义客户端
|
||||
- **日志系统**: richuru (rich + loguru)
|
||||
|
||||
## 快速体验
|
||||
|
||||
```bash
|
||||
# 克隆项目
|
||||
git clone https://github.com/LoveACE-Team/LoveACE.git
|
||||
cd LoveACE
|
||||
|
||||
# 安装依赖
|
||||
pdm install
|
||||
|
||||
# 配置数据库
|
||||
启动 App 生成配置文件并编辑：
|
||||
|
||||
```bash
|
||||
python main.py
|
||||
```
|
||||
|
||||
编辑`config.json`文件，配置以下关键参数：
|
||||
|
||||
```json
|
||||
{
|
||||
"database": {
|
||||
"url": "mysql+aiomysql://username:password@host:port/database"
|
||||
},
|
||||
"app": {
|
||||
"host": "0.0.0.0",
|
||||
"port": 8000
|
||||
}
|
||||
}
|
||||
|
||||
# 启动服务
|
||||
uvicorn main:app --reload
|
||||
```
|
||||
|
||||
## 社区
|
||||
|
||||
如果您有任何问题或建议，欢迎：
|
||||
|
||||
- 📝 [提交Issue](https://github.com/LoveACE-Team/LoveACE/issues)
|
||||
- 🔀 [发起Pull Request](https://github.com/LoveACE-Team/LoveACE/pulls)
|
||||
- 💬 加入讨论组
|
||||
|
||||
## 许可证
|
||||
|
||||
本项目采用 MIT 许可证开源。详情请查看 [LICENSE](https://github.com/LoveACE-Team/LoveACE/blob/main/LICENSE) 文件。
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 11 KiB |
2758
docs/public/openapi.json
generated
2758
docs/public/openapi.json
generated
File diff suppressed because it is too large
Load Diff
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
Reference in New Issue
Block a user