# ERPNext 对接通途

**Repository Path**: keyapi/tongtool_integration

## Basic Information

- **Project Name**: ERPNext 对接通途
- **Description**: ERPNext 通途对接 获取订单
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2025-08-28
- **Last Updated**: 2025-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Tongtool Integration for ERPNext

一个完整的通途(Tongtool)与ERPNext集成方案，专为跨境电商业务设计。

## 功能特性

- 🔄 **自动订单同步**: 支持自发货和FBA订单的自动同步
- 🎯 **智能SKU匹配**: 基于现有customer_items表的智能匹配机制
- 💰 **成本计算**: 集成物流价格，自动计算头程运费和订单利润
- ⏰ **定时任务**: 每日自动同步，支持手动触发
- 🔒 **安全可靠**: 完整的错误处理、重试机制和缓存支持
- 📊 **数据分析**: 毛利计算、利润分析和多维度统计

## 技术架构

### 核心组件

```
tongtool_integration/
├── api/                    # API客户端模块
│   ├── client.py          # 通途API客户端
│   ├── orders.py          # 订单API封装
│   └── test_client.py     # 测试工具
├── sync/                   # 同步服务
│   └── order_sync.py      # 订单同步逻辑
└── tongtool_integration/   # DocType定义
    └── doctype/
        ├── tongtool_settings/      # 配置管理
        ├── tongtool_order/         # 订单主表
        └── tongtool_order_item/    # 订单明细
```

### 数据模型

#### Tongtool Order (订单主表)
- 基本信息: 订单号、平台、状态、时间
- 买家信息: 姓名、邮箱、国家、地址
- 金额信息: 订单金额、商品总价、运费、平台费
- 利润分析: 物料成本、头程费用、毛利润、毛利率
- 同步状态: 匹配状态、同步状态、错误信息

#### Tongtool Order Item (订单明细)
- SKU信息: 平台SKU、通途SKU、ERPNext物料
- 数量价格: 数量、交易价格
- 成本信息: 物料成本、头程运费
- 匹配状态: 已匹配、未匹配、需人工处理

## 安装配置

### 1. 安装应用

```bash
# 开发环境
bench get-app tongtool_integration --branch develop

# 生产环境  
bench get-app tongtool_integration --branch main

# 安装到站点
bench --site your-site install-app tongtool_integration
```

### 2. 配置API

1. 在通途开放平台创建应用，获取App Key和App Secret
2. 在ERPNext中打开"Tongtool Settings"
3. 填入API凭证并保存

### 3. 配置SKU映射

确保ERPNext Item的customer_items子表中配置了通途SKU：

```
Item Code: KS0001-TR-183-ORANGE
├── Customer Items:
    └── Customer: 通途
        Ref Code: KS0001-TR-183-ORANGE
```

## 使用说明

### 手动同步

```python
# 同步指定日期
from tongtool_integration.sync.order_sync import manual_sync
result = manual_sync('2024-08-27', '2024-08-28')

# 同步昨天订单
from tongtool_integration.sync.order_sync import sync_yesterday_orders
result = sync_yesterday_orders()
```

### API测试

```python
# 运行完整测试
from tongtool_integration.api.test_client import run_all_tests
run_all_tests()

# 测试订单API
from tongtool_integration.api.orders import OrderAPI
api = OrderAPI()
orders, is_last = api.get_orders({
    'sale_date_from': '2024-08-27 00:00:00',
    'sale_date_to': '2024-08-27 23:59:59'
})
```

## 业务逻辑

### SKU匹配策略

系统按以下优先级自动匹配通途SKU到ERPNext Item：

1. **精确客户匹配**: customer_name = '通途'
2. **客户组匹配**: customer_group = '电商平台' 且 customer_name为空
3. **通用匹配**: customer_name和customer_group都为空

### 成本计算逻辑

```python
利润 = 商品总价 - 物料成本 - 头程运费 - 平台费用

其中:
- 物料成本: 从Item Price (Standard Buying)获取
- 头程运费: 基于Logistic Price和物料重量/体积计算
- 平台费用: 从通途订单数据获取
```

### 头程运费计算

```python
# 获取物料重量和体积
item_weight = 物料单重 * 数量
item_volume = 长*宽*高 / 1000000 * 数量

# 计算体积重量  
volumetric_weight = item_volume / 6000  # 空运标准

# 计费重量取大值
chargeable_weight = max(item_weight, volumetric_weight)

# 运费计算
if chargeable_weight == volumetric_weight:
    cost = chargeable_weight * 体积重量单价
else:
    cost = chargeable_weight * 实重单价
```

## 定制开发

### 添加自定义字段

```python
# 通过Customize Form添加字段到Tongtool Order
custom_fields = [
    {
        'fieldname': 'sales_person',
        'fieldtype': 'Link',
        'options': 'Employee',
        'label': '运营人员'
    }
]
```

### 自定义同步逻辑

```python
# 继承OrderSyncService
class CustomOrderSyncService(OrderSyncService):
    def _process_order(self, order_data, order_type):
        # 添加自定义处理逻辑
        order_data['custom_field'] = self.calculate_custom_value(order_data)
        return super()._process_order(order_data, order_type)
```

## 监控运维

### 日志监控

```bash
# 查看同步日志
bench logs | grep "tongtool"

# 查看错误日志
tail -f logs/worker.error.log | grep "tongtool"
```

### 性能监控

- 同步耗时: Tongtool Settings显示最后同步时间
- 错误统计: Error Log中查看错误记录  
- API调用: 缓存命中率和请求频率

### 数据校验

```sql
-- 检查同步状态
SELECT sync_status, COUNT(*) 
FROM `tabTongtool Order` 
GROUP BY sync_status;

-- 检查匹配状态  
SELECT match_status, COUNT(*)
FROM `tabTongtool Order`
GROUP BY match_status;
```

## FAQ

**Q: 如何处理未匹配的SKU？**
A: 在Tongtool Order中点击"重新匹配"按钮，或在Item Customer Detail中添加ref_code配置。

**Q: 订单同步失败怎么办？**
A: 查看Error Log获取详细错误信息，常见问题是API限频或网络超时。

**Q: 如何自定义利润计算？**
A: 重写TongtoolOrder.calculate_profit()方法，添加自己的成本项目。

**Q: 支持哪些通途订单类型？**
A: 支持自发货订单和FBA订单，会自动识别订单类型。

## 技术支持

- 项目地址: [GitHub/GitEE]
- 文档wiki: [项目文档]
- 问题反馈: [Issues]

## 许可证

MIT License

## 更新日志

### v1.0.0 (2024-08-28)
- ✨ 初版发布
- ✅ 基础订单同步功能
- ✅ SKU自动匹配
- ✅ 成本计算和利润分析
- ✅ 定时任务支持