456 lines
15 KiB
Markdown
456 lines
15 KiB
Markdown
# 蝶雅采购智能体平台
|
||
|
||
> 采购部 AI 项目数据源 — 库存/出库/产品/采购一站式数据管理平台
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [系统架构](#系统架构)
|
||
- [数据库说明](#数据库说明)
|
||
- [API 接口一览](#api-接口一览)
|
||
- [数据更新流程](#数据更新流程)
|
||
- [运维指南](#运维指南)
|
||
- [版本管理](#版本管理)
|
||
- [部署](#部署)
|
||
|
||
---
|
||
|
||
## 系统架构
|
||
|
||
### 整体结构
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────┐
|
||
│ 钉钉云盘 (DingTalk Drive) │
|
||
│ ┌──────────────────┐ ┌──────────────────────────────┐ │
|
||
│ │ 日出库数据源文件 │ │ 库存数据源文件 │ │
|
||
│ │ 20260609-wdt-cksj │ │ 20260609-wdt-kcmx-01.csv │ │
|
||
│ │ 20260609-tmgj-cksj│ │ 20260609-wdt-kcmx-02.csv... │ │
|
||
│ └────────┬─────────┘ └─────────────┬────────────────┘ │
|
||
└───────────┼──────────────────────────┼────────────────────┘
|
||
│ dws drive download │ dws drive download
|
||
▼ ▼
|
||
┌──────────────────────────────────────────────────────────┐
|
||
│ 本地CSV缓存(tmp_csv/) │
|
||
│ reimport.py batch_import_inventory.py │
|
||
│ │ │ │
|
||
│ ▼ ▼ │
|
||
│ ├───────── MySQL ─────────┤ │
|
||
│ │ dy_data 数据库 │ │
|
||
│ │ daily_outbound │ │
|
||
│ │ inventory_detail │ │
|
||
│ │ products / bom │ │
|
||
│ │ suppliers / warehouses │ │
|
||
│ │ purchase_orders │ │
|
||
│ └──────────┬──────────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ Flask Web 应用 (app.py) │
|
||
│ Port 18888 │
|
||
└──────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
浏览器访问 → http://服务器IP:18888
|
||
```
|
||
|
||
### 项目目录说明
|
||
|
||
```
|
||
dy-dashboard/
|
||
├── app.py # Flask 入口
|
||
├── run.py # 启动脚本（开发/生产模式）
|
||
├── config.py # 数据库 & 应用配置
|
||
├── deploy.sh # 一键部署脚本
|
||
│
|
||
├── routes/ # Web 路由 / API
|
||
│ ├── auth.py # 登录/权限
|
||
│ ├── dashboard.py # 仪表盘
|
||
│ ├── data.py # 日出库数据
|
||
│ ├── inventory.py # 库存数据
|
||
│ ├── products.py # 产品/BOM/供应商
|
||
│ ├── purchase.py # 采购单
|
||
│ ├── warehouse.py # 仓库管理
|
||
│ └── users.py # 用户管理
|
||
│
|
||
├── services/ # 业务逻辑层
|
||
│ ├── db.py # 数据库连接池
|
||
│ ├── cache.py # 缓存机制 (RefreshableCache)
|
||
│ ├── forecast.py # 销售预测
|
||
│ ├── inventory_calc.py # 库存计算
|
||
│ ├── product_type.py # 产品分类
|
||
│ ├── sales_calc.py # 销量统计
|
||
│ └── simple_cache.py # 简易缓存
|
||
│
|
||
├── templates/ # HTML 模板
|
||
├── static/ # CSS/JS/图片
|
||
│
|
||
├── auto_update.py # 定时自动更新入口
|
||
├── reimport.py # 日出库数据导入（全量重刷）
|
||
├── batch_import_inventory.py # 库存导入（批量下载钉盘）
|
||
├── import_new_inventory.py # 库存增量导入（动态检测新文件）
|
||
├── sync_dingtalk.py # 钉盘同步工具
|
||
├── update_data.py # 钉盘增量更新
|
||
│
|
||
├── import_inventory.py # 单个库存文件导入
|
||
├── import_suppliers.py # 供应商导入
|
||
├── import_warehouses.py # 仓库导入
|
||
├── import_purchase_order*.py # 采购单导入
|
||
├── init_db.py # 数据库初始化
|
||
│
|
||
├── tmp_csv/ # 钉盘缓存CSV（可重新下载）
|
||
├── logs/ # 运行日志
|
||
├── venv/ # Python 虚拟环境
|
||
│
|
||
├── .gitignore
|
||
├── README.md
|
||
└── deploy.sh
|
||
```
|
||
|
||
---
|
||
|
||
## 数据库说明
|
||
|
||
### 表一览
|
||
|
||
| 表名 | 记录数 | 大小 | 用途 |
|
||
|------|--------|------|------|
|
||
| `inventory_detail` | ~86万 | 175MB | **日库存明细** — 每个仓库每天商品库存快照 |
|
||
| `daily_outbound` | ~7.5万 | 20MB | **日出库记录** — 各平台每日出库流水 |
|
||
| `products` | ~8,600 | 3.4MB | **产品基础信息** — 编号/名称/品牌/分类/跟单 |
|
||
| `suppliers` | 531 | 0.1MB | 供应商信息 |
|
||
| `warehouses` | 21 | — | 仓库对照表 |
|
||
| `bom` | 5,854 | 1.5MB | 物料清单（成品→包材） |
|
||
| `purchase_orders` | 2 | — | 采购单 |
|
||
| `purchase_order_items` | 2 | — | 采购单项 |
|
||
| `dashboard_users` | 34 | — | 平台用户 |
|
||
| `dashboard_logs` | 245 | — | 操作日志 |
|
||
| `role_permissions` | 66 | — | 角色权限 |
|
||
| `global_config` | 2 | — | 全局配置 |
|
||
| `sales_predict_config` | 9 | — | 预测配置 |
|
||
| `trend_config` | 9 | — | 趋势配置 |
|
||
| `user_column_schemes` | 7 | — | 用户列方案 |
|
||
|
||
### 核心表详解
|
||
|
||
#### `inventory_detail` — 日库存明细
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `data_date` | date | 库存日期 |
|
||
| `source` | varchar | 数据来源（wdt = 旺店通） |
|
||
| `warehouse_code` | varchar | 仓库编码 |
|
||
| `product_code` | varchar | 货品编号 |
|
||
| `product_name` | varchar | 货品名称 |
|
||
| `brand` | varchar | 品牌 |
|
||
| `cost_price` | decimal | 成本价 |
|
||
| `available_qty` | int | **可用库存**（核心字段） |
|
||
| `production_in_transit` | int | 生产在途量 |
|
||
| `purchase_in_transit` | int | 采购在途 |
|
||
| `category1/2/3` | varchar | 三级类目 |
|
||
| `created_time` | datetime | 单品创建时间 |
|
||
|
||
> **重要**: 每天全量快照，按 `data_date + warehouse_code` 区分。每天约 1.9 万条。
|
||
|
||
#### `daily_outbound` — 日出库记录
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `日期` | date | 出库日期 |
|
||
| `货品编号` | varchar | 产品编码 |
|
||
| `货品名称` | varchar | 产品名称 |
|
||
| `品牌` | varchar | 品牌 |
|
||
| `仓库` | varchar | 发货仓库 |
|
||
| `店铺` | varchar | 店铺名称 |
|
||
| `货品数量` | int | **出库数量** |
|
||
| `货品成本` | decimal | 出库成本 |
|
||
| `数据来源` | varchar | wdt/tmgj/jdbz/jdgj/jdjwt |
|
||
| `数据类型` | varchar | cksj |
|
||
|
||
> **注意**: 来源含多种平台（旺店通/天猫国际/京东泊紫/京东国际/京东洁维塔）
|
||
|
||
#### `products` — 产品基础信息
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `product_code` | varchar（唯一） | 货品编号 |
|
||
| `product_name` | varchar | 货品名称 |
|
||
| `brand` | varchar | 品牌 |
|
||
| `product_type` | varchar | **产品类型**: 成品/包材/清库存/现货/赠品/物料/小样/其他 |
|
||
| `cost_price` | decimal | 成本价 |
|
||
| `category1/2/3` | varchar | 三级类目 |
|
||
| `supplier_name_match` | varchar | 供应商匹配名 |
|
||
| `procurement_follower` | varchar | 采购跟单人 |
|
||
| `procurement_planner` | varchar | 采购计划人 |
|
||
| `lead_time` | int | 生产周期（天） |
|
||
|
||
---
|
||
|
||
## API 接口一览
|
||
|
||
### 仪表盘
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/dashboard/stats` | GET | 仪表盘统计数据 |
|
||
|
||
### 库存
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/inventory/list` | GET | 库存明细列表（支持分页/筛选） |
|
||
| `/api/inventory/filters` | GET | 库存筛选选项（品牌/类目/日期/仓库） |
|
||
| `/api/inventory/export` | POST | 导出库存数据（CSV/Excel） |
|
||
| `/inventory` | GET | 库存页面 |
|
||
| `/inventory/finished` | GET | 成品库存页 |
|
||
| `/inventory/packaging` | GET | 包材库存页 |
|
||
|
||
### 日出库
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/data/list` | GET | 出库明细列表 |
|
||
| `/api/data/dates` | GET | 可选日期列表 |
|
||
| `/api/data/summary` | GET | 出库汇总统计 |
|
||
| `/api/data/summary-stats` | GET | 汇总图表数据 |
|
||
| `/api/data/sku-detail` | GET | SKU 出库详情 |
|
||
|
||
### 产品
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/products/list` | GET | 产品列表 |
|
||
| `/api/products/filters` | GET | 筛选选项 |
|
||
| `/api/product/update_fields` | POST | 更新产品字段 |
|
||
| `/api/product/batch_update` | POST | 批量更新 |
|
||
| `/api/bom/list` | GET | BOM 物料清单 |
|
||
| `/api/suppliers/list` | GET | 供应商列表 |
|
||
|
||
### 采购
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/purchase/pending_list` | GET | 待采购列表 |
|
||
| `/api/purchase/create_order` | POST | 创建采购单 |
|
||
| `/api/purchase/orders/list` | GET | 采购单列表 |
|
||
|
||
### 认证 & 用户
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/login` | POST | 登录 |
|
||
| `/api/logout` | POST | 退出 |
|
||
| `/api/profile` | GET | 个人信息 |
|
||
| `/api/users/list` | GET | 用户列表 |
|
||
| `/api/permissions/list` | GET | 权限列表 |
|
||
|
||
---
|
||
|
||
## 数据更新流程
|
||
|
||
### 数据流向
|
||
|
||
```
|
||
钉钉云盘 → dws下载 → tmp_csv/ → Python导入脚本 → MySQL → Flask API → 浏览器
|
||
```
|
||
|
||
### 更新方式
|
||
|
||
**方式一：全量自动更新**（推荐）
|
||
```bash
|
||
python3 auto_update.py
|
||
```
|
||
- 下载钉盘最新出库+库存CSV
|
||
- 全量重导入数据库
|
||
- 刷新系统缓存
|
||
- 建议配置定时任务每天 7:00 / 12:00 / 18:00 执行
|
||
|
||
**方式二：单独更新出库数据**
|
||
```bash
|
||
python3 reimport.py
|
||
```
|
||
- 扫描 `tmp_csv/` 下所有 `*cksj*.csv` 文件
|
||
- 清空 `daily_outbound` 表，全量重写
|
||
|
||
**方式三：单独更新库存数据**
|
||
```bash
|
||
# 全量
|
||
python3 batch_import_inventory.py
|
||
|
||
# 增量（只导入新文件）
|
||
python3 import_new_inventory.py
|
||
```
|
||
|
||
### 钉盘文件夹 ID
|
||
|
||
| 名称 | 文件夹ID | 说明 |
|
||
|------|---------|------|
|
||
| 日出库数据源文件 | `3NwLYZXWynyBjRB4tZjwNxDvVkyEqBQm` | 每日出库CSV |
|
||
| 库存数据源文件 | `NkDwLng8ZLGrXmrnFxYq3vRqVKMEvZBY` | 每日库存CSV（按仓库分文件） |
|
||
| 所属空间 | `28814565790` | 采购部AI项目数据源 |
|
||
|
||
---
|
||
|
||
## 运维指南
|
||
|
||
### 启动/停止
|
||
|
||
```bash
|
||
# 启动（开发模式）
|
||
cd /home/gxd/.openclaw/workspace/dy-dashboard
|
||
python3 app.py
|
||
|
||
# 启动（生产模式，推荐）
|
||
python3 run.py --prod
|
||
|
||
# 或使用 deploy.sh
|
||
bash deploy.sh
|
||
|
||
# 停止
|
||
kill $(lsof -t -i:18888)
|
||
```
|
||
|
||
### 查看日志
|
||
|
||
```bash
|
||
# 应用日志
|
||
tail -f logs/app.log
|
||
|
||
# 自动更新日志
|
||
tail -f logs/auto_update.log
|
||
|
||
# 访问日志
|
||
tail -f logs/access.log
|
||
```
|
||
|
||
### 刷新缓存
|
||
|
||
系统使用 `RefreshableCache` 机制。重启服务会自动刷新：
|
||
|
||
```bash
|
||
kill $(lsof -t -i:18888); sleep 2; python3 run.py --prod
|
||
```
|
||
|
||
### 数据校验
|
||
|
||
```bash
|
||
# 检查库存数据
|
||
mysql -u dy_app -p'***' dy_data -e "
|
||
SELECT data_date, COUNT(*) AS cnt, SUM(available_qty) AS total_avail
|
||
FROM inventory_detail
|
||
GROUP BY data_date ORDER BY data_date DESC LIMIT 5;"
|
||
|
||
# 检查出库数据
|
||
mysql -u dy_app -p'***' dy_data -e "
|
||
SELECT 日期, COUNT(*) AS cnt, SUM(货品数量) AS total_qty
|
||
FROM daily_outbound
|
||
GROUP BY 日期 ORDER BY 日期 DESC LIMIT 5;"
|
||
```
|
||
|
||
### 常见问题
|
||
|
||
**Q: 库存数据显示为0**
|
||
- 原因：导入脚本解析CSV时编码或列映射出错
|
||
- 解决：删除错误数据，重新从CSV导入
|
||
|
||
**Q: 出库数据缺少某天**
|
||
- 原因：当天CSV文件未下载
|
||
- 解决：手动从钉盘下载该文件放到 `tmp_csv/`，运行 `python3 reimport.py`
|
||
|
||
**Q: 页面访问 502/连接拒绝**
|
||
- 原因：服务未启动或崩溃
|
||
- 解决：`python3 run.py --prod` 重新启动
|
||
|
||
**Q: 定时更新没跑**
|
||
- 原因：crontab 未配置或服务器重启
|
||
- 解决：`crontab -e` 确认任务存在，或手动运行 `python3 auto_update.py`
|
||
|
||
### 模块命名规则
|
||
|
||
**新建 .py 文件前先检查：**
|
||
1. `ls services/*.py` 查看已有模块
|
||
2. `grep -rn "from services.\|import services."` 检查现有导入
|
||
3. 确认无冲突再新建
|
||
|
||
---
|
||
|
||
## 版本管理
|
||
|
||
### Git 标签
|
||
|
||
```bash
|
||
# 查看版本
|
||
git tag
|
||
|
||
# 查看当前版本详情
|
||
git log --oneline --decorate
|
||
|
||
# 切换到某个版本
|
||
git checkout v1.0
|
||
```
|
||
|
||
### 发版流程
|
||
|
||
```bash
|
||
# 1. 提交代码
|
||
git add -A
|
||
git commit -m "v1.1 - 修复xxx / 新增xxx"
|
||
|
||
# 2. 打标签
|
||
git tag -a v1.1 -m "v1.1 - 说明"
|
||
|
||
# 3. 导出对应版本的数据库
|
||
mysqldump -u dy_app -p'***' dy_data > dy_data_v1.1.sql
|
||
```
|
||
|
||
### 回滚
|
||
|
||
```bash
|
||
# 代码回滚
|
||
git reset --hard v1.0
|
||
|
||
# 数据库回滚（需要手动导入旧版本备份）
|
||
mysql -u dy_app -p'***' dy_data < dy_data_v1.0.sql
|
||
```
|
||
|
||
---
|
||
|
||
## 部署
|
||
|
||
### 新服务器部署
|
||
|
||
```bash
|
||
# 前置条件（Ubuntu）
|
||
sudo apt update && sudo apt install -y python3 python3-pip python3-venv mysql-server
|
||
|
||
# 解压项目
|
||
tar xzf dy-dashboard-package.tar.gz
|
||
cd dy-dashboard
|
||
|
||
# 一键部署
|
||
bash deploy.sh
|
||
```
|
||
|
||
`deploy.sh` 会自动完成：
|
||
1. ✅ 检测 Python/MySQL 环境
|
||
2. ✅ 创建数据库和用户
|
||
3. ✅ 导入数据（如果有 `dy_data_backup.sql`）
|
||
4. ✅ 创建 Python 虚拟环境并安装依赖
|
||
5. ✅ 启动 Gunicorn 服务
|
||
6. ✅ 配置定时更新任务
|
||
|
||
### 使用变量
|
||
|
||
| 配置项 | 默认值 | 位置 |
|
||
|--------|--------|------|
|
||
| 端口 | 18888 | `config.py` → `APP_PORT` |
|
||
| 数据库名 | dy_data | `config.py` → `DB_CONFIG.database` |
|
||
| 数据库用户 | dy_app | `config.py` → `DB_CONFIG.user` |
|
||
| 数据库密码 | dy_data_2026 | `config.py` → `DB_CONFIG.password` |
|
||
| 默认账号 | 甘旭东 | 数据库 `dashboard_users` 表 |
|
||
| 默认密码 | admin123 | 数据库 `dashboard_users` 表 |
|
||
|
||
---
|
||
|
||
### 相关链接
|
||
|
||
- 钉钉云盘空间ID: `28814565790`（采购部AI项目数据源）
|
||
- 日出库文件夹ID: `3NwLYZXWynyBjRB4tZjwNxDvVkyEqBQm`
|
||
- 库存文件夹ID: `NkDwLng8ZLGrXmrnFxYq3vRqVKMEvZBY`
|
||
- 项目路径: `/home/gxd/.openclaw/workspace/dy-dashboard/`
|
||
|
||
---
|
||
|
||
*最后更新: 2026-06-10 | v1.0*
|