添加项目说明

2026-04-29 18:52:49 +08:00
parent 02b3470075
commit af02c33af8
3 changed files with 322 additions and 2 deletions
@@ -0,0 +1,297 @@
+# 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：
+
+- `channel-inventory-sync-0915`：每天 09:15 执行渠道库存统计并写入飞书。
+- `batch-inventory-repor-0915`：每天 09: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
+docker compose exec -T prefect-inventory-worker prefect --no-prompt deploy --name batch-inventory-repor-0915
+```
+
+启动 Docker worker：
+
+```bash
+docker compose up -d --build
+```
+
+手动触发：
+
+```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。