# 得卡 DECA 采集项目 · 运维总览

> 抓取得卡 DECA 平台（`api.decalive.com`）的商家 / 在售 / 已售 / 购买记录 / 拆卡报告等数据入 MySQL，
> 并对指定商家（当前 **881226408 魔都兄弟球星卡**）做实时提醒与每日报告（**2026/08/11 起提醒与报告统一发企业微信群机器人**）。
> Python 3.12.10 ｜ 公共库 `charley-utils`（`from mysql_pool import MySQLConnectionPool`）｜ DB 配置读运行目录 `application.yml`。
> 深入细节见 `HANDOFF.md` 与 `docs/`；本文只讲「**要启动哪些脚本、各干什么、用哪些表**」。

> **⚠️ 2026/09/05 重大变更**：站方把**免 token 的全站在售接口 `home/search` 砍成首屏推荐（只返前 20 条、不可翻页）**，`exhibition/list` 商家列表也砍成首屏 30。原「空 query 翻页拿全量在售」失效 →
> 在售全量只能靠**逐商家 `on-sale-list`（需 token）**枚举。据此改为**一机一账号**部署（天然一机一 IP，降低账号关联封号/顶号）：
> - 电脑 A（已售报告 #4 + 随机团 #2）= 现有主号，不动；
> - 服务器 B（购买记录 #1）= 账号 `18040545025`：4 家监控走 on-sale-list 带 token，购买记录仍 detail 免 token；
> - 电脑 C（提醒 #3 + 在售报告 #5）= 账号 `18086100242`：提醒采 1 家、报告发报告前全站对账 161 家（均带 token）。
> 每台 `token.json` 填 `{"phone","password","countryCode"}` 即可（首次自动登录补 access/refresh，也便于人工分辨该机用哪个账号）。详见 [memory] 与下文第七节。

---

## 一、需要常驻启动的脚本（生产环境要跑的）

> 全部从**项目根目录**运行。带 ★ 的是数据源，必须先跑起来；报告类依赖库里已有数据。

| # | 脚本 | 干什么 | 启动命令 | 频率 | 用到的表 | 需 token |
|---|---|---|---|---|---|---|
| 1 ★ | `buy_record_analysis/buy_record_spider.py` | **在售数据主采集 + 购买记录**：①每轮拉 4 家监控商家（`MERCHANT_IDS`）`on-sale-list`（**带 token 走直连**）落库 + 记进度快照；②采本商家购买记录（`detail` 免 token、自适应频率、售罄/结束自动停采）。**（2026/09/05 起①由全站 home/search 免 token 改为逐 4 家 on-sale-list 带 token；不再做全站下架对账）** | `python buy_record_analysis/buy_record_spider.py` | 常驻循环（自适应） | 写 `deca_onsale_shop_record`、`deca_onsale_product_record`、`deca_onsale_product_daily_record`、`deca_onsale_product_progress_record`、`deca_buy_record` | **是**（在售列表；购买记录免） |
| 2 ★ | `deca_team_spider.py` | **随机团总价采集**：选队随机抓 team-options 存队伍明细+算总价；剩余随机存 snapshot 实时算。转成剩余随机后 team-options 永久失效，故必须常驻不断采 | `python deca_team_spider.py`（2026/08/20 由 on_sale/ 迁回根目录） | 常驻，每 5 分钟一轮 | 写 `deca_groupbuy_team_record`；更新 `deca_onsale_product_record.team_total_amount` | 部分（选队 team-options 需） |
| 3 | `onsale_alert_spider.py` | **在售提醒（企微）**：监控 881226408，按上架时间提醒「窗口起点后新上架」+ 进度过半 + 一车结束战报。**（2026/09/05 起自采从全站 home/search 免 token 改为本商家 `on-sale-list` 带 token 直连；详情仍免 token）** | `python onsale_alert_spider.py [HH:MM]`（默认 20:30，可传如 `17:00`） | 常驻，默认 20:30~次日 06:00 轮询（起点可传参） | 读写 `deca_onsale_alert_record`；读 `deca_buy_record`（结束战报的参与人数） | **是**（在售列表；详情免） |
| 4 | `sold_daily_spider.py` | **已售拼团每日增量**：商家→已售→详情→拆卡报告+回放（连续无新页早停） | `python sold_daily_spider.py` | 常驻定时（每天 **08:00**，代码实际值；docstring 写的 03:00 已过时） | 写 `deca_shop_record`、`deca_product_record`、`deca_report_record`、`deca_groupbuy_team_record`、`deca_kami_record`(默认关) | **是** |
| 5 | `on_sale/deca_on_sale_report.py` | **在售每日报告（企微 Excel）**：**发报告前先全站对账**（遍历库内 161 家 `on-sale-list` 带 token 全量落库 + `is_on_sale` 下架对账 + `fill_product_details` 回填 publish_at/规格），再查库生成多 Sheet Excel 发群 | `python on_sale/deca_on_sale_report.py loop` | 定时 09:00/15:00/20:00/01:00 | 写/读 `deca_onsale_shop_record`、`deca_onsale_product_record`、`deca_onsale_product_daily_record` | **是**（全站对账） |
| 6 | `stats/daily_report.py` | **已售每日报告（企微 Excel）**：成交时间窗 [昨天17点,今天3点] 的平台/商家汇总+明细 | `python stats/daily_report.py` | 定时（每天 09:10） | 读 `deca_product_record`、`deca_report_record`、`deca_buy_record`、`deca_onsale_product_progress_record` | 否 |
| 7 | `keep_awake.py` | **防 Windows 自动锁屏/息屏**，保证机器与上述常驻脚本可用（挡不住手动 Win+L / 域策略强制锁屏） | `python keep_awake.py` | 常驻 | — | 否 |

