# 电商代码

**Repository Path**: caigxx/shopify_dev

## Basic Information

- **Project Name**: 电商代码
- **Description**: No description available
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-15
- **Last Updated**: 2025-11-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Shopify 集成服务平台

## 1. 项目概述
本项目是基于 FastAPI 开发的集成服务平台，为 Shopify 店铺提供全面的业务支持。核心功能包括：**文本翻译**、**货币汇率查询/计算**、**积分管理**、**IP定位**以及**Shopify webhook集成**。平台具备自动生成接口文档、请求参数校验、全局统一异常处理、多线程压测支持等特性，可直接部署至生产环境或基于现有框架进行二次开发。

## 2. 项目结构
```
shopify_dev/
├── .gitignore                # Git 忽略文件配置
├── LICENSE                   # 许可证文件
├── README.md                 # 项目主文档
├── README_SUPPLEMENT.md      # 补充文档
├── __init__.py               # Python 包标识文件
├── app/                      # 应用主目录
│   ├── __init__.py           # 应用包标识文件
│   ├── conf/                 # 配置目录
│   │   ├── __init__.py
│   │   ├── config.py         # 应用配置（DEBUG 模式、代理等）
│   │   └── db_config.py      # 数据库配置
│   ├── main.py               # 应用入口（创建 FastAPI 实例、注册路由与中间件）
│   ├── routes/               # 路由层（API 接口定义）
│   │   ├── __init__.py
│   │   ├── exchange_route.py # 汇率相关接口
│   │   ├── ip_location_route.py # IP定位接口
│   │   ├── point_route.py    # 积分管理接口
│   │   ├── shopify_webhook_route.py # Shopify webhook处理接口
│   │   └── translate_route.py # 翻译接口
│   ├── services/             # 服务层（核心业务逻辑实现）
│   │   ├── __init__.py
│   │   ├── exchange_service.py # 汇率业务逻辑
│   │   ├── ip_location_service.py # IP定位业务逻辑
│   │   ├── point_calculator_service.py # 积分计算服务
│   │   ├── point_service.py  # 积分管理服务
│   │   ├── shopify_payment_service.py # Shopify支付处理服务
│   │   └── translate_service.py # 翻译业务逻辑
│   └── utils/                # 工具层（通用功能模块）
│       ├── __init__.py
│       ├── db_utils.py       # 数据库操作工具
│       ├── error_handler.py  # 全局异常处理
│       └── response_handler.py # 统一响应格式
├── datas/                    # 数据文件目录
│   ├── __init__.py
│   └── exchange_map.txt      # 全球货币代码对照表
├── requiresments.txt         # 项目依赖列表
├── scripts/                  # 脚本目录
│   ├── __init__.py
│   └── 压测脚本.py           # 多线程压测工具
└── test/                     # 测试目录
    ├── __init__.py
    └── db_test.py            # 数据库测试
```

## 3. 环境准备

### 3.1 依赖版本说明
项目依赖已固定版本，避免版本兼容问题，具体如下：

| 依赖包         | 版本                  | 用途                     |
|----------------|-----------------------|--------------------------|
| fastapi        | 0.104.1               | 核心Web框架（接口开发）  |
| uvicorn        | 0.24.0.post1          | ASGI服务器（启动服务）   |
| pydantic       | 2.5.2                 | 数据校验（请求体/响应）  |
| googletrans    | 4.0.0-rc1             | 文本翻译（对接Google翻译）|
| requests       | 2.31.0                | HTTP请求（调用外部API/压测） |
| python-dotenv  | 1.0.0                 | 环境变量管理（配置文件） |
| pymysql        | 1.1.1                 | MYSQL数据库连接        |

### 3.2 依赖安装命令
在项目根目录（`Trans/FastAPI/`）下执行以下命令，安装所有依赖：
```bash
pip install -r requirements.txt
```

## 4. 服务执行流程

### 4.1 配置调整（可选）
DEBUG 模式开关：修改 config.py 中的 DEBUG = True/False（开发环境建议设为True，支持热重载；生产环境设为False，提升性能）。

代理配置：若需通过代理访问外部服务（如 Google 翻译），取消 config.py 中 HTTP_PROXY/HTTPS_PROXY 的注释，并替换为实际代理地址：
```python
# config.py 代理配置示例
HTTP_PROXY = os.getenv("HTTP_PROXY", "http://127.0.0.1:7897")
HTTPS_PROXY = os.getenv("HTTPS_PROXY", "http://127.0.0.1:7897")
```

### 4.2 启动服务
在项目根目录执行 main.py，启动 FastAPI 服务：
```bash
python main.py
```

