Metadata-Version: 2.5
Name: ibspot_order_assistant
Version: 0.0.220
Summary: IBSPOT order assistant
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: click~=8.1.7
Requires-Dist: SQLAlchemy~=2.0.25
Requires-Dist: pyyaml~=6.0.1
Requires-Dist: gspread~=6.0.2
Requires-Dist: mysqlclient~=2.2.4
Requires-Dist: wrapt~=1.16
Requires-Dist: python-dateutil~=2.8
Requires-Dist: tzdata
Requires-Dist: PyDispatcher~=2.0
Requires-Dist: cmutils
Requires-Dist: sqlalchemy-utils~=0.41
Requires-Dist: shipengine
Requires-Dist: tracking_api
Requires-Dist: psycopg2-binary
Requires-Dist: python-telegram-bot~=21.0
Requires-Dist: gmail-api-wrapper
Requires-Dist: tenacity
Requires-Dist: gmail-api-wrapper
Requires-Dist: pytest
Requires-Dist: pytz
Requires-Dist: Jinja2
Requires-Dist: us
Project-URL: Documentation, https://github.com/FG-IT/ibspot_order_assistant/blob/main/README.md
Project-URL: Repository, https://github.com/FG-IT/ibspot_order_assistant
Import-Name: ibspot_order_assistant

# IBSPOT Order Assistant

IBSPOT 订单运营自动化工具，通过独立的命令行任务，在 IBSPOT / Spree、OMS、Google Sheets、仓库及财务数据库之间同步业务数据，并对接物流查询、客服和消息通知服务。

## 主要功能

| 业务范围 | 功能 |
| --- | --- |
| 订单与履约 | 订单、订单明细、采购表格及履约状态同步 |
| 仓库与物流 | 国内及国际仓库发货、ShipStation 发货与 webhook 事件、运单上传与轨迹更新 |
| 财务 | 付款、退款、拒付及拒付胜诉交易同步，成本上传、利润更新和结算生成 |
| 供应商与商品 | 供应商、库存地点、供应商商品和转售商品同步 |
| 通知与运营 | Telegram 订单通知、物流异常通知、评价邀请及 Google Ads 数据同步 |

任务入口以 [pyproject.toml](pyproject.toml) 中的 `[project.scripts]` 为准；具体参数与默认时间范围见 [script_entries.py](src/ibspot_order_assistant/script_entries.py)。`tasks/` 中的模块并非全部注册了命令行入口。

## 环境与安装

建议使用 Python 3.10 或更高版本。虽然项目元数据声明 `Python >= 3.8`，当前源码已使用 `zoneinfo`、内置泛型及 `X | None` 类型注解，不宜按 Python 3.8 环境部署。

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
```

项目使用 Flit 构建，依赖列表维护在 `pyproject.toml`。`mysqlclient` 安装可能需要系统提供编译工具、MySQL / MariaDB 开发库和 `pkg-config`。若 `cmutils`、`tracking_api` 等依赖无法从当前包源获取，需要使用团队提供的包源或安装包。

## 配置

### 配置文件位置

应用在导入包时读取固定位置的 `config.yml`，并创建工作目录：

| 系统 | 工作目录 |
| --- | --- |
| Linux | `/var/lib/ibspot_order_assistant` |
| macOS | `~/appdata/ibspot_order_assistant` |
| Windows | `%LOCALAPPDATA%\ibspot_order_assistant` |

运行账户需要对工作目录有读写权限。Linux 首次部署可由管理员创建目录并授权给运行账户：

```bash
sudo install -d -m 750 -o "$(id -un)" -g "$(id -gn)" /var/lib/ibspot_order_assistant
```

将下面的模板保存为工作目录下的 `config.yml`，再替换占位值。命令行当前未提供统一的 `--config` 参数，也不会自动读取项目根目录的 `.env`。即使只运行 `--help`，也需要先完成导入阶段使用的配置。

### 基础配置模板

```yaml
general:
  timezone: America/New_York
  environment: development
  ibspot_api_token: "REPLACE_WITH_TOKEN"
  # 使用相应 API 的任务还需要以下配置：
  # oms_api_domain: "https://oms.example.com"
  # cs_api_token: "REPLACE_WITH_TOKEN"

