README

Tianjin college, USTB 学生财务系统 HTTP 客户端（PHP）。
为TJUSTB学生财务收费系统提供面向对象的接口封装：SSO 登录、缴费信息查询、订单记录、学分学费、缓交申请、补助发放、发票申请与查询等。

包名：airmole/tjustb-finasys
许可证：GPL-3.0-or-later
运行环境：PHP 8.0+

特性

基于 cURL 的轻量 HTTP 封装，统一超时、Header、Cookie 处理
提供简洁门面类 Airmole\TjustbFinasys\Finasys 聚合常用能力
标准 PSR-4 自动加载
环境配置优先级明确：环境变量 > .env 文件 > 默认值
统一异常类型 Airmole\TjustbFinasys\Exception\Exception

环境要求

PHP >= 8.0
扩展：ext-curl、ext-json、ext-openssl

安装

通过 Composer 安装：

composer require airmole/tjustb-finasys

快速开始

建议通过门面类 Finasys 使用，大部分接口只需要完成一次 SSO 登录（获取 Cookie）后调用。

<?php

use Airmole\TjustbFinasys\Finasys;

// 1) 可选：通过环境变量或 .env 配置财务系统地址与超时（见下方“配置”）
// putenv('FINASYS_URL=http://221.238.213.131:8809');
// putenv('FINASYS_TIMEOUT=8');

// 2) SSO 免密登录（需要上游系统颁发的 ticket）
$client = new Finasys();
$login = $client->ssoLogin($ticket); // $ticket 由外部系统提供
if ($login['code'] !== 200) {
    // 登录异常，$login['data'] 为错误消息或响应内容
    throw new RuntimeException('登录失败：' . ($login['data'] ?? '未知错误'));
}

// 3) 检查登录态
if (!$client->isLogined()) {
    throw new RuntimeException('登录态失效');
}

// 4) 获取个人信息
$profile = $client->profile();
// $profile['code'] === 200 且 $profile['data'] 为数组

// 5) 查询待缴/已缴费业务
$list = $client->queryFeeInfo(showPaid: true, pageIndex: 0, pageSize: 10);

// 6) 更多能力见下文 API 概览

也可在已有 Cookie 的场景直连（跳过 ssoLogin），例如：

<?php

use Airmole\TjustbFinasys\Finasys;

// 从字符串解析 Cookie
$client = new Finasys();
$cookieArray = $client->parseCookieString('ASP.NET_SessionId=xxxxxx'); 
$client->cookie = $cookieArray;

// 或直接赋值
// $client->cookie = ['ASP.NET_SessionId' => 'xxxxxx'];

$ok = $client->isLogined();

配置

Base 类支持以下配置项，优先级：环境变量 > .env 文件（默认路径见下） > 内置默认值。

FINASYS_URL：财务系统基地址
- 默认：http://221.238.213.131:8809
FINASYS_TIMEOUT：请求超时时间（秒）
- 默认：5
FINASYS_ENV：.env 文件路径
- 默认：未设置时使用“项目根目录/.env”（即 dirname(__DIR__) . '/.env'）

配置方式举例：

环境变量（优先）：

export FINASYS_URL="http://example.com"
export FINASYS_TIMEOUT=8

.env 文件（键值对，忽略空行和以 # 开头注释）：

FINASYS_URL=http://example.com
FINASYS_TIMEOUT=8

代码中动态设置（可选）：

$base = new \Airmole\TjustbFinasys\Base();
$base->setConfigPath('/path/to/.env');
$base->setFinasysUrl('http://example.com');

API 概览

所有方法返回统一结构：

['code' => int, 'data' => mixed]
code 一般为 HTTP 状态码（成功 200）；data 为字符串或解码后的数组（库内在可解析为 JSON 时已自动解码）

异常：当必要前置条件缺失或流程错误（如缺少 Cookie、登录失败）时，抛出 Airmole\TjustbFinasys\Exception\Exception。

门面类 Airmole\TjustbFinasys\Finasys：

