# 得卡 DECA 自动化爬虫

得卡（decalive.com，国内球星卡 / 卡片交易平台）数据采集与报告系统。多任务常驻采集在售 / 已售 / 购买记录 / 选队总价，定时产出企微报告，底层由 **20 账号池 + 1 号 1 专属静态 IP** 支撑，账号可经接码平台全自动补货。

> ⚠️ **上线头等风险**：本目录与旧目录 `D:\work\2026-08-02(deca_spider)` 背后是同一批得卡账号，`refreshToken` 一次性轮换。**两边同时真跑会互相踩废 token**。上线前务必先停旧目录对应任务，确认只有一处在跑。

---

## 一、快速开始

```bash
# 1. 进入项目根目录
cd "D:\work\2026-09-08(deca_auto_spider)"

# 2. 安装依赖（首次）
pip install -r requirements.txt
# 公共库 charley-utils（mysql_pool / YamlLoader）单独 editable 安装，见下「环境依赖」

# 3. 一键启动全部常驻任务（采集 + 报告调度 + 运维，崩溃自动重启）
python start_all.py

# 只启动部分任务
python start_all.py buy_record team
```

`Ctrl+C` 优雅终止所有子任务。

---

## 二、目录结构

```
2026-09-08(deca_auto_spider)/
├── start_all.py             # ★统一部署入口：一键拉起全部常驻任务 + 崩溃自动重启
├── application.yml           # 数据库配置（host 100.64.0.25 / db crawler）
│
├── common/        # 公共库（采集 + 报告都 import，扁平 import 名）
│   ├── settings.py    #   ★集中配置：账号池阈值 / 接口路径 / 接码 Key / 代理 IP 池
│   ├── account_pool.py    #   ★账号池：取号 / 切号 / 续期 / 状态机 / 巡检 / 自动补货
│   ├── deca_sold_core.py     #   核心：签名 / do_request / 账号池接入（线程隔离）
│   ├── isms_client.py   #   接码平台（爱接码 i-sms.app）客户端
│   ├── deca_on_sale_daily_spider.py#   在售详情解析 / 入库（现全走免登录接口）
│   ├── auto_send_wx_msg.py         #   企微群机器人推送
│   └── deca_account_ddl.sql        # 账号表 deca_account_record 建表 DDL
│
├── spiders/              # 采集任务（脚本内自行 chdir 到项目根，共用根配置）
│   ├── buy_record_spider.py        #购买记录（重点 5 家，8 线程并发）
│   ├── onsale_alert_spider.py      #   上架提醒（新上架监控推送）
│   ├── sold_daily_spider.py        # 已售每日采集
│   ├── sold_history_spider.py      #   已售历史回补
│   ├── deca_team_spider.py #   选队随机总价（5 分钟/轮，只扫重点 5 家）
│   ├── replenish_accounts.py       #   ★一键补号（经接码平台自动注册入库）
│   └── maintenance.py       #   ★运维：cooling 巡检 + Excel 定时清理
│
└── reports/
    ├── onsale_report/# 在售报告（用 token，chdir 项目根）
    │   └── deca_on_sale_report.py  #   在售报告：每天 09/15/20/01 四次（仅出 Excel）
    └── sold_report/    # 已售报告（不用 token，chdir 自身目录）
        ├── run_scheduler.py   #   ★调度器：日报 09:10 + 周报周一 09:20 + 月报 1 号 09:30
     ├── daily_report.py         #   已售每日报告（重点商家明细 + 买家排行）
        ├── weekly_report.py#   魔都球星卡周报
        ├── monthly_report.py       #   魔都球星卡月报
    └── application.yml 球队.json ...   # 本目录自带（因 chdir 自身目录）
```

---

## 三、环境依赖

- **Python 3.12.10**
- **第三方包**（见 `requirements.txt`）：`requests` `loguru` `tenacity` `schedule` `openpyxl` `matplotlib`
- **公共库 `charley-utils`**（`mysql_pool` / `YamlLoader`，本机 editable 安装，各项目直接 import）：

  ```bash
  cd D:\work\common\charley-utils
  pip install -e .          # 换新环境导入失败时执行一次即可
  ```

  依赖 `pymysql` `DBUtils` `PyYAML`（由该包声明）。**禁止把 mysql_pool.py 复制进本项目**——统一维护一份。

- **数据库**：`mysql_pool` 读**运行目录**下的 `application.yml`（`mysql.host/port/username/password/db`）。项目根与 `reports/sold_report/` 各自带一份。

---

## 四、配置

所有账号池 / 接码 / 代理相关配置集中在 **`common/settings.py`**，改配置只动这一处：

| 配置项 | 说明 |
|---|---|
| `POOL_TARGET_SIZE = 20` | 账号池目标规模 |
| `LEASE_TTL_SEC = 6h` | 进程独占一个号的租约 TTL（崩溃后到期自动可再租，不死占） |
| `DEAD_CODES = {10010}` | 续期判死码（10010 =「长期未登录，请重新登录」→ 判 dead 摘池） |
| `ISMS_API_KEY` / `ISMS_PROJECT_KEYWORD` | 接码平台（爱接码）Key 与项目关键词「优豪卡」 |
| `PROXY_USER/PASS/PORT` + `PROXY_IPS[20]` | 20 个国内静态 IP（1 号 1 IP 永久绑定，端口 16816） |

