feat(order): 扩展订单地址字段并集成百度翻译服务

- 添加东南亚地址扩展字段到CreateCustomerOrderRequestDTO - 在CustomerOrder实体类中新增详细地址字段和特殊地址字段JSON存储 - 实现CustomerOrderServiceImpl中地址字段的存储和转换逻辑 - 集成BaiduTranslatorUtils实现订单内容自动翻译功能 - 在CustomerOrderResponseDTO中添加特殊地址字段Map格式支持 - 配置百度翻译API相关参数到application-dev.yml - 移除过时的架构文档和配置说明文件
2025-12-24 11:19:48 +08:00
parent 48eece45e5
commit 425c46217e
25 changed files with 490 additions and 2415 deletions
--- a/mt-pay/README.md
+++ b/mt-pay/README.md
@@ -1,218 +1,157 @@
-# MT Pay - PingPong支付对接
+# MT Pay - 支付系统

 ## 项目简介

-本项目实现了PingPong支付平台的内嵌SDK接入，支持收银台模式支付。
+面向东南亚地区的电商支付系统，支持PayPal支付、商品管理、订单管理、货币转换等功能。

 ## 功能特性

- ✅ 支付订单创建（checkout接口）
- ✅ MD5/SHA256签名生成和验证
- ✅ 支付回调处理
- ✅ 订单状态查询
- ✅ 收银台页面集成
+- ✅ PayPal支付集成（创建订单、捕获支付、Webhook处理）
+- ✅ 商品管理（商品、SKU、商品链接）
+- ✅ 客户订单管理（支持东南亚地址格式）
+- ✅ 货币转换（实时汇率，支持多币种）
+- ✅ 百度翻译集成（商品名称、SKU名称自动翻译）
+- ✅ 订单状态管理
 - ✅ 支付记录管理
- ✅ 预授权支持（AUTH/CAPTURE/VOID）

 ## 技术栈

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

-## 数据库表结构
+## 快速开始

-### payment_order（支付订单表）
- 存储支付订单基本信息
- 包含商户订单号、PingPong交易流水号、金额、状态等
+### 1. 数据库配置

-### payment_record（支付记录表）
- 存储支付操作记录
- 包含回调记录、查询记录等
+执行数据库脚本（按顺序）：
+```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**: 百度翻译工具

 ## 配置说明

-在 `application.properties` 中配置以下参数：
-
-```properties
-# PingPong支付配置
-pingpong.client-id=your-client-id          # PingPong商户号
-pingpong.acc-id=your-acc-id                # PingPong商户店铺编号
-pingpong.secret=your-secret-key            # 签名密钥
-pingpong.sign-type=MD5                      # 签名类型（MD5或SHA256）
-pingpong.gateway=https://sandbox-acquirer-payment.pingpongx.com  # API网关地址
-pingpong.mode=sandbox                       # 环境模式（sandbox/test/build）
+### PayPal配置
+```yaml
+paypal:
+  client-id: your-client-id
+  client-secret: your-client-secret
+  mode: sandbox  # sandbox 或 production
+  enabled: true
 ```