**对应关系速记**：在售数据从哪来 → #1；随机团总价 → #2；实时提醒 → #3；已售入库 → #4；在售报告 → #5；已售报告 → #6。

---

## 二、一次性 / 手动脚本（按需跑，不常驻）

| 脚本 | 干什么 | 运行 | 用到的表 |
|---|---|---|---|
| `init_db.py` | 读 `schema.sql` 幂等建表（首次或新增表后跑一次） | `python init_db.py` | 建全部 |
| `sold_history_spider.py` | 已售**历史全量**深翻（首次建库存量，手动跑一次） | `python sold_history_spider.py` | 写 `deca_shop_record`、`deca_product_record`、`deca_report_record`、`deca_kami_record` |
| `get_token.py` | **root 直读本地** App 存储提取登录态写 `token.json`（供 #4 已售、#2 随机团选队用；token 失效时跑）。设备已 root，读 DataStore `deka_settings.preferences_pb` 解析当前登录账号，覆盖写 `token.json` | `python get_token.py` | — |
| `stats/export_teams_excel.py` | 把 `球队.json` 导出成 Excel | `python stats/export_teams_excel.py` | — |

---

## 三、库 / 辅助模块（被 import，不单独启动）

| 模块 | 作用 |
|---|---|
| `deca_sold_core.py` | **核心库**：签名 / token 续期 / 带重试请求 / 已售采集管道 / 随机团总价计算。被各已售脚本 `import deca_sold_core as core`。 |
| `auto_send_wx_msg.py` | **企微群机器人发送（主发送渠道，只此一份）**：`send_wechat_group_msg()` 发 text/markdown_v2、`send_wechat_group_file()` 发文件(Excel)。`on_sale/`、`stats/` 脚本用 `sys.path` 引导 import 根目录这份 —— **换群只改本文件 `WEBHOOK_URL` 一处**（当前指测试群）。 |
| `on_sale/deca_on_sale_daily_spider.py` | 原「在售每日采集」，**已退休不单独常驻**；其纯解析/落库函数（`parse_product`/`save_products`/`fill_product_details`/`_sweep_offsale`）被 #1、#3、#5 复用。**注：其 `fetch_all_onsale`（home/search 免 token 全站）2026/09/05 起已被站方砍成首屏 20，不再用于全量采集。** |
| `deca_wechat.py`（及 `on_sale/`、`stats/` 副本） | PC 版微信(wxauto4)发送，**2026/08/11 起停用**、保留可回退（提醒脚本切 `SEND_CHANNEL="pc"` 复用）。 |

---

## 四、数据表一览（谁写谁读）

| 表 | 说明 | 写入方 | 读取方 |
|---|---|---|---|
| `deca_onsale_shop_record` | 在售商家 | ~~#1~~（**商家发现 2026/09/05 已停**：`exhibition/list` 被砍成首屏 30 且需 token；表现为历史存量 161 家，新商家不再自动入库） | #5 |
| `deca_onsale_product_record` | 在售商品（最新状态，含 `team_total_amount`） | #1（仅 4 家监控商家）、#5（全站对账 161 家）、#2(改总价) | #2、#5 |
| `deca_onsale_product_daily_record` | 在售商品每日售卖快照 | #1、#5 | #5 |
| `deca_onsale_product_progress_record` | 在售进度时间序列（60s，变化才写） | #1 | #6 |
| `deca_buy_record` | 购买记录（去重买家名单） | #1 | #3、#6 |
| `deca_groupbuy_team_record` | 随机团各队明细 | #2、#4 | 报告/统计 |
| `deca_onsale_alert_record` | 在售提醒状态（`new_notified`/`half_notified`/`ended_notified` 去重） | #3 | #3 |
| `deca_shop_record` | 已售商家 | #4、历史全量 | — |
| `deca_product_record` | 已售商品（含详情/回放/`team_total_amount`） | #4、历史全量 | #6 |
| `deca_report_record` | 拆卡报告（开出的卡+中卡用户+卡图） | #4、历史全量 | #6 |
| `deca_kami_record` | 卡密清单（量大，`FILL_KAMI` 默认关） | #4(开关)、历史全量 | — |

> 表结构以 `schema.sql`（从库真实导出）为准；所有表统一带 `gmt_create_time` / `gmt_modified_time`。

---

## 五、部署 / 启动要点

