inventory_analytics/PROJECT_GUIDE.md

Inventory Analytics 项目说明

1. 项目概览

当前项目围绕 3 条业务链路运行：

• 委外批次库存上传：通过本地网页上传 Excel/CSV 文件，归档原始文件，并逐行写入 Raw PostgreSQL。
• 渠道库存统计同步飞书：从 Analytics PostgreSQL 查询渠道库存、挂单量、销售与商品信息，并同步到飞书多维表格。
• 批次库存统计报表：读取最新批次库存、关联 Analytics 店铺库存与近 30 天销售，生成本地报表并可同步到飞书。

命名说明：

• “渠道库存统计”是框架层命名，当前默认业务目标仍是羽心堂渠道库存-9：00和19：00。
• “批次库存统计”是框架层命名，当前默认业务目标仍是羽心堂批次库存。
• 后续扩展到其他品牌时，优先复用这两条通用链路，而不是继续新增带品牌名的脚本和包名。

项目已经完成一轮框架调整：

• 新实现逐步迁入 inventory_analytics/ 包。
• 根目录脚本保留兼容入口。
• scripts/ 目录提供新的标准执行入口。
• 旧的 inventory_sync/ 仍保留，当前被渠道库存统计链路复用，属于过渡层。

2. 当前目录结构

inventory_analytics/
├── .env
├── pyproject.toml
├── PROJECT_GUIDE.md
├── REFACTOR_PLAN.md
├── Dockerfile
├── docker-compose.yaml
├── docker-entrypoint.sh
├── supervisord.conf
├── prefect.yaml
├── prefect_inventory_scheduler.py
├── generate_batch_inventory_report.py
├── generate_yxt_batch_inventory_report.py
├── list_feishu_base_tables.py
├── sync_channel_inventory.py
├── upload_inventory_page.py
├── scripts/
│   ├── generate_batch_inventory_report.py
│   ├── register_prefect_deployments.sh
│   ├── sync_channel_inventory.py
│   └── upload_batch_inventory.py
├── inventory_analytics/
│   ├── __init__.py
│   ├── config.py
│   ├── logging_utils.py
│   ├── paths.py
│   ├── db/
│   │   └── __init__.py
│   ├── feishu/
│   │   ├── __init__.py
│   │   └── client.py
│   ├── batch_upload/
│   │   ├── __init__.py
│   │   └── web.py
│   ├── channel_inventory_sync/
│   │   ├── __init__.py
│   │   ├── cli.py
│   │   ├── entrypoint.py
│   │   ├── queries.py
│   │   ├── service.py
│   │   └── specs.py
│   └── batch_inventory_report/
│       ├── __init__.py
│       ├── cli.py
│       └── service.py
├── inventory_sync/
│   ├── __init__.py
│   ├── cli.py
│   ├── feishu.py
│   ├── postgres.py
│   ├── service.py
│   ├── settings.py
│   ├── specs.py
│   └── sql.py
├── batch_inventory_data/
├── logs/
└── reports/

说明：

• inventory_analytics/ 是当前主包，后续新增实现优先放这里。
• scripts/ 是推荐执行入口。
• 根目录兼容入口仍保留，避免旧命令立即失效。
• inventory_sync/ 当前仍在使用，但属于待进一步收敛的历史模块。

3. 模块职责

3.1 通用基础层

文件	说明
inventory_analytics/config.py	统一加载 .env、读取数据库和飞书配置
inventory_analytics/logging_utils.py	统一日志初始化与敏感信息脱敏
inventory_analytics/paths.py	统一维护项目根目录、日志目录、报表目录、上传目录

3.2 上传链路

文件	说明
scripts/upload_batch_inventory.py	推荐入口
upload_inventory_page.py	兼容入口
inventory_analytics/batch_upload/web.py	上传页、文件解析、Raw 写库实现

3.3 渠道库存统计链路

文件	说明
scripts/sync_channel_inventory.py	推荐入口，默认等价于 --action all
sync_channel_inventory.py	通用兼容入口
list_feishu_base_tables.py	历史兼容入口
inventory_analytics/channel_inventory_sync/entrypoint.py	新入口日志封装
inventory_analytics/channel_inventory_sync/cli.py	当前复用旧 inventory_sync.cli
inventory_sync/	当前渠道库存统计实际实现所在模块

3.4 批次库存统计链路

文件	说明
scripts/generate_batch_inventory_report.py	推荐入口
generate_batch_inventory_report.py	通用兼容入口
generate_yxt_batch_inventory_report.py	历史兼容入口
inventory_analytics/batch_inventory_report/service.py	报表查询、汇总、导出、飞书同步实现

4. 环境变量

项目主要使用以下配置：

4.1 Raw 数据库

RAW_DB_HOST
RAW_DB_PORT
RAW_DB_USER
RAW_DB_PASSWORD
RAW_DB_NAME

4.2 Analytics 数据库

ANALYTICS_DB_HOST
ANALYTICS_DB_PORT
ANALYTICS_DB_USER
ANALYTICS_DB_PASSWORD
ANALYTICS_DB_NAME

4.3 飞书配置

FEISHU_APP_ID
FEISHU_APP_SECRET
FEISHU_BASE_URL
FEISHU_APP_TOKEN

说明：

• FEISHU_APP_TOKEN 可选。
• 当 FEISHU_BASE_URL 已包含 /base/ 或 /wiki/ 时，可以不额外配置 FEISHU_APP_TOKEN。
• 配置优先从项目根目录 .env 读取，若缺失则回退到当前 shell 环境变量。

5. 执行方式

5.1 推荐入口

启动上传页：