> ⚠️ `settings.py` 含接码 API Key 与代理账密，**私有仓库专用，勿外传 / 勿提交公开仓库**。

数据库配置在 `application.yml`（当前库：`100.64.0.25 / crawler`）。

---

## 五、账号池

得卡 need_auth 接口的登录态由账号池统一管理，采集脚本无需关心 token。

- **数据模型**：表 `deca_account_record`（DDL 见 `common/deca_account_ddl.sql`）。自增 id 主键、`phone` 唯一键、每号独立 access/refresh/token_exp、`proxy_url`（专属 IP）、`status`（healthy/cooling/dead）、进程独占租约字段。
- **取号策略**：**每批随机**——每 20 个 need_auth 请求随机换一个 healthy 号，请求量摊到全池，单号风控面最小。
- **登录态操作走专属 IP**：续期 / 短信登录都从该号绑定的静态 IP 发出，不暴露本机 IP。
- **多线程安全**：`buy_record` 用 8 线程并发，账号池按 **thread-local 隔离**——每线程独立持号、独立续期，互不踩踏。
- **判死与恢复**：续期命中 `10010` → 判 dead 摘池 + 企微通知；网络异常算软失败不判死；`maintenance.py` 每 10 分钟巡检恢复 cooling 号。
- **短信登录即注册**：得卡无独立注册接口，短信验证码登录即完成注册。补号经接码平台租号 → 收码 → 短信登录入库 → 绑定空闲 IP。

### 补号（账号不足时）

```bash
python spiders/replenish_accounts.py --target 20 --batch 5
```

- `--target` 池子总目标数，`--batch` 单次最多补几个。
- ⚠️ **得卡强风控，别一次连续注册一大批**（半小时爆十几个新号是典型连坐信号），建议**分几天补**（每天 `--batch 3~5`）。
- 补号是长任务（每号错峰停顿 30~90s、收码等待），**在终端里跑**，别用受超时限制的环境。
- 注意接码平台余额（失败号也扣取号费）。

---

## 六、任务清单与调度

`start_all.py` 统一管理以下 7 个常驻任务，任一崩溃退出 15s 后自动重启：

| 任务名 | 脚本 | 说明 / 调度 |
|---|---|---|
| `buy_record` | buy_record_spider.py | 购买记录（重点 5 家，8 线程） |
| `onsale_alert` | onsale_alert_spider.py | 上架提醒（新上架监控推送） |
| `sold_daily` | sold_daily_spider.py | 已售每日采集 |
| `team` | deca_team_spider.py | 选队随机总价（5 分钟/轮，只扫重点 5 家） |
| `onsale_report` | deca_on_sale_report.py loop | 在售报告：每天 **09 / 15 / 20 / 01** 四次（仅出 Excel） |
| `sold_report` | run_scheduler.py | 已售：日报 **09:10** + 周报**周一 09:20** + 月报 **1 号 09:30** |
| `maintenance` | maintenance.py | 账号池 cooling 巡检（每 10 分钟）+ Excel 清理（每天 03:00，保留 30 天） |

单独运行任一脚本也可（各脚本自带 bootstrap 会 chdir 到所需目录）：

```bash
python spiders/buy_record_spider.py
python reports/sold_report/run_scheduler.py
```

---

## 七、服务器常驻（最简方式）

`start_all.py` 已自带崩溃自动重启，服务器上只需让它在后台常驻即可。

**Windows**（后台启动，日志落 `logs/`）：

```bash
start /b python start_all.py
```

**Linux**（nohup 后台 + 日志重定向）：

```bash
cd /path/to/2026-09-08(deca_auto_spider)
nohup python -u start_all.py > logs/start_all.out 2>&1 &
```

> 如需开机自启 / 掉电自恢复，可进一步用 Windows 计划任务（nssm）或 Linux systemd 托管 `start_all.py`——按需再加，最简常驻用上面即可。

---

## 八、注意事项

1. **上线前先停旧目录**：确认 `D:\work\2026-08-02(deca_spider)` 对应生产任务已停，避免同账号双跑踩废 token（见文首风险提示）。
2. **登录态全由账号池接管**：所有 need_auth 请求统一走账号池（随机取号 + 续签 + 各号专属静态 IP）。`deca_sold_core` 仅暴露 `init_account_pool(...)` 一个开关，采集脚本启动时调用即生效，无其它登录态路径。
3. **代理 IP 有效期**：当前 20 个静态 IP 有效期至 **2026-10-09**，到期需在快代理续费并同步 `settings.PROXY_IPS`。
4. **版本号写入**：涉及 Python / 依赖版本时，先 `--version` 实测再写，勿凭记忆。

---

## 九、相关文档

- 账号池落地全文：`docs/账号池落地_得卡DECA_20260909.md`（架构 / 数据模型 / 短信登录=注册 / 判死 / IP 选型 / 实测 / 上线步骤）
- 进度台账 / 交接：`HANDOFF.md`（新窗口接手先读）