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

swagger: "2.0"
info:
  title: HY Activity Service API
  version: "1.0.0"
  description: |
    activity-service 当前只暴露内部 gRPC + protobuf 同步查询接口，没有 HTTP JSON router。
    房间事件消费通过 consumer 边界接入，不伪装成同步 RPC。
    本文件用 OpenAPI 2.0 记录 gRPC 合约，`paths` 使用 gRPC full method 作为文档路径，不代表真实 HTTP endpoint。
host: localhost:13006
basePath: /
schemes:
  - http
consumes:
  - application/grpc+proto
produces:
  - application/grpc+proto
tags:
  - name: activity
    description: ActivityService，活动服务同步查询接口。
  - name: health
    description: 标准 grpc.health.v1.Health。
responses:
  GRPCError:
    description: gRPC status error；稳定业务原因放在 google.rpc.ErrorInfo.reason。
    schema:
      $ref: "#/definitions/GRPCError"
paths:
  /hyapp.activity.v1.ActivityService/PingActivity:
    post:
      tags:
        - activity
      summary: 活动服务连通性探测
      operationId: activityPingActivity
      x-grpc-full-method: /hyapp.activity.v1.ActivityService/PingActivity
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/PingActivityRequest"
      responses:
        "200":
          description: 服务当前可接受同步 RPC。
          schema:
            $ref: "#/definitions/PingActivityResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.activity.v1.ActivityService/GetActivityStatus:
    post:
      tags:
        - activity
      summary: 查询活动状态
      operationId: activityGetActivityStatus
      x-grpc-full-method: /hyapp.activity.v1.ActivityService/GetActivityStatus
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/GetActivityStatusRequest"
      responses:
        "200":
          description: 查询成功。
          schema:
            $ref: "#/definitions/GetActivityStatusResponse"
        default:
          $ref: "#/responses/GRPCError"
  /grpc.health.v1.Health/Check:
    post:
      tags:
        - health
      summary: 标准 gRPC health check
      operationId: activityHealthCheck
      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: activityHealthWatch
      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:
  RequestMeta:
    type: object
    properties:
      request_id:
        type: string
        description: 链路追踪 ID，不作为幂等键。
      caller:
        type: string
      gateway_node_id:
        type: string
      sent_at_ms:
        type: integer
        format: int64
  PingActivityRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
  PingActivityResponse:
    type: object
    properties:
      ok:
        type: boolean
      node_id:
        type: string
  GetActivityStatusRequest:
    type: object
    required:
      - activity_id
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      activity_id:
        type: string
  GetActivityStatusResponse:
    type: object
    properties:
      activity_id:
        type: string
      status:
        type: string
        description: 当前活动状态；具体业务活动会扩展自己的状态枚举。
  HealthCheckRequest:
    type: object
    properties:
      service:
        type: string
        description: gRPC health service name；activity-service 使用 `activity-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、NOT_FOUND、UNAVAILABLE。
      message:
        type: string
      error_info_reason:
        type: string
        description: google.rpc.ErrorInfo.reason；活动常见值包括 RULE_NOT_ACTIVE、EVENT_ALREADY_CONSUMED、REWARD_PENDING。