ournd/dev/: ibspot-order-assistant-0.0.220 metadata and description

Simple index

IBSPOT order assistant

description_content_type text/markdown
project_urls
  • Documentation, https://github.com/FG-IT/ibspot_order_assistant/blob/main/README.md
  • Repository, https://github.com/FG-IT/ibspot_order_assistant
requires_dist
  • click~=8.1.7
  • SQLAlchemy~=2.0.25
  • pyyaml~=6.0.1
  • gspread~=6.0.2
  • mysqlclient~=2.2.4
  • wrapt~=1.16
  • python-dateutil~=2.8
  • tzdata
  • PyDispatcher~=2.0
  • cmutils
  • sqlalchemy-utils~=0.41
  • shipengine
  • tracking_api
  • psycopg2-binary
  • python-telegram-bot~=21.0
  • gmail-api-wrapper
  • tenacity
  • gmail-api-wrapper
  • pytest
  • pytz
  • Jinja2
  • us
requires_python >=3.8
File Tox results History
ibspot_order_assistant-0.0.220-py3-none-any.whl
Size
198 KB
Type
Python Wheel
Python
3

IBSPOT Order Assistant

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

主要功能

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

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

环境与安装

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

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 首次部署可由管理员创建目录并授权给运行账户:

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

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

基础配置模板

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 读取。连接 URL 使用 host 字段,非默认端口应写为 主机:端口;独立的 port 字段目前不会参与 URL 拼接。用户名和密码中的 URL 特殊字符需要进行相应编码。

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

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

按任务补充外部服务配置

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

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 通知可配置开发告警和订单通知两组机器人:

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。配置完成后可查看帮助:

ibspot_orders_syncer --help
fulfillment_syncer_v2 --help
generate_settlements --help

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

# 按更新时间同步订单及订单明细
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 为准。

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

日志与调度

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

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 或现有调度平台调用独立命令,并明确任务间的数据依赖和执行顺序。

项目结构

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 搜索路径。准备好应用配置后,可先运行范围较小的备注解析测试:

python -m pytest tests/common/test_order_remark.py

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