# 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`