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'）

配置方式举例：

1. 环境变量（优先）：

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

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

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

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

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

所有方法返回统一结构：

• ['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
• 本项目仅用于与天津学院（北科大）学生财务系统进行集成开发与学习，请遵守相关使用与数据安全规范。