默认启动参数：
- 访问地址：0.0.0.0（支持外部设备访问，而非仅本地）
- 端口：5000（可在 main.py 的 uvicorn.run 中修改 port 参数）
- 工作进程：4（多进程提升并发处理能力，可根据服务器 CPU 核心数调整）
- 热重载：DEBUG=True 时自动启用（代码修改后无需重启服务）

### 4.3 接口文档访问
服务启动后，可通过以下地址访问自动生成的接口文档（无需手动编写）：
- Swagger UI（推荐）：支持在线调试接口，地址：http://localhost:5000/docs
- ReDoc（纯文档）：仅展示接口信息，格式更简洁，地址：http://localhost:5000/redoc

### 4.4 模块业务说明
#### 4.4.1 翻译模块 (translate)
- **功能描述**：提供多语言文本翻译服务，支持自动检测源语言和手动指定语言对
- **核心特性**：
  - 集成Google翻译API，支持多种语言之间的互译
  - 文本长度统计和积分消耗计算（每字符5积分）
  - 支持Shopify店铺域名关联和元数据模型字段
- **业务流程**：接收翻译请求 → 验证参数 → 调用翻译服务 → 计算字符长度和积分消耗 → 返回统一格式响应

#### 4.4.2 汇率模块 (exchange)
- **功能描述**：提供全球货币汇率查询和金额计算服务
- **核心特性**：
  - 支持200+种全球货币的汇率查询
  - 汇率实时计算，支持金额转换
  - 支持货币代码验证
- **业务流程**：接收汇率查询/计算请求 → 验证货币代码 → 调用汇率API → 计算转换结果 → 返回统一格式响应

#### 4.4.3 积分模块 (point)
- **功能描述**：提供用户积分管理服务，支持积分计算、扣除和充值
- **核心特性**：
  - 基于文本长度的积分消耗计算（每字符5积分）
  - 支持Shopify订单关联的积分充值
  - 积分余额查询和管理
- **业务流程**：积分计算 → 积分扣除/充值 → 记录变更日志 → 更新积分余额

#### 4.4.4 IP定位模块 (ip_location)
- **功能描述**：提供IP地址地理位置查询服务
- **核心特性**：
  - 支持IP地址的国家、地区、城市信息查询
  - 实时地理位置数据获取
- **业务流程**：接收IP查询请求 → 调用IP定位服务 → 解析地理位置信息 → 返回统一格式响应

#### 4.4.5 Shopify集成模块 (shopify_webhook)
- **功能描述**：提供Shopify webhook接收和处理服务，支持订单支付和退款事件
- **核心特性**：
  - Webhook签名验证，确保数据安全
  - 订单支付和退款事件处理
  - 支持从请求体或请求头获取shopify_domain
  - 自动关联订单金额与积分充值
- **业务流程**：接收webhook事件 → 验证签名 → 解析订单数据 → 处理支付/退款 → 执行积分操作 → 返回处理结果

### 4.4 请求流转逻辑（以 "汇率查询" 为例）
1. 客户端向接口 POST /api/v1/exchange/rate 发送 JSON 格式请求；
2. 路由层 exchange_route.py 接收请求，通过 ExchangeRateRequest 模型校验参数（如货币代码是否为 3 位）；
3. 校验通过后，路由层调用服务层 exchange_service.py 的 get_exchange_rate 函数；
4. 服务层向第三方汇率 API（fawazahmed0/currency-api）发送请求，获取汇率数据并处理；
5. 服务层返回结果给路由层，路由层通过 SuccessResponse 统一封装响应格式，返回给客户端；
6. 若任一环节出错（如参数校验失败、API 调用超时），触发 error_handler.py 中的全局异常处理器，返回统一格式的错误响应。

## 5. 核心 API 文档
所有接口均使用 POST 方法，请求体为 JSON 格式，响应遵循 "成功 / 失败" 统一结构。

### 5.1 文本翻译接口

**基本信息**
- 接口路径：/api/v1/translate
- 接口描述：支持多语言文本翻译，默认自动检测源语言，可手动指定源语言/目标语言，并提供文本长度统计和积分消耗计算
- 请求方法：POST

**请求体参数**
| 字段名 | 类型 | 是否必填 | 默认值 | 示例值 | 描述 |
|--------|------|----------|--------|--------|------|
| text | string | 是 | - | "富士山下，樱花盛开" | 需要翻译的文本 |
| source_lang | string | 否 | "" | "zh-cn" | 源语言代码（如 zh-cn = 中文、en = 英文），为空时自动检测 |
| target_lang | string | 否 | "en" | "ja" | 目标语言代码（如 ja = 日语、fr = 法语） |
| shopify_domain | string | 否 | "" | "lucky@myshopify.com" | Shopify店铺域名，用于关联店铺信息 |
| metadata_modle | string | 否 | "" | "product_description" | 元数据模型，用于记录翻译内容类型 |

