Files
push_fenxiangfengshi/README.md
T

178 lines
8.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 丰享订单监控 v5
监控丰享商家端(fs.szfx.com)新订单,实时推送到企业微信;可选本地语音播报。
支持两种运行形态:**Windows 本机** 和 **Linux 服务器 Docker 常驻**。
---
## 1. 架构
```
┌──────────────────────────────┐
本机 Windows │ fengxiang_scraper.py │
(人工过验证码) │ Playwright 登录 → Cookie │
└───────────┬──────────────────┘
│ POST /api/cookies(token 鉴权)
▼
服务器 Docker ┌──────────────────────────────┐
fengxiang-monitor │ admin.py :8089 /healthz │
│ monitor.py 主循环 │
│ ├─ client.py → 丰享订单 API │ ← 5~10s 轮询
│ ├─ store.py 状态去重 │
│ └─ notify.py → 企业微信 │
└──────────────────────────────┘
```
- **为什么登录必须在本地**:丰享登录挂腾讯 TCaptcha,无法纯接口绕过;服务器上没有桌面。
所以「人工过验证码」留在本机,登录成功后把 Cookie 推给服务器,服务器热加载,无需重启。
- **为什么不用 TTS 跑在服务器**:IndexTTS2 依赖 torch + GPU + 声卡,容器里跑不了。
服务器只负责推送,手机端企业微信本身就有提示音。需要喇叭播报时另见 §7。
---
## 2. 快速开始(Windows 本机)
```bat
python -m pip install -r requirements-local.txt
playwright install chromium
copy config.example.yaml config.yaml :: 填 notify.wecom.webhook
run.bat
```
- `run.bat`:启动监控(自动识别 `.venv` / IndexTTS2 环境 / 系统 Python)
- `login.bat`:登录丰享并把 Cookie 上传到服务器(仅服务器形态需要)
- `setup_autostart.ps1`:注册开机自启任务计划
## 3. 部署到服务器(Docker)
```bash
# 服务器上
mkdir -p /data/docker/fengxiang-monitor && cd /data/docker/fengxiang-monitor
# 上传代码后:
cp config.example.yaml config.yaml
vi config.yaml # 填 admin.token(必填,用于接收 Cookie)
cat > .env <<'EOF'
FX_WECOM_WEBHOOK=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx
FX_ADMIN_TOKEN=改成足够长的随机串
EOF
docker compose up -d --build
docker compose ps # STATUS 应为 healthy
curl -s localhost:52100/healthz | python3 -m json.tool
```
> 镜像基于 `alpine:3.20` + apk(阿里云源),构建约 10 秒。
> 官方 `python:3.12-slim` 在国内常卡在基础层下载,Dockerfile 末尾保留了切换回去的注释。
首次部署后必须在本地跑一次 `login.bat`(或 `fengxiang_scraper.py --upload`)把 Cookie 推上去,
否则监控会一直停在「等待 Cookie」状态。
## 4. 目录与文件
| 文件 | 说明 |
|------|------|
| `order_monitor.py` | 统一入口(本地 / 容器共用) |
| `fengxiang/config.py` | 配置加载:环境变量 > config.yaml > 默认值 |
| `fengxiang/client.py` | 丰享 API 客户端(连接复用、重试、异常分类) |
| `fengxiang/monitor.py` | 主循环:轮询调度、夜间暂停、Cookie 热重载 |
| `fengxiang/store.py` | 状态持久化(最新订单号 + 去重集合,原子写) |
| `fengxiang/notify.py` | 通知通道(企业微信 / 飞书,可插拔 + 告警冷却) |
| `fengxiang/admin.py` | 管理接口:`/healthz`、`/api/cookies`、`/api/test-push` |
| `fengxiang/tts.py` | 本地播报队列(仅 Windows,容器自动禁用) |
| `fengxiang_scraper.py` | 本机登录 + 上传 Cookie |
| `fetch_orders.py` / `push_latest_order.py` | 调试工具:取单 / 单次推送 |
| `healthcheck.py` | 容器健康检查(判断是否还在轮询) |
| `tests/test_core.py` | 22 项单元测试,不联网 |
运行数据都在 `data/`(容器内 `/app/data`):`cookies.json`、`state.json`、`logs/monitor.log`。
## 5. 管理接口
| 接口 | 鉴权 | 用途 |
|------|------|------|
| `GET /healthz`(= `/api/status`) | 否 | 运行状态,Docker HEALTHCHECK 用 |
| `POST /api/cookies` | 是 | 更新 Cookie,立即校验并热生效 |
| `POST /api/test-push` | 是 | 发一条测试消息验证通道 |
鉴权:`X-Auth-Token: <token>` 或 `Authorization: Bearer <token>` 或 `?token=`。
未配置 token 时**只允许 127.0.0.1** 调用写接口(安全默认)。
```bash
curl -s localhost:52100/healthz
curl -X POST localhost:52100/api/test-push -H "X-Auth-Token: $T" -d '{"text":"测试"}'
```
`/healthz` 返回:
```json
{"app":"fengxiang-monitor","mode":"peak","cookie_valid":true,"cookie_age_sec":120,
"last_order_id":"...","last_poll_age_sec":3,"total_pushed":42,"uptime_sec":3600}
```
`mode`:`peak` / `idle` / `night`。`cookie_age_sec` 超过 7 天就要留意续期。
## 6. 运维手册
**Cookie 过期(最常见)**
1. 企业微信会收到「登录已失效」告警(30 分钟冷却,不会刷屏)
2. 本机跑 `login.bat`(或 `fengxiang_scraper.py --upload`)
3. 服务器收到后自动恢复,并回推一条「监控恢复,中断约 N 分钟」
**查日志**
```bash
docker logs -f --tail 100 fengxiang-monitor
docker exec fengxiang-monitor tail -f /app/data/logs/monitor.log
```
**重启 / 升级**
```bash
docker compose restart
docker compose up -d --build # 改代码后
```
**误推送了历史订单**:删 `data/state.json` 后重启会让程序重新建立基线(不推历史)。
**想补推某个时间段的订单**:当前设计不做补推,恢复时会合并成一条汇总(阈值见 `bulk_summary_threshold`)。
## 7. 可选:喇叭播报
服务器侧不跑 TTS。若确实需要店里喇叭响,两条路:
1. 服务器上已有的 `wework-xiaoai-bot` 容器带小爱 TTS,把本项目的推送目标改成它;
2. 店内电脑跑一个极简「取单播放」客户端(轮询 `/healthz` 不够,需另加接口)→ 本地 IndexTTS2 播报。
## 8. 配置项速查
见 `config.example.yaml` 全文注释。关键几项:
| 配置 | 默认 | 说明 |
|------|------|------|
| `polling.interval_min/max` | 5 / 10 | 轮询间隔(秒,随机取值) |
| `polling.peak_page_size` | 20 | 高峰时段每次拉取条数 |
| `polling.idle_page_size` | 5 | 闲时拉取条数 |
| `polling.night_start/end` | 21:00 / 07:40 | 夜间暂停区间 |
| `polling.bulk_summary_threshold` | 5 | 积压超过 N 单改发汇总 |
| `notify.alert_cooldown_sec` | 1800 | 同类告警冷却 |
| `admin.token` | 空 | 空则写接口只允许本机 |
## 9. 与原版的差异(重构要点)
| 原问题 | 现状 |
|--------|------|
| `cookies.json` 不在仓库,服务器上直接弹浏览器 | 服务器不弹浏览器:告警 + 等 Cookie 推送,自动恢复 |
| TTS 绑死 Windows `winsound` + 本机 IndexTTS2 | TTS 变可选通道,非 Windows 自动禁用 |
| `test_push.py` 仍 `import miservice`(小爱已删) | 已删除 |
| `run_monitor.bat` 写死 `d:\coding\fengxiang` | 已删除,`run.bat` 基于脚本目录 |
| 初始拉单失败会把 20 单全推一遍 | 首次只建基线,不推历史 |
| `speak()` 阻塞主循环数秒 | 后台线程 + 队列 |
| 只有 print,无日志/无健康检查 | 文件日志滚动 + `/healthz` + Docker HEALTHCHECK |
| webhook / shopId 硬编码在源码 | 全部走 config/env |
| 飞书 webhook 失效(`code=19001`)却一直报错 | 保留配置位,默认关闭,填了才启用 |
| 每 5 秒新建 TLS 连接 | Session 复用 + 有限重试 + 指数退避 |
## 10. 已知限制
- 丰享接口是非官方逆向,字段/错误码随时可能变;`client.py` 集中处理,改一处即可。
- 只监控「快捷买单」订单列表,不含退款、取消等状态变更。
- 单实例运行(状态文件无锁);同一店铺不要起两个容器。
- `shopId` 目前只有一个店铺(益选便利店),多店铺需扩展为列表。