-## API接口
-
-### 1. 创建支付订单
-
-**接口地址：** `POST /api/payment/checkout`
-
-**请求示例：**
-```json
-{
-  "accId": "2018092714313010016291",
-  "amount": "20.00",
-  "currency": "USD",
-  "merchantTransactionId": "MTN193495030728",
-  "paymentType": "SALE",
-  "shopperResultUrl": "http://your-domain.com/api/callback/result",
-  "shopperCancelUrl": "http://your-domain.com/api/callback/result",
-  "signType": "MD5",
-  "riskInfo": {
-    "customer": {
-      "firstName": "James",
-      "lastName": "LeBron",
-      "email": "demo@pingpongx.com",
-      "phone": "15988890852",
-      "registerTime": "20191101122000",
-      "registerIp": "222.126.52.23",
-      "orderTime": "20191201122000",
-      "orderIp": "222.126.52.23"
-    },
-    "goods": [{
-      "name": "Macaron",
-      "description": "Colorful macaron",
-      "sku": "20191201331",
-      "averageUnitPrice": "20",
-      "number": "1",
-      "virtualProduct": "N"
-    }],
-    "shipping": {
-      "firstName": "James",
-      "lastName": "LeBron",
-      "phone": "13588185079",
-      "street": "1986 Broad Street",
-      "postcode": "35222",
-      "city": "Birmingham",
-      "state": "Alabama",
-      "country": "US"
-    },
-    "billing": {
-      "firstName": "James",
-      "lastName": "LeBron",
-      "phone": "13588185079",
-      "street": "1986 Broad Street",
-      "postcode": "35222",
-      "city": "Birmingham",
-      "state": "Alabama",
-      "country": "US"
-    }
-  },
-  "notificationUrl": "http://your-domain.com/api/callback/pingpong"
-}
+### 百度翻译配置
+```yaml
+baidu:
+  translator:
+    app-id: your-app-id
+    securityKey: your-security-key
+    transApiHost: https://fanyi-api.baidu.com/api/trans/vip/translate
 ```

-**响应示例：**
-```json
-{
-  "code": "0000",
-  "message": "订单创建成功",
-  "data": {
-    "merchantTransactionId": "MTN193495030728",
-    "token": "vr_YVR8u7rn7C1gG97DOg5W0OxzazxNYIE56ShWjA4lJrY4wchTnb47oNmp-9ubP",
-    "paymentUrl": "https://sandbox-pay-checkout.pingpongx.com/index.html?token=...",
-    "status": "PENDING"
-  }
-}
-```
+## 数据库表

-### 2. 查询订单状态
+- `mt_product` - 商品表
+- `mt_product_sku` - SKU表
+- `mt_product_link` - 商品链接表
+- `customer_order` - 客户订单表
+- `payment_order` - 支付订单表
+- `payment_record` - 支付记录表

-**接口地址：** `GET /api/payment/order/{merchantTransactionId}`
+## 地址字段设计

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

-**接口地址：** `GET /api/payment/checkout/page?token={token}`
+详见：`database/customer_order_address_optimized.sql`

-### 4. 支付回调接口
+## 相关文档

-**接口地址：** `POST /api/callback/pingpong`
-
-### 5. 支付结果页面
-
-**接口地址：** `GET /api/callback/result?merchantTransactionId={id}&status={status}`
-
-## 使用流程
-
-1. **创建支付订单**
-   - 调用 `/api/payment/checkout` 接口创建订单
-   - 获取返回的 `token`
-
-2. **跳转到收银台**
-   - 方式1：直接使用返回的 `paymentUrl` 跳转
-   - 方式2：调用 `/api/payment/checkout/page?token={token}` 获取收银台页面
-
-3. **用户完成支付**
-   - 用户在收银台页面完成支付
-   - 支付完成后跳转到 `shopperResultUrl`
-
-4. **接收回调通知**
-   - PingPong会异步调用 `notificationUrl` 通知支付结果
-   - 系统自动更新订单状态
-
-## 注意事项
-
-1. **订单号唯一性**：`merchantTransactionId` 必须全局唯一，不可重复
-2. **金额格式**：`amount` 必须精确到两位小数，如 "20.00"
-3. **环境模式**：开发测试使用 `sandbox`，生产环境必须使用 `build`
-4. **签名验证**：所有回调都会进行签名验证，确保数据安全
-5. **风控信息**：`riskInfo` 中的 `shipping`、`billing`、`goods` 不能为空，影响交易成功率
-6. **REVIEW状态**：如果订单状态为 `REVIEW`，需要及时进行内部审核
-
-## 预授权功能
-
-### AUTH（预授权）
- 在创建订单时设置 `paymentType` 为 `AUTH`
-
-### CAPTURE（预授权完成）
- 调用二次交易接口，设置 `paymentType` 为 `CAPTURE`
- 需要在预授权成功后的7天内完成
-
-### VOID（预授权撤销）
- 调用二次交易接口，设置 `paymentType` 为 `VOID`
- 只能全额撤销
-
-## 开发说明
-
-### 项目结构
-```
-com.mtkj.mtpay/
-├── config/          # 配置类
-├── controller/       # 控制器
-├── dto/             # 数据传输对象
-├── entity/          # 实体类
-├── exception/       # 异常处理
-├── repository/      # 数据访问层
-└── service/         # 业务服务层
-```
-
-### 核心服务
-
- **SignatureService**：签名生成和验证服务
- **PingPongPayService**：PingPong API调用服务
- **PaymentOrderService**：支付订单业务服务
- **CallbackService**：回调处理服务
-
-## 数据库初始化
-
-项目启动后，JPA会自动创建表结构。也可以手动执行SQL：
-
-```sql
-- 根据实体类自动生成，或参考实体类定义手动创建
-```
-
-## 测试
-
-1. 配置沙箱环境参数
-2. 调用创建订单接口
-3. 使用沙箱测试卡号完成支付测试
+- `SYSTEM_ARCHITECTURE.md` - 系统架构文档
+- `../PAYPAL_WEBHOOK_GUIDE.md` - PayPal Webhook配置指南
+- `../PAYPAL_TEST_ACCOUNT.md` - PayPal测试账号说明

 ## 许可证

 MIT
-