docs: 恢复README.md完整内容, 更新集成步骤引用scripts/load_path.py
This commit is contained in:
parent
092d74133e
commit
55b84f5fe8
236
README.md
236
README.md
@ -1,2 +1,236 @@
|
|||||||
# supplychain
|
# 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`
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user