db_connections:
  # YAML 锚点仅用于复用示例结构；实际连接应分别填写。
  ibspot_reader: &mysql_connection
    driver: mysql+mysqldb
    host: "127.0.0.1:3306"
    database: "REPLACE_WITH_DATABASE"
    username: "REPLACE_WITH_USERNAME"
    password: "REPLACE_WITH_PASSWORD"
    charset: utf8mb4
  oms_test:
    <<: *mysql_connection
    database: "REPLACE_WITH_OMS_TEST_DATABASE"
  finance_dev:
    <<: *mysql_connection
    database: "REPLACE_WITH_FINANCE_DEV_DATABASE"
  ibspot_amazon_forward:
    <<: *mysql_connection
    database: "REPLACE_WITH_FORWARD_DATABASE"
  websites:
    <<: *mysql_connection
    database: "REPLACE_WITH_WEBSITES_DATABASE"
  ibspot_data:
    <<: *mysql_connection
    database: "REPLACE_WITH_DATA_DATABASE"
  cs:
    <<: *mysql_connection
    database: "REPLACE_WITH_CS_DATABASE"
```

数据库配置由 [session_utils.py](src/ibspot_order_assistant/utils/session_utils.py) 读取。连接 URL 使用 `host` 字段，非默认端口应写为 `主机:端口`；独立的 `port` 字段目前不会参与 URL 拼接。用户名和密码中的 URL 特殊字符需要进行相应编码。

`environment` 为 `production` 时，OMS 和财务连接名称分别切换为 `oms`、`finance`，需要补充这两个配置项；其他连接名称保持不变。开发环境切换仅影响这两组绑定，其他数据库也应配置为相应的测试资源。

会话模块会在导入时为所有当前环境的连接创建引擎，因此只执行某个任务也需要提供上述连接配置。仓库中的 [examples/config.yml](examples/config.yml) 是旧版单连接示例，不能直接用于当前版本。

### 按任务补充外部服务配置

Google Sheets 任务使用 OAuth 用户凭据，并要求授权账户可以访问目标表格：

```yaml
googlesheets_credentials:
  token: "REPLACE_WITH_ACCESS_TOKEN"
  refresh_token: "REPLACE_WITH_REFRESH_TOKEN"
  token_uri: "https://oauth2.googleapis.com/token"
  client_id: "REPLACE_WITH_CLIENT_ID"
  client_secret: "REPLACE_WITH_CLIENT_SECRET"
  scopes:
    - "https://www.googleapis.com/auth/drive"
```

Telegram 通知可配置开发告警和订单通知两组机器人：

```yaml
telegram_bot:
  dev:
    token: "REPLACE_WITH_BOT_TOKEN"
    chat_group_id: "REPLACE_WITH_CHAT_ID"
  ibspot_messenger:
    token: "REPLACE_WITH_BOT_TOKEN"
    chat_group_id: "REPLACE_WITH_CHAT_ID"
```

物流查询任务还需要 `tracking_api` 配置，其结构由所安装的 `tracking_api` 包决定；评价邀请发送任务需要 `klaviyo.api_key` 和 `klaviyo.public_key`。请按实际执行的任务补充配置，不要将真实凭据提交到仓库。

## 运行任务

安装后每个任务都是独立命令，参数名使用下划线，日期格式为 `YYYY-MM-DD`。配置完成后可查看帮助：

```bash
ibspot_orders_syncer --help
fulfillment_syncer_v2 --help
generate_settlements --help
```

以下命令会实际执行同步或更新，请先将连接配置为测试资源，并按业务范围调整日期。

```bash
# 按更新时间同步订单及订单明细
ibspot_orders_syncer --date_start 2026-11-01
ibspot_order_items_syncer --date_start 2026-11-01

# 同步指定 Google Sheets 工作表的履约信息，向前回溯 40 天
fulfillment_syncer_v2 --ss_id YOUR_SPREADSHEET_ID --sheet_name "Sheet1,Sheet2" --date_start 2026-11-09 --days_back 40

# 更新指定订单的物流状态
order_shipment_status_updator --order_number YOUR_ORDER_NUMBER

# 按日期范围同步退款
ibspot_order_refunds_syncer --date_start 2026-11-01 --date_end 2026-11-09

