正方教务系统完整解决方案 - 微信小程序 + 后端 API

GitHub Stars GitHub Stars License TypeScript Python

项目简介

这是一个完整的正方教务系统第三方解决方案，包含微信小程序前端和 Python 后端 API 服务。该项目为学生提供便捷的教务管理服务，支持课表查询、成绩管理、选课系统等核心功能。

⚠️ 重要说明：本项目为第三方开发的非官方 API，仅供学习交流使用。

🔗 前端项目: ZFJW-miniprogram
🔗 后端项目: ZFJW-backend

项目架构

整体架构图

┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│                     │    │                     │    │                     │
│   微信小程序端       │◄──►│   Python 后端 API   │◄──►│   正方教务系统       │
│                     │    │                     │    │                     │
│  - TypeScript 100%  │    │  - Python 99.6%    │    │  - 各高校教务系统    │
│  - 本地数据缓存      │    │  - Flask 框架       │    │  - 第三方接口调用    │
│  - 隐私保护设计      │    │  - RESTful API     │    │  - 数据获取与解析    │
│                     │    │                     │    │                     │
└─────────────────────┘    └─────────────────────┘    └─────────────────────┘

技术栈对比

组件 前端小程序 后端 API
语言 TypeScript (100%) Python (99.6%)
框架 微信小程序原生 Flask 2.0+
特性 本地缓存、隐私保护 RESTful API、多校支持
部署 微信小程序平台 独立服务器/Docker

核心功能

🎯 完整功能矩阵

功能模块 前端实现 后端支持 状态
用户认证 ✅ 登录界面、密码管理 ✅ 验证码登录、Session 管理 已完成
个人信息 ✅ 信息展示、资料管理 ✅ 学生信息查询 已完成
智能课表 ✅ 周视图、手势滑动 ✅ 课表查询 已完成
成绩管理 ✅ 多学期查询、GPA 计算 ✅ 成绩统计分析 已完成
考试安排 ✅ 考试时间展示 ✅ 考试信息查询 已完成
选课系统 ✅ 已选课程显示 🚧 选课操作开发中 部分完成
教学评价 ✅ 一键评教功能 ✅ 评价数据处理 已完成
通知公告 ✅ 通知展示 ✅ 消息推送 已完成
空教室查询 🚧 界面开发中 🚧 查询接口开发中 计划中

🔥 核心特性

前端特性

  • 🎨 现代化界面: 简洁美观的用户界面设计
  • 📱 响应式布局: 适配不同屏幕尺寸
  • 💾 智能缓存: 离线数据查看，减少网络请求
  • 🔒 隐私保护: 数据本地存储，不上传云端
  • ⚡ 流畅体验: 手势操作，快速响应

后端特性

  • 🚀 高性能: 基于 Flask 的轻量级架构
  • 🏫 多校支持: 灵活的学校配置系统
  • 🔐 安全可靠: 完善的认证和会话管理
  • 🐳 容器化: 支持 Docker 部署
  • 📊 数据处理: 智能的数据解析和统计

详细功能介绍

📅 智能课表系统

前端实现：

// 课表周视图组件
interface ScheduleWeekView {
  currentWeek: number;
  scheduleData: CourseInfo[];
  weekDays: string[];
  timeSlots: TimeSlot[];
}

// 手势滑动切换周次
const handleSwipeChange = (e: any) => {
  const { current } = e.detail;
  setCurrentWeek(current + 1);
  loadScheduleData(current + 1);
};

后端 API：

@app.route('/api/schedule', methods=['GET'])
def get_schedule():
    """获取课表数据"""
    week = request.args.get('week', 1)
    try:
        schedule_data = zfn_api.get_schedule(week)
        return jsonify({
            'code': 200,
            'data': schedule_data,
            'message': 'success'
        })
    except Exception as e:
        return jsonify({
            'code': 500,
            'message': str(e)
        })

📊 成绩管理系统

前端功能：

  • 多学期成绩查询
  • GPA 自动计算
  • 成绩统计图表
  • 学分统计展示

后端处理：

