# API 文档

所有API通过API Gateway (`http://localhost:8080`) 访问。

> **💡 快速生成测试数据？** 查看 [BATCH_TEST_API.md](BATCH_TEST_API.md) 获取批量模拟请求API
> 
> 一句命令生成50个订单: `curl http://localhost:8080/api/test/order/batch?count=50`

## 订单服务 (Order Service)

### 1. 创建订单
**请求:**
```http
POST /api/order/create
Content-Type: application/json
X-User-Id: user123

{
  "userId": "user123",
  "price": 99.99,
  "description": "test order"
}
```

**响应 (成功 200):**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "orderId": "ORD-A1B2C3D4",
    "userId": "user123",
    "price": 99.99,
    "status": "CREATED",
    "description": "test order",
    "createdAt": 1707200445123
  }
}
```

**响应 (失败):**
```json
{
  "code": -1,
  "msg": "price must be > 0",
  "data": null
}
```

---

### 2. 获取订单详情
**请求:**
```http
GET /api/order/{orderId}
```

**示例:**
```bash
curl http://localhost:8080/api/order/ORD-A1B2C3D4
```

**响应 (成功 200):**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "orderId": "ORD-A1B2C3D4",
    "userId": "user123",
    "price": 99.99,
    "status": "CREATED",
    "description": "test order",
    "createdAt": 1707200445123
  }
}
```

---

### 3. 支付订单
**请求:**
```http
POST /api/order/{orderId}/pay
```

**示例:**
```bash
curl -X POST http://localhost:8080/api/order/ORD-A1B2C3D4/pay
```

**响应 (成功 200):**
```json
{
  "code": 0,
  "msg": "success",
  "data": null
}
```

---

### 4. 删除订单
**请求:**
```http
POST /api/order/delete/{orderId}
```

**示例:**
```bash
curl -X POST http://localhost:8080/api/order/delete/ORD-A1B2C3D4
```

**响应 (成功 200):**
```json
{
  "code": 0,
  "msg": "success",
  "data": null
}
```

**响应 (已支付订单不能删除):**
```json
{
  "code": -1,
  "msg": "Paid order cannot be deleted",
  "data": null
}
```

---

## 支付服务 (Payment Service)

### 1. 支付订单
**请求:**
```http
POST /api/payment/pay
Content-Type: application/json
X-User-Id: user123

{
  "orderId": "ORD-A1B2C3D4",
  "amount": 99.99,
  "paymentMethod": "WECHAT"
}
```

**支付方式选项:**
- `CARD` - 银行卡
- `WECHAT` - 微信
- `ALIPAY` - 支付宝

**响应 (成功 200):**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "paymentId": "PAY-X1Y2Z3W4",
    "orderId": "ORD-A1B2C3D4",
    "amount": 99.99,
    "status": "SUCCESS",
    "paymentMethod": "WECHAT",
    "paidAt": 1707200500234
  }
}
```

**响应 (失败 - 30% 概率):**
```json
{
  "code": -1,
  "msg": "Third party payment failed",
  "data": null
}
```

---

### 2. 获取支付详情
**请求:**
```http
GET /api/payment/{paymentId}
```

**示例:**
```bash
curl http://localhost:8080/api/payment/PAY-X1Y2Z3W4
```

**响应 (成功 200):**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "paymentId": "PAY-X1Y2Z3W4",
    "orderId": "ORD-A1B2C3D4",
    "amount": 99.99,
    "status": "SUCCESS",
    "paymentMethod": "WECHAT",
    "paidAt": 1707200500234
  }
}
```

---

### 3. 退款
**请求:**
```http
POST /api/payment/refund/{paymentId}
```

**示例:**
```bash
curl -X POST http://localhost:8080/api/payment/refund/PAY-X1Y2Z3W4
```

**响应 (成功 200):**
```json
{
  "code": 0,
  "msg": "success",
  "data": null
}
```

**响应 (非成功支付无法退款):**
```json
{
  "code": -1,
  "msg": "Only success payment can be refunded",
  "data": null
}
```

---

## 日志对应关系

### 订单创建流程产生的日志链路

```
1. Gateway 收到请求
   └─ traceId: abc-123-def-456
   └─ uri: /api/order/create
   └─ uri_group: /order/*

2. Order Service 处理请求
   └─ event_class: order
   └─ duration: 156ms
   └─ status: success

3. 返回响应
   └─ 记录完整的MDC上下文
```

### 支付流程产生的日志链路

```
1. Gateway 收到请求
   └─ traceId: xyz-789-uvw-012
   └─ uri: /api/payment/pay
   └─ uri_group: /payment/*

2. Payment Service 处理请求
   └─ event_class: payment
   └─ duration: 234ms
   └─ status: success (70%) 或 server_error (30%)

3. 返回响应
   └─ 记录完整的MDC上下文
```

---

## cURL 测试脚本

### 完整的订单+支付流程

```bash
#!/bin/bash

# 1. 创建订单
echo "Creating order..."
ORDER_RESPONSE=$(curl -s -X POST http://localhost:8080/api/order/create \
  -H "Content-Type: application/json" \
  -H "X-User-Id: user123" \
  -d '{
    "userId":"user123",
    "price":99.99,
    "description":"test order"
  }')

ORDER_ID=$(echo $ORDER_RESPONSE | jq -r '.data.orderId')
echo "Order created: $ORDER_ID"

# 2. 获取订单详情
echo "Fetching order details..."
curl -s http://localhost:8080/api/order/$ORDER_ID | jq .

# 3. 支付订单
echo "Processing payment..."
PAYMENT_RESPONSE=$(curl -s -X POST http://localhost:8080/api/payment/pay \
  -H "Content-Type: application/json" \
  -d "{
    \"orderId\":\"$ORDER_ID\",
    \"amount\":99.99,
    \"paymentMethod\":\"WECHAT\"
  }")

PAYMENT_ID=$(echo $PAYMENT_RESPONSE | jq -r '.data.paymentId')
echo "Payment processed: $PAYMENT_ID"

# 4. 标记订单为已支付
echo "Marking order as paid..."
curl -s -X POST http://localhost:8080/api/order/$ORDER_ID/pay | jq .

# 5. 尝试删除已支付订单（应该失败）
echo "Attempting to delete paid order..."
curl -s -X POST http://localhost:8080/api/order/delete/$ORDER_ID | jq .

# 6. 获取支付详情
echo "Fetching payment details..."
curl -s http://localhost:8080/api/payment/$PAYMENT_ID | jq .

# 7. 退款
echo "Processing refund..."
curl -s -X POST http://localhost:8080/api/payment/refund/$PAYMENT_ID | jq .
```

保存为 `test.sh` 并运行：
```bash
chmod +x test.sh
./test.sh
```

---

## HTTP 状态码

| 状态码 | 含义 |
|--------|------|
| 200 | 请求成功（响应体中 code=0 表示业务成功） |
| 400 | 请求参数错误 |
| 500 | 服务器错误 |

## 请求头

| 头| 说明 | 示例 |
|----|------|------|
| `Content-Type` | 必需 (POST/PUT) | `application/json` |
| `X-User-Id` | 可选，用于日志追踪 | `user123` |
| `X-B3-TraceId` | 可选，Jaeger/Zipkin追踪ID | `550e8400-e29b-41d4` |

---

## 错误处理

所有API响应都遵循统一的格式：

```json
{
  "code": 0,           // 0 表示成功，非0表示错误
  "msg": "success",    // 错误或成功信息
  "data": {...}        // 业务数据（错误时为null）
}
```

实际的HTTP状态码始终是200，业务状态通过 `code` 字段判断。