# 得卡 DECA 自动化爬虫 优化记录

## 1. 优化背景

账号池（2026/09/10 起）已是 `need_auth` 请求**唯一路径**——根 `token.json` / `token.json.lock` / `get_token.py` 已清理下线，卡密 `km_spdier` 任务已删除。但在源码与文档里仍有**若干过期描述**沿用「老 token.json / 沿用老 ensure_token」字眼，会让接手人误以为还存在第二条登录态路径，或误以为还有临时回退方案可用。本次统一刷新所有过期描述，与现状对齐。

## 2. 改动内容

### 2.1 代码注释 / docstring 修正

| 文件 | 旧描述 | 新描述 | 改因 |
|---|---|---|---|
| `common/deca_sold_core.py:231` | `need_auth 请求的取 token 统一走「账号池随机取号 + 续签 + 各号专属 proxy_url」，已无 token.json 回退。` | `need_auth 请求的 token 统一走账号池（随机取号 + 续签 + 各号专属 proxy_url），账号池为唯一路径。` | 消除「回退」对比，纯正向说明 |
| `common/deca_sold_core.py:236` | `# 账号池是否已登记；init_account_pool() 置 True（未启用时 need_auth 报错）` | `# 账号池是否已登记；采集脚本启动调 init_account_pool() 置 True（必须登记才不缺 token）` | 强调「必须主动启用」，去掉「报错」字面 |
| `common/deca_sold_core.py:249` | docstring `need_auth 请求必须先调用本函数登记账号池（否则直接报错，已无 token.json 回退）。仅登记「共享 DB` | docstring `need_auth 请求必须先调用本函数登记账号池（否则直接报错，无其它路径）。仅登记「共享 DB` | 同 231 |
| `spiders/onsale_alert_spider.py:36` | `挂靠新项目根：...CWD 对齐新根(token.json/application.yml/logs 生效)` | `挂靠新项目根：...CWD 对齐新根（application.yml / logs / 账号池 DB 生效）` | token.json 已删，无 `生效` 可言 |
| `spiders/buy_record_spider.py:56` | `复用核心签名/token/请求/代理层，让 application.yml、token.json 生效` | `复用核心签名/账号池/请求/代理层，让 application.yml / 账号池 DB 生效` | 同上 |
| `spiders/deca_team_spider.py:32` | `与 alert / sold_daily 共用同一份根目录 token.json；续签已加跨进程锁防踩踏（deca_sold_core._token_lock，2026/08/20 根治多进程互相踩废 refreshToken 的问题）` | `与 alert / sold_daily 走同一账号池（每批随机换号 + 各号专属 IP），无共享 token.json；续签在 AccountPool.ensure_access 里按号独立轮换 refreshToken，由 report_failure 兜底判死` | 描述账号池现状 |
| `spiders/deca_team_spider.py:47` | `CWD 对齐新根(token.json / application.yml / ./logs 均在此)` | `CWD 对齐新根（application.yml / ./logs / 账号池 DB 均在此）` | 同上 |
| `spiders/sold_daily_spider.py:17` | `CWD 对齐新根(token.json/application.yml/logs 生效)` | `CWD 对齐新根（application.yml / logs / 账号池 DB 生效）` | 同上 |
| `spiders/sold_history_spider.py:16` | 同上 | 同上 | 同上 |
| `reports/onsale_report/deca_on_sale_report.py:27` | `CWD 对齐新根(token.json/application.yml/logs 生效)` | `CWD 对齐新根（application.yml / logs / 账号池 DB 生效）` | 同上 |

### 2.2 README.md

- **第 36 行**：删 `get_token.py` 目录条目（文件已删）。
- **第 175 条注意事项**：原「`deca_sold_core` 里的单 token 逻辑仅作账号池关闭时的回退保留」改为「`deca_sold_core` 仅暴露 `init_account_pool(...)` 一个开关，采集脚本启动时调用即生效，无其它登录态路径」——消除「回退」暗示。
- **第 176 条**：原「临时回退单 token」指南整条删除——回退路径已彻底不可用（token.json + get_token.py 已删）。

### 2.3 HANDOFF.md（台账同步现状）