# 更新指定订单的利润
order_profit_updator --order_number YOUR_ORDER_NUMBER
```

### 常用命令索引

| 场景 | 命令 |
| --- | --- |
| 订单及明细 | `ibspot_orders_syncer`、`ibspot_order_items_syncer`、`sync_orders`、`sync_order_items` |
| 表格履约同步 | `sync_fulfillment`、`fulfillment_syncer_v2` |
| 履约及发货状态 | `ibspot_order_fulfillments_updator`、`order_fulfillment_shipment_status_syncer` |
| 仓库发货 | `sync_warehouse_shipments`、`ibspot_warehouse_shipments_syncer`、`intl_warehouse_shipments_syncer` |
| 国际仓库明细 | `intl_warehouse_shipment_items_syncer`、`intl_warehouse_shipment_items_updator` |
| ShipStation | `sync_shipstation_shipments`、`shipstation_webhook_events_syncer` |
| 运单与轨迹 | `ibspot_shipments_syncer`、`ibspot_tracking_uploader`、`ibspot_tracking_status_syncer`、`order_shipment_status_updator` |
| 退款及支付状态 | `ibspot_order_refunds_syncer`、`ibspot_payment_status_syncer` |
| 财务交易 | `sync_order_transactions`、`sync_order_refunds_transactions`、`sync_order_disputes_transactions`、`sync_order_disputes_won_transactions` |
| 成本、利润及结算 | `upload_order_cost`、`order_profit_updator`、`generate_settlements` |
| 供应商 | `sync_data_vendors`、`sync_oms_vendors`、`sync_finance_vendors`、`supplier_info_syncer`、`supplier_info_check` |
| 商品与库存 | `vendor_products_syncer`、`resell_products_syncer`、`sync_vendor_stock_locations`、`ibspot_inventory_units_syncer` |
| 消息与评价邀请 | `ibspot_orders_notification`、`ibspot_shipments_exceptions_notification`、`ibspot_review_request_syncer`、`ibspot_review_request_sender` |
| 广告数据 | `sync_google_ads_account_insights`、`ibspot_order_ads_fee_syncer` |

`init_db` 仅尝试创建 `Fulfillments`、`Trackings` 和 `LineItems` 对应的表，并非完整数据库初始化或迁移工具。部署前仍需准备任务依赖的数据库结构及基础业务数据。

### 表格同步与时间范围

`sync_fulfillment` 默认回溯 45 天，`fulfillment_syncer_v2` 默认回溯 40 天。采购表格的跨表迁移、重复明细和历史记录会影响差异计算，应覆盖完整业务周期；历史使用约定是至少覆盖 30 天，补历史数据时应扩大范围。

V2 会对表格与数据库记录进行差异比较，执行新增、更新、软删除和缺失标记。旧文档中的“已履约记录任何情况下均不删除”不适用于 V2 的所有分支；具体匹配和删除条件以 [fulfillment_syncer_v2.py](src/ibspot_order_assistant/tasks/fulfillment_syncer_v2.py) 为准。

部分任务使用 `DateFlag` 保存同步进度：显式 `--date_start` 优先，否则读取已有标记，没有标记时通常从三天前开始。其他任务有各自的默认时间范围，不应假定所有命令都支持相同的增量机制或起止日期语义。

## 日志与调度

大部分命令通过统一的 `execute()` 执行器运行，在工作目录下按任务创建目录，记录 PID、心跳和日志，并检查同名任务是否已有实例运行。

```text
ibspot_order_assistant/
├── config.yml
├── pickles/
└── <task_name>/
    ├── logs/<task_name>.log
    ├── _heartbeat
    └── flag/                  # 使用 DateFlag 的任务
```

控制台输出 DEBUG 及以上日志，任务文件记录 INFO 及以上日志；日志文件达到 200 MiB 后轮转，默认保留 5 份备份。配置了开发 Telegram 机器人时，相关错误信号会触发告警。

`execute()` 捕获任务异常后会记录日志并发送错误信号，未重新抛出异常；外部调度不能仅以进程退出码判断任务成功，还应检查日志、心跳及业务结果。

仓库未提供统一调度配置。部署时可使用 cron、systemd timer 或现有调度平台调用独立命令，并明确任务间的数据依赖和执行顺序。

## 项目结构

```text
src/ibspot_order_assistant/
├── __init__.py             # 配置加载、工作目录、日志和错误通知
├── script_entries.py       # Click 命令入口及任务执行器
├── tasks/                  # 业务同步、更新和通知任务
├── model/                  # Spree、OMS、财务、仓库等 SQLAlchemy 模型
├── service/                # 数据库、表格、API、结算和消息服务
├── api/                    # IBSPOT / Spree API 封装
├── common/                 # 地址、订单备注等业务对象
└── utils/                  # 会话、同步标记、物流和表格工具
examples/                   # 历史配置示例
tests/                      # 测试、集成验证和临时脚本
```

## 开发与验证

项目使用 pytest，`pytest.ini` 已将 `src` 加入 Python 搜索路径。准备好应用配置后，可先运行范围较小的备注解析测试：

```bash
python -m pytest tests/common/test_order_remark.py
```

现有测试包含数据库建表、Google Sheets 和 Telegram 等真实服务操作，完整测试集需要专用测试数据库及服务凭据。`tests/config_test.yml` 由测试夹具读取，但不会替代包导入时读取的工作目录配置；`tests/tmp/` 中的脚本应逐个检查后再执行。

