# 单商户订单

<cite>
**本文档引用的文件**  
- [order.vue](file://src/views/merchant/single/order.vue)
- [kami-api-merchant-v1-order-query-req.ts](file://src/api/generated/models/kami-api-merchant-v1-order-query-req.ts)
- [kami-api-merchant-v1-order-query-res.ts](file://src/api/generated/models/kami-api-merchant-v1-order-query-res.ts)
- [kami-api-merchant-v1-order-query-record.ts](file://src/api/generated/models/kami-api-merchant-v1-order-query-record.ts)
</cite>

## 目录

1. [简介](#简介)
2. [订单查询功能](#订单查询功能)
3. [订单数据结构](#订单数据结构)
4. [订单界面渲染逻辑](#订单界面渲染逻辑)
5. [订单状态显示与操作](#订单状态显示与操作)
6. [性能与安全控制](#性能与安全控制)
7. [故障排除](#故障排除)

## 简介

本文档详细说明kami_frontend项目中单商户订单功能的实现机制。该功能允许商户通过订单号查询订单详情，查看订单状态、金额、操作记录等信息。系统通过API接口获取订单数据，并在前端进行结构化展示，支持实时查询和状态更新。

## 订单查询功能

单商户订单查询功能允许用户输入商户订单号进行精确查询。系统通过`apiMerchantOrderQueryGet`接口获取订单数据，支持异步加载和错误处理。查询过程中显示加载状态，查询完成后展示结果或提示未找到信息。

**订单查询请求参数：**

- `merchantOrderNo`：商户订单号（可选）

**查询流程：**

1. 用户输入订单号并点击查询
2. 设置加载状态为true
3. 调用API接口发送查询请求
4. 接收响应数据并更新视图
5. 无论成功或失败，最终设置加载状态为false

```mermaid
sequenceDiagram
participant 用户
participant 前端界面
participant API客户端
participant 后端服务
用户->>前端界面 : 输入订单号并点击查询
前端界面->>前端界面 : 设置加载状态
前端界面->>API客户端 : 调用apiMerchantOrderQueryGet
API客户端->>后端服务 : 发送GET请求
后端服务-->>API客户端 : 返回订单数据
API客户端-->>前端界面 : 解析响应
前端界面->>前端界面 : 更新渲染数据
前端界面->>前端界面 : 设置加载状态为false
前端界面-->>用户 : 展示查询结果
```

**图示来源**

- [order.vue](file://src/views/merchant/single/order.vue#L78-L117)

**节来源**

- [order.vue](file://src/views/merchant/single/order.vue#L40-L117)

## 订单数据结构

订单功能涉及多个数据模型，定义了请求参数、响应数据和记录项的结构。

### 请求数据结构

`KamiApiMerchantV1OrderQueryReq`接口定义了查询请求的数据结构：

**KamiApiMerchantV1OrderQueryReq**

- `merchantOrderNo` (string): 商户订单号

### 响应数据结构

`KamiApiMerchantV1OrderQueryRes`接口定义了查询响应的数据结构：

**KamiApiMerchantV1OrderQueryRes**

- `total` (number): 总记录数
- `list` (Array<KamiApiMerchantV1OrderQueryRecord>): 记录列表
- `bankOrderId` (string): 平台订单号
- `createTime` (string): 创建时间
- `amount` (number): 充值金额

### 记录数据结构

`KamiApiMerchantV1OrderQueryRecord`接口定义了单条记录的数据结构：

**KamiApiMerchantV1OrderQueryRecord**

- `orderNo` (string): 订单号
- `operation` (string): 操作类型（created、failed、recharging）
- `remark` (string): 备注信息
- `createdAt` (string): 创建时间
- `accountName` (string): 账号名称

```mermaid
classDiagram
class KamiApiMerchantV1OrderQueryReq {
+merchantOrderNo : string
}
class KamiApiMerchantV1OrderQueryRes {
+total : number
+list : Array<KamiApiMerchantV1OrderQueryRecord>
+bankOrderId : string
+createTime : string
+amount : number
}
class KamiApiMerchantV1OrderQueryRecord {
+orderNo : string
+operation : string
+remark : string
+createdAt : string
+accountName : string
}
KamiApiMerchantV1OrderQueryRes --> KamiApiMerchantV1OrderQueryRecord : "包含"
```

**图示来源**

- [kami-api-merchant-v1-order-query-req.ts](file://src/api/generated/models/kami-api-merchant-v1-order-query-req.ts)
- [kami-api-merchant-v1-order-query-res.ts](file://src/api/generated/models/kami-api-merchant-v1-order-query-res.ts)
- [kami-api-merchant-v1-order-query-record.ts](file://src/api/generated/models/kami-api-merchant-v1-order-query-record.ts)

**节来源**

- [kami-api-merchant-v1-order-query-req.ts](file://src/api/generated/models/kami-api-merchant-v1-order-query-req.ts)
- [kami-api-merchant-v1-order-query-res.ts](file://src/api/generated/models/kami-api-merchant-v1-order-query-res.ts)
- [kami-api-merchant-v1-order-query-record.ts](file://src/api/generated/models/kami-api-merchant-v1-order-query-record.ts)

## 订单界面渲染逻辑

订单界面采用响应式设计，使用Vue 3的Composition API实现数据绑定和状态管理。

### 主要组件

- `a-input-search`：搜索输入框，支持大尺寸和加载状态
- `a-descriptions`：描述列表，用于展示订单基本信息
- `a-typography-paragraph`：段落文本，用于展示操作记录
- `a-tag`：标签组件，用于突出显示关键信息

### 数据绑定

- `renderData`：响应式引用，存储查询返回的订单数据
- `loading`：布尔值，控制加载状态显示
- `state.value`：存储用户输入的查询条件

### 条件渲染

系统根据数据状态动态显示不同内容：

- 当`renderData.list`有数据时，显示"查询结果"标题
- 当`renderData.createTime`存在时，显示订单信息描述列表
- 当`renderData.list`为空且有查询条件时，显示"没有查询到结果"
- 当无查询条件时，显示"请输入查询条件"

## 订单状态显示与操作

订单状态通过文本和标签形式展示，系统根据操作类型显示相应的状态信息。

### 状态类型

- `created`：已创建
- `failed`：失败
- `recharging`：充值中

### 界面元素

- **平台订单号**：显示商户输入的查询订单号
- **系统订单号**：显示后端返回的平台订单号
- **订单时间**：显示订单创建时间
- **订单金额**：显示充值金额
- **操作记录**：按时间顺序列出所有操作及备注

系统通过`v-for`指令遍历`renderData.list`数组，为每条记录创建一个段落，格式为"【创建时间】操作 备注"。

## 性能与安全控制

系统实现了多项性能优化和安全控制措施。

### 性能优化

- **异步加载**：使用async/await实现非阻塞查询，避免界面卡顿
- **加载状态**：在查询期间显示加载动画，提升用户体验
- **错误处理**：使用try-catch捕获异常，确保finally块始终执行，正确更新加载状态

### 安全控制

- **输入验证**：虽然当前代码未显式验证，但API层应验证订单号格式
- **错误隐藏**：catch块中未暴露具体错误信息，防止敏感信息泄露
- **类型安全**：使用TypeScript定义接口，确保数据类型正确

## 故障排除

以下是一些常见问题及其解决方案：

### 问题1：查询无结果

**可能原因：**

- 订单号输入错误
- 订单不存在或已被删除
- 网络连接问题

**解决方案：**

- 检查订单号是否正确
- 确认订单状态
- 检查网络连接

### 问题2：界面卡顿

**可能原因：**

- 查询响应时间过长
- 数据量过大

**解决方案：**

- 检查API性能
- 确认是否返回了过多数据

### 问题3：加载状态不消失

**可能原因：**

- 异常未被捕获
- finally块未执行

**解决方案：**

- 检查错误处理逻辑
- 确保setLoading(false)在finally块中执行

**节来源**

- [order.vue](file://src/views/merchant/single/order.vue)
- [kami-api-merchant-v1-order-query-res.ts](file://src/api/generated/models/kami-api-merchant-v1-order-query-res.ts)
