# 天猫游戏店铺订单API

<cite>
**Referenced Files in This Document**   
- [t-mall-game-shop-order.ts](file://src/api/t-mall-game-shop-order.ts)
- [kami-api-card-info-tmall-game-v1-tmall-game-shop-order-list-req.ts](file://src/api/generated/models/kami-api-card-info-tmall-game-v1-tmall-game-shop-order-list-req.ts)
- [kami-api-card-info-tmall-game-v1-tmall-game-shop-order-list-res.ts](file://src/api/generated/models/kami-api-card-info-tmall-game-v1-tmall-game-shop-order-list-res.ts)
- [kami-api-card-info-tmall-game-v1-tmall-game-shop-order-get-one-res.ts](file://src/api/generated/models/kami-api-card-info-tmall-game-v1-tmall-game-shop-order-get-one-res.ts)
- [kami-api-card-info-tmall-game-v1-tmall-game-shop-order-history-res.ts](file://src/api/generated/models/kami-api-card-info-tmall-game-v1-tmall-game-shop-order-history-res.ts)
- [kami-internal-model-entity-v1-recharge-tmall-shop.ts](file://src/api/generated/models/kami-internal-model-entity-v1-recharge-tmall-shop.ts)
- [kami-internal-model-entity-v1-recharge-tmall-order.ts](file://src/api/generated/models/kami-internal-model-entity-v1-recharge-tmall-order.ts)
- [kami-internal-model-entity-v1-recharge-tmall-account.ts](file://src/api/generated/models/kami-internal-model-entity-v1-recharge-tmall-account.ts)
- [kami-internal-model-entity-v1-recharge-tmall-shop-history.ts](file://src/api/generated/models/kami-internal-model-entity-v1-recharge-tmall-shop-history.ts)
- [kami-internal-model-entity-v1-recharge-tmall-order-history.ts](file://src/api/generated/models/kami-internal-model-entity-v1-recharge-tmall-order-history.ts)
</cite>

## 目录

1. [简介](#简介)
2. [核心接口](#核心接口)
3. [请求参数详解](#请求参数详解)
4. [响应数据结构](#响应数据结构)
5. [数据模型关系](#数据模型关系)
6. [数据同步机制](#数据同步机制)
7. [代码示例](#代码示例)
8. [历史查询策略](#历史查询策略)

## 简介

天猫游戏店铺订单API提供了一套完整的店铺维度订单管理功能，支持店铺订单查询、历史记录获取和单个订单详情获取等核心操作。该API系统通过将平台订单与店铺订单进行映射，实现了从平台级数据到店铺级数据的转换和聚合，为店铺运营提供了精细化的数据支持。

API系统主要包含三个核心功能模块：店铺订单列表查询、单个订单详情获取和店铺订单历史查询。这些功能通过统一的数据模型和同步机制，确保了数据的一致性和完整性。系统设计考虑了数据分析场景的需求，提供了灵活的时间范围限制和数据聚合方式，便于进行业务分析和决策支持。

**Section sources**

- [t-mall-game-shop-order.ts](file://src/api/t-mall-game-shop-order.ts#L1-L90)

## 核心接口

天猫游戏店铺订单API提供了三个主要接口用于店铺订单管理：

1. **店铺订单列表查询接口**：通过`queryTMallShopOrderList`函数实现，用于获取店铺维度的订单列表数据。该接口支持分页查询和多种筛选条件，是获取批量订单数据的主要途径。

2. **单个订单详情获取接口**：提供对特定订单的详细信息查询功能，返回订单的完整属性信息，包括交易状态、支付信息、买家信息等关键数据。

3. **店铺订单历史查询接口**：通过`queryTMallOrderOrderHistory`函数实现，用于获取特定店铺的订单操作历史记录。该接口以店铺ID作为查询参数，返回该店铺相关的所有历史操作记录。

这些接口共同构成了店铺订单管理的核心功能体系，支持从批量查询到详细查看再到历史追溯的完整业务流程。接口设计遵循RESTful原则，通过HTTP GET方法进行数据获取，确保了接口的简洁性和易用性。

```mermaid
flowchart TD
A[客户端] --> B[店铺订单列表查询]
A --> C[单个订单详情获取]
A --> D[店铺订单历史查询]
B --> E[分页订单数据]
C --> F[订单详细信息]
D --> G[操作历史记录]
```

**Diagram sources**

- [t-mall-game-shop-order.ts](file://src/api/t-mall-game-shop-order.ts#L30-L55)
- [t-mall-game-shop-order.ts](file://src/api/t-mall-game-shop-order.ts#L75-L90)

**Section sources**

- [t-mall-game-shop-order.ts](file://src/api/t-mall-game-shop-order.ts#L6-L90)

## 请求参数详解

### KamiApiCardInfoTMallGameV1TMallGameShopOrderListReq请求参数

`KamiApiCardInfoTMallGameV1TMallGameShopOrderListReq`接口定义了店铺订单列表查询的所有请求参数，这些参数允许客户端对查询结果进行精确控制和筛选。

| 参数名称      | 类型          | 描述                                 | 是否必需 |
| ------------- | ------------- | ------------------------------------ | -------- |
| current       | number        | 页数，用于分页控制                   | 是       |
| pageSize      | enum          | 页码大小，定义每页返回的记录数量     | 是       |
| account       | string        | 充值账户，用于筛选特定账户的订单     | 否       |
| tMallOrderNo  | string        | 淘宝订单号，用于精确查找特定订单     | 否       |
| buyerNickName | string        | 买家昵称，用于按买家信息筛选订单     | 否       |
| orderNo       | string        | 订单号，用于查找特定订单             | 否       |
| dateRange     | Array<string> | 时间范围，用于筛选指定时间段内的订单 | 否       |

在实际使用中，`current`和`pageSize`参数共同实现了分页功能，允许客户端按需获取数据，避免一次性返回过多数据导致性能问题。`dateRange`参数特别重要，它支持时间范围查询，为数据分析场景提供了基础支持。当`dateRange`参数被使用时，系统会自动将其转换为`startDate`和`endDate`两个参数，以便后端进行时间范围筛选。

**Section sources**

- [kami-api-card-info-tmall-game-v1-tmall-game-shop-order-list-req.ts](file://src/api/generated/models/kami-api-card-info-tmall-game-v1-tmall-game-shop-order-list-req.ts#L19-L62)

## 响应数据结构

### KamiApiCardInfoTMallGameV1TMallGameShopOrderListRes响应结构

`KamiApiCardInfoTMallGameV1TMallGameShopOrderListRes`定义了店铺订单列表查询接口的响应数据结构，包含分页信息和订单数据列表。

| 属性名称 | 类型                   | 描述                                   |
| -------- | ---------------------- | -------------------------------------- |
| total    | number                 | 总记录数，表示满足查询条件的订单总数   |
| list     | Array<ShopOrderRecord> | 订单记录列表，包含当前页的所有订单数据 |

### KamiApiCardInfoTMallGameV1TMallGameShopOrderHistoryRes响应结构

`KamiApiCardInfoTMallGameV1TMallGameShopOrderHistoryRes`定义了店铺订单历史查询接口的响应结构，主要包含历史记录列表。

| 属性名称 | 类型                                                      | 描述                                     |
| -------- | --------------------------------------------------------- | ---------------------------------------- |
| list     | Array<KamiInternalModelEntityV1RechargeTMallOrderHistory> | 订单历史记录列表，包含所有匹配的历史操作 |

### 单个订单详情响应结构

单个订单详情接口返回`KamiApiCardInfoTMallGameV1TMallGameShopOrderGetOneRes`结构，包含订单的所有详细信息，如订单号、充值账号、淘宝订单号、买家信息、交易状态、支付金额等完整属性。

```mermaid
classDiagram
class KamiApiCardInfoTMallGameV1TMallGameShopOrderListRes {
+total : number
+list : Array<ShopOrderRecord>
}
class KamiApiCardInfoTMallGameV1TMallGameShopOrderHistoryRes {
+list : Array<KamiInternalModelEntityV1RechargeTMallOrderHistory>
}
class KamiApiCardInfoTMallGameV1TMallGameShopOrderGetOneRes {
+id : number
+orderNo : string
+account : string
+tMallOrderNo : string
+buyerNick : string
+buyerRate : number
+status : string
+payment : string
+totalFee : string
+payTime : string
+tradeStatus : string
+buyerMemo : string
+alipayNo : string
+buyerMessage : string
+createTime : string
+endTime : string
}
KamiApiCardInfoTMallGameV1TMallGameShopOrderListRes --> ShopOrderRecord : "包含"
KamiApiCardInfoTMallGameV1TMallGameShopOrderHistoryRes --> KamiInternalModelEntityV1RechargeTMallOrderHistory : "包含"
```

**Diagram sources**

- [kami-api-card-info-tmall-game-v1-tmall-game-shop-order-list-res.ts](file://src/api/generated/models/kami-api-card-info-tmall-game-v1-tmall-game-shop-order-list-res.ts#L25-L38)
- [kami-api-card-info-tmall-game-v1-tmall-game-shop-order-history-res.ts](file://src/api/generated/models/kami-api-card-info-tmall-game-v1-tmall-game-shop-order-history-res.ts#L23-L32)
- [kami-api-card-info-tmall-game-v1-tmall-game-shop-order-get-one-res.ts](file://src/api/generated/models/kami-api-card-info-tmall-game-v1-tmall-game-shop-order-get-one-res.ts#L19-L136)

**Section sources**

- [kami-api-card-info-tmall-game-v1-tmall-game-shop-order-list-res.ts](file://src/api/generated/models/kami-api-card-info-tmall-game-v1-tmall-game-shop-order-list-res.ts#L19-L38)
- [kami-api-card-info-tmall-game-v1-tmall-game-shop-order-history-res.ts](file://src/api/generated/models/kami-api-card-info-tmall-game-v1-tmall-game-shop-order-history-res.ts#L19-L32)
- [kami-api-card-info-tmall-game-v1-tmall-game-shop-order-get-one-res.ts](file://src/api/generated/models/kami-api-card-info-tmall-game-v1-tmall-game-shop-order-get-one-res.ts#L19-L136)

## 数据模型关系

### ShopOrderRecord模型结构

`ShopOrderRecord`模型定义了店铺订单的核心数据结构，包含订单的基本信息和交易状态。

| 属性名称     | 类型   | 描述         |
| ------------ | ------ | ------------ |
| id           | number | 订单唯一标识 |
| orderNo      | string | 订单号       |
| tMallOrderNo | number | 淘宝订单号   |
| created      | Date   | 交易创建时间 |
| buyerNick    | string | 买家昵称     |
| buyerRate    | number | 买家评价状态 |
| status       | string | 交易状态     |
| payment      | string | 实付金额     |
| totalFee     | string | 商品金额     |
| payTime      | Date   | 付款时间     |
| tradeStatus  | string | 天猫返回状态 |
| endTime      | Date   | 交易结束时间 |
| buyerMemo    | string | 买家备注     |
| alipayNo     | string | 支付宝交易号 |
| buyerMessage | string | 买家留言     |

### 店铺信息与账户信息的关联关系

系统通过多个核心数据模型实现了店铺信息和账户信息的关联：

1. **KamiInternalModelEntityV1RechargeTMallShop**：代表天猫店铺订单，包含订单的完整信息，如订单号、充值账号、买家信息、交易状态等。

2. **KamiInternalModelEntityV1RechargeTMallAccount**：代表充值账户信息，包含账户余额、充值次数、账户状态等属性。

3. **KamiInternalModelEntityV1RechargeTMallOrder**：代表平台订单，作为店铺订单与账户之间的桥梁，通过`accountId`和`shopId`字段实现关联。

这种三层关联结构确保了数据的完整性和一致性，使得可以从账户维度追踪到具体的店铺订单，也可以从店铺订单追溯到关联的账户信息。

```mermaid
erDiagram
ACCOUNT ||--o{ ORDER : "拥有"
ORDER ||--o{ SHOP_ORDER : "关联"
ACCOUNT {
string id PK
string accountNumber
number balance
number rechargeTimes
string status
string createdAt
string updatedAt
}
ORDER {
string orderNo PK
string accountId FK
string accountNumber
number amount
string status
number shopId FK
string createdAt
string updatedAt
}
SHOP_ORDER {
number id PK
string orderNo
string tMallOrderNo
string buyerNick
string status
string payment
string totalFee
string payTime
string tradeStatus
string endTime
string createdAt
string updatedAt
}
```

**Diagram sources**

- [t-mall-game-shop-order.ts](file://src/api/t-mall-game-shop-order.ts#L6-L22)
- [kami-internal-model-entity-v1-recharge-tmall-shop.ts](file://src/api/generated/models/kami-internal-model-entity-v1-recharge-tmall-shop.ts#L19-L134)
- [kami-internal-model-entity-v1-recharge-tmall-order.ts](file://src/api/generated/models/kami-internal-model-entity-v1-recharge-tmall-order.ts#L19-L122)
- [kami-internal-model-entity-v1-recharge-tmall-account.ts](file://src/api/generated/models/kami-internal-model-entity-v1-recharge-tmall-account.ts#L19-L68)

**Section sources**

- [t-mall-game-shop-order.ts](file://src/api/t-mall-game-shop-order.ts#L6-L22)
- [kami-internal-model-entity-v1-recharge-tmall-shop.ts](file://src/api/generated/models/kami-internal-model-entity-v1-recharge-tmall-shop.ts#L19-L134)
- [kami-internal-model-entity-v1-recharge-tmall-order.ts](file://src/api/generated/models/kami-internal-model-entity-v1-recharge-tmall-order.ts#L19-L122)
- [kami-internal-model-entity-v1-recharge-tmall-account.ts](file://src/api/generated/models/kami-internal-model-entity-v1-recharge-tmall-account.ts#L19-L68)

## 数据同步机制

### 店铺订单与平台订单的映射机制

系统通过`KamiInternalModelEntityV1RechargeTMallOrder`模型中的`shopId`字段实现店铺订单与平台订单的映射。每个平台订单都关联一个店铺订单ID，从而建立了从平台维度到店铺维度的数据映射关系。这种映射机制使得系统能够将分散的平台订单数据聚合到具体的店铺维度，为店铺运营提供针对性的数据支持。

### 数据同步策略

系统采用主动同步与被动回调相结合的数据同步策略：

1. **主动请求同步**：系统定期主动向天猫平台请求订单数据，确保数据的及时性和完整性。这种策略适用于需要保证数据完整性的场景。

2. **回调通知同步**：通过接收天猫平台的回调通知，实时更新订单状态。这种策略能够实现近乎实时的数据同步，特别适用于需要快速响应订单状态变化的场景。

3. **数据聚合方式**：系统在接收到原始订单数据后，会进行数据清洗、格式化和聚合处理，将平台级的原始数据转换为适合店铺管理的结构化数据。聚合过程包括字段映射、数据类型转换、状态归一化等操作。

4. **历史数据存储**：通过`KamiInternalModelEntityV1RechargeTMallShopHistory`和`KamiInternalModelEntityV1RechargeTMallOrderHistory`模型，系统保存了完整的操作历史记录，包括状态变更、备注更新等所有操作，为数据追溯和审计提供了支持。

```mermaid
sequenceDiagram
participant Platform as 天猫平台
participant System as 订单系统
participant Database as 数据库
Platform->>System : 订单状态变更回调
System->>System : 验证回调数据
System->>Database : 更新店铺订单状态
Database-->>System : 状态更新成功
System-->>Platform : 回调确认
System->>Platform : 定期查询订单数据
Platform-->>System : 返回订单列表
System->>System : 数据清洗与转换
System->>Database : 批量更新/插入订单数据
Database-->>System : 数据更新完成
```

**Diagram sources**

- [kami-internal-model-entity-v1-recharge-tmall-order.ts](file://src/api/generated/models/kami-internal-model-entity-v1-recharge-tmall-order.ts#L19-L122)
- [kami-internal-model-entity-v1-recharge-tmall-shop-history.ts](file://src/api/generated/models/kami-internal-model-entity-v1-recharge-tmall-shop-history.ts#L19-L68)
- [kami-internal-model-entity-v1-recharge-tmall-order-history.ts](file://src/api/generated/models/kami-internal-model-entity-v1-recharge-tmall-order-history.ts#L19-L74)

**Section sources**

- [kami-internal-model-entity-v1-recharge-tmall-order.ts](file://src/api/generated/models/kami-internal-model-entity-v1-recharge-tmall-order.ts#L19-L122)
- [kami-internal-model-entity-v1-recharge-tmall-shop-history.ts](file://src/api/generated/models/kami-internal-model-entity-v1-recharge-tmall-shop-history.ts#L19-L68)
- [kami-internal-model-entity-v1-recharge-tmall-order-history.ts](file://src/api/generated/models/kami-internal-model-entity-v1-recharge-tmall-order-history.ts#L19-L74)

## 代码示例

以下代码示例展示了如何使用`t-mall-game-shop-order.ts`中的方法获取店铺维度的订单数据：

```typescript
import {
  queryTMallShopOrderList,
  TMallOrderParams
} from '@/api/t-mall-game-shop-order';

// 定义查询参数
const params: TMallOrderParams = {
  current: 1,
  pageSize: 20,
  account: 'example_account',
  dateRange: [new Date('2023-01-01'), new Date('2023-12-31')]
};

// 调用API获取店铺订单列表
queryTMallShopOrderList(params)
  .then(response => {
    console.log('订单总数:', response.data.total);
    console.log('订单列表:', response.data.list);
  })
  .catch(error => {
    console.error('获取订单失败:', error);
  });
```

在上述示例中，`queryTMallShopOrderList`函数接收`TMallOrderParams`类型的参数对象，该对象继承自分页参数并扩展了`ShopOrderRecord`的部分属性。系统会自动处理`dateRange`参数，将其转换为`startDate`和`endDate`，然后发送HTTP GET请求到`/api/recharge/tMallGame/shopOrder/getList`端点。

**Section sources**

- [t-mall-game-shop-order.ts](file://src/api/t-mall-game-shop-order.ts#L30-L55)

## 历史查询策略

### 时间范围限制

店铺订单历史查询接口虽然没有直接的时间参数，但其数据源受到严格的时间范围限制。系统通常只保留最近一定时期（如90天或180天）的订单历史记录，超出此范围的数据可能会被归档或删除。这种设计既保证了查询性能，又满足了大多数业务场景的需求。

### 数据聚合方式

历史查询接口采用以下数据聚合策略：

1. **按店铺聚合**：以店铺ID为维度，聚合该店铺的所有历史操作记录，形成完整的操作时间线。

2. **状态变更记录**：详细记录订单状态的每次变更，包括变更前后的状态值、变更时间和操作人等信息。

3. **操作类型分类**：将历史记录按操作类型分类，如状态变更、备注更新、评价处理等，便于后续分析。

4. **原始数据保留**：通过`originalData`字段保留每次操作的原始数据快照，为数据追溯和问题排查提供依据。

### 数据分析使用指导

在数据分析场景中，建议采用以下策略使用历史查询接口：

1. **分批查询**：对于大量数据的分析，建议分批查询，避免一次性获取过多数据导致性能问题。

2. **时间窗口分析**：结合时间范围参数，分析特定时间段内的订单趋势和用户行为。

3. **状态流转分析**：利用历史记录分析订单状态的流转路径和耗时，识别流程瓶颈。

4. **异常检测**：通过分析历史记录中的异常状态变更，及时发现系统或业务流程中的问题。

**Section sources**

- [t-mall-game-shop-order.ts](file://src/api/t-mall-game-shop-order.ts#L75-L90)
- [kami-api-card-info-tmall-game-v1-tmall-game-shop-order-history-res.ts](file://src/api/generated/models/kami-api-card-info-tmall-game-v1-tmall-game-shop-order-history-res.ts#L19-L32)