**成功响应示例**
```json
{
  "status": "success",
  "code": 200,
  "shopify_domain": "lucky@myshopify.com",
  "data": {
    "original_text": "富士山下，樱花盛开",
    "source_language": "zh-cn",
    "target_language": "ja",
    "translated_text": "富士山の下、桜が満開です",
    "text_length": 8,
    "point_consume": 40,
    "timestamp": "2024-06-01 15:20:30",
    "metadata_modle": "product_description"
  }
}
```

**异常情况说明**
| HTTP 状态码 | 错误信息 | 可能原因 |
|-------------|----------|----------|
| 422 | 字段校验失败（如 text 为空、语言代码格式错误） | 请求体参数不符合要求 |
| 500 | 服务器内部错误：翻译服务调用失败 | Google 翻译服务不可达、超时或被限制 |

**错误响应示例**
```json
{
  "status": "error",
  "code": 500,
  "shopify_domain": "lucky@myshopify.com",
  "data": null,
  "metadata_modle": "product_description",
  "error": "翻译服务调用失败"
}

### 5.2 货币汇率查询接口

**基本信息**
- 接口路径：/api/v1/exchange/rate
- 接口描述：查询两种货币的汇率（基准货币汇率固定为 1，返回目标货币相对基准货币的汇率）
- 请求方法：POST

**请求体参数**
| 字段名 | 类型 | 是否必填 | 示例值 | 描述 |
|--------|------|----------|--------|------|
| base_currency | string | 是 | "CNY" | 基准货币代码（3 位字母，参考 exchange_map.txt） |
| target_currency | string | 是 | "USD" | 目标货币代码（3 位字母） |

**成功响应示例**
```json
{
  "status": "success",
  "code": 200,
  "data": {
    "base_currency": "CNY",
    "target_currency": "USD",
    "base_rate": "1",
    "target_rate": "0.139",
    "timestamp": "2024-06-01 15:30:45"
  }
}
```

**异常情况说明**
| HTTP 状态码 | 错误信息 | 可能原因 |
|-------------|----------|----------|
| 422 | 字段校验失败（如货币代码非 3 位） | 请求体参数格式错误 |
| 404 | 无法获取指定货币对的汇率 | 目标货币代码不存在、第三方 API 无数据 |
| 500 | 服务器内部错误：汇率 API 请求失败 | 第三方汇率 API 超时、网络异常 |

### 5.3 货币汇率计算接口

**基本信息**
- 接口路径：/api/v1/exchange/calculate
- 接口描述：根据基准货币金额和汇率，计算目标货币的对应金额
- 请求方法：POST

**请求体参数**
| 字段名 | 类型 | 是否必填 | 示例值 | 描述 |
|--------|------|----------|--------|------|
| base_currency | string | 是 | "CNY" | 基准货币代码（3 位字母） |
| target_currency | string | 是 | "USD" | 目标货币代码（3 位字母） |
| base_price | float | 是 | 1000.0 | 基准货币金额（必须大于 0） |

**成功响应示例**
```json
{
  "status": "success",
  "code": 200,
  "data": {
    "base_currency": "CNY",
    "target_currency": "USD",
    "base_rate": "1",
    "target_rate": "0.139",
    "base_price": "1000.0",
    "target_price": "139.00",
    "timestamp": "2024-06-01 15:35:10",
    "status": "成功"
  }
}
```

**异常情况说明**
| HTTP 状态码 | 错误信息 | 可能原因 |
|-------------|----------|----------|
| 422 | 字段校验失败（如 base_price≤0） | 请求体参数不符合要求（金额需为正数） |
| 404 | 货币转换失败，无法获取有效汇率 | 汇率查询失败（参考 "汇率查询接口" 异常） |
| 500 | 服务器内部错误：货币转换计算失败 | 汇率计算过程中出现类型错误、数值溢出 |

## 6. 全局异常处理
服务对常见 HTTP 异常进行统一封装，所有错误响应格式一致，便于客户端解析。根据不同接口类型，错误响应会包含相应的业务字段（如 shopify_domain 和 metadata_modle）。

### 6.1 错误响应格式
```json
{
  "status": "error",
  "code": 500,
  "shopify_domain": "",
  "data": null,
  "metadata_modle": "",
  "error": "错误描述信息"
}
```

### 6.2 支持的异常类型
| HTTP 状态码 | 错误含义 | 错误信息（message） | 典型场景 |
|-------------|----------|---------------------|----------|
| 404 | 资源不存在 | "Resource not found" | 访问不存在的接口（如 /api/v1/test） |
| 500 | 服务器内部错误 | "Internal server error" | 业务逻辑异常（如翻译服务调用失败） |
| 502 | 网关错误 | "Bad gateway" | 第三方 API 返回错误（如汇率 API 故障） |
| 503 | 服务不可用 | "Service temporarily unavailable" | 服务过载、维护中或进程崩溃 |

## 7. 压测脚本使用
项目提供 压测脚本.py，支持对翻译 / 汇率接口进行多线程压测，用于验证服务并发能力。

### 7.1 压测参数配置
压测脚本位于 `scripts/压测脚本.py`，可通过修改以下参数指定压测目标：
```python
# 1. 压测接口（选择要压测的接口）
URL = "http://127.0.0.1:5000/api/v1/exchange/rate"  # 汇率查询接口
# URL = "http://127.0.0.1:5000/api/v1/translate"     # 翻译接口（带积分计算）
# URL = "http://127.0.0.1:5000/api/v1/exchange/calculate" # 汇率计算接口