登录与用户
- ssoLogin(string $ticket): array SSO 免密登录，成功时内部保存 Cookie
- isLogined(): bool 判断登录态
- profile(): array 获取个人信息
- parseCookieString(string $cookieString): array 将 Cookie: 或 cookie 字符串解析为数组
发票
- getBillingProbjects(string $year = '', int $stuType = 0, int $pageIndex = 0, int $pageSize = 10, string $sortField = '', string $sortOrder = ''): array
- getOpenBillAppliedData(int $stuType = 0, int $pageIndex = 0, int $pageSize = 10, string $sortField = '', string $sortOrder = ''): array
- getOpenBillAppliedDetails(string $cfid): array
学分学费
- credittuitionQuery(bool $showPaid = true, int $pageIndex = 0, int $pageSize = 10, string $sortField = '', string $sortOrder = ''): array
缓交
- queryPersonDeferFeeInfo(bool $record = false, int $pageIndex = 0, int $pageSize = 10, string $sortField = '', string $sortOrder = ''): array
- getDeferRecords(int $pageIndex = 0, int $pageSize = 10, string $sortField = '', string $sortOrder = ''): array
缴费业务与记录
- queryFeeInfo(bool $showPaid = true, int $pageIndex = 0, int $pageSize = 10, string $sortField = '', string $sortOrder = ''): array
- getPaidRecordSearchConditions(): array
- queryTreePaidRecords(int $pageIndex = 0, int $pageSize = 10, array $conditions = [], string $sortField = '', string $sortOrder = ''): array
订单
- getOrderRecord(int $pageIndex = 0, int $pageSize = 10): array
自助缴费
- querySelfChargeRecords(int $pageIndex = 0, int $pageSize = 10, string $sortField = '', string $sortOrder = ''): array
补助
- getSubidyListInfo(int $pageIndex = 0, int $pageSize = 10, bool $showUnreleased = true): array

底层类说明（可直接使用，需先设置 $cookie）：

Login：ssoLogin、isLogined、profile
Bill：发票相关
Credittuition：学分学费
Defer：缓交申请与记录
FeeInfo：缴费业务与记录
Order：订单记录
SelfCharge：自助缴费
Subidy：补助信息
Base：HTTP、Cookie、配置等通用能力

Cookie 使用要点：

登录成功后内部将 ASP.NET_SessionId 注入 Cookie
也可使用 parseCookieString/parseCookieArray 转换
Base 提供 getCookieString()、insertCookie()、parseCookieString()、parseCookieArray() 等工具

返回值与错误处理

网络/协议层：httpRequest 遇到 cURL 错误时返回 ['code' => 0, 'data' => 'cURL Error: ...']
业务异常：如登录失败、缺少 Cookie 等，抛出 Airmole\TjustbFinasys\Exception\Exception
成功：code 通常为 200，data 为字符串或已 JSON 解码的数组（库内已尝试自动解码）

目录结构

.
├── composer.json
└── src
    ├── Base.php
    ├── Bill.php
    ├── Credittuition.php
    ├── Defer.php
    ├── FeeInfo.php
    ├── Finasys.php
    ├── Login.php
    ├── Order.php
    ├── SelfCharge.php
    ├── Subidy.php
    └── Exception
        └── Exception.php

开发与调试

建议在 .env 或环境变量中设置 FINASYS_URL 指向测试/仿真环境
可通过 FINASYS_TIMEOUT 调整接口超时
如果需自定义 .env 路径，设置 FINASYS_ENV=/path/to/.env
避免在代码或日志中泄露 Cookie、ticket 等敏感信息

本库未内置测试命令；如需贡献测试，请提交 PR 并附加最小可复现的伪造响应或录制桩。

常见问题

登录 302 未携带期望的 Location
- 确认 ticket 有效；Login::ssoLogin 期望 Location: /PayList.html，ticket值获取可使用 airmole/tjustb-authsys->visitOtherSystem('http://10.2.254.80:8809/Login/JinZhi_Login')方法获取
登录成功但 isLogined() 返回 false
- 检查 Cookie 是否正确注入（ASP.NET_SessionId 是否存在/未过期）
data 未 JSON 解码
- 目标接口可能返回纯文本；请按需手动解析

许可证

GPL-3.0-or-later

致谢

Author: Airmole admin@airmole.cn
本项目仅用于与天津学院（北科大）学生财务系统进行集成开发与学习，请遵守相关使用与数据安全规范。

airmole / tjustb-finasys

Maintainers

Details