MTKJPAY/mt-pay/README.md

# MT Pay - 支付系统

## 项目简介

面向东南亚地区的电商支付系统，支持PayPal支付、商品管理、订单管理、货币转换等功能。

## 功能特性

- ✅ PayPal支付集成（创建订单、捕获支付、Webhook处理）
- ✅ 商品管理（商品、SKU、商品链接）
- ✅ 客户订单管理（支持东南亚地址格式）
- ✅ 货币转换（实时汇率，支持多币种）
- ✅ 百度翻译集成（商品名称、SKU名称自动翻译）
- ✅ 订单状态管理
- ✅ 支付记录管理

## 技术栈

- Spring Boot 4.0.0
- MyBatis-Plus
- MySQL 5.7+
- Jackson (JSON处理)
- Lombok
- RestTemplate

## 快速开始

### 1. 数据库配置

执行数据库脚本（按顺序）：
```sql
-- 1. 商品相关表
source database/customer_order_schema.sql;

-- 2. 货币转换字段
source database/customer_order_currency_update.sql;

-- 3. 地址字段（混合方案）
source database/customer_order_address_optimized.sql;
```

### 2. 配置文件

编辑 `src/main/resources/application-dev.yml`：
- 数据库连接信息
- PayPal API凭证（Client ID、Client Secret）
- 百度翻译配置（App ID、Security Key）
- 阿里云OSS配置

### 3. 启动项目

```bash
mvn spring-boot:run
```

或

```bash
mvn clean package
java -jar target/mt-pay-0.0.1-SNAPSHOT.jar
```

### 4. 访问地址

- 后端API: http://localhost:8082/api
- Druid监控: http://localhost:8082/druid
- 前端地址: http://localhost:3000

## 核心API

### 商品管理
- `GET /api/product/{id}` - 获取商品详情
- `GET /api/product/link/{linkCode}` - 通过链接码获取商品
- `POST /api/product` - 创建商品

### 订单管理
- `POST /api/order` - 创建客户订单
- `GET /api/order/{orderNo}` - 获取订单详情
- `POST /api/order/calculate-currency-conversion` - 计算货币转换

### PayPal支付
- `POST /api/paypal/order` - 创建PayPal订单
- `POST /api/paypal/capture` - 捕获支付
- `POST /api/paypal/webhook` - Webhook回调

## 项目结构

```
com.mtkj.mtpay/
├── config/          # 配置类（PayPal、百度翻译、数据源等）
├── controller/      # REST控制器
├── dto/             # 数据传输对象
│   ├── request/     # 请求DTO
│   └── response/    # 响应DTO
├── entity/          # 实体类
├── exception/       # 异常处理
├── mapper/          # MyBatis Mapper
├── service/         # 业务服务层
│   └── impl/        # 服务实现
└── util/            # 工具类
```

## 核心服务

- **ProductService**: 商品管理服务
- **CustomerOrderService**: 客户订单服务
- **PayPalService**: PayPal支付服务
- **PayPalWebhookService**: PayPal Webhook处理服务
- **ExchangeRateService**: 汇率转换服务
- **BaiduTranslatorUtils**: 百度翻译工具

## 配置说明

### PayPal配置
```yaml
paypal:
  client-id: your-client-id
  client-secret: your-client-secret
  mode: sandbox  # sandbox 或 production
  enabled: true
```

### 百度翻译配置
```yaml
baidu:
  translator:
    app-id: your-app-id
    securityKey: your-security-key
    transApiHost: https://fanyi-api.baidu.com/api/trans/vip/translate
```

## 数据库表

- `mt_product` - 商品表
- `mt_product_sku` - SKU表
- `mt_product_link` - 商品链接表
- `customer_order` - 客户订单表
- `payment_order` - 支付订单表
- `payment_record` - 支付记录表

## 地址字段设计

采用混合方案：
- **基础字段**（独立列）：国家、城市、州/省、邮编、详细地址1/2
- **特殊字段**（JSON存储）：各国特殊字段（组屋号、Barangay、泰文地址等）

详见：`database/customer_order_address_optimized.sql`

## 相关文档

- `SYSTEM_ARCHITECTURE.md` - 系统架构文档
- `../PAYPAL_WEBHOOK_GUIDE.md` - PayPal Webhook配置指南
- `../PAYPAL_TEST_ACCOUNT.md` - PayPal测试账号说明

## 许可证

MIT