1. **运行目录**：常驻脚本务必从项目根目录启动（`buy_record_spider` 会自动 `chdir` 到根），否则 `application.yml` / `token.json` / `./logs` 找不到。
2. **建表**：首次先 `python init_db.py`；历史存量先跑一次 `sold_history_spider.py`。
3. **token.json（一机一账号）**：**2026/09/05 起 #1/#3/#5 的在售采集也需 token**（免 token 全站接口被砍）。三台机各放一份 `token.json`，内含**本机账号**的 `phone`/`password`/`countryCode`（首次只填这三项，`deca_sold_core` 会自动密码登录补 `access`/`refresh`；缺失时回落硬编码主号）——这样各用各号、不互相顶号，打开文件即可分辨该机用哪个账号。旧 `get_token.py`（root 直读本地 App）仍可用于电脑 A 的主号。**带 token 请求走直连、免 token 详情走隧道换 IP**（`do_request(use_proxy=...)` 按调用区分）。
4. **企微群**：提醒与报告都发 `auto_send_wx_msg.WEBHOOK_URL`（当前=测试群）；换正式群**只改根目录 `auto_send_wx_msg.py` 一处**。
5. **启动顺序建议**：`init_db` →（首次）`sold_history_spider` → 常驻 #1 #2 #3 #4 → 定时 #5 #6 →（会锁屏的机器）#7。
6. **提醒消息不带商品链接**：分享落地页 `share-detail` 只认带 token 生成的 shareCode，免 token 一律失效；为不引入登录态已去链接、标题改加粗（详见 `docs/优化记录_得卡企微迁移_20260811.md`）。

---

## 六、历史遗留 / 暂不启用（勿误启）

| 脚本 | 状态 |
|---|---|
| ~~`on_sale/deca_sold_spider.py`~~（`deca_sold_record`） | 旧在售版已售采集，已被根目录 `sold_daily_spider.py` 取代 → **2026/08/20 脚本已删除；表 `deca_sold_record` 本就不存在** |
| ~~`on_sale/deca_track.py`~~（`deca_track_record`） | 历史遗留追踪脚本 → **2026/08/20 脚本已删除；表 `deca_track_record`(278 行) 已 DROP** |
| `on_sale/km_spdier.py`（`deca_onsale_kami_record`） | 在售卡密清单采集，量大、默认不跑 |
| `11.py` | 临时探测脚本（含旧 shareCode 样本），可删 |
| `*_bak.py` | 备份文件 |

---

## 七、签名 / Token 机制（精简）

- 业务接口需 `signature` 头：`signature = md5( md5(参数按 key 升序拼接) + currentTime[-6:] + "biu_card_nbclass" )`（逆向自 APK `mf/c0.java`，4 样本验证）。
- 部分接口另需 `Authorization: Bearer <JWT>`（`access token` 15 分钟过期），走 `token/refresh` 续期规避阿里云验证码风控；`密码登录` 仅兜底。
- 免 token 接口：商品详情 `groupbuy/detail`（含购买记录 `purchaseRecords`，高频轮询命脉）、分享校验 `groupbuy/share-detail`。
- 需 token 接口：**逐商家在售 `groupbuy/merchant/on-sale-list`（2026/09/05 起在售全量唯一入口）**、商家列表 `merchant/exhibition/list`、已售 `sold-list`、卡密 `card/list`、拆卡报告 `open-card-report`、回放 `live/replay/detail`、随机团 `team-options`。
- **2026/09/05 站方改版**：`home/search`（全站在售）与 `exhibition/list`（商家列表）都退化成「首屏推荐」——`home/search` 只返前 20、`page≥2` 空、`pageSize>20` 报 `10001`；`exhibition/list` 只返前 30。故全站免 token 翻页失效，在售/商家枚举改走带 token 的 `on-sale-list` + 库内已存商家 ID。
- **token.json 账号凭据**：现支持在 `token.json` 存 `phone`/`password`/`countryCode`（`deca_sold_core.load_token/save_token/login`），密码登录兜底优先用本机所配账号；缺失回落硬编码主号。旧 `get_token.py` 直读 App DataStore（`deka_settings.preferences_pb` 的 `switch_accounts`）仍可用于主号种子。
- 完整逆向与登录续期说明见 `on_sale/README.md`。

---

## 八、相关文档

- `HANDOFF.md` —— 完整交接文档（文件清单、DB 表、提醒逻辑、待办）。
- `docs/选队随机与剩余随机_总价口径与采集_20260811.md` —— 随机团总价口径设计。
- `docs/在售商品进度时间序列_采集与统计_20260811.md` —— 进度快照表与统计 SQL。
- `docs/优化记录_得卡企微迁移_20260811.md` —— 企微迁移与去链接优化记录。
- `docs/优化记录_deca报告用时列修复_20260812.md` —— 已售报告「到X%用时」列修复（删到100%、坍缩留空）+ 进度快照冻结排查。
- `buy_record_analysis/README.md` —— 购买记录采集子项目（去重逻辑演进）。
- `on_sale/README.md` —— 在售流程 + 签名/token 逆向原始说明。