| 行号 | 改动 |
|---|---|
| 26 | `⏳ 未做（后续）：录号 + 各自 proxy_url、step3、清理 token.json` → `✅ 账号池上线齐备（2026/09/10）：… token.json / token.json.lock 已清理下线` |
| 35 | `核心：签名/do_request/token 管理（现仍是单 token.json 机制）` → `核心：签名/do_request/账号池接入（线程隔离）` |
| 40 | `共用根 token.json/application.yml/logs` → `共用根 application.yml/logs` |
| 47 | `用 token，chdir 新根` → `走账号池，chdir 新根` |
| 49 | `km_spdier.py 卡密采集` 整行删除 |
| 58 | `token.json (+ .lock) 单份，多采集进程共用（账号池落地后废弃、清理）` 整行删除 |
| 59 | `get_token.py adb+su 从 App 读 token 灌回` 整行删除 |
| 68 | `用 token → chdir 到新根，共用根 token.json/application.yml/logs` → `走账号池 → chdir 到新根，共用根 application.yml/logs` |
| 96 | `人工白天离线补货（App 登录过滑块 + get_token.py 灌回）` → `人工白天补货走短信登录=注册（AccountPool.sms_login）入库，不依赖 get_token.py/ADB` |
| 116 | `总开关 USE_ACCOUNT_POOL（默认 False 走老 token.json）` → `总开关 USE_ACCOUNT_POOL（默认 False——未登记账号池就发 need_auth 会直接 RuntimeError，账号池为唯一路径）` |
| 119 | `要临时回退单 token.json 注释该行即可` → `账号池为 need_auth 唯一路径，无单 token 回退` |
| 121 | `5.【清理】账号池验证 OK 后：清理 token.json…` → `5.✅【清理·2026/09/10】token.json / token.json.lock / get_token.py 已删除下线…` |
| 173 | `⛔ 问题1/5·不动（卡密依赖）…根 token.json 不能删…问题5 token.json 清理取消` → `✅ 问题1/5·已处理（2026/09/10）卡密 km_spdier 任务已删除…根 token.json / token.json.lock / get_token.py 已删除` |

### 2.4 保留不动（有意）

| 位置 | 内容 | 为何保留 |
|---|---|---|
| `deca_sold_core.py:163/212` | 防护文案「已无 token.json 回退」 | 主公明确指示「该留」 |
| `HANDOFF.md:10-11` | 头等风险段核心警示（旧目录用旧 token.json） | 警示仍然有效，且这是新窗口接手第一眼看到的风险提示 |
| `HANDOFF.md:69` | 「TOKEN_FILE 写死绝对路径已改回 token.json」历史 bug 修复 | 迁移阶段台账 |
| `common/account_pool.py:7` / `common/deca_account_ddl.sql:2` | 「把原来集中在单账号 token.json 的登录态，改为多账号入池…」 | 描述**改造背景**的模块头注释，正确 |
| `common/deca_on_sale_daily_spider.py:22` | 「原供 km_spdier 复用的 token 机制已随 km_spdier 一并移除」 | 描述已发生的清理动作，正确 |
| `docs/账号池落地_得卡DECA_20260909.md` | 全文「老 token.json 时代 → 账号池」对比描述 | 设计文档的「改造前 → 改造后」历史记录，台账价值 |

## 3. 改动前后对比

### 3.1 `common/deca_sold_core.py` 注释段

**改前**（231 行）：
```python
# need_auth 请求的取 token 统一走「账号池随机取号 + 续签 + 各号专属 proxy_url」，已无 token.json 回退。
```

**改后**：
```python
# need_auth 请求的 token 统一走账号池（随机取号 + 续签 + 各号专属 proxy_url），账号池为唯一路径。
```

**改前**（249 行 docstring）：
```python
need_auth 请求必须先调用本函数登记账号池（否则直接报错，已无 token.json 回退）。仅登记「共享 DB
```

**改后**：
```python
need_auth 请求必须先调用本函数登记账号池（否则直接报错，无其它路径）。仅登记「共享 DB
```

### 3.2 `spiders/deca_team_spider.py` 登录态段（影响最大的一处）

**改前**：
```
- 与 alert / sold_daily 共用同一份根目录 token.json；续签已加跨进程锁防踩踏
  （deca_sold_core._token_lock，2026/08/20 根治多进程互相踩废 refreshToken 的问题）。
```

**改后**：
```
- 与 alert / sold_daily 走同一账号池（每批随机换号 + 各号专属 IP），无共享 token.json；
  续签在 AccountPool.ensure_access 里按号独立轮换 refreshToken，由 report_failure 兜底判死。
```

## 4. 注意事项

- **本次纯注释 / 文档刷新**：未改任何业务逻辑；所有改动通过 `python -m py_compile` 校验，语法零问题。
- **接手人阅读顺序**：先看 `HANDOFF.md` 顶部「⚠️ 头等风险」段（警示仍然有效），再看「账号池上线齐备（2026/09/10）」段（现状）。
- **设计文档不动**：`docs/账号池落地_得卡DECA_20260909.md` 是改造完成时的设计快照，记录「老 token.json → 账号池」对比，台账价值大于改写。
- **不影响上线判断**：本次改动不触及 `core.do_request` / `core.do_get` 的运行时分支——运行时行为完全等同改动前。

---

**日期**：2026/09/10
**触发**：主公审查定位 5 处过期描述，其中 2 处（163/212 防护文案）保留、3 处（231/236/249 账号池段注释）已更新为正向口径，并顺手把 README/HANDOFF/6 个入口脚本里的同类过期描述一起刷新。