ournd/dev/: ibspot-order-assistant-0.0.220 metadata and description
IBSPOT order assistant
| description_content_type | text/markdown |
| project_urls |
|
| requires_dist |
|
| requires_python | >=3.8 |
| File | Tox results | History |
|---|---|---|
ibspot_order_assistant-0.0.220-py3-none-any.whl
|
|
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/ 中的脚本应逐个检查后再执行。