def calculate_gpa(grades_data):
    """计算 GPA"""
    total_credits = 0
    total_grade_points = 0
    
    for grade in grades_data:
        credit = float(grade.get('credit', 0))
        score = float(grade.get('score', 0))
        grade_point = score_to_gpa(score)
        
        total_credits += credit
        total_grade_points += credit * grade_point
    
    return total_grade_points / total_credits if total_credits > 0 else 0

🔐 安全认证机制

前端实现：

// 登录管理器
class LoginManager {
  private static instance: LoginManager;
  
  // 登录验证
  async login(username: string, password: string, captcha: string) {
    const loginData = {
      username,
      password: this.encryptPassword(password),
      captcha
    };
    
    const response = await api.post('/login', loginData);
    if (response.code === 200) {
      this.saveLoginInfo(response.data);
      return true;
    }
    return false;
  }
  
  // 密码加密
  private encryptPassword(password: string): string {
    // 实现密码加密逻辑
    return btoa(password);
  }
}

后端验证：

@app.route('/api/login', methods=['POST'])
def login():
    """用户登录验证"""
    data = request.get_json()
    username = data.get('username')
    password = data.get('password')
    captcha = data.get('captcha')
    
    try:
        # 验证登录信息
        login_result = zfn_api.login(username, password, captcha)
        if login_result['success']:
            # 创建会话
            session['user_id'] = username
            session['login_time'] = datetime.now()
            
            return jsonify({
                'code': 200,
                'data': login_result['data'],
                'message': '登录成功'
            })
        else:
            return jsonify({
                'code': 401,
                'message': login_result['message']
            })
    except Exception as e:
        return jsonify({
            'code': 500,
            'message': f'登录失败: {str(e)}'
        })

部署指南

🖥️ 后端部署

本地开发环境

# 1. 克隆后端项目
git clone https://github.com/drfccv/ZFJW-backend.git
cd ZFJW-backend

# 2. 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# 3. 安装依赖
pip install -r requirements.txt

# 4. 配置学校信息
cp school_config.example.json school_config.json
# 编辑 school_config.json 添加你的学校配置

# 5. 启动服务
python app.py

Docker 部署

# 1. 构建镜像
docker build -t zfjw-backend .

# 2. 运行容器
docker run -d -p 5000:5000 --name zfjw-backend zfjw-backend

# 3. 查看日志
docker logs -f zfjw-backend

生产环境部署

# 使用 Gunicorn 部署
pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 app:app

# 或使用 uWSGI
pip install uwsgi
uwsgi --http :5000 --module app:app --processes 4

📱 前端部署

开发环境

# 1. 克隆前端项目
git clone https://github.com/drfccv/ZFJW-miniprogram.git
cd ZFJW-miniprogram

# 2. 安装依赖
npm install

# 3. 配置后端 API 地址
# 修改 utils/config.ts 中的 API_BASE_URL

# 4. 微信开发者工具
# 使用微信开发者工具打开项目目录
# 开启"不校验合法域名"选项

生产环境

# 1. 配置服务器域名
# 在微信小程序后台添加 request 合法域名
# https://your-api-domain.com

# 2. 上传代码
# 使用微信开发者工具上传代码
# 提交审核并发布

学校配置

添加新学校支持

  1. 获取学校教务系统信息
# 访问学校教务系统，获取以下信息：
# - 教务系统 URL
# - 登录接口路径
# - 验证码接口
# - 页面编码格式
  1. 创建学校配置文件
{
  "school_code": "your_school",
  "school_name": "你的学校名称",
  "base_url": "http://jwxt.your-school.edu.cn",
  "login_url": "/jsxsd/xk/LoginToXk",
  "captcha_url": "/jsxsd/verifycode.servlet",
  "encoding": "gbk",
  "timeout": 30,
  "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",
    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
    "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
    "Accept-Encoding": "gzip, deflate",
    "Connection": "keep-alive",
    "Upgrade-Insecure-Requests": "1"
  }
}
  1. 测试配置
# 创建测试脚本
import requests
from school_config import load_school_config

config = load_school_config('your_school')
session = requests.Session()

# 测试登录
response = session.post(
    config['base_url'] + config['login_url'],
    data={
        'userAccount': 'test_username',
        'userPassword': 'test_password',
        'RANDOMCODE': 'test_captcha'
    },
    headers=config['headers']
)