# 2. 对应接口的请求数据（与接口匹配）
# 汇率查询请求数据
DATA = {"base_currency":"CNY","target_currency":"USD"}
# 翻译请求数据（若压测翻译接口，启用以下配置）
# DATA = {"text":"富士山下，樱花盛开","source_lang":"zh-cn","target_lang":"ja","shopify_domain":"test@myshopify.com","metadata_modle":"test"}
# 汇率计算请求数据
# DATA = {"base_currency":"CNY","target_currency":"USD","base_price":1000.0}

# 3. 压测并发配置
THREAD_COUNT = 50    # 最大并发线程数（根据服务器性能调整）
REQUEST_COUNT = 200  # 总请求数（压测期间发送的请求总量）
```

### 7.2 执行压测
在项目根目录执行脚本：
```bash
python 压测脚本.py
```

### 7.3 压测结果示例
```
总请求数: 200
并发数: 50
成功请求数: 197
失败请求数: 3
总耗时: 4.12 秒
```

## 8. 注意事项
- **货币代码参考**：所有货币代码需符合 ISO 4217 标准，具体可参考 datas/exchange_map.txt（包含全球国家/地区的货币代码）。
- **翻译服务限制**：googletrans 依赖 Google 翻译服务，若国内无法访问，需在 config.py 中配置代理。
- **积分计算规则**：翻译接口默认按每字符5积分计算消耗，可在 point_calculator_service.py 中调整计算规则。
- **Shopify Webhook配置**：使用前需在Shopify店铺管理后台配置正确的webhook URL和事件类型。
- **生产环境优化**：
  - 关闭 DEBUG 模式（config.py 中 DEBUG = False）；
  - 根据服务器 CPU 核心数调整 workers 数量（main.py 中 uvicorn.run 的 workers 参数）；
  - 建议使用 Nginx 作为反向代理，提升服务稳定性和并发能力；
  - 配置数据库连接池，优化数据库性能。
- **汇率数据时效性**：第三方汇率 API（fawazahmed0/currency-api）数据每日更新，若需实时汇率，需替换为实时性更高的 API。

## 9. 新增功能说明

### 9.1 翻译积分计算
- **功能描述**：翻译接口新增文本长度统计和积分消耗计算
- **计算规则**：每翻译1个字符消耗5积分
- **相关接口**：POST /api/v1/translate
- **实现模块**：point_calculator_service.py

### 9.2 Shopify Webhook集成
- **功能描述**：支持接收和处理Shopify的订单支付和退款webhook事件
- **支持事件**：
  - 订单创建事件（orders/create）：处理支付并充值积分
  - 退款创建事件（refunds/create）：处理退款并扣除积分
- **安全机制**：支持webhook签名验证，确保数据安全
- **相关接口**：POST /api/v1/shopify/webhook
- **实现模块**：shopify_webhook_route.py, shopify_payment_service.py

### 9.3 IP定位服务
- **功能描述**：提供IP地址的地理位置查询功能
- **返回信息**：包括国家、地区、城市等地理位置信息
- **相关接口**：POST /api/v1/ip/location
- **实现模块**：ip_location_route.py, ip_location_service.py

### 9.4 积分管理系统
- **功能描述**：提供积分余额查询、充值和扣除功能
- **核心特性**：
  - 支持按订单金额自动计算积分充值
  - 与翻译服务集成，自动扣除翻译消耗的积分
  - 提供积分流水记录
- **相关接口**：POST /api/v1/point/*（多个积分相关接口）
- **实现模块**：point_route.py, point_service.py, point_calculator_service.py