237 lines
7.1 KiB
Markdown
237 lines
7.1 KiB
Markdown
# supplychain — 供应商和分销商管理模块
|
||
|
||
## 概述
|
||
|
||
supplychain 模块为 Sage 平台提供供应商和分销商的全链路管理功能，包括：
|
||
|
||
- **供应商管理**：添加和管理供应商基本信息、联系方式、财务信息
|
||
- **供销合同管理**：运营人员创建与供应商的供销合同，设置合同有效期和产品折扣
|
||
- **二级分销商管理**：销售人员添加和管理二级分销商
|
||
- **分销协议管理**：销售人员与二级分销商签署分销协议，设置产品分销折扣
|
||
- **供销记账**：产品销售时自动计算供销关系的记账金额（进货金额、分销金额、利润）
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
supplychain/
|
||
├── supplychain/ # Python 包
|
||
│ ├── __init__.py
|
||
│ └── init.py # 模块初始化 + ServerEnv 注册
|
||
├── wwwroot/ # 前端文件
|
||
│ ├── index.ui # 模块入口页
|
||
│ ├── menu.ui # 导航菜单
|
||
│ ├── suppliers.ui # 供应商管理页
|
||
│ ├── supply_contracts.ui # 供销合同页
|
||
│ ├── sub_distributors.ui # 二级分销商页
|
||
│ ├── distribution_agreements.ui # 分销协议页
|
||
│ ├── accounting.ui # 供销记账页
|
||
│ └── api/ # API 端点
|
||
│ ├── *_create.dspy
|
||
│ ├── *_update.dspy
|
||
│ ├── *_delete.dspy
|
||
│ ├── calculate_accounting.dspy # 记账计算 API
|
||
│ ├── query_supply_discount.dspy # 查询进货折扣
|
||
│ └── query_dist_discount.dspy # 查询分销折扣
|
||
├── models/ # 数据库表定义
|
||
│ ├── suppliers.json
|
||
│ ├── supply_contracts.json
|
||
│ ├── supply_contract_items.json
|
||
│ ├── sub_distributors.json
|
||
│ ├── distribution_agreements.json
|
||
│ ├── distribution_agreement_items.json
|
||
│ └── supplychain_accounting.json
|
||
├── json/ # CRUD 配置
|
||
│ ├── suppliers_list.json
|
||
│ ├── supply_contracts_list.json
|
||
│ ├── supply_contract_items_list.json
|
||
│ ├── sub_distributors_list.json
|
||
│ ├── distribution_agreements_list.json
|
||
│ ├── distribution_agreement_items_list.json
|
||
│ └── supplychain_accounting_list.json
|
||
├── init/
|
||
│ └── data.json # 初始化数据（可选）
|
||
├── scripts/
|
||
│ └── load_path.py # RBAC 权限管理脚本
|
||
├── pyproject.toml
|
||
├── build.sh
|
||
└── README.md
|
||
```
|
||
|
||
## 数据库表
|
||
|
||
| 表名 | 说明 | 类别 |
|
||
|------|------|------|
|
||
| suppliers | 供应商表 | entity |
|
||
| supply_contracts | 供销合同表 | entity |
|
||
| supply_contract_items | 供销合同产品折扣明细 | relation |
|
||
| sub_distributors | 二级分销商表 | entity |
|
||
| distribution_agreements | 分销协议表 | entity |
|
||
| distribution_agreement_items | 分销协议产品折扣明细 | relation |
|
||
| supplychain_accounting | 供销记账表 | relation |
|
||
|
||
## 角色权限
|
||
|
||
| 角色 | 权限范围 |
|
||
|------|----------|
|
||
| 运营 (operator) | 供应商管理、供销合同管理（含产品折扣） |
|
||
| 销售 (sale) | 二级分销商管理、分销协议管理（含产品折扣） |
|
||
| 所有登录用户 | 供销记账查看 |
|
||
|
||
## 折扣计算规则
|
||
|
||
### 进货折扣（供应商 → 分销商）
|
||
|
||
查找优先级：
|
||
1. 供销合同 → 产品明细（精确匹配 productid）
|
||
2. 供销合同 → 产品明细（匹配 prodtypeid）
|
||
3. 供销合同 → 默认折扣（default_discount）
|
||
|
||
### 分销折扣（分销商 → 二级分销商）
|
||
|
||
查找优先级：
|
||
1. 分销协议 → 产品明细（精确匹配 productid）
|
||
2. 分销协议 → 产品明细（匹配 prodtypeid）
|
||
3. 分销协议 → 默认折扣（default_discount）
|
||
|
||
### 记账金额计算
|
||
|
||
```
|
||
销售总额 = 单价 × 数量
|
||
进货金额 = 销售总额 × 进货折扣 (或 结算单价 × 数量)
|
||
分销金额 = 销售总额 × 分销折扣 (或 结算单价 × 数量)
|
||
利润金额 = 分销金额 - 进货金额
|
||
```
|
||
|
||
## API 接口
|
||
|
||
### 记账计算 API
|
||
|
||
**端点**: `/supplychain/api/calculate_accounting.dspy`
|
||
|
||
**请求方法**: POST
|
||
|
||
**参数**:
|
||
```json
|
||
{
|
||
"productid": "产品ID",
|
||
"prodtypeid": "产品分类ID (可选)",
|
||
"quantity": 10,
|
||
"unit_price": 100.00,
|
||
"sub_distributor_id": "二级分销商ID (可选)",
|
||
"sale_date": "2026-05-25 (可选, 默认今天)",
|
||
"source_type": "2 (来源类型: 1=手动, 2=API)",
|
||
"source_id": "来源记录ID (可选)",
|
||
"remark": "备注 (可选)"
|
||
}
|
||
```
|
||
|
||
**返回**:
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"data": {...},
|
||
"summary": {
|
||
"total_amount": 1000.00,
|
||
"supply_amount": 700.00,
|
||
"dist_amount": 900.00,
|
||
"profit_amount": 200.00,
|
||
"supply_discount": 0.7,
|
||
"dist_discount": 0.9
|
||
}
|
||
}
|
||
```
|
||
|
||
### 折扣查询 API
|
||
|
||
**进货折扣查询**: `/supplychain/api/query_supply_discount.dspy`
|
||
- 参数: `productid`, `prodtypeid` (可选)
|
||
|
||
**分销折扣查询**: `/supplychain/api/query_dist_discount.dspy`
|
||
- 参数: `sub_distributor_id`, `productid`, `prodtypeid` (可选)
|
||
|
||
## Python 模块函数
|
||
|
||
通过 `ServerEnv` 注册后可在 .dspy 文件中直接调用：
|
||
|
||
```python
|
||
# 获取进货折扣
|
||
supply_info = await get_active_supply_discount(sor, resellerid, productid, prodtypeid, sale_date)
|
||
|
||
# 获取分销折扣
|
||
dist_info = await get_active_dist_discount(sor, resellerid, sub_distributor_id, productid, prodtypeid, sale_date)
|
||
|
||
# 计算并创建记账记录
|
||
record = await calculate_sale_accounting(sor, resellerid, productid, quantity, unit_price,
|
||
sub_distributor_id, prodtypeid, sale_date, source_type, source_id, created_by, remark)
|
||
```
|
||
|
||
## 安装步骤
|
||
|
||
### 1. 克隆模块
|
||
|
||
```bash
|
||
cd ~/repos
|
||
git clone git@git.opencomputing.cn:yumoqing/supplychain.git
|
||
```
|
||
|
||
### 2. 构建模块
|
||
|
||
```bash
|
||
cd ~/repos/supplychain
|
||
chmod +x build.sh
|
||
./build.sh
|
||
```
|
||
|
||
### 3. 生成 DDL 并创建数据库表
|
||
|
||
```bash
|
||
cd ~/repos/supplychain/models
|
||
mysql -h <host> -u <user> -p <dbname> < mysql.ddl.sql
|
||
```
|
||
|
||
### 4. 集成到 Sage
|
||
|
||
**a. 修改 `app/sage.py`**:
|
||
```python
|
||
from supplychain.init import load_supplychain
|
||
# 在 init() 函数中添加:
|
||
load_supplychain()
|
||
```
|
||
|
||
**b. 修改 `build.sh`** (Sage 根目录):
|
||
```bash
|
||
for m in ... supplychain
|
||
```
|
||
|
||
### 5. 注册 RBAC 权限
|
||
|
||
模块提供 `scripts/load_path.py` 权限管理脚本，自动注册所有路径：
|
||
|
||
```bash
|
||
cd ~/repos/sage
|
||
./py3/bin/python ~/repos/supplychain/scripts/load_path.py
|
||
```
|
||
|
||
脚本按角色分类注册:
|
||
- `any`: 静态资源/CRUD 别名目录
|
||
- `logined`: 所有页面和 API
|
||
- `reseller.operator`: 供应商、供销合同管理
|
||
- `reseller.sale`: 二级分销商、分销协议管理
|
||
|
||
**维护规则**: 每次代码变更如有新 path 出现，需同步更新 `scripts/load_path.py` 中的路径列表。
|
||
|
||
### 6. 重启 Sage
|
||
|
||
```bash
|
||
cd ~/repos/sage
|
||
./stop.sh && ./start.sh
|
||
```
|
||
|
||
## 产品模块引用
|
||
|
||
本模块的 `productid` 和 `prodtypeid` 字段引用 product 模块的 `products` 和 `product_types` 表。
|
||
已在以下模型的 `codes` 段添加引用配置：
|
||
- `models/supply_contract_items.json`
|
||
- `models/distribution_agreement_items.json`
|
||
- `models/supplychain_accounting.json`
|