print(f"登录测试结果: {response.status_code}")

常见问题与解决方案

❓ 登录相关问题

Q: 登录失败怎么办？

A: 检查以下几点：
1. 学号密码是否正确
2. 验证码是否正确输入
3. 学校教务系统是否正常运行
4. 网络连接是否稳定
5. 后端服务是否正常启动

Q: 验证码识别不准确？

A: 验证码识别问题：
1. 刷新验证码重新输入
2. 检查验证码图片是否清晰
3. 确认输入的验证码字符正确
4. 如果持续失败，可能需要手动输入

🔧 技术问题

Q: 后端 API 启动失败？

# 检查 Python 版本
python --version  # 需要 3.7+

# 检查依赖安装
pip list | grep Flask

# 检查端口占用
netstat -an | grep 5000
lsof -i :5000  # Linux/Mac

# 查看详细错误日志
python app.py --debug

Q: 小程序无法连接后端？

// 检查 API 地址配置
const API_BASE_URL = 'https://your-api-domain.com';

// 检查网络请求
wx.request({
  url: API_BASE_URL + '/api/health',
  success: (res) => {
    console.log('API 连接正常:', res.data);
  },
  fail: (err) => {
    console.error('API 连接失败:', err);
  }
});

Q: 数据不显示或显示错误？

A: 数据问题排查：
1. 检查登录状态是否有效
2. 确认学期时间设置正确
3. 查看控制台错误日志
4. 验证后端 API 返回数据
5. 清除缓存重新获取数据

安全与隐私

🔒 数据安全措施

  1. 前端安全

    • 敏感数据本地加密存储
    • 不上传个人信息到第三方服务器
    • 支持随时清除本地数据
    • 使用 HTTPS 加密通信

  2. 后端安全

    • 不存储用户密码
    • Session 超时自动清理
    • 请求频率限制
    • 输入数据验证和过滤

  3. 通信安全

    • API 接口使用 HTTPS
    • 数据传输加密
    • 防止中间人攻击
    • 会话令牌管理

🛡️ 隐私保护承诺

✅ 不收集用户个人隐私信息
✅ 不进行用户行为跟踪分析
✅ 数据仅用于教务查询功能
✅ 支持用户随时删除数据
✅ 遵循最小数据收集原则
✅ 本地存储优先原则

贡献指南

🤝 参与贡献

我们欢迎所有形式的贡献！

贡献类型：

  • 🐛 Bug 修复
  • ✨ 新功能开发
  • 📝 文档完善
  • 🏫 学校配置添加
  • 🧪 测试用例编写
  • 🎨 UI/UX 改进

贡献流程：

  1. Fork 项目到个人账号
  2. 创建功能分支 git checkout -b feature/amazing-feature
  3. 提交更改 git commit -m 'Add amazing feature'
  4. 推送分支 git push origin feature/amazing-feature
  5. 创建 Pull Request

📋 开发规范

代码规范：

# 前端 TypeScript
npm run lint          # 代码检查
npm run format        # 代码格式化

# 后端 Python
pip install black flake8
black .               # 代码格式化
flake8 .              # 代码检查

提交规范：

feat: 新功能
fix: 修复bug
docs: 文档更新
style: 代码格式调整
refactor: 重构代码
test: 测试相关
chore: 其他修改

社区与支持

💬 交流渠道

📧 联系方式

免责声明

⚠️ 重要提醒：

1. 本项目为第三方开发的非官方工具
2. 仅供学习交流和个人使用
3. 请勿用于商业用途或违法活动
4. 使用本项目造成的任何后果由使用者承担
5. 开发者不对数据准确性承担责任
6. 请遵守学校相关规定和法律法规

开源协议

本项目采用 MIT License 开源协议。

致谢

感谢所有贡献者和用户的支持！

  • 感谢微信小程序平台提供的开发环境
  • 感谢 Flask 框架的优秀设计
  • 感谢开源社区的无私奉献
  • 感谢所有提供学校配置的同学

⭐ 如果这个项目对你有帮助，请给我们一个 Star！

Made with ❤️ by drfccv | 最后更新: 2024-12-08