# ShopOrder API 文档

## 概述

商家订单系统 API，提供订单创建、订单查询等功能。支持微信支付、支付宝支付和银联支付三种支付方式。

**基础路径**: `/api/shop_order`  
**认证方式**: Bearer Token  
**数据格式**: JSON

---

## 目录

- [获取订单详情](#获取订单详情)
- [创建订单支付](#创建订单支付)
- [获取商户银联待入账金额列表](#获取商户银联待入账金额列表)
- [获取商户银联待入账金额列表 (带日期和分页)](#获取商户银联待入账金额列表带日期和分页)

---

## 接口列表

### 认证方式

所有接口都需要通过 `ApiMiddleware` 中间件进行认证。

**支持的认证方式：**

1. **Header 方式**（推荐）:
   ```
   Authorization: Bearer <your-token>
   ```

2. **Query 参数方式**:
   ```
   GET /api/shop_order/info?order_sn=xxx&token=your-token
   ```

---

### 1. 获取订单详情

#### 基本信息
- **接口路径**: `/api/shop_order/info`
- **请求方式**: GET
- **接口描述**: 根据订单编号查询订单详细信息（包含店铺名称）
- **认证要求**: 需要 Token 认证
- **请求头要求**:
  - `Content-Type`: application/json
  - `Authorization`: Bearer {token}

#### 请求参数

| 参数名 | 类型 | 位置 | 必填 | 说明 | 验证规则 |
|--------|------|------|------|------|----------|
| order_sn | string | query | 是 | 订单编号 | required, min=1, max=64 |

#### 请求示例

```http
GET /api/shop_order/info?order_sn=382FS1234567890 HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Authorization: Bearer your-token-here
```

#### 响应格式

**成功响应 (200)**
```json
{
    "code": 200,
    "message": "success",
    "data": {
        "rs_sn": "382FS1234567890",
        "pay_sn": "PAY20260312001",
        "status": 2,
        "pay_money": "100.00",
        "shop_name": "某某店铺"
    }
}
```

**失败响应 - 参数错误 (400)**
```json
{
    "code": 400,
    "message": "订单编号不能为空",
    "data": []
}
```

**失败响应 - 订单不存在 (400)**
```json
{
    "code": 400,
    "message": "订单不存在",
    "data": []
}
```

**失败响应 - 认证失败 (401)**
```json
{
    "code": 401,
    "message": "token 失效",
    "data": null
}
```

#### 返回字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| rs_sn | string | 店铺订单支付编号 |
| pay_sn | string | 支付编号 |
| status | int | 订单状态（1：待支付，2：已支付，3：已退款/已完成） |
| pay_money | decimal | 支付金额 |
| shop_name | string | 店铺名称 |

#### cURL 测试示例

```bash
# 正常查询
curl -X GET "http://localhost:8080/api/shop_order/info?order_sn=382FS1234567890" \
  -H "Authorization: Bearer your-token"

# 缺少参数测试
curl -X GET "http://localhost:8080/api/shop_order/info"

# 订单不存在测试
curl -X GET "http://localhost:8080/api/shop_order/info?order_sn=INVALID_SN"
```

#### 注意事项

1. 该接口需要登录认证（通过 `ApiMiddleware`）
2. 订单编号必须是有效的字符串，长度不超过 64 个字符
3. 如果订单不存在，会返回"订单不存在"的错误提示
4. 接口会自动关联店铺表，返回店铺名称信息

---

### 2. 创建订单支付

#### 基本信息
- **接口路径**: `/api/shop_order/create`
- **请求方式**: GET/POST
- **接口描述**: 创建订单并获取支付信息（支持微信、支付宝、银联）
- **认证要求**: ⚠️ 必须登录（微信支付时需要验证用户身份）
- **请求头要求**:
  - `Content-Type`: application/json
  - `Authorization`: Bearer {token}（微信支付时必须）

#### 请求参数

| 参数名 | 类型 | 位置 | 必填 | 说明 | 验证规则 |
|--------|------|------|------|------|----------|
| shop_id | int | body/query | 是 | 商家 ID | required, gt=0 |
| pay_type | int | body/query | 是 | 支付方式（1：微信，2：支付宝） | required, gt=0, lt=3 |
| pay_money | string | body/query | 是 | 支付金额 | required, gt=0, lte=1000000 |
| pay_code_source | int | body/query | 否 | 收款码来源（1：普通，2：烟草） | omitempty |

**参数说明：**
- `shop_id`: 商家店铺 ID，必须大于 0
- `pay_type`: 支付方式，1=微信支付，2=支付宝支付
- `pay_money`: 支付金额，支持小数，最大 1000000
- `pay_code_source`: 可选参数，默认为 1

#### 请求示例

```http
POST /api/shop_order/create HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Authorization: Bearer your-token-here

{
    "shop_id": 1,
    "pay_type": 1,
    "pay_money": "100.00",
    "pay_code_source": 1
}
```

#### 响应格式

**成功响应 (200)**
```json
{
    "code": 200,
    "message": "success",
    "data": {
        "is_bank": 0,
        "wx_pay": {
            "appId": "wx1234567890",
            "timeStamp": "1234567890",
            "nonceStr": "random_string",
            "package": "prepay_id=xxx",
            "signType": "RSA",
            "paySign": "signature"
        },
        "zfb_pay": "",
        "pay_url": ""
    }
}
```

**失败响应 - 参数错误 (400)**
```json
{
    "code": 400,
    "message": "商家 id 不能为空",
    "data": []
}
```

**失败响应 - 金额错误 (400)**
```json
{
    "code": 400,
    "message": "金额不合法",
    "data": []
}
```

**失败响应 - 会员信息错误 (409)**
```json
{
    "code": 409,
    "message": "会员信息错误",
    "data": []
}
```

**失败响应 - 商户号信息错误 (400)**
```json
{
    "code": 400,
    "message": "商户号信息错误 xxx",
    "data": []
}
```

**失败响应 - 订单创建失败 (400)**
```json
{
    "code": 400,
    "message": "订单创建失败",
    "data": []
}
```

#### 返回字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| is_bank | int | 是否银联支付（0：否，1：是） |
| wx_pay | object | 微信支付参数（仅微信支付时返回） |
| zfb_pay | string | 支付宝支付 URL（仅支付宝支付时返回） |
| pay_url | string | H5 支付跳转 URL（仅银联支付时返回） |

**wx_pay 对象结构（微信支付时返回）：**
```json
{
    "appId": "wx1234567890",
    "timeStamp": "1234567890",
    "nonceStr": "random_string",
    "package": "prepay_id=xxx",
    "signType": "RSA",
    "paySign": "signature"
}
```

#### cURL 测试示例

```bash
# 创建微信订单
curl -X POST "http://localhost:8080/api/shop_order/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "shop_id": 1,
    "pay_type": 1,
    "pay_money": "100.00"
  }'

# 创建支付宝订单
curl -X POST "http://localhost:8080/api/shop_order/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "shop_id": 1,
    "pay_type": 2,
    "pay_money": "50.00"
  }'
```

#### 注意事项

1. 当 `pay_type=1`（微信支付）时，必须携带有效的 token 以获取用户 openid
2. 支付金额最小为 0.01 元，最大为 1000000 元
3. 如果商户配置了银联信息，会走银联支付通道（`is_bank=1`）
4. 微信支付返回前端 SDK 需要的支付参数，支付宝返回支付 URL，银联支付返回 H5 跳转链接
5. 订单编号由系统自动生成，格式如：382FS + 时间戳

---

### 3. 获取商户银联待入账金额列表

#### 基本信息
- **接口路径**: `/api/shop_order/bank_total`
- **请求方式**: GET
- **接口描述**: 获取商户银联待入账订单列表（最新 10 条）及待入账总金额（已扣除清分金额）
- **认证要求**: 需要 Token 认证
- **请求头要求**:
  - `Content-Type`: application/json
  - `Authorization`: Bearer {token}

#### 请求参数

无需参数，自动从 token 中获取会员信息并查询关联店铺。

#### 请求示例

```http
GET /api/shop_order/bank_total HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Authorization: Bearer your-token-here
```

#### 响应格式

**成功响应 (200)**
```json
{
    "code": 200,
    "message": "success",
    "data": {
        "total_money": "19600.00",
        "list": [
            {
                "rs_sn": "382FS1234567890",
                "pay_money": "98.00",
                "is_clearing": 0,
                "status": 6,
                "created_at": "2026-03-14T10:00:00Z"
            },
            {
                "rs_sn": "382FS1234567891",
                "pay_money": "196.00",
                "is_clearing": 0,
                "status": 6,
                "created_at": "2026-03-14T09:00:00Z"
            }
        ]
    }
}
```

**失败响应 - 未授权 (401)**
```json
{
    "code": 401,
    "message": "缺少登陆信息",
    "data": []
}
```

**失败响应 - 未找到店铺 (400)**
```json
{
    "code": 400,
    "message": "未找到店铺信息",
    "data": []
}
```

#### 返回字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| total_money | string | 银联待入账总金额（已扣除清分金额） |
| list | array | 订单列表（最新 10 条） |

**list 数组元素结构：**

| 字段名 | 类型 | 说明 |
|--------|------|------|
| rs_sn | string | 订单编号 |
| pay_money | string | 支付金额（已扣除清分金额） |
| is_clearing | int | 是否清分（0：待清分，1：已清分） |
| status | int | 订单状态（6：待入账） |
| created_at | string | 创建时间（RFC3339 格式） |

#### cURL 测试示例

```bash
# 查询最新 10 条银联待入账订单
curl -X GET "http://localhost:8080/api/shop_order/bank_total" \
  -H "Authorization: Bearer your-token"
```

#### 注意事项

1. 该接口需要登录认证，自动从 token 中获取会员 ID
2. 根据会员 ID 自动查询其关联的店铺（未删除且状态为 1）
3. 仅查询 status=6（待入账）且 is_bank=1（银联支付）的订单
4. 固定返回最新的 10 条记录，按 ID 降序排序
5. 返回的金额为扣除清分金额后的实际收益金额
6. 清分比例由商户配置的 discount 字段决定（折扣百分比）
7. 计算公式：`待入账金额 = 总金额 - (总金额 × discount / 100)`

---

### 4. 获取商户银联待入账金额列表 (带日期和分页)

#### 基本信息
- **接口路径**: `/api/shop_order/bank_list`
- **请求方式**: GET
- **接口描述**: 获取指定月份的商户银联待入账订单列表（支持分页）及统计信息
- **认证要求**: 需要 Token 认证
- **请求头要求**:
  - `Content-Type`: application/json
  - `Authorization`: Bearer {token}

#### 请求参数

| 参数名 | 类型 | 位置 | 必填 | 说明 | 验证规则 |
|--------|------|------|------|------|----------|
| date | string | query | 否 | 查询月份，格式：Y-m，默认本月 | datetime=2006-01 |
| page | int | query | 否 | 页码，默认 1 | gt=0 |
| page_size | int | query | 否 | 每页数量，默认 10，最大 100 | gt=0, lte=100 |

#### 请求示例

```http
GET /api/shop_order/bank_list?date=2026-03&page=1&page_size=10 HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Authorization: Bearer your-token-here
```

#### 响应格式

**成功响应 (200)**
```json
{
    "code": 200,
    "message": "success",
    "data": {
        "total": 50,
        "items": [
            {
                "rs_sn": "382FS1234567890",
                "pay_money": "98.00",
                "is_clearing": 0,
                "status": 6,
                "created_at": "2026-03-14T10:00:00Z"
            },
            {
                "rs_sn": "382FS1234567891",
                "pay_money": "196.00",
                "is_clearing": 0,
                "status": 4,
                "created_at": "2026-03-13T09:00:00Z"
            }
        ],
        "limit": 10,
        "end_date": "2026-04"
    }
}
```

**失败响应 - 未授权 (401)**
```json
{
    "code": 401,
    "message": "缺少登陆信息",
    "data": []
}
```

**失败响应 - 参数错误 (400)**
```json
{
    "code": 400,
    "message": "日期格式不正确",
    "data": []
}
```

#### 返回字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| total | int | 订单总数 |
| items | array | 订单列表（已扣除清分金额） |
| limit | int | 每页数量 |
| end_date | string | 查询月份的下一月（用于前端显示范围） |

**items 数组元素结构：**

| 字段名 | 类型 | 说明 |
|--------|------|------|
| rs_sn | string | 订单编号 |
| pay_money | string | 支付金额（已扣除清分金额） |
| is_clearing | int | 是否清分（0：待清分，1：已清分） |
| status | int | 订单状态（4：已支付，6：待入账） |
| created_at | string | 创建时间（RFC3339 格式） |

#### cURL 测试示例

```bash
# 查询本月数据
curl -X GET "http://localhost:8080/api/shop_order/bank_list" \
  -H "Authorization: Bearer your-token"

# 查询指定月份
curl -X GET "http://localhost:8080/api/shop_order/bank_list?date=2026-03" \
  -H "Authorization: Bearer your-token"

# 自定义分页
curl -X GET "http://localhost:8080/api/shop_order/bank_list?date=2026-03&page=2&page_size=20" \
  -H "Authorization: Bearer your-token"
```

#### 注意事项

1. 该接口需要登录认证，自动从 token 中获取会员 ID
2. 根据会员 ID 自动查询其关联的店铺（未删除且状态为 1）
3. 仅查询 is_bank=1（银联支付）且 status 为 4 或 6 的订单
4. 日期参数格式为 `Y-m`（如：2026-03），默认为当前月份
5. 查询范围为指定月份的 1 号至月底
6. 返回的金额为扣除清分金额后的实际收益金额
7. 清分比例由商户配置的 discount 字段决定（折扣百分比）
8. 分页参数有默认值，page 默认 1，page_size 默认 10，最大 100
9. end_date 返回的是查询月份的下一月，用于前端显示时间范围

---

### 通用说明

### 错误码说明

| 错误码 | HTTP 状态码 | 说明 | 常见场景 |
|--------|-----------|------|----------|
| 200 | 200 OK | 成功 | 请求成功处理 |
| 400 | Bad Request | 请求参数错误 | 参数缺失、格式错误、验证失败 |
| 401 | Unauthorized | 未授权/认证失败 | token 无效、过期或缺失 |
| 409 | Conflict | 资源冲突 | 会员信息错误、数据不存在 |

**业务错误信息详见各接口的响应格式说明。**

### 数据格式

**请求/响应格式：** JSON (`application/json`)

**金额精度：**
- 使用 `decimal.Decimal` 类型，保留两位小数
- 支持字符串或数字传递

**时间格式：** RFC3339 格式（`created_at`、`updated_at`）

### 版本信息

- **API 版本**: v1
- **最后更新**: 2026-03-14
- **维护者**: 开发团队
- **文档路径**: `/doc/shopOrder.md`

### 更新日志

#### v1.2.0 (2026-03-14)
- ✨ 新增：获取商户银联待入账金额列表接口 `/bank_list`（带日期和分页）
- 📝 说明：原 `/bank_total` 接口保留，作为快速查询接口

#### v1.1.0 (2026-03-14)
- ✨ 新增：获取商户银联待入账金额列表接口 `/bank_total`
- 🐛 修复：优化订单查询逻辑，移除分页参数
- 🔧 改进：简化响应数据结构，提升查询性能
- 📝 重构：方法名从 `GetBankOrderList` 改为 `GetShopBankOrder`

#### v1.0.0 (2026-03-13)
- ✨ 新增：获取订单详情接口 `/info`
- 🐛 修复：优化订单查询接口的参数验证
- 📝 改进：完善 API 文档说明

#### v1.0.0 (2026-03-12)
- ✨ 初始版本：创建订单支付接口 `/create`