Metadata-Version: 2.4
Name: autotd-buaa
Version: 0.1.9
Summary: BUAA TD automation command line utility
Author: autoTD maintainers
Keywords: buaa,td,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# AutoTD

> **需在校园网下使用**

`autoTD` 是一个可安装的命令行工具包。安装后提供 `autotd` 命令，用于初始化本地配置目录、管理用户和图片、运行 TD 打卡流程、查询服务器返回的本学期锻炼次数，以及在后台进行定时检测。

## PyPI 安装

> 要求：python >= 3.10

```bash
pip install autotd-buaa==0.1.9
```

## 本地开发

本项目采用标准 `pyproject.toml` 包结构：

```bash
python3 -m pip install -e .
autotd --help
```

构建本地 wheel/sdist：

```bash
python3 -m build
```

内部测试发布可使用 TestPyPI：

```bash
python3 -m twine upload --repository testpypi dist/*
```

## 初始化

所有运行数据存储在 `~/.autoTD` 下。测试或临时运行时可用 `AUTOTD_HOME` 覆盖：

```bash
autotd init
autotd init --from ./autoTD
```

从 `0.1.3` 开始，如果已有 `~/.autoTD/config.json` 仍是旧默认 `127.0.0.1:8888`，再次运行 `autotd init` 会自动迁移为当前默认 TD 服务器地址，不会覆盖用户、图片和机器配置。

目录结构：

```text
~/.autoTD/
├── config.json
├── users.json
├── settings.json
├── state.json
├── telemetry_queue.jsonl
├── images/
└── logs/
    └── YYYY-MM-DD-daytime-log.txt
```

## Telemetry 上报

从 `0.1.7` 开始，AutoTD 默认开启 telemetry，用于向维护者的 Cloudflare Worker + D1 后台上报安装、运行、停止、用户变化、TD 次数变化和后台运行跨日快照。`0.1.9` 默认 endpoint 为 `https://autotd-telemetry.autotd-buaa.workers.dev`。

会上报的数据包括：明文学号、每个学号最近一次 TD 次数、当前用户数量、安装实例 ID、AutoTD 版本、平台、事件类型和事件时间。

不会上报的数据包括：`card_id`、图片、图片文件名、入口/出口机器编号、TD 服务器地址、日志内容。

用户可以随时关闭：

```bash
autotd telemetry disable
```

重新开启或配置 Cloudflare Worker endpoint：

```bash
autotd telemetry enable --endpoint https://autotd-telemetry.autotd-buaa.workers.dev
autotd telemetry status
autotd telemetry sync
```

如果 endpoint 尚未配置，事件会保存在 `~/.autoTD/telemetry_queue.jsonl`，不会影响打卡流程；配置 endpoint 后可用 `autotd telemetry sync` 发送。

维护者侧 Worker/D1 实现在 `telemetry-worker/`，Cloudflare Pages 管理前端实现在 `telemetry-pages/`。当前 Pages 地址为 `https://autotd-telemetry-dashboard.pages.dev/`，Admin Token 保存在仓库外的 `/Users/denerate/ELSE/autotd-telemetry-admin-token.txt`。

## 用户管理

```bash
autotd user add 22375080 --entrance 2 --exit 6 --entrance-image image3.jpg --exit-image image2.jpg
autotd user add 22375080 --quick 沙河
autotd user add 22375080 --quick 学院路
autotd user list
autotd user show 22375080
autotd user update 22375080 --card-id CARDID --entrance 3 --exit 7 --entrance-image image1.jpg --exit-image image2.jpg
autotd user delete 22375080
autotd user count 22375080
autotd user count 22375080 --refresh
```

`card_id` 为空时会自动使用学号的 16 进制大写形式。

`autotd user count <student_id>` 默认读取 `~/.autoTD/state.json` 中最近一次缓存的锻炼次数，不访问服务器。需要发送真实 checkdata 请求并刷新缓存时，使用 `--refresh`；该刷新请求需要服务器在当前时间返回包含“本学期锻炼次数”的消息。

使用 `--quick` 时，只需要指定校区：

- `--quick 沙河`: 随机选择沙河入口机 `8/9/10`、沙河出口机 `11/12/13`，并从 `~/.autoTD/images/` 随机选择入口/出口图片。
- `--quick 学院路`: 随机选择学院路/本部入口机 `2/3/4`、学院路/本部出口机 `5/6/7`，并从 `~/.autoTD/images/` 随机选择入口/出口图片。
- 其他字段使用默认值：`rounds=3`、`wait_time_min=180`、`wait_time_max=240`、`card_id` 自动生成。

## 图片管理

```bash
autotd image add ./image3.jpg
autotd image add ./photo.jpg --name entrance.jpg
autotd image add ./photo.jpg --name entrance.jpg --overwrite
autotd image list
```

图片会复制到 `~/.autoTD/images/`。用户配置中引用的是图片文件名。

## 立即运行

立即执行一次所有用户：

```bash
autotd run --once
```

`autotd run --once` 会在当前终端前台执行并打印汇总。执行时某个用户失败会记录日志并继续后续用户。

## 定时运行

`autotd run` 会启动后台定时检测进程，终端会立即返回，不持续展示运行日志。日志写入 `~/.autoTD/logs/`。

```bash
autotd schedule show
autotd schedule set --poll-seconds 60 --windows "07:30-10:00,11:30-14:00,15:30-20:00"
autotd run
autotd status
autotd --stop
```

`autotd run` 会启动后台轮询。查看后台进程和今日用户打卡状态用 `autotd status`，运行中会显示 PID、每位用户的今日进度、等待倒计时或错误信息；如果 pid 文件已过期，会提示并自动清理。需要停止后台定时检测时运行 `autotd --stop`。

默认时间段为：

- 07:30 - 10:00
- 11:30 - 14:00
- 15:30 - 20:00

定时模式按北京时间判断窗口。后台进程每次轮询都会重新读取用户配置：新增用户会加入当天队列，删除用户会取消待执行状态。每位用户独立记录今日轮次和下一次打卡时间，入口成功后等待再出口，出口成功后如有下一轮也会等待再入口。若倒计时到期时已不在合法窗口，本轮作废，下个窗口从入口重新开始。请求失败会进入 error 状态，可用 `autotd status` 查看；重新运行 `autotd run` 会清除今日错误状态并允许重试。

## 连接失败排查

如果日志中出现 `Connection refused` 或 `无法连接 TD 服务器`，先检查：

```bash
cat ~/.autoTD/config.json
```

`server.ip` 应为可访问的 TD 服务器地址，例如默认模板中的 `10.212.28.38`，端口为 `8888`。如果现有配置仍是 `127.0.0.1`，请编辑 `~/.autoTD/config.json`，或重新导入已有项目配置：

```bash
autotd init --from /path/to/autoTD
```

同时确认当前网络可访问校园网或已连接 VPN。

## 测试

```bash
/opt/homebrew/anaconda3/envs/autotd/bin/python -m unittest discover -s tests -v
```
