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