168 lines
6.0 KiB
Markdown
168 lines
6.0 KiB
Markdown
# Supplychain Module
|
|
|
|
Supplier and Reseller Management module for Sage platform.
|
|
|
|
## Overview
|
|
|
|
Manages the complete supply chain workflow for reseller/distributor organizations:
|
|
- **Operators** manage suppliers and supply contracts with product-level discount terms
|
|
- **Sales** manage sub-resellers (tier-2 distributors) and distribution agreements with product-level discount terms
|
|
- **Sales ledger** records transactions and calculates supply/distribution amounts for accounting
|
|
|
|
## Architecture
|
|
|
|
### Tables
|
|
|
|
| Table | Description |
|
|
|-------|-------------|
|
|
| `suppliers` | Supplier master data (contact, bank, tax info) |
|
|
| `supply_contracts` | Supply contracts between reseller and supplier |
|
|
| `supply_contract_items` | Product-level discount details per supply contract |
|
|
| `sub_resellers` | Sub-reseller (tier-2 distributor) master data |
|
|
| `distribution_agreements` | Distribution agreements between reseller and sub-reseller |
|
|
| `distribution_agreement_items` | Product-level discount details per distribution agreement |
|
|
| `sales_ledger` | Sales transaction records with calculated amounts |
|
|
|
|
### Discount Calculation Logic
|
|
|
|
`calculate_sale_amounts()` API is called during product sales:
|
|
|
|
1. Finds active supply contract for the supplier (filtered by date and status)
|
|
2. Looks up product-specific discount in contract items (priority: exact product > product type > default)
|
|
3. Finds active distribution agreement for the sub-reseller
|
|
4. Looks up product-specific discount in agreement items (same priority)
|
|
5. Calculates: supply_amount = total * supply_discount, distribution_amount = total * distribution_discount, profit = distribution - supply
|
|
|
|
### Role-Based Access
|
|
|
|
- `reseller.operator` — manage suppliers, supply contracts, and contract items
|
|
- `reseller.sale` — manage sub-resellers, distribution agreements, and agreement items
|
|
- `reseller.accountant` — view and manage sales ledger entries
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
supplychain/
|
|
├── supplychain/
|
|
│ ├── __init__.py # Package init
|
|
│ └── init.py # Module init + ServerEnv registration
|
|
├── wwwroot/
|
|
│ ├── index.ui # Module entry point
|
|
│ ├── menu.ui # Navigation menu
|
|
│ └── api/ # CRUD API endpoints (.dspy files)
|
|
├── models/ # Table definitions (JSON)
|
|
├── json/ # CRUD definitions (JSON)
|
|
├── init/ # Initialization data
|
|
├── pyproject.toml
|
|
├── build.sh
|
|
└── README.md
|
|
```
|
|
|
|
## Sage Integration
|
|
|
|
### 1. Install module
|
|
```bash
|
|
cd ~/repos/sage/pkgs
|
|
git clone https://git.opencomputing.cn/yumoqing/supplychain
|
|
cd supplychain
|
|
../../py3/bin/pip install .
|
|
```
|
|
|
|
### 2. Generate DDL and apply to database
|
|
```bash
|
|
cd ~/repos/sage/pkgs/supplychain/models
|
|
../../py3/bin/json2ddl mysql . > mysql.ddl.sql
|
|
mysql -h <db_host> -u <db_user> -p sage < mysql.ddl.sql
|
|
```
|
|
|
|
### 3. Generate CRUD UI files
|
|
```bash
|
|
cd ~/repos/sage/pkgs/supplychain/json
|
|
../../py3/bin/xls2ui -m ../models -o ../wwwroot supplychain *.json
|
|
```
|
|
|
|
### 4. Link wwwroot
|
|
```bash
|
|
cd ~/repos/sage/wwwroot
|
|
ln -sf ../pkgs/supplychain/wwwroot supplychain
|
|
```
|
|
|
|
### 5. Register module in Sage
|
|
Add to `~/repos/sage/app/sage.py`:
|
|
```python
|
|
from supplychain.init import load_supplychain
|
|
# In init():
|
|
load_supplychain()
|
|
```
|
|
|
|
### 6. Register RBAC permissions
|
|
Add to `~/repos/sage/load_path.py`:
|
|
```
|
|
/supplychain logined
|
|
/supplychain/index.ui logined
|
|
/supplychain/menu.ui any
|
|
/supplychain/suppliers_list logined
|
|
/supplychain/suppliers_list/index.ui logined
|
|
/supplychain/supply_contracts_list logined
|
|
/supplychain/supply_contracts_list/index.ui logined
|
|
/supplychain/supply_contract_items_list logined
|
|
/supplychain/supply_contract_items_list/index.ui logined
|
|
/supplychain/sub_resellers_list logined
|
|
/supplychain/sub_resellers_list/index.ui logined
|
|
/supplychain/distribution_agreements_list logined
|
|
/supplychain/distribution_agreements_list/index.ui logined
|
|
/supplychain/distribution_agreement_items_list logined
|
|
/supplychain/distribution_agreement_items_list/index.ui logined
|
|
/supplychain/sales_ledger_list logined
|
|
/supplychain/sales_ledger_list/index.ui logined
|
|
/supplychain/api/suppliers_create.dspy logined
|
|
/supplychain/api/suppliers_update.dspy logined
|
|
/supplychain/api/suppliers_delete.dspy logined
|
|
/supplychain/api/supply_contracts_create.dspy logined
|
|
/supplychain/api/supply_contracts_update.dspy logined
|
|
/supplychain/api/supply_contracts_delete.dspy logined
|
|
/supplychain/api/supply_contract_items_create.dspy logined
|
|
/supplychain/api/supply_contract_items_update.dspy logined
|
|
/supplychain/api/supply_contract_items_delete.dspy logined
|
|
/supplychain/api/sub_resellers_create.dspy logined
|
|
/supplychain/api/sub_resellers_update.dspy logined
|
|
/supplychain/api/sub_resellers_delete.dspy logined
|
|
/supplychain/api/distribution_agreements_create.dspy logined
|
|
/supplychain/api/distribution_agreements_update.dspy logined
|
|
/supplychain/api/distribution_agreements_delete.dspy logined
|
|
/supplychain/api/distribution_agreement_items_create.dspy logined
|
|
/supplychain/api/distribution_agreement_items_update.dspy logined
|
|
/supplychain/api/distribution_agreement_items_delete.dspy logined
|
|
/supplychain/api/sales_ledger_create.dspy logined
|
|
/supplychain/api/sales_ledger_update.dspy logined
|
|
/supplychain/api/sales_ledger_delete.dspy logined
|
|
```
|
|
|
|
Then run:
|
|
```bash
|
|
cd ~/repos/sage && ./py3/bin/python load_path.py
|
|
```
|
|
|
|
### 7. Restart Sage
|
|
```bash
|
|
cd ~/repos/sage && ./stop.sh && ./start.sh
|
|
```
|
|
|
|
## API for External Modules
|
|
|
|
Other modules can call `calculate_sale_amounts()` to compute supply/distribution amounts during sales:
|
|
|
|
```python
|
|
env = ServerEnv()
|
|
result = await env.calculate_sale_amounts(request, {
|
|
"resellerid": org_id,
|
|
"sub_reseller_id": sub_reseller_id, # optional
|
|
"supplier_id": supplier_id, # optional
|
|
"prodtypeid": product_type_id,
|
|
"productid": product_id,
|
|
"quantity": qty,
|
|
"unit_price": price,
|
|
})
|
|
# Returns: {contract_id, agreement_id, total_amount, supply_discount, supply_amount, distribution_discount, distribution_amount, profit_amount}
|
|
```
|