python3 scripts/upload_batch_inventory.py

启动后访问：

http://127.0.0.1:8080

执行渠道库存统计完整流程：

python3 scripts/sync_channel_inventory.py

这条命令默认等价于：

python3 scripts/sync_channel_inventory.py --action all

按动作拆分执行：

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 scripts/generate_batch_inventory_report.py

只生成本地报表，不同步飞书：

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

自定义输出路径：

python3 scripts/generate_batch_inventory_report.py --output reports/custom.xlsx

5.2 兼容入口

以下旧命令或兼容命令仍可继续使用：

python3 upload_inventory_page.py
python3 sync_channel_inventory.py --action all
python3 list_feishu_base_tables.py --action all
python3 generate_batch_inventory_report.py
python3 generate_yxt_batch_inventory_report.py

6. 各链路行为说明

6.1 委外批次库存上传

支持文件：

• .xlsx
• .xlsm
• .xls
• .csv

单文件大小限制：

200 MB

上传成功后会执行：

1. 保存原始文件到 batch_inventory_data/
2. 解析 Excel 或 CSV
3. 自动确认 raw_data.wangdian_batch_inventory 表存在
4. 每一行写入一条 JSONB payload

写入表：

raw_data.wangdian_batch_inventory

6.2 渠道库存统计同步飞书

当前支持动作：

feishu
postgres
sync-brand
all

说明：

• 当前脚本名已经泛化为“渠道库存统计”，但内部动作参数 sync-brand 仍来自历史实现，后续可再统一。
• 当前默认同步目标仍是羽心堂渠道库存-9：00和19：00。

渠道库存统计目标和字段映射当前仍维护在：

• inventory_sync/specs.py
• inventory_sync/sql.py

6.3 批次库存统计报表

当前报表链路会：

1. 读取 raw_data.wangdian_batch_inventory 中最新批次数据
2. 提取商家编码
3. 查询 Analytics 中对应店铺可发库存、商品信息、近 30 天销售数量
4. 生成合并报表
5. 输出到 reports/
6. 可选同步到飞书 批次库存 表

说明：

• 当前命名已泛化为“批次库存统计”
• 当前默认业务规则仍针对羽心堂

默认输出文件名格式：

reports/批次库存统计_YYYYMMDD_HHMMSS.xlsx

7. 字段同步策略

渠道库存统计和批次库存统计在同步飞书时，都采用相同策略：

1. 先读取当前飞书表字段
2. 判断当前字段结构是否与期望配置一致
3. 如果一致：只删除旧记录，再写入新记录
4. 如果不一致：删除受管字段并按配置重新创建，再写入新记录

8. 日志说明

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

YYYY-MM-DD HH:MM:SS LEVEL logger_name 事件=中文事件描述 中文字段=字段值

主要日志文件：

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

说明：

• 上传页日志主要输出到 stdout，并写入 upload_inventory_page.log
• 渠道库存统计日志主要输出到 stderr，并写入 sync_channel_inventory.log
• 批次库存统计日志输出到 stdout，并写入 generate_batch_inventory_report.log

9. 推荐验证方式

验证渠道库存统计入口：

python3 scripts/sync_channel_inventory.py --action feishu

验证上传页：

python3 scripts/upload_batch_inventory.py

验证批次库存统计本地导出：

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

编译校验：

PYTHONPYCACHEPREFIX=/tmp/inventory_analytics_pycache python3 -m compileall inventory_analytics scripts generate_batch_inventory_report.py generate_yxt_batch_inventory_report.py sync_channel_inventory.py list_feishu_base_tables.py upload_inventory_page.py prefect_inventory_scheduler.py

10. Docker 与 Prefect 部署

项目已补齐以下部署文件：

Dockerfile
docker-compose.yaml
docker-entrypoint.sh
supervisord.conf
prefect.yaml
prefect_inventory_scheduler.py

10.1 调度目标

当前通过 Prefect 定义了 2 个 deployment，每个 deployment 用一条 cron 覆盖每天 09:15 和 19:15（Asia/Shanghai）：

• 渠道库存统计并写入飞书
• 批次库存统计报表并写入飞书

10.2 依赖前提

需要先准备：

• 可访问的 Prefect API
• 已创建的 Prefect work pool：inventory-analytics-pool
• 项目根目录 .env

如果 Prefect API 跑在宿主机本地，容器默认使用：

http://host.docker.internal:4200/api

10.3 容器内按名称注册 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

10.4 启动 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

这会启动一个容器，容器内通过 supervisord 常驻运行：

prefect worker start --pool "inventory-analytics-pool" --type process

10.5 手工触发 Prefect flow

立即执行渠道库存统计：

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

立即执行批次库存统计：

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

10.6 本地 serve 模式

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

10.7 调度入口说明

Prefect 调度脚本不会走 shell 子进程，而是直接调用当前项目入口逻辑：

• 渠道库存统计等价于 python3 scripts/sync_channel_inventory.py --action all
• 批次库存统计等价于 python3 scripts/generate_batch_inventory_report.py

11. 维护建议

• 新增功能优先落在 inventory_analytics/ 包内，不再继续向根目录增加重脚本。
• 新命令优先使用 scripts/ 目录中的入口。
• 渠道库存统计后续应继续把 inventory_sync/ 中的实现迁入 inventory_analytics/channel_inventory_sync/ 与 inventory_analytics/feishu/。
• 公共配置、日志、路径处理统一走 config.py、logging_utils.py、paths.py。
• 涉及渠道库存统计 SQL 和字段映射时，当前仍优先修改 inventory_sync/sql.py 与 inventory_sync/specs.py。