# 阿里云 APS 同步命令清单

本文档整理项目中常用的爬取、同步、入库、调度、增量和运行时控制命令。

## 1. 项目目录

### 前端爬取项目

```powershell
cd D:\project\python\aliyun-sync\aliyun-aps-sync
```

### 后端入库项目

```powershell
cd D:\project\python\aliyun-sync\aps-aliyun-sync
```

## 2. 安装依赖

在前端爬取项目目录执行：

```powershell
npm install
```

## 3. 登录

```powershell
npm run login
```

作用：

- 打开浏览器。
- 手动完成阿里云 / RAM 登录。
- 自动验证“我的客户”和“账单查询”页面。
- 保存登录态到 `.browser/` 和 `.browser/storage-state.json`。

## 4. 爬取 / 同步命令

### 全量同步全部模块

```powershell
npm run sync
```

默认同步：

- customers
- customerDetails
- orders
- orderDetails
- bills

### 仅爬取账单

```powershell
npm run bills
```

### 基于 checkpoint 断点续爬账单

```powershell
npm run bills -- --resume
```

作用：

- 自动读取 `data/checkpoints/bills/` 下最新 checkpoint。
- 从 checkpoint 记录的月份和页码之后继续抓取。

### 启动定时同步

```powershell
npm run schedule
```

默认 cron：

```env
ALIYUN_APS_CRON=0 6 * * *
```

表示每天早上 6 点执行。

## 5. 增量同步

### 默认增量同步

在 `.env` 中设置：

```env
ALIYUN_APS_FULL_SYNC=false
```

然后执行：

```powershell
npm run sync
```

默认行为：

- 订单只查昨天。
- 订单详情跟随本次订单结果。
- 账单按数据库最新消费时间增量。

### 指定订单 / 订单详情增量起始日期

临时命令方式：

```powershell
npm run sync -- --incremental-order-start-date=2026-01-01
```

`.env` 固定配置方式：

```env
ALIYUN_APS_FULL_SYNC=false
ALIYUN_APS_INCREMENTAL_ORDER_START_DATE=2026-01-01
```

然后执行：

```powershell
npm run sync
```

行为：

- 订单从指定日期开始补抓到今天。
- 订单详情跟随这些订单抓取。

### 指定账单起始月份

在 `.env` 中设置：

```env
ALIYUN_APS_BILL_START_MONTH=2024-01
```

然后执行：

```powershell
npm run bills
```

说明：当前账单爬取支持按月份开始；如需按具体日期开始，需要新增账单日期过滤参数。

## 6. 后端入库命令

进入后端入库项目目录：

```powershell
cd D:\project\python\aliyun-sync\aps-aliyun-sync
```

### 全量入库

```powershell
python aps_db_sync.py
```

### 增量入库

```powershell
python aps_db_sync.py --incremental
```

### 指定同步对象入库

```powershell
python aps_db_sync.py --sync-target all
python aps_db_sync.py --sync-target customer
python aps_db_sync.py --sync-target order
python aps_db_sync.py --sync-target orderdetails
python aps_db_sync.py --sync-target bills
```

### 增量只同步账单入库

```powershell
python aps_db_sync.py --incremental --sync-target bills
```

### 直接将最新 bills checkpoint 入库

```powershell
python aps_db_sync.py --sync-target bills --from-checkpoint
```

### 查询数据库最新账单消费时间

```powershell
python aps_db_sync.py --latest-bill-consumption-time
```

## 7. 后端调度器命令

进入后端入库项目目录：

```powershell
cd D:\project\python\aliyun-sync\aps-aliyun-sync
```

### 启动调度器

```powershell
python aps_scheduler.py
```

### 指定同步对象启动调度器

```powershell
python aps_scheduler.py --sync-target all
python aps_scheduler.py --sync-target customer
python aps_scheduler.py --sync-target order
python aps_scheduler.py --sync-target orderdetails
python aps_scheduler.py --sync-target bills
```

## 8. 常用 `.env` 示例

文件位置：

```powershell
D:\project\python\aliyun-sync\aliyun-aps-sync\.env
```

### 全量模式

```env
ALIYUN_APS_BASE_URL=https://aps.aliyun.com
ALIYUN_APS_HEADLESS=false
ALIYUN_APS_TIMEZONE=Asia/Shanghai
ALIYUN_APS_CRON=0 6 * * *
ALIYUN_APS_FULL_SYNC=true
ALIYUN_APS_ORDER_START_DATE=2024-01-01
ALIYUN_APS_INCREMENTAL_ORDER_START_DATE=
ALIYUN_APS_BILL_START_MONTH=2024-01
ALIYUN_APS_CLOSE_BROWSER=true
ALIYUN_APS_DB_SYNC_SCRIPT=../aps-aliyun-sync/aps_db_sync.py
```

### 增量模式：默认只查昨天订单

```env
ALIYUN_APS_FULL_SYNC=false
ALIYUN_APS_INCREMENTAL_ORDER_START_DATE=
```

### 增量模式：指定订单起始日期

```env
ALIYUN_APS_FULL_SYNC=false
ALIYUN_APS_INCREMENTAL_ORDER_START_DATE=2026-01-01
```

## 9. 常用组合

### 首次使用

```powershell
cd D:\project\python\aliyun-sync\aliyun-aps-sync
npm install
npm run login
npm run sync
```

### 只抓账单

```powershell
cd D:\project\python\aliyun-sync\aliyun-aps-sync
npm run login
npm run bills
```

### 订单 / 订单详情从指定日期补抓

```powershell
cd D:\project\python\aliyun-sync\aliyun-aps-sync
npm run login
npm run sync -- --incremental-order-start-date=2026-01-01
```

### 抓完后只同步账单入库

```powershell
cd D:\project\python\aliyun-sync\aps-aliyun-sync
python aps_db_sync.py --sync-target bills
```

### 抓完后增量同步账单入库

```powershell
cd D:\project\python\aliyun-sync\aps-aliyun-sync
python aps_db_sync.py --incremental --sync-target bills
```

## 10. 清理登录态

如果登录态异常，可以删除 `.browser` 后重新登录：

```powershell
cd D:\project\python\aliyun-sync\aliyun-aps-sync
Remove-Item -Recurse -Force .browser
npm run login
```

## 11. 运行时热键

脚本运行时可在当前终端中使用：

| 按键 | 功能 |
| --- | --- |
| F7 | 暂停 |
| F8 | 继续 |
| F9 | 终止 |

注意：这是当前终端进程内热键，不是系统级全局热键。