增量

aliyun-sync/COMMANDS.md

@@ -0,0 +1,304 @@
+# 阿里云 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
+```
+
+### 启动定时同步
+
+```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
+```
+
+### 查询数据库最新账单消费时间
+
+```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 | 终止 |
+
+注意：这是当前终端进程内热键，不是系统级全局热键。