OpenSWU

OpenSWU 是一个面向西南大学相关数据访问场景的 Java 库，目标是把登录、基础信息、课表、教室查询、宿舍楼与宿舍水电等能力收敛为可复用的接口。

当前仓库同时包含两条演进中的 API 路线：

• 兼容历史接入方式的统一接口 SwuInterface
• 面向后续扩展的细粒度服务接口，例如 StudentService、CalendarService、ClassroomService、DormitoryUtilityService

这不是一个“所有能力都已经稳定完成”的成熟 SDK，而是一个正在持续演进的集成库。README 以当前仓库中的真实实现状态为准。

目录

• 特性概览
• 当前状态
• 快速开始
• API 概览
• 项目结构
• 开发与测试
• 已知限制
• 贡献指南
• English Summary
• License

特性概览

• 提供旧版统一入口 SwuInterface，适合已有调用方式快速接入。
• 提供更细粒度的服务层接口，便于按业务域拆分实现。
• 已覆盖的能力方向包括：
  • 登录与基础身份信息
  • 课表查询
  • 教学楼/空教室查询
  • 学生信息与部分教务相关查询
  • 宿舍楼列表与宿舍水电信息
• 同时保留不同 provider 的实现，便于逐步迁移和对比。

当前状态

Provider 状态

Provider	当前用途	状态说明
xdbbt	旧版统一接口实现	当前完成度更高，已实现 login、getBaseInfo、getSchedule
zflocal	新版细粒度服务实现为主	覆盖能力更广，但对旧版 SwuInterface 的兼容实现仍未补全

统一接口状态

cn.blue16.swuLayer.SwuInterface 当前定义如下：

public interface SwuInterface {
    LoginResult login(String username, String password) throws LoginFailedException, ConnectionException;
    LoginResult getBaseInfo(String username) throws LoginExpiredException;
    ScheduleResult getSchedule(String username) throws LoginExpiredException;
}

当前仓库中的实现现状：

• cn.blue16.provider.xdbbt.xdbbtImp
  • login: 已实现
  • getBaseInfo: 已实现
  • getSchedule: 已实现
• cn.blue16.provider.zflocal.zflocalImp
  • login: 已实现
  • getBaseInfo: 当前返回 null
  • getSchedule: 当前返回 null

如果你希望以最短路径验证已有功能，优先从 xdbbtImp 开始更稳妥。

细粒度服务接口状态

仓库已经定义并部分实现了以下服务接口：

• CalendarService
• ClassroomService
• CredentialService
• StudentService
• DormitoryBuildingService
• DormitoryUtilityService
• NotificationService

可从仓库中确认到的实现包括：

• CalendarServiceImp
• ClassroomServiceImp
• CredentialServiceImp
• StudentServiceImp
• DormitoryBuildingServiceImp
• DormitoryUtilityServiceImp

这些接口主要位于 zflocal 方向，说明项目正在从“单一大接口”向“服务化接口层”迁移。

快速开始

Maven 依赖

从当前仓库中的 pom.xml 可以确认该模块的坐标为：

<dependency>
    <groupId>cn.blue16</groupId>
    <artifactId>openswu</artifactId>
    <version>2.3.0</version>
</dependency>

最小示例

下面的示例基于当前完成度较高的 xdbbtImp：

import cn.blue16.provider.xdbbt.xdbbtImp;
import cn.blue16.swuLayer.SwuInterface;
import cn.blue16.swuLayer.exception.ConnectionException;
import cn.blue16.swuLayer.exception.LoginExpiredException;
import cn.blue16.swuLayer.exception.LoginFailedException;
import cn.blue16.swuLayer.response.LoginResult;
import cn.blue16.swuLayer.response.ScheduleResult;

public class Demo {
    public static void main(String[] args)
            throws LoginFailedException, ConnectionException, LoginExpiredException {
        SwuInterface client = new xdbbtImp();

        LoginResult profile = client.login("your-student-id", "your-password");
        System.out.println(profile.getName());

        ScheduleResult schedule = client.getSchedule("your-student-id");
        System.out.println(schedule.getRes().size());
    }
}

