257 lines
5.1 KiB
Markdown
257 lines
5.1 KiB
Markdown
# Inventory Analytics 工程说明
|
||
|
||
## 项目概览
|
||
|
||
当前工程包含两条独立业务链路：
|
||
|
||
- 委外批次库存上传：通过本地网页上传 Excel/CSV 文件，保存原始文件，并逐行写入 Raw PostgreSQL 表。
|
||
- 飞书库存同步：从 Analytics PostgreSQL 查询库存、挂单量、销售和商品信息，并同步到飞书多维表格。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
inventory_analytics/
|
||
├── .env
|
||
├── PROJECT_GUIDE.md
|
||
├── REFACTOR_PLAN.md
|
||
├── upload_inventory_page.py
|
||
├── list_feishu_base_tables.py
|
||
└── inventory_sync/
|
||
├── __init__.py
|
||
├── cli.py
|
||
├── feishu.py
|
||
├── postgres.py
|
||
├── service.py
|
||
├── settings.py
|
||
├── specs.py
|
||
└── sql.py
|
||
```
|
||
|
||
运行后会自动创建或使用：
|
||
|
||
```text
|
||
batch_inventory_data/
|
||
```
|
||
|
||
该目录保存上传的委外批次库存原始文件，不纳入业务代码结构。
|
||
|
||
## 环境变量
|
||
|
||
### 委外批次库存上传
|
||
|
||
上传页使用 `.env` 中的 Raw 数据库配置：
|
||
|
||
```text
|
||
RAW_DB_HOST
|
||
RAW_DB_PORT
|
||
RAW_DB_USER
|
||
RAW_DB_PASSWORD
|
||
RAW_DB_NAME
|
||
```
|
||
|
||
写入目标：
|
||
|
||
```text
|
||
raw_data.wangdian_batch_inventory
|
||
```
|
||
|
||
表结构由 `upload_inventory_page.py` 内的 `get_create_table_sql()` 创建：
|
||
|
||
```sql
|
||
payload JSONB NOT NULL,
|
||
start_time TIMESTAMP WITH TIME ZONE,
|
||
end_time TIMESTAMP WITH TIME ZONE,
|
||
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
|
||
reserved_1 TEXT,
|
||
reserved_2 TEXT
|
||
```
|
||
|
||
### 飞书库存同步
|
||
|
||
飞书同步使用 `.env` 中的飞书和 Analytics 数据库配置：
|
||
|
||
```text
|
||
FEISHU_APP_ID
|
||
FEISHU_APP_SECRET
|
||
FEISHU_BASE_URL
|
||
FEISHU_APP_TOKEN
|
||
ANALYTICS_DB_HOST
|
||
ANALYTICS_DB_PORT
|
||
ANALYTICS_DB_USER
|
||
ANALYTICS_DB_PASSWORD
|
||
ANALYTICS_DB_NAME
|
||
```
|
||
|
||
`FEISHU_APP_TOKEN` 可选；当 `FEISHU_BASE_URL` 已包含 `/base/` 或 `/wiki/` 时，可以不单独配置。
|
||
|
||
## 委外批次库存上传
|
||
|
||
启动上传页：
|
||
|
||
```bash
|
||
python3 upload_inventory_page.py
|
||
```
|
||
|
||
打开页面：
|
||
|
||
```text
|
||
http://127.0.0.1:8080
|
||
```
|
||
|
||
支持文件：
|
||
|
||
- `.xlsx`
|
||
- `.xlsm`
|
||
- `.xls`
|
||
- `.csv`
|
||
|
||
单文件大小限制：
|
||
|
||
```text
|
||
200 MB
|
||
```
|
||
|
||
上传成功后会执行：
|
||
|
||
1. 保存文件到 `batch_inventory_data/`。
|
||
2. 解析 Excel/CSV 为行数据。
|
||
3. 创建 Raw schema/table 和 `created_at` 索引。
|
||
4. 每一行插入一条 JSONB payload。
|
||
|
||
payload 示例：
|
||
|
||
```json
|
||
{
|
||
"source_file": "委外批次库存.xlsx",
|
||
"stored_file": "20260423_172410_委外批次库存.xlsx",
|
||
"uploaded_at": "2026-04-23T18:20:00",
|
||
"total_count": 120,
|
||
"inventory_data": {
|
||
"货品编码": "SKU001",
|
||
"批次": "BATCH001",
|
||
"数量": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
## 飞书库存同步
|
||
|
||
查看飞书 Base 表：
|
||
|
||
```bash
|
||
python3 list_feishu_base_tables.py --action feishu
|
||
```
|
||
|
||
只查询 PostgreSQL：
|
||
|
||
```bash
|
||
python3 list_feishu_base_tables.py --action postgres
|
||
```
|
||
|
||
同步品牌库存到飞书：
|
||
|
||
```bash
|
||
python3 list_feishu_base_tables.py --action sync-brand
|
||
```
|
||
|
||
执行完整流程：
|
||
|
||
```bash
|
||
python3 list_feishu_base_tables.py --action all
|
||
```
|
||
|
||
同步目标配置在 `inventory_sync/specs.py`：
|
||
|
||
```python
|
||
BRAND_SYNC_TARGETS = [
|
||
BrandSyncTarget(brand_name="羽心堂", table_name="羽心堂", warehouse_keys=(2, 3, 7, 13)),
|
||
]
|
||
```
|
||
|
||
字段映射也集中维护在 `inventory_sync/specs.py` 的 `FIELD_SPECS`。
|
||
|
||
## 日志说明
|
||
|
||
项目使用结构化事件日志，格式：
|
||
|
||
```text
|
||
YYYY-MM-DD HH:MM:SS LEVEL logger_name 事件=中文事件描述 中文字段=字段值 ...
|
||
```
|
||
|
||
上传页日志输出到 stdout，典型事件包括：
|
||
|
||
```text
|
||
事件=上传服务启动中
|
||
事件=收到上传请求
|
||
事件=已解析上传文件
|
||
事件=上传文件已保存
|
||
事件=开始解析库存文件
|
||
事件=已解析Excel工作表
|
||
事件=已加载Raw数据库配置
|
||
事件=Raw数据表确认完成
|
||
事件=Raw数据写入完成
|
||
事件=上传请求处理完成
|
||
```
|
||
|
||
飞书同步日志输出到 stderr，JSON 结果仍输出到 stdout，便于命令行管道消费。典型事件包括：
|
||
|
||
```text
|
||
事件=飞书同步入口启动
|
||
事件=飞书同步动作开始
|
||
事件=已加载环境变量文件
|
||
事件=开始读取飞书Base信息
|
||
事件=开始查询PostgreSQL
|
||
事件=开始同步品牌数据
|
||
事件=开始同步目标飞书表
|
||
事件=目标飞书表同步完成
|
||
事件=飞书同步入口完成
|
||
```
|
||
|
||
## 查看和关闭上传服务
|
||
|
||
查看 8080 端口：
|
||
|
||
```bash
|
||
lsof -nP -iTCP:8080 -sTCP:LISTEN
|
||
```
|
||
|
||
关闭服务：
|
||
|
||
```bash
|
||
kill <PID>
|
||
```
|
||
|
||
如果普通关闭失败：
|
||
|
||
```bash
|
||
kill -9 <PID>
|
||
```
|
||
|
||
## 验证命令
|
||
|
||
语法检查：
|
||
|
||
```bash
|
||
python3 -m py_compile upload_inventory_page.py list_feishu_base_tables.py inventory_sync/*.py
|
||
```
|
||
|
||
查看飞书同步帮助：
|
||
|
||
```bash
|
||
python3 list_feishu_base_tables.py --help
|
||
```
|
||
|
||
本地启动上传页：
|
||
|
||
```bash
|
||
python3 upload_inventory_page.py
|
||
```
|
||
|
||
## 维护原则
|
||
|
||
- 上传 Raw 数据保持原始粒度，每行一条 payload，不在上传阶段做复杂业务清洗。
|
||
- 飞书同步使用 `inventory_sync/specs.py` 管理品牌目标和字段映射。
|
||
- SQL 调整优先修改 `inventory_sync/sql.py`。
|
||
- 入口脚本保持稳定，便于人工执行和后续定时任务接入。
|
||
- 日志新增时优先使用 `事件=<中文描述>`，并输出足够定位问题的关键字段。
|