inventory_analytics/README.md

# Inventory Analytics

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

## 项目目标

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

## 核心链路

### 1. 委外批次库存上传

入口：

```bash
python3 scripts/upload_batch_inventory.py
```

功能：

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

兼容入口：

```bash
python3 upload_inventory_page.py
```

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

入口：

```bash
python3 scripts/sync_channel_inventory.py
```

功能：

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

可选动作：

```bash
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
```

兼容入口：

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

### 3. 批次库存统计报表

入口：

```bash
python3 scripts/generate_batch_inventory_report.py
```

功能：

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

常用参数：

```bash
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 批次库存
```

兼容入口：

```bash
python3 generate_batch_inventory_report.py
python3 generate_yxt_batch_inventory_report.py
```

## 目录结构

```text
.
├── 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 数据库：

```text
RAW_DB_HOST
RAW_DB_PORT
RAW_DB_USER
RAW_DB_PASSWORD
RAW_DB_NAME
```

Analytics 数据库：

```text
ANALYTICS_DB_HOST
ANALYTICS_DB_PORT
ANALYTICS_DB_USER
ANALYTICS_DB_PASSWORD
ANALYTICS_DB_NAME
```

飞书：

```text
FEISHU_APP_ID
FEISHU_APP_SECRET
FEISHU_BASE_URL
FEISHU_APP_TOKEN
```

Prefect：

```text
PREFECT_API_URL
```

说明：

- `.env` 不应提交到版本库。
- 日志默认不会输出数据库连接信息、飞书 app token、飞书 base URL、表 ID、密码或密钥。
- `FEISHU_APP_TOKEN` 可选；当 `FEISHU_BASE_URL` 已包含 `/base/` 或 `/wiki/` 时，可以不单独配置。
- 渠道库存同步允许飞书字段任意排序，但会严格校验必填字段名称、类型和数字格式。校验失败时不会修改表头或记录，并会向指定的飞书通知群发送错误消息。应用需开启机器人能力、具备发送群消息权限，并已加入该通知群。

## Prefect 调度

项目定义了两个 Prefect deployment，每个 deployment 用一条 cron 覆盖 09:15 和 19:15：

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

注册 deployment：

```bash
sh scripts/register_prefect_deployments.sh
```

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

```bash
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：

```bash
docker compose up -d --build
```

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

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

手动触发：

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

本地 serve：

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

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

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

## 日志策略

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

```text
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

主要日志文件：

```text
logs/upload_inventory_page.log
logs/sync_channel_inventory.log
logs/generate_batch_inventory_report.log
```

## 开发与验证

安装依赖：

```bash
pip install -e .
```

语法检查：

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

验证上传页：

```bash
python3 scripts/upload_batch_inventory.py
```

验证渠道库存飞书连接：

```bash
python3 scripts/sync_channel_inventory.py --action feishu
```

验证批次库存本地报表：

```bash
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。