hyapp-server/docs/openapi/wallet.swagger.yaml

swagger: "2.0"
info:
  title: HY Wallet Service API
  version: "1.0.0"
  description: |
    wallet-service 当前只暴露内部 gRPC + protobuf 接口，没有 HTTP JSON router。
    本文件用 OpenAPI 2.0 记录 gRPC 合约，`paths` 使用 gRPC full method 作为文档路径，不代表真实 HTTP endpoint。
host: localhost:13004
basePath: /
schemes:
  - http
consumes:
  - application/grpc+proto
produces:
  - application/grpc+proto
tags:
  - name: wallet
    description: WalletService，账务扣费接口；当前房间送礼由 room-service 同步调用。
  - name: health
    description: 标准 grpc.health.v1.Health。
responses:
  GRPCError:
    description: gRPC status error；稳定业务原因放在 google.rpc.ErrorInfo.reason。
    schema:
      $ref: "#/definitions/GRPCError"
paths:
  /hyapp.wallet.v1.WalletService/DebitGift:
    post:
      tags:
        - wallet
      summary: 送礼扣费
      operationId: walletDebitGift
      x-grpc-full-method: /hyapp.wallet.v1.WalletService/DebitGift
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/DebitGiftRequest"
      responses:
        "200":
          description: 扣费成功；重复 `command_id` 命中幂等时返回原始扣费回执。
          schema:
            $ref: "#/definitions/DebitGiftResponse"
        default:
          $ref: "#/responses/GRPCError"
  /grpc.health.v1.Health/Check:
    post:
      tags:
        - health
      summary: 标准 gRPC health check
      operationId: walletHealthCheck
      x-grpc-full-method: /grpc.health.v1.Health/Check
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/HealthCheckRequest"
      responses:
        "200":
          description: 标准 health check 响应。
          schema:
            $ref: "#/definitions/HealthCheckResponse"
        default:
          $ref: "#/responses/GRPCError"
  /grpc.health.v1.Health/Watch:
    post:
      tags:
        - health
      summary: 标准 gRPC health watch
      operationId: walletHealthWatch
      x-grpc-full-method: /grpc.health.v1.Health/Watch
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/HealthCheckRequest"
      responses:
        "200":
          description: 标准 health watch 流式响应；OpenAPI 只记录单条消息结构。
          schema:
            $ref: "#/definitions/HealthCheckResponse"
        default:
          $ref: "#/responses/GRPCError"
definitions:
  DebitGiftRequest:
    type: object
    required:
      - command_id
      - room_id
      - sender_user_id
      - target_user_id
      - gift_id
      - gift_count
    properties:
      command_id:
        type: string
        description: 账务幂等键；room-service 传入房间命令 `command_id`。
      room_id:
        type: string
        description: 礼物发生的房间 ID。
      sender_user_id:
        type: integer
        format: int64
        description: 扣费用户。
      target_user_id:
        type: integer
        format: int64
        description: 礼物接收用户。
      gift_id:
        type: string
      gift_count:
        type: integer
        format: int32
        minimum: 1
      price_version:
        type: string
        description: 指定礼物价格版本；为空时使用当前生效价格。
      region_id:
        type: integer
        format: int64
        description: 房间 visible_region_id，用于校验礼物区域可用性。
  DebitGiftResponse:
    type: object
    properties:
      billing_receipt_id:
        type: string
        description: 扣费回执 ID，room-service 会写入房间礼物事件。
      transaction_id:
        type: string
        description: 钱包交易 ID。
      coin_spent:
        type: integer
        format: int64
        description: 兼容旧调用方的扣费数量；新调用方应优先读取 charge_asset_type 和 charge_amount。
      charge_asset_type:
        type: string
        enum:
          - COIN
          - DIAMOND
        description: 本次实际扣减的资产类型。
      charge_amount:
        type: integer
        format: int64
        description: 本次实际扣减的资产数量。
      gift_point_added:
        type: integer
        format: int64
        description: 本次实际增加的 GIFT_POINT 数量。
      heat_value:
        type: integer
        format: int64
        description: room-service 用于房间热度和榜单的结算值。
      price_version:
        type: string
        description: 本次命中的服务端价格版本。
      balance_after:
        type: integer
        format: int64
        description: 扣费后的发送方被扣费资产余额。
  HealthCheckRequest:
    type: object
    properties:
      service:
        type: string
        description: gRPC health service name；wallet-service 使用 `wallet-service`。
  HealthCheckResponse:
    type: object
    properties:
      status:
        type: string
        enum:
          - UNKNOWN
          - SERVING
          - NOT_SERVING
          - SERVICE_UNKNOWN
  GRPCError:
    type: object
    properties:
      code:
        type: string
        description: gRPC status code，例如 INVALID_ARGUMENT、FAILED_PRECONDITION、UNAVAILABLE。
      message:
        type: string
      error_info_reason:
        type: string
        description: google.rpc.ErrorInfo.reason；账务常见值包括 INSUFFICIENT_BALANCE、DUPLICATE_BILLING_COMMAND、LEDGER_CONFLICT。