适合谁用

• 如果你已经基于旧代码使用统一接口，优先看 SwuInterface 和 xdbbtImp
• 如果你准备继续扩展新的校园业务能力，优先看 zflocal 下的服务层接口与实现

API 概览

统一接口

• SwuInterface
  • login
  • getBaseInfo
  • getSchedule

服务层接口

• CredentialService: 负责获取和释放认证凭据
• StudentService: 负责学生信息、课表、成绩、考试安排、学分统计等
• CalendarService: 负责学年学期和教学日历信息
• ClassroomService: 负责空教室与教学楼查询
• DormitoryBuildingService: 负责宿舍楼列表
• DormitoryUtilityService: 负责宿舍水电余额、日结和缴费记录查询

服务层接口已经具备较明确的职责边界，但并不意味着所有实现都已经稳定对外承诺。

项目结构

src/
  main/
    java/cn/blue16/
      provider/
        xdbbt/      # 旧版统一接口的主要实现
        zflocal/    # 新版服务层接口的主要实现
      swuLayer/     # 公共接口、异常和模型定义
  test/
    java/
    resources/

开发与测试

构建前提

当前仓库不能在“只克隆本仓库”的前提下直接独立构建，因为 pom.xml 依赖父工程：

• Parent: cn.blue16:aistudymate:2.3.0
• relativePath: ../pom.xml

这意味着如果本地没有对应父工程，直接执行下面的命令会失败：

mvn compile

因此，开发前请先确认你具备对应的父工程或制品来源。

测试准备

仓库当前的测试并不是纯离线单元测试，而是包含真实上游系统交互的集成性质测试。

你会在仓库中看到：

• src/test/resources/test-credentials.properties.example
• 依赖真实登录流程的测试代码
• 部分依赖真实账号、密码或会话信息的测试逻辑

建议的本地准备方式：

1. 复制 src/test/resources/test-credentials.properties.example
2. 创建 src/test/resources/test-credentials.properties
3. 写入仅供本地调试使用的测试凭据

请不要把真实凭据、会话 token 或宿舍/个人敏感数据提交到仓库。

已知限制

• 当前模块依赖父 POM，无法作为一个裸仓库直接构建通过
• zflocalImp 对旧版 SwuInterface 的兼容尚未完成
• 测试依赖真实校园系统和真实凭据，不适合直接放入公开 CI 运行
• 仓库里存在演进中的接口，实际可用性请以具体实现类为准

贡献指南

欢迎通过 Issue 和 Pull Request 参与改进。

在提交问题时，建议尽量提供：

• 使用的是哪个 provider，例如 xdbbt 或 zflocal
• 调用的是哪个接口或实现类
• 是否依赖真实学号、密码、宿舍信息或上游系统状态
• 复现步骤
• 关键异常堆栈或响应内容

相关入口：

• Issues: https://github.com/Blue16-WangFudi/openswu/issues
• Pull Requests: https://github.com/Blue16-WangFudi/openswu/pulls

English Summary

OpenSWU is a Java library for Southwest University related integrations.

What is included today:

• A legacy unified API: SwuInterface
• A newer service-oriented API surface for credentials, students, calendar, classrooms, and dormitory utilities
• Multiple provider implementations, mainly xdbbt and zflocal

Repository facts worth knowing before you use it:

• xdbbt is currently the more complete implementation for the legacy unified interface
• zflocal contains broader service-oriented work, but not every compatibility path is finished
• The module cannot be built standalone unless the parent POM cn.blue16:aistudymate:2.3.0 is available in your environment
• Tests currently depend on real credentials and live upstream systems

For bug reports and contributions, please use:

• Issues: https://github.com/Blue16-WangFudi/openswu/issues
• Pull Requests: https://github.com/Blue16-WangFudi/openswu/pulls

License

This project is licensed under the GNU Affero General Public License v3.0. See LICENSE for details.