# aliyun-aps-sync

Node 版阿里云 APS 同步工具。

当前主流程已经统一为：

- Playwright 抓取 APS 页面
- 本地保留 `current/history/delta/checkpoints/errors` 数据
- 同步过程中直接写入 MySQL
- 定时任务默认执行日增量

## 同步范围

- customers
- customerDetails
- orders
- orderDetails
- bills
- messages

## 模式说明

### Full 模式

执行：

```bash
npm run sync
```

如果要让 full sync 从已有 checkpoint 继续（覆盖 customers / customerDetails / orders / orderDetails / bills / messages）：

```bash
npm run sync -- --resume
```

行为：

- 抓全量 customer + customerDetails
- 抓 orders / orderDetails / bills / messages
- 同步过程中直接写数据库

### Incremental 模式

执行：

```bash
npm run incremental
```

行为：

- 不抓 customer
- 抓 orders / orderDetails / bills / messages
- 以数据库 watermark + overlap 为增量窗口

### Hot 模式

执行：

```bash
npm run hot
```

行为：

- 每次只抓**当天订单**
- 从订单第一页开始扫描
- 订单列表按“连续稳定行 / 连续稳定页 / 最大页数”提前停止
- 订单详情只抓：新增订单、列表有变化订单、缺失详情订单、非终态且到达兜底刷新时间的订单
- 消息按数据库最新时间回退分钟 overlap 后抓取，并在旧页提前停止

适用场景：

- 白天高频追当天订单
- 订单量较大，不希望每 5 分钟重复扫完整个当天分页
- 需要兼顾详情完整性和抓取效率

## 登录

```bash
npm run login
```

会自动验证：

- 我的客户
- 账单查询

并保存登录态到：

- `.browser/`
- `.browser/storage-state.json`

## 账单

### 单独抓账单

```bash
npm run bills
```

### 从最新 checkpoint 继续抓账单

```bash
npm run bills -- --resume
```

## 订单

只同步订单：

```bash
npm run orders
```

说明：该命令会同时抓取：

- orders（订单列表）
- orderDetails（订单详情）

订单增量：

```bash
npm run orders -- --incremental
```

订单从 checkpoint 继续：

```bash
npm run orders -- --resume
```

## 消息

单独抓消息：

```bash
npm run messages
```

## 高频同步

手动执行一次高频同步：

```bash
npm run hot
```

如果 PowerShell 禁止 `npm.ps1`，可以直接执行：

```bash
node src/index.js hot
```

说明：

- `hot` 只覆盖当天订单、订单详情、消息
- 不抓 customer / customerDetails / bills
- 适合作为工作时间内的高频轮询任务

## 定时任务

```bash
npm run schedule
```

默认按 `.env` 中：

```env
ALIYUN_APS_SCHEDULE_MODE=incremental
```

执行日增量。

如果要执行 5 分钟高频同步，可以设置：

```env
ALIYUN_APS_SCHEDULE_MODE=hot
ALIYUN_APS_HOT_CRON=*/5 * * * *
```

然后执行：

```bash
npm run schedule
```

说明：

- `incremental`：按现有增量策略抓 orders / orderDetails / bills / messages
- `full`：按全量策略执行
- `hot`：每轮只抓当天 orders / orderDetails / messages
- hot 模式内置任务锁；如果上一轮还没结束，会跳过下一轮，避免重叠执行

## 增量窗口

### 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
ALIYUN_APS_SCHEDULE_MODE=hot
ALIYUN_APS_HOT_CRON=*/5 * * * *
ALIYUN_APS_HOT_MESSAGE_OVERLAP_MINUTES=15
ALIYUN_APS_HOT_ORDER_STABLE_THRESHOLD=100
ALIYUN_APS_HOT_ORDER_STABLE_PAGE_THRESHOLD=2
ALIYUN_APS_HOT_ORDER_MAX_PAGES=20
ALIYUN_APS_HOT_MESSAGE_MAX_PAGES=10
ALIYUN_APS_HOT_ORDER_DETAIL_REFRESH_MINUTES=30
ALIYUN_APS_HOT_FINAL_STATUSES=已完成,已关闭,已取消,已退款完成
```

含义：

- `ALIYUN_APS_HOT_CRON`：高频任务 cron，默认每 5 分钟一次
- `ALIYUN_APS_HOT_MESSAGE_OVERLAP_MINUTES`：消息高频模式的回扫分钟数
- `ALIYUN_APS_HOT_ORDER_STABLE_THRESHOLD`：订单扫描中连续多少条稳定记录后停止
- `ALIYUN_APS_HOT_ORDER_STABLE_PAGE_THRESHOLD`：订单扫描中连续多少页无新增/变更后停止
- `ALIYUN_APS_HOT_ORDER_MAX_PAGES`：订单每轮最多扫描页数，防止高峰期跑太久
- `ALIYUN_APS_HOT_MESSAGE_MAX_PAGES`：消息每轮最多扫描页数
- `ALIYUN_APS_HOT_ORDER_DETAIL_REFRESH_MINUTES`：非终态订单详情兜底刷新间隔
- `ALIYUN_APS_HOT_FINAL_STATUSES`：视为终态的订单状态，终态订单在无变化时会尽量跳过详情抓取

默认策略：

- 订单按最新到最旧扫描
- 新订单或列表字段变化的订单会进入详情抓取
- 已抓过且无变化的终态订单会直接跳过详情
- 非终态订单会按兜底刷新时间周期性重抓详情
- 消息使用 watermark + overlap，避免 5 分钟轮询时漏边界消息

## 数据库配置

`.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_MODE=launch
ALIYUN_APS_BROWSER_CHANNEL=
ALIYUN_APS_BROWSER_EXECUTABLE_PATH=
ALIYUN_APS_CDP_URL=http://127.0.0.1:9222
```

说明：

- `ALIYUN_APS_BROWSER_MODE=launch`：由 Playwright 自己启动浏览器。
- `ALIYUN_APS_BROWSER_MODE=cdp`：附着到你手动打开的 Chrome/Edge。
- 两项都留空：使用 Playwright 自带 Chromium。
- `ALIYUN_APS_BROWSER_CHANNEL=chrome`：使用本机 Chrome。
- `ALIYUN_APS_BROWSER_CHANNEL=msedge`：使用本机 Edge。
- `ALIYUN_APS_BROWSER_EXECUTABLE_PATH=...`：指定本地浏览器可执行文件路径。

### 手动打开 Chrome 后再让脚本附着

如果阿里云风控要求你手动过滑块，可以改成：

```env
ALIYUN_APS_BROWSER_MODE=cdp
ALIYUN_APS_CDP_URL=http://127.0.0.1:9222
```

然后你手动启动浏览器：

```powershell
chrome.exe --remote-debugging-port=9222 --user-data-dir="C:\temp\aps-manual-profile"
```

在浏览器里手动登录并过验证码后，再执行：

```bash
npm run sync
```

或：

```bash
npm run bills -- --resume
```

附着模式下脚本不会自动关闭你手动打开的浏览器。

## 邮件告警

任意运行异常会尝试：

- 保存错误上下文 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。