Inventory Analytics

Inventory Analytics 是一个内部库存数据处理项目，围绕委外批次库存上传、渠道库存统计同步、批次库存统计报表三条业务链路运行。项目从 Raw PostgreSQL、Analytics PostgreSQL 和飞书多维表格之间同步与汇总库存数据，并支持本地执行、Docker 部署和 Prefect 定时调度。

项目目标

• 上传委外批次库存文件，并写入 Raw 数据库。
• 从 Analytics 数据库读取渠道库存、锁定库存、销售和商品信息。
• 生成批次库存统计数据，可输出本地报表，也可同步到飞书多维表格。
• 通过 Prefect 每天定时执行渠道库存统计和批次库存统计同步。
• 统一日志输出，保留关键节点与异常信息，同时避免输出数据库、飞书等敏感配置。

核心链路

1. 委外批次库存上传

入口：

python3 scripts/upload_batch_inventory.py

功能：

• 启动本地上传页面。
• 支持 Excel 和 CSV 文件上传。
• 保存原始文件到 batch_inventory_data/。
• 将解析后的每一行写入 Raw PostgreSQL 的 raw_data.wangdian_batch_inventory。

兼容入口：

python3 upload_inventory_page.py

2. 渠道库存统计同步飞书

入口：

python3 scripts/sync_channel_inventory.py

功能：

• 读取飞书 Base 与目标表信息。
• 查询 Analytics PostgreSQL 中的渠道库存数据。
• 按目标品牌和飞书字段配置整理数据。
• 清空并重写飞书目标表记录。

可选动作：

python3 scripts/sync_channel_inventory.py --action feishu
python3 scripts/sync_channel_inventory.py --action postgres
python3 scripts/sync_channel_inventory.py --action sync-brand
python3 scripts/sync_channel_inventory.py --action all

兼容入口：

python3 sync_channel_inventory.py --action all
python3 list_feishu_base_tables.py --action all

3. 批次库存统计报表

入口：

python3 scripts/generate_batch_inventory_report.py

功能：

• 读取 Raw 数据库中最新的委外批次库存。
• 查询 Analytics 数据库中的店铺库存、锁定库存、商品信息和近 30 天销售数量。
• 按批次维度汇总库存数据。
• 计算保质期、距离到期天数、效期比例等字段。
• 可输出本地 Excel/CSV 报表。
• 可同步到飞书 批次库存 表。

常用参数：

python3 scripts/generate_batch_inventory_report.py --skip-feishu-sync
python3 scripts/generate_batch_inventory_report.py --skip-report-output
python3 scripts/generate_batch_inventory_report.py --output reports/custom.xlsx
python3 scripts/generate_batch_inventory_report.py --feishu-table 批次库存

兼容入口：

python3 generate_batch_inventory_report.py
python3 generate_yxt_batch_inventory_report.py

目录结构

.
├── inventory_analytics/                  # 当前主包
│   ├── config.py                         # 配置加载
│   ├── logging_utils.py                  # 日志与脱敏
│   ├── paths.py                          # 项目路径
│   ├── batch_upload/                     # 委外批次库存上传
│   ├── batch_inventory_report/           # 批次库存统计报表
│   ├── channel_inventory_sync/           # 渠道库存同步入口封装
│   ├── db/                               # 数据库相关扩展位置
│   └── feishu/                           # 飞书客户端封装
├── inventory_sync/                       # 渠道库存同步历史实现，当前仍在复用
├── scripts/                              # 推荐命令入口
├── batch_inventory_data/                 # 上传原始文件归档目录
├── logs/                                 # 日志目录
├── reports/                              # 本地报表输出目录
├── Dockerfile
├── docker-compose.yaml
├── prefect.yaml
├── prefect_inventory_scheduler.py        # Prefect flow 定义与本地触发入口
└── PROJECT_GUIDE.md                      # 更详细的维护说明

配置

项目通过 .env 或当前 Shell 环境变量读取配置。主要配置项如下：

Raw 数据库：

RAW_DB_HOST
RAW_DB_PORT
RAW_DB_USER
RAW_DB_PASSWORD
RAW_DB_NAME

Analytics 数据库：

