{
  "openapi": "3.0.3",
  "info": {
    "title": "ChatApp Gateway HTTP API",
    "version": "1.0.0",
    "description": "Gateway 对外 HTTP 接口定义，采用 OpenAPI 3.0.3，可直接导入 Apifox。该文件覆盖当前 Gateway 暴露的全部 HTTP 路由。"
  },
  "servers": [
    {
      "url": "http://127.0.0.1:8080",
      "description": "本地默认地址，来源于 config/local.yaml"
    }
  ],
  "tags": [
    {
      "name": "System",
      "description": "健康检查与就绪检查"
    },
    {
      "name": "Auth",
      "description": "用户注册"
    },
    {
      "name": "Pay",
      "description": "支付下单"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "健康检查",
        "operationId": "getHealth",
        "parameters": [
          {
            "$ref": "#/components/parameters/XRequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "服务存活",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceStatusResponse"
                },
                "example": {
                  "status": "ok",
                  "service": "chatappgateway"
                }
              }
            }
          }
        }
      }
    },
    "/heath": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "健康检查兼容别名",
        "description": "兼容历史拼写错误的 `/heath` 路由，行为与 `/health` 完全一致。",
        "operationId": "getHealthAlias",
        "deprecated": true,
        "parameters": [
          {
            "$ref": "#/components/parameters/XRequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "服务存活",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceStatusResponse"
                },
                "example": {
                  "status": "ok",
                  "service": "chatappgateway"
                }
              }
            }
          }
        }
      }
    },
    "/ready": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "就绪检查",
        "description": "当 Gateway 可接收流量且下游依赖检查通过时返回 ready。",
        "operationId": "getReady",
        "parameters": [
          {
            "$ref": "#/components/parameters/XRequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "服务已就绪",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceStatusResponse"
                },
                "example": {
                  "status": "ready",
                  "service": "chatappgateway"
                }
              }
            }
          },
          "503": {
            "description": "服务未就绪或正在摘流",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "dependency_not_ready": {
                    "summary": "依赖未就绪",
                    "value": {
                      "code": "not_ready",
                      "message": "chatappuser not ready",
                      "request_id": "b31e6d8248775b9a"
                    }
                  },
                  "service_shutting_down": {
                    "summary": "服务摘流中",
                    "value": {
                      "code": "not_ready",
                      "message": "service is shutting down",
                      "request_id": "b31e6d8248775b9a"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/users/register": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "用户注册",
        "description": "校验注册参数后转发到用户服务。`nickname` 为空时会自动回退为 `account`。",
        "operationId": "postUserRegister",
        "parameters": [
          {
            "$ref": "#/components/parameters/XRequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegisterRequest"
              },
              "example": {
                "account": "demo@example.com",
                "password": "secret",
                "country_code": "+86",
                "verify_code": "123456",
                "nickname": "Neo",
                "device_id": "dev-1",
                "platform": "ios",
                "app_version": "1.0.0"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "注册成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegisterSuccessEnvelope"
                },
                "example": {
                  "code": "ok",
                  "message": "ok",
                  "request_id": "b31e6d8248775b9a",
                  "data": {
                    "user_id": "u-100",
                    "access_token": "access-token",
                    "is_new_user": true,
                    "profile": {
                      "user_id": "u-100",
                      "nickname": "Neo",
                      "avatar_url": "https://example.com/avatar.png"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "请求参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "invalid_json": {
                    "summary": "JSON 非法",
                    "value": {
                      "code": "bad_request",
                      "message": "invalid json body",
                      "request_id": "b31e6d8248775b9a"
                    }
                  },
                  "missing_account": {
                    "summary": "缺少账号",
                    "value": {
                      "code": "bad_request",
                      "message": "account is required",
                      "request_id": "b31e6d8248775b9a"
                    }
                  },
                  "missing_password": {
                    "summary": "缺少密码",
                    "value": {
                      "code": "bad_request",
                      "message": "password is required",
                      "request_id": "b31e6d8248775b9a"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "鉴权失败",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "code": "unauthorized",
                  "message": "register denied",
                  "request_id": "b31e6d8248775b9a"
                }
              }
            }
          },
          "405": {
            "description": "请求方法不允许",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "code": "method_not_allowed",
                  "message": "method not allowed",
                  "request_id": "b31e6d8248775b9a"
                }
              }
            }
          },
          "502": {
            "description": "下游服务错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "code": "upstream_error",
                  "message": "user service unavailable",
                  "request_id": "b31e6d8248775b9a"
                }
              }
            }
          },
          "504": {
            "description": "下游服务超时",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "code": "upstream_timeout",
                  "message": "upstream request timeout",
                  "request_id": "b31e6d8248775b9a"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/pay": {
      "post": {
        "tags": [
          "Pay"
        ],
        "summary": "发起支付",
        "description": "校验支付参数后转发到支付服务创建支付单。",
        "operationId": "postPay",
        "parameters": [
          {
            "$ref": "#/components/parameters/XRequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PayRequest"
              },
              "example": {
                "order_no": "order-001",
                "user_id": "u-100",
                "amount": "9.99",
                "currency": "USD",
                "pay_method": "apple_pay",
                "subject": "vip"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "支付单创建成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaySuccessEnvelope"
                },
                "example": {
                  "code": "ok",
                  "message": "ok",
                  "request_id": "b31e6d8248775b9a",
                  "data": {
                    "payment_id": "pay-001",
                    "order_no": "order-001",
                    "user_id": "u-100",
                    "status": "processing",
                    "amount": "9.99",
                    "currency": "USD",
                    "pay_method": "apple_pay",
                    "subject": "vip",
                    "created_at": "2026-04-04T12:00:00Z"
                  }
                }
              }
            }
          },
          "400": {
            "description": "请求参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "invalid_json": {
                    "summary": "JSON 非法",
                    "value": {
                      "code": "bad_request",
                      "message": "invalid json body",
                      "request_id": "b31e6d8248775b9a"
                    }
                  },
                  "missing_order_no": {
                    "summary": "缺少订单号",
                    "value": {
                      "code": "bad_request",
                      "message": "order_no is required",
                      "request_id": "b31e6d8248775b9a"
                    }
                  },
                  "missing_user_id": {
                    "summary": "缺少用户 ID",
                    "value": {
                      "code": "bad_request",
                      "message": "user_id is required",
                      "request_id": "b31e6d8248775b9a"
                    }
                  },
                  "missing_amount": {
                    "summary": "缺少金额",
                    "value": {
                      "code": "bad_request",
                      "message": "amount is required",
                      "request_id": "b31e6d8248775b9a"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "请求方法不允许",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "code": "method_not_allowed",
                  "message": "method not allowed",
                  "request_id": "b31e6d8248775b9a"
                }
              }
            }
          },
          "502": {
            "description": "下游支付服务错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "code": "upstream_error",
                  "message": "pay service unavailable",
                  "request_id": "b31e6d8248775b9a"
                }
              }
            }
          },
          "504": {
            "description": "下游支付服务超时",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "code": "upstream_timeout",
                  "message": "upstream request timeout",
                  "request_id": "b31e6d8248775b9a"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "XRequestIdHeader": {
        "name": "X-Request-Id",
        "in": "header",
        "required": false,
        "description": "可选链路请求 ID。不传时由 Gateway 自动生成，并在响应头与响应体中返回。",
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "ServiceStatusResponse": {
        "type": "object",
        "required": [
          "status",
          "service"
        ],
        "properties": {
          "status": {
            "type": "string",
            "description": "服务状态",
            "example": "ok"
          },
          "service": {
            "type": "string",
            "description": "服务名称",
            "example": "chatappgateway"
          }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "required": [
          "code",
          "message",
          "request_id"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "业务错误码",
            "example": "bad_request"
          },
          "message": {
            "type": "string",
            "description": "错误描述",
            "example": "account is required"
          },
          "request_id": {
            "type": "string",
            "description": "请求链路 ID",
            "example": "b31e6d8248775b9a"
          }
        }
      },
      "RegisterRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "account",
          "password"
        ],
        "properties": {
          "account": {
            "type": "string",
            "description": "注册账号",
            "example": "demo@example.com"
          },
          "password": {
            "type": "string",
            "description": "登录密码",
            "example": "secret"
          },
          "country_code": {
            "type": "string",
            "description": "国家区号",
            "example": "+86"
          },
          "verify_code": {
            "type": "string",
            "description": "验证码",
            "example": "123456"
          },
          "nickname": {
            "type": "string",
            "description": "昵称；为空时服务端回退为 account",
            "example": "Neo"
          },
          "device_id": {
            "type": "string",
            "description": "设备 ID",
            "example": "dev-1"
          },
          "platform": {
            "type": "string",
            "description": "平台标识",
            "example": "ios"
          },
          "app_version": {
            "type": "string",
            "description": "App 版本号",
            "example": "1.0.0"
          }
        }
      },
      "UserProfile": {
        "type": "object",
        "properties": {
          "user_id": {
            "type": "string",
            "example": "u-100"
          },
          "nickname": {
            "type": "string",
            "example": "Neo"
          },
          "avatar_url": {
            "type": "string",
            "format": "uri",
            "example": "https://example.com/avatar.png"
          }
        }
      },
      "RegisterResponseData": {
        "type": "object",
        "properties": {
          "user_id": {
            "type": "string",
            "example": "u-100"
          },
          "access_token": {
            "type": "string",
            "example": "access-token"
          },
          "is_new_user": {
            "type": "boolean",
            "example": true
          },
          "profile": {
            "$ref": "#/components/schemas/UserProfile"
          }
        }
      },
      "RegisterSuccessEnvelope": {
        "type": "object",
        "required": [
          "code",
          "message",
          "request_id",
          "data"
        ],
        "properties": {
          "code": {
            "type": "string",
            "example": "ok"
          },
          "message": {
            "type": "string",
            "example": "ok"
          },
          "request_id": {
            "type": "string",
            "example": "b31e6d8248775b9a"
          },
          "data": {
            "$ref": "#/components/schemas/RegisterResponseData"
          }
        }
      },
      "PayRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "order_no",
          "user_id",
          "amount"
        ],
        "properties": {
          "order_no": {
            "type": "string",
            "description": "业务订单号",
            "example": "order-001"
          },
          "user_id": {
            "type": "string",
            "description": "用户 ID",
            "example": "u-100"
          },
          "amount": {
            "type": "string",
            "description": "金额，当前按字符串透传",
            "example": "9.99"
          },
          "currency": {
            "type": "string",
            "description": "币种",
            "example": "USD"
          },
          "pay_method": {
            "type": "string",
            "description": "支付方式",
            "example": "apple_pay"
          },
          "subject": {
            "type": "string",
            "description": "支付主题或商品描述",
            "example": "vip"
          }
        }
      },
      "PayResponseData": {
        "type": "object",
        "properties": {
          "payment_id": {
            "type": "string",
            "example": "pay-001"
          },
          "order_no": {
            "type": "string",
            "example": "order-001"
          },
          "user_id": {
            "type": "string",
            "example": "u-100"
          },
          "status": {
            "type": "string",
            "example": "processing"
          },
          "amount": {
            "type": "string",
            "example": "9.99"
          },
          "currency": {
            "type": "string",
            "example": "USD"
          },
          "pay_method": {
            "type": "string",
            "example": "apple_pay"
          },
          "subject": {
            "type": "string",
            "example": "vip"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-04-04T12:00:00Z"
          }
        }
      },
      "PaySuccessEnvelope": {
        "type": "object",
        "required": [
          "code",
          "message",
          "request_id",
          "data"
        ],
        "properties": {
          "code": {
            "type": "string",
            "example": "ok"
          },
          "message": {
            "type": "string",
            "example": "ok"
          },
          "request_id": {
            "type": "string",
            "example": "b31e6d8248775b9a"
          },
          "data": {
            "$ref": "#/components/schemas/PayResponseData"
          }
        }
      }
    }
  }
}