Metadata-Version: 2.4
Name: NXIST-WiFi-Login
Version: 0.1.0
Summary: Low-level Python API for NXIST WiFi portal authentication
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: platformdirs>=4.0
Requires-Dist: requests>=2.31
Requires-Dist: tabulate>=0.9
Requires-Dist: wcwidth>=0.2

# nxist-login

`nxist-login` 是一个用于 NXIST 校园网 WiFi 门户认证的 Python 工具。项目分为两层：

- `nxwifiapi`：底层 API 模块，只封装认证门户 HTTP 请求，不负责 CLI、文件存储或账号管理。
- `nxwificli` / `nxist-login`：命令行工具，负责单账号保存、cookie/session 信息保存、一键登录、状态查看和退出登录。

命令行输出为英文，方便脚本读取；本文档使用中文说明。

## 平台支持

目标支持：

- Windows
- macOS
- Linux

跨平台处理方式：

- 配置文件路径使用 `platformdirs.user_config_dir()` 获取，不硬编码系统路径。
- 配置文件使用 UTF-8 JSON。
- CLI 入口通过 `pyproject.toml` 的 `[project.scripts]` 注册，安装后在 Windows/macOS/Linux 上均由 Python 打包工具生成对应可执行入口。
- 文件路径使用 `pathlib.Path`。
- 表格输出使用 `tabulate`，并开启宽字符模式；列宽计算使用 `wcwidth`，用于兼容中英文混排的套餐名称等内容。
- 配置文件权限在支持的平台上尝试设置为当前用户可读写；不支持时会静默跳过，不影响 Windows 使用。

## 安装

项目使用 `src` 布局。开发环境中推荐在虚拟环境内安装：

```bash
python -m pip install -e .
```

安装后会注册命令：

```bash
nxist-login --help
```

依赖由 `pyproject.toml` 声明：

- `requests`
- `beautifulsoup4`
- `platformdirs`
- `tabulate`
- `wcwidth`

## 配置文件

查看当前平台上的配置文件路径：

```bash
nxist-login config-path
```

示例路径：

- Windows: `C:\Users\<User>\AppData\Local\nxist-login\nxist-login\config.json`
- macOS: `/Users/<User>/Library/Application Support/nxist-login/config.json`
- Linux: `/home/<User>/.config/nxist-login/config.json`

配置文件为 JSON，保存内容包括：

- 单个账号的用户名和密码
- 是否允许自动重登
- `requests` cookie 信息
- 最近一次登录后的用户 IP、设备 IP、用户 MAC 等认证信息

注意：当前 CLI 按需求使用 JSON 保存账号信息，密码会以明文形式保存在本机配置文件中。请不要把配置文件提交到仓库，也不要在共享机器上保存账号。

## 常用命令

保存单个账号：

```bash
nxist-login save -u USERNAME
```

也可以直接通过参数提供密码：

```bash
nxist-login save -u USERNAME -p PASSWORD
```

保存账号但禁用自动重登策略：

```bash
nxist-login save -u USERNAME --no-auto-login
```

使用已保存账号一键登录：

```bash
nxist-login login
```

临时指定账号登录：

```bash
nxist-login login -u USERNAME
```

临时指定账号登录并在成功后保存：

```bash
nxist-login login -u USERNAME --save
```

查看当前状态：

```bash
nxist-login status
```

退出登录，保留自动登录状态：

```bash
nxist-login logout
```

退出登录，并请求关闭自动登录，同时关闭本地自动重登策略：

```bash
nxist-login logout --disable-auto-login
```

清除本地保存的账号、cookie 和 session 信息：

```bash
nxist-login clear
```

## 登录行为

`nxist-login login` 的行为：

1. 加载平台标准配置路径中的 JSON 配置。
2. 恢复上次保存的 cookie。
3. 先探测当前是否已经在线。
4. 如果已经在线，则输出网络信息表。
5. 如果未在线，则使用参数提供的账号或保存的账号发起用户名密码登录。
6. 登录成功后保存 cookie、`userIndex` 和认证结果页中的网络信息。

登录成功后的输出为英文表格，例如：

```text
+---------------+------------------+
| Field         | Value            |
+===============+==================+
| Status        | Login successful |
| Username      | 123456789        |
| User IP       | 10.x.x.x         |
| Device IP     | 192.168.x.x      |
| User MAC      | aabbccddeeff     |
| Service ID    | (default)        |
| MAC Fast Auth | Disabled         |
| Package       | F package name   |
+---------------+------------------+
```

## 底层 API

底层模块可以被外部程序直接调用：

```python
from nxwifiapi import NXWifiClient

client = NXWifiClient()
result = client.login(username="USERNAME", password="PASSWORD")
print(result.response.result)
```

`nxwifiapi` 不读写配置文件，不保存账号，不提供 CLI。外部程序可以自行传入 `requests.Session` 来控制 cookie 生命周期：

```python
import requests
from nxwifiapi import NXWifiClient

session = requests.Session()
client = NXWifiClient(session=session)
```

## 项目结构

```text
src/
  nxwifiapi/
    client.py       # 底层认证 API
    models.py       # 类型化数据模型
    exceptions.py   # 异常类型
  nxwificli/
    cli.py          # CLI 入口和命令
    config.py       # JSON 配置和 cookie 序列化
    output.py       # 英文终端表格输出
docs/
  api-spec.zh-CN.md # 根据抓包整理的认证 API 规范
```

## 注意事项

- 该工具依赖 NXIST 校园网门户地址和当前校园网环境；在非校园网环境下登录探测通常会失败。
- 当前实现不支持二维码登录。
- 如果门户要求验证码，底层 API 支持验证码字段，但 CLI 暂未提供自动识别验证码能力。
- `session` 或 `JSESSIONID` 不是长期上网授权；CLI 的自动登录策略是保存 cookie，并在需要时使用保存的用户名密码重新登录。
