python切换node的版本

aliyun-sync/aliyun-aps-sync/README.md

@@ -1,82 +1,223 @@
 # aliyun-aps-sync
 
-用于抓取阿里云伙伴中心里的 `我的客户`、`订单查询`、`账单查询`，并把结果和本地上一次同步结果做增量对比。
+Node 版阿里云 APS 同步工具。
 
-## 功能
+当前主流程已经统一为：
 
-- 首次 `login` 用浏览器手动登录，后续复用本地登录态。
-- `sync` 会同步 3 个模块的数据。
-- 同步后会生成：
-  - `data/current/*.json` 当前全量
-  - `data/history/<dataset>/*.json` 每次快照
-  - `data/delta/<dataset>/*.json` 增量变化
-  - `data/runs/*.json` 每次任务汇总
-- `schedule` 支持常驻进程方式按 cron 表达式每天自动同步。
+- Playwright 抓取 APS 页面
+- 本地保留 `current/history/delta/checkpoints/errors` 数据
+- 同步过程中直接写入 MySQL
+- 定时任务默认执行日增量
 
-## 安装
+## 同步范围
 
-```bash
-cd /Users/qiangredhad/aliyun-aps-sync
-npm install
-cp .env.example .env
-```
+- customers
+- customerDetails
+- orders
+- orderDetails
+- bills
+- messages
 
-## 配置
+## 模式说明
 
-`.env` 里最重要的时间范围：
+### Full 模式
 
-- `ALIYUN_APS_ORDER_START_DATE`: 订单查询的起始日期，会按月滚动抓取直到今天。
-- `ALIYUN_APS_INCREMENTAL_ORDER_START_DATE`: 订单/订单详情在增量模式下的指定起始日期；留空时仍默认只查昨天。
-- `ALIYUN_APS_BILL_START_MONTH`: 账单查询的起始佣金月份，会按月滚动抓取直到当前月。
-
-## 使用
-
-1. 首次登录并保存会话
-
-```bash
-npm run login
-```
-
-2. 手动执行一次同步
+执行：
 
 ```bash
 npm run sync
 ```
 
-仅抓账单：
+行为：
+
+- 抓全量 customer + customerDetails
+- 抓 orders / orderDetails / bills / messages
+- 同步过程中直接写数据库
+
+### Incremental 模式
+
+执行：
+
+```bash
+npm run incremental
+```
+
+行为：
+
+- 不抓 customer
+- 抓 orders / orderDetails / bills / messages
+- 以数据库 watermark + overlap 为增量窗口
+
+## 登录
+
+```bash
+npm run login
+```
+
+会自动验证：
+
+- 我的客户
+- 账单查询
+
+并保存登录态到：
+
+- `.browser/`
+- `.browser/storage-state.json`
+
+## 账单
+
+### 单独抓账单
 
 ```bash
 npm run bills
 ```
 
-如果要从最新账单 checkpoint 继续：
+### 从最新 checkpoint 继续抓账单
 
 ```bash
 npm run bills -- --resume
 ```
 
-如果需要在增量模式下让订单和订单详情从指定日期开始补抓，可以配置：
+## 消息
+
+单独抓消息：
 
 ```bash
-ALIYUN_APS_INCREMENTAL_ORDER_START_DATE=2026-01-01
+npm run messages
 ```
 
-或临时执行：
-
-```bash
-npm run sync -- --incremental-order-start-date=2026-01-01
-```
-
-3. 常驻定时同步
+## 定时任务
 
 ```bash
 npm run schedule
 ```
 
-默认 cron 是每天早上 6 点，可在 `.env` 里改 `ALIYUN_APS_CRON`。
+默认按 `.env` 中：
 
-## 注意
+```env
+ALIYUN_APS_SCHEDULE_MODE=incremental
+```
 
-- 脚本现在基于页面表格 DOM 抓取，如果阿里云伙伴中心页面结构改版，需要调整 `src/sync.js` 里的表格和筛选器选择逻辑。
-- 订单和账单的日期输入框是通过页面已有日期值自动识别的，所以首次跑之前建议先在页面确认默认筛选存在。
-- 如果登录态过期，重新执行 `npm run login` 即可。
+执行日增量。
+
+## 增量窗口
+
+### orders
+
+由数据库中 `aps_order.order_time` 最大值决定，回退：
+
+```env
+ALIYUN_APS_ORDER_INCREMENTAL_OVERLAP_DAYS=2
+```
+
+### bills
+
+由数据库中 `aps_bill.consumption_time` 最大值决定，回退：
+
+```env
+ALIYUN_APS_BILL_INCREMENTAL_OVERLAP_DAYS=7
+```
+
+### messages
+
+由数据库中 `aliyun_aps_messages.gmt_modified/gmt_created` 最大值决定，回退：
+
+```env
+ALIYUN_APS_MESSAGE_INCREMENTAL_OVERLAP_DAYS=7
+```
+
+## 数据库配置
+
+`.env` 需要配置：
+
+```env
+ALIYUN_APS_DB_HOST=
+ALIYUN_APS_DB_PORT=3306
+ALIYUN_APS_DB_USER=
+ALIYUN_APS_DB_PASSWORD=
+ALIYUN_APS_DB_NAME=
+ALIYUN_APS_DB_CHARSET=utf8mb4
+ALIYUN_APS_DB_CONNECTION_LIMIT=5
+```
+
+## 浏览器配置
+
+默认不再强制使用 Google Chrome。
+
+可选配置：
+
+```env
+ALIYUN_APS_BROWSER_CHANNEL=
+ALIYUN_APS_BROWSER_EXECUTABLE_PATH=
+```
+
+说明：
+
+- 两项都留空：使用 Playwright 自带 Chromium。
+- `ALIYUN_APS_BROWSER_CHANNEL=chrome`：使用本机 Chrome。
+- `ALIYUN_APS_BROWSER_CHANNEL=msedge`：使用本机 Edge。
+- `ALIYUN_APS_BROWSER_EXECUTABLE_PATH=...`：指定本地浏览器可执行文件路径。
+
+## 邮件告警
+
+任意运行异常会尝试：
+
+- 保存错误上下文 JSON
+- 截图当前页面
+- 发送告警邮件
+
+`.env` 配置：
+
+```env
+ALIYUN_APS_SMTP_HOST=
+ALIYUN_APS_SMTP_PORT=465
+ALIYUN_APS_SMTP_SECURE=true
+ALIYUN_APS_SMTP_USER=
+ALIYUN_APS_SMTP_PASS=
+ALIYUN_APS_NOTIFY_EMAIL=
+```
+
+错误文件目录：
+
+```text
+data/errors/<dataset>/
+```
+
+## 本地数据目录
+
+```text
+data/current/
+data/history/
+data/delta/
+data/checkpoints/
+data/runs/
+data/errors/
+```
+
+## customer 状态规则
+
+- full 抓到 customer 时，默认写为 `active=1`
+- messages 中如果明确识别到“释放”，则标记：
+  - `active=0`
+  - `status='released'`
+- messages 中如果明确识别到“关联/报备成功/新增客户/绑定客户”，则恢复：
+  - `active=1`
+  - `status='active'`
+
+## 安装
+
+```bash
+npm install
+```
+
+## 运行时热键
+
+- `F7` 暂停
+- `F8` 继续
+- `F9` 终止
+
+## 说明
+
+- Python 入库脚本已不再是主流程依赖。
+- bills 仍保留 checkpoint/resume 能力。
+- messages 当前先按列表分页抓取，如后续页面需要详情抓取，再补 detail flow。