ANALYTICS_DB_HOST
ANALYTICS_DB_PORT
ANALYTICS_DB_USER
ANALYTICS_DB_PASSWORD
ANALYTICS_DB_NAME

飞书：

FEISHU_APP_ID
FEISHU_APP_SECRET
FEISHU_BASE_URL
FEISHU_APP_TOKEN

Prefect：

PREFECT_API_URL

说明：

• .env 不应提交到版本库。
• 日志默认不会输出数据库连接信息、飞书 app token、飞书 base URL、表 ID、密码或密钥。
• FEISHU_APP_TOKEN 可选；当 FEISHU_BASE_URL 已包含 /base/ 或 /wiki/ 时，可以不单独配置。

Prefect 调度

项目定义了两个 Prefect deployment：

• channel-inventory-sync-0915-1915：每天 09:15 和 19:15 执行渠道库存统计并写入飞书。
• batch-inventory-report-0915-1915：每天 09:15 和 19:15 执行批次库存统计并写入飞书。

注册 deployment：

sh scripts/register_prefect_deployments.sh

该脚本会进入 Docker 容器内，按 deployment 名称分别注册：

docker compose exec -T prefect-inventory-worker prefect --no-prompt deploy --name channel-inventory-sync-0915-1915
docker compose exec -T prefect-inventory-worker prefect --no-prompt deploy --name batch-inventory-report-0915-1915

启动 Docker worker：

docker compose up -d --build

如果调整了 Python 依赖或 Prefect 版本，需要重新构建镜像后再注册 deployment：

docker compose build --no-cache prefect-inventory-worker
docker compose up -d prefect-inventory-worker
sh scripts/register_prefect_deployments.sh

手动触发：

python3 prefect_inventory_scheduler.py --run-channel-inventory-sync
python3 prefect_inventory_scheduler.py --run-batch-inventory-report

本地 serve：

python3 prefect_inventory_scheduler.py --serve-channel-inventory-sync
python3 prefect_inventory_scheduler.py --serve-batch-inventory-report

Prefect 调度下，批次库存统计默认不生成本地 reports/ 文件，只同步飞书。如需同时生成本地报表，可使用：

python3 prefect_inventory_scheduler.py --run-batch-inventory-report --write-report-output

日志策略

日志采用结构化事件格式：

YYYY-MM-DD HH:MM:SS LEVEL logger_name 事件=事件名称 字段=字段值

正常执行会输出关键节点：

• 任务启动与完成
• 配置加载完成
• 数据库查询开始与完成
• 数据整理与汇总完成
• 飞书访问令牌获取
• 飞书表读取
• 飞书记录删除与新增数量
• 本地报表是否输出
• 总耗时

异常情况会输出：

• 失败阶段
• 异常类型
• 脱敏后的错误信息
• 已执行耗时

日志不会输出：

• 数据库 host、port、user、password、database name
• 飞书 app id、app secret、app token、base URL
• 飞书 table id、field id、record id
• .env 完整路径
• 含 token 的 URL

主要日志文件：

logs/upload_inventory_page.log
logs/sync_channel_inventory.log
logs/generate_batch_inventory_report.log

开发与验证

安装依赖：

pip install -e .

语法检查：

PYTHONPYCACHEPREFIX=/tmp/inventory_analytics_pycache python3 -m compileall inventory_analytics inventory_sync scripts prefect_inventory_scheduler.py

验证上传页：

python3 scripts/upload_batch_inventory.py

验证渠道库存飞书连接：

python3 scripts/sync_channel_inventory.py --action feishu

验证批次库存本地报表：

python3 scripts/generate_batch_inventory_report.py --skip-feishu-sync

维护约定

• 新增业务代码优先放入 inventory_analytics/。
• 新命令优先放入 scripts/，根目录脚本只作为兼容入口。
• 公共配置、路径和日志逻辑统一使用 config.py、paths.py、logging_utils.py。
• 当前渠道库存同步仍复用 inventory_sync/，后续可逐步迁移到 inventory_analytics/channel_inventory_sync/。
• 涉及日志输出时，默认只记录业务状态和计数，不记录连接配置、密钥、Token 或内部资源 ID。