# 得卡 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/`；本文只讲「**要启动哪些脚本、各干什么、用哪些表**」。

---

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

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

| # | 脚本 | 干什么 | 启动命令 | 频率 | 用到的表 | 需 token |
|---|---|---|---|---|---|---|
| 1 ★ | `buy_record_analysis/buy_record_spider.py` | **在售数据主采集 + 购买记录**：①每分钟免 token 拉全站在售落库 + 每 60s 记进度快照；②采本商家购买记录（自适应频率、售罄/结束自动停采） | `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，按上架时间提醒「窗口起点后新上架」+ 进度过半 + 一车结束战报 | `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）**：查库生成多 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` | 原「在售每日采集」，**已退休不单独常驻**；其免 token 抓取函数（`fetch_all_onsale`/`get_shop_list` 等）被 #1、#3 复用。 |
| `deca_wechat.py`（及 `on_sale/`、`stats/` 副本） | PC 版微信(wxauto4)发送，**2026/08/11 起停用**、保留可回退（提醒脚本切 `SEND_CHANNEL="pc"` 复用）。 |

---

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

| 表 | 说明 | 写入方 | 读取方 |
|---|---|---|---|
| `deca_onsale_shop_record` | 在售商家 | #1 | #5 |
| `deca_onsale_product_record` | 在售商品（最新状态，含 `team_total_amount`） | #1、#2(改总价) | #2、#5 |
| `deca_onsale_product_daily_record` | 在售商品每日售卖快照 | #1 | #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**：#4（已售）与 #2（随机团选队）需登录态；失效时跑 `get_token.py` 刷新（**root 直读本地**，替代旧 mitmproxy 代理抓包；脚本认「最新登录」账号，多账号切换时先在 App 切到目标账号再跑）。#1/#3 全链路免 token。
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 接口：全站在售 `home/search`、商品详情 `groupbuy/detail`、分享校验 `groupbuy/share-detail`。
- 需 token 接口：已售 `sold-list`、卡密 `card/list`、拆卡报告 `open-card-report`、回放 `live/replay/detail`、随机团 `team-options`。
- **token.json 来源**：设备已 root，`get_token.py` 直读 App 的 Jetpack DataStore（`files/datastore/deka_settings.preferences_pb`，token 存在顶层 key `switch_accounts` 的 JSON 里，账号字段 `uid`）解析当前登录账号的 `accessToken`/`refreshToken` 覆盖写；只需种一次，之后由 `deca_sold_core.ensure_token` 靠 `refreshToken` 自续期。已弃用 mitmproxy 代理抓包（`capture_token.py`/`run_capture_token.py` 已删）。
- 完整逆向与登录续期说明见 `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 逆向原始说明。