这是一个本地运行的寝室电费余额监控工具，用于查询一个已授权寝室在「慧新易校」里的电费余额，定时保存历史记录，并在浏览器里展示余额曲线和消耗趋势。
项目默认只适合查询你自己有权限查询的寝室。请不要用于查询未授权寝室，也不要上传 .env、token 或本地数据库。
- 定时查询电费余额，默认每 30 分钟一次。
- 启动服务后会立即查询一次。
- 支持网页手动点击「立即刷新」。
- 使用 SQLite 本地保存余额历史。
- 浏览器 Dashboard 展示：
- 当前余额；
- 最近一次更新时间；
- token / 查询状态；
- 余额变化曲线；
- 每次余额变化；
- 最近 24 小时消耗；
- 最近 7 日日均消耗；
- 按当前速度预计还能用多少天。
- token 失效时会在页面提示，不会在页面显示 token。
下面是本地服务成功查询后的监控页面示例：
electricitybill/ 后端服务和静态页面
electricitybill/static/ 浏览器 Dashboard
tests/ 自动化测试
scripts/ 跨平台启动脚本
.env.example 配置模板，不含真实 token
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env然后编辑 .env：
AUTH_MODE=manual
SYNJONES_AUTH=bearer 你的token
ROOM=你的寝室号
FEEITEM_ID=261
QUERY_INTERVAL_MINUTES=30
DATABASE_PATH=electricity.db启动服务：
uvicorn electricitybill.app:app --reload打开：
http://127.0.0.1:8000
也可以使用脚本启动：
chmod +x scripts/run-macos-linux.sh
./scripts/run-macos-linux.sh在 PowerShell 中执行：
py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env编辑 .env 后启动：
uvicorn electricitybill.app:app --host 127.0.0.1 --port 8000打开：
http://127.0.0.1:8000
也可以使用脚本启动：
.\scripts\run-windows.ps1如果 PowerShell 阻止脚本运行，可以先在当前窗口执行：
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass然后再运行脚本。
树莓派上按 macOS / Linux 的方式安装依赖和配置 .env。
如果只在树莓派本机访问：
./scripts/run-macos-linux.sh如果希望同一局域网内的手机或电脑访问，把服务绑定到所有网卡：
HOST=0.0.0.0 PORT=8000 ./scripts/run-macos-linux.sh然后在其他设备打开：
http://树莓派IP:8000
建议把 .env 和 electricity.db 保存在树莓派本地。它们已经被 .gitignore 忽略，不应该上传到 GitHub。
当前版本使用手动 token 模式：
- 使用 Reqable 等抓包工具，只抓取你自己账号、自己寝室的正常查询请求。
- 找到请求头里的
synjones-auth。 - 把完整值复制到
.env的SYNJONES_AUTH中。
示例格式：
SYNJONES_AUTH=bearer paste_token_here不要把真实 token 发给别人，也不要提交到 GitHub。
如果确认你的账号登录接口不需要验证码、短信验证或其他风控比如说慧新易校，可以把 .env 切换为自动登录模式：
AUTH_MODE=login
LOGIN_USERNAME=your_student_id
LOGIN_PASSWORD=your_password
# 可选；不填时默认使用 web
LOGIN_DEVICE_TOKEN=web
ROOM=your_authorized_room_id
FEEITEM_ID=261
QUERY_INTERVAL_MINUTES=30
DATABASE_PATH=electricity.db自动登录模式会在首次查询时用账号密码获取 token，并且只把 token 缓存在当前进程内存里；程序不会把 token、密码或 refresh token 写入数据库，也不会返回给浏览器页面。
LOGIN_DEVICE_TOKEN 可以不填；不填或留空时程序默认使用 web。如果你的学校环境里 web 登录失败，再从自己 App 的登录请求里抓取真实 device_token 后填入。
启动服务后，打开页面点击「立即刷新」。
如果成功，页面会显示当前余额和更新时间。
如果 token 失效，页面会显示认证失败。这时需要重新从 App 请求中复制新的 synjones-auth，更新 .env，然后重启服务。
也可以直接访问接口检查：
http://127.0.0.1:8000/api/status
python3 -m pytest tests -v如果你使用的是 macOS 自带 Python，推荐用虚拟环境里的 Python：
.venv/bin/python -m pytest tests -v先看终端里 uvicorn 是否报错。如果看到类似：
TypeError: unsupported operand type(s) for |: 'type' and 'type'
说明运行环境是 Python 3.9，而代码需要兼容类型标注。当前版本已经修复这个问题，请拉取最新代码后重启服务。
打开：
http://127.0.0.1:8000/api/status
查看 last_query_status：
success：查询成功；auth_error：手动 token 失效/填写错误，或自动登录账号、密码、device token 有误；error：网络、接口或解析失败。
历史数据只在服务运行时记录。如果电脑休眠、服务停止，期间不会查询。
- 只查询你有权限查询的寝室。
.env只保存在本地，不要上传 GitHub。electricity.db是本地历史数据，也不要上传。- 自动登录模式会从
.env读取账号密码，但不会把账号密码、access token 或 refresh token 写入数据库、页面或 README 示例。 - 本项目不会自动缴费。
- 本项目不会绕过验证码、短信验证、设备指纹或其他安全保护。
当前自动登录只支持已经确认的账号密码直登接口。程序会在首次查询时登录一次；如果后续查电费返回认证失败，会自动重新登录并重试一次。
如果登录接口后续出现以下情况，本项目不会尝试绕过：
- 验证码；
- 短信验证；
- 设备指纹；
- 加密密码；
- 风控限制。
refresh_token 暂时不会保存或使用；如果之后确认有合法、稳定的刷新接口，可以再单独设计。