lawless/api/openapi.yaml

openapi: 3.0.0
info:
  title: 洪荒大陆挂机手游 API
  description: 基于 TDD-05 的 RESTful 接口定义（OpenAPI 3.0）
  version: 1.0.0
  contact:
    name: 洪荒大陆服务端团队
servers:
  - url: https://api.honghuang.example.com
    description: 生产网关
  - url: https://api-test.honghuang.example.com
    description: 测试网关

security:
  - bearerAuth: []

paths:
  /api/v1/auth/register:
    post:
      tags: [Auth]
      summary: 注册（公开）
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResp'

  /api/v1/auth/login:
    post:
      tags: [Auth]
      summary: 登录（公开）
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResp'

  /api/v1/characters:
    post:
      tags: [Character]
      summary: 创建角色
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCharacterReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CharacterResp'

  /api/v1/characters/{character_id}:
    get:
      tags: [Character]
      summary: 获取角色状态
      parameters:
        - name: character_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: with_snapshot
          in: query
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CharacterResp'

  /api/v1/characters/{character_id}/realm:
    get:
      tags: [Realm]
      summary: 获取境界进度
      parameters:
        - name: character_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealmProgressResp'

  /api/v1/characters/{character_id}/realm/breakthrough:
    post:
      tags: [Realm]
      summary: 尝试突破
      parameters:
        - name: character_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BreakthroughReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BreakthroughResp'

  /api/v1/characters/{character_id}/realm/tribulation:
    post:
      tags: [Realm]
      summary: 发起渡劫
      parameters:
        - name: character_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TribulationReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TribulationResp'
    get:
      tags: [Realm]
      summary: 查询渡劫结果
      parameters:
        - name: character_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TribulationResp'

  /api/v1/characters/{character_id}/realm/world-break:
    post:
      tags: [Realm]
      summary: 破界（晋级新世界）
      parameters:
        - name: character_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorldBreakReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorldBreakResp'

  /api/v1/combats:
    post:
      tags: [Battle]
      summary: 发起战斗
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartCombatReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CombatResp'

  /api/v1/combats/{battle_id}:
    get:
      tags: [Battle]
      summary: 查询战报
      parameters:
        - name: battle_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BattleReportResp'

  /api/v1/combats/pvp:
    post:
      tags: [Battle]
      summary: PVP 挑战
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PvpChallengeReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CombatResp'

  /api/v1/characters/{character_id}/manuals:
    get:
      tags: [Manual]
      summary: 获取功法列表
      parameters:
        - name: character_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: is_buffing
          in: query
          schema:
            type: boolean
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: page_size
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManualListResp'

  /api/v1/characters/{character_id}/manuals/{manual_instance_id}/upgrade:
    post:
      tags: [Manual]
      summary: 功法升层
      parameters:
        - name: character_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: manual_instance_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpgradeManualReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManualResp'

  /api/v1/characters/{character_id}/manuals/{manual_instance_id}/buff:
    post:
      tags: [Manual]
      summary: 设置加持功法
      parameters:
        - name: character_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: manual_instance_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuffManualReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuffSlotResp'

  /api/v1/characters/{character_id}/skills/learn:
    post:
      tags: [Skill]
      summary: 学习技能
      parameters:
        - name: character_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LearnSkillReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillResp'

  /api/v1/characters/{character_id}/skills/{skill_instance_id}/jade-slip:
    post:
      tags: [Skill]
      summary: 生成功法玉简
      parameters:
        - name: character_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: skill_instance_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JadeSlipReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemResp'

  /api/v1/characters/{character_id}/currencies:
    get:
      tags: [Economy]
      summary: 获取货币余额
      parameters:
        - name: character_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrencyBalancesResp'

  /api/v1/market/orders:
    post:
      tags: [Economy]
      summary: 交易行挂单
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarketOrderReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketOrderResp'

  /api/v1/market/orders/{order_id}:
    delete:
      tags: [Economy]
      summary: 交易行撤单
      parameters:
        - name: order_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketOrderResp'

  /api/v1/market/orders/{order_id}/buy:
    post:
      tags: [Economy]
      summary: 交易行购买
      parameters:
        - name: order_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuyOrderReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeResp'

  /api/v1/auctions:
    get:
      tags: [Economy]
      summary: 查询拍卖列表
      parameters:
        - name: world_tier
          in: query
          schema:
            type: integer
        - name: auction_type
          in: query
          schema:
            type: string
        - name: category
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuctionListResp'

  /api/v1/auctions/{auction_id}/bids:
    post:
      tags: [Economy]
      summary: 拍卖出价
      parameters:
        - name: auction_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BidReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BidResp'

  /api/v1/intelligence:
    get:
      tags: [Economy]
      summary: 查询天机阁情报
      parameters:
        - name: intel_type
          in: query
          schema:
            type: string
        - name: target_world_tier
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntelListResp'

  /api/v1/intelligence/{order_id}/buy:
    post:
      tags: [Economy]
      summary: 购买情报
      parameters:
        - name: order_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntelBuffResp'

  /api/v1/guilds:
    post:
      tags: [Social]
      summary: 创建组织
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrgReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgResp'

  /api/v1/guilds/{guild_id}:
    get:
      tags: [Social]
      summary: 获取组织信息
      parameters:
        - name: guild_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgResp'

  /api/v1/guilds/{guild_id}/members:
    post:
      tags: [Social]
      summary: 加入组织
      parameters:
        - name: guild_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgMemberResp'

  /api/v1/guilds/{guild_id}/members/me:
    delete:
      tags: [Social]
      summary: 退出组织
      parameters:
        - name: guild_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgMemberResp'

  /api/v1/guilds/{guild_id}/members/{character_id}:
    put:
      tags: [Social]
      summary: 管理成员权限
      parameters:
        - name: guild_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: character_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRoleReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgMemberResp'

  /api/v1/relations/{relation_type}/requests:
    post:
      tags: [Social]
      summary: 发起关系请求
      parameters:
        - name: relation_type
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RelationReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelationResp'

  /api/v1/relations/{relation_type}/requests/{request_id}/respond:
    post:
      tags: [Social]
      summary: 响应关系请求
      parameters:
        - name: relation_type
          in: path
          required: true
          schema:
            type: string
        - name: request_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RelationResponseReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelationResp'

  /api/v1/contracts:
    post:
      tags: [Social]
      summary: 发布佣兵委托
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishContractReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractResp'

  /api/v1/contracts/{contract_id}/accept:
    post:
      tags: [Social]
      summary: 接取佣兵委托
      parameters:
        - name: contract_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptContractReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractResp'

  /api/v1/bounties:
    post:
      tags: [Social]
      summary: 发布悬赏
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishBountyReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BountyResp'

  /api/v1/bounties/{bounty_id}/accept:
    post:
      tags: [Social]
      summary: 接取悬赏
      parameters:
        - name: bounty_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BountyResp'

  /api/v1/world/regions/{region_id}:
    get:
      tags: [Map]
      summary: 获取区域信息
      parameters:
        - name: region_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionResp'

  /api/v1/world/regions/{region_id}/nearby:
    get:
      tags: [Map]
      summary: 查询附近玩家与事件
      parameters:
        - name: region_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          schema:
            type: integer
            default: 30
        - name: event_types
          in: query
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NearbyResp'

  /api/v1/instances/{instance_id}/enter:
    post:
      tags: [Map]
      summary: 进入副本/遗迹
      parameters:
        - name: instance_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnterInstanceReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceRunResp'

  /api/v1/world/events:
    get:
      tags: [Map]
      summary: 查询世界事件
      parameters:
        - name: world_tier
          in: query
          schema:
            type: integer
        - name: region_id
          in: query
          schema:
            type: string
            format: uuid
        - name: event_scope
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorldEventListResp'
    post:
      tags: [Map]
      summary: 发起玩家事件
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlayerEventReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorldEventResp'

  /api/v1/disciples/{disciple_id}/dispatch:
    post:
      tags: [Disciple]
      summary: 派遣弟子
      parameters:
        - name: disciple_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DispatchReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscipleMissionResp'

  /api/v1/missions/{mission_id}/claim:
    post:
      tags: [Disciple]
      summary: 领取弟子/领地产出
      parameters:
        - name: mission_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MissionRewardResp'

  /api/v1/guilds/{guild_id}/territories/bids:
    post:
      tags: [Disciple]
      summary: 帮派领地竞标
      parameters:
        - name: guild_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TerritoryBidReq'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TerritoryBidResp'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "Nakama 颁发的 session token，格式 Authorization: Bearer <token>"

  schemas:
    CommonResp:
      type: object
      required: [code, message, trace_id]
      properties:
        code:
          type: integer
          description: 业务状态码，0 为成功
        message:
          type: string
        trace_id:
          type: string
          format: uuid

    RegisterReq:
      type: object
      required: [device_id, platform]
      properties:
        device_id:
          type: string
        platform:
          type: string
          enum: [ios, android, harmony, guest]
        invite_code:
          type: string

    LoginReq:
      type: object
      required: [device_id, platform]
      properties:
        device_id:
          type: string
        platform:
          type: string
        refresh_token:
          type: string

    AuthResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                player_id:
                  type: string
                nakama_token:
                  type: string
                expires_at:
                  type: string
                  format: date-time
                is_new:
                  type: boolean

    CreateCharacterReq:
      type: object
      required: [name, race_id]
      properties:
        name:
          type: string
        race_id:
          type: string
        birth_world_tier:
          type: integer

    CharacterResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                character_id:
                  type: string
                player_id:
                  type: string
                name:
                  type: string
                race_id:
                  type: string
                world_tier:
                  type: integer
                realm_tier:
                  type: integer
                minor_realm:
                  type: integer
                realm_status:
                  type: string
                level:
                  type: integer
                exp:
                  type: integer
                  format: int64
                status:
                  type: string
                base_stats:
                  type: object
                battle_stats:
                  type: object
                san_current:
                  type: integer
                san_max:
                  type: integer
                crime_score:
                  type: integer
                reputation_score:
                  type: integer
                last_online_at:
                  type: string
                  format: date-time
                created_at:
                  type: string
                  format: date-time

    RealmProgressResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                realm_tier:
                  type: integer
                minor_realm:
                  type: integer
                realm_name:
                  type: string
                exp:
                  type: integer
                  format: int64
                exp_to_next:
                  type: integer
                  format: int64
                max_unlocked_world_tier:
                  type: integer
                realm_status:
                  type: string
                breakthrough_ready:
                  type: boolean
                tribulation_pending:
                  type: boolean

    BreakthroughReq:
      type: object
      required: [target_minor_realm, idempotency_key]
      properties:
        target_minor_realm:
          type: integer
        consumables:
          type: array
          items:
            $ref: '#/components/schemas/MaterialCost'
        helper_ids:
          type: array
          items:
            type: string
            format: uuid
        idempotency_key:
          type: string

    BreakthroughResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                success:
                  type: boolean
                from:
                  $ref: '#/components/schemas/RealmPoint'
                to:
                  $ref: '#/components/schemas/RealmPoint'
                exp_consumed:
                  type: integer
                  format: int64
                record_id:
                  type: string
                special_event:
                  type: string

    TribulationReq:
      type: object
      required: [target_realm_tier]
      properties:
        target_realm_tier:
          type: integer
        tribulation_type:
          type: string
        consumables:
          type: array
          items:
            $ref: '#/components/schemas/MaterialCost'
        helper_ids:
          type: array
          items:
            type: string
            format: uuid

    TribulationResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                tribulation_id:
                  type: string
                status:
                  type: string
                base_success_rate:
                  type: number
                modified_success_rate:
                  type: number
                estimated_ticks:
                  type: integer
                start_at:
                  type: string
                  format: date-time
                result:
                  type: string
                from_realm_tier:
                  type: integer
                to_realm_tier:
                  type: integer
                penalties:
                  type: object
                drops:
                  type: array
                  items:
                    $ref: '#/components/schemas/ItemAmount'

    WorldBreakReq:
      type: object
      required: [target_world_tier, confirm]
      properties:
        target_world_tier:
          type: integer
        key_item_instance_id:
          type: string
          format: uuid
        confirm:
          type: boolean

    WorldBreakResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                success:
                  type: boolean
                from_world_tier:
                  type: integer
                to_world_tier:
                  type: integer
                from_realm_tier:
                  type: integer
                to_realm_tier:
                  type: integer
                breakthrough_record_id:
                  type: string
                world_event:
                  type: string
                ruin_generated:
                  type: boolean

    StartCombatReq:
      type: object
      required: [battle_type, context_id]
      properties:
        battle_type:
          type: string
        context_id:
          type: string
          format: uuid
        party_members:
          type: array
          items:
            type: string
            format: uuid
        preferred_skills:
          type: array
          items:
            type: string
            format: uuid

    PvpChallengeReq:
      type: object
      required: [target_character_id]
      properties:
        target_character_id:
          type: string
          format: uuid
        bounty_id:
          type: string
          format: uuid
        use_paid_chance:
          type: boolean

    CombatResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                battle_id:
                  type: string
                status:
                  type: string
                result_summary:
                  type: object
                drops:
                  type: object
                death_penalty_applied:
                  type: boolean
                honor_points:
                  type: integer
                daily_pvp_count:
                  type: integer
                daily_pvp_limit:
                  type: integer

    BattleReportResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                battle_id:
                  type: string
                type:
                  type: string
                realm_tier:
                  type: integer
                game_timestamp:
                  type: string
                  format: date-time
                attacker:
                  type: object
                defender:
                  type: object
                rounds:
                  type: array
                  items:
                    type: object
                result:
                  type: object
                special_events:
                  type: array
                  items:
                    type: object

    ManualListResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                total:
                  type: integer
                list:
                  type: array
                  items:
                    $ref: '#/components/schemas/ManualItem'

    ManualItem:
      type: object
      properties:
        manual_instance_id:
          type: string
        manual_id:
          type: string
        name:
          type: string
        current_layer:
          type: integer
        max_layer:
          type: integer
        proficiency:
          type: integer
        is_main:
          type: boolean
        is_buffing:
          type: boolean
        domain:
          type: string
        element:
          type: string
        source_tag:
          type: string

    UpgradeManualReq:
      type: object
      required: [materials, idempotency_key]
      properties:
        materials:
          type: array
          items:
            $ref: '#/components/schemas/MaterialCost'
        use_insight_item:
          type: boolean
        idempotency_key:
          type: string

    ManualResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                manual_instance_id:
                  type: string
                old_layer:
                  type: integer
                new_layer:
                  type: integer
                success:
                  type: boolean
                proficiency_left:
                  type: integer
                unlocked_skill:
                  $ref: '#/components/schemas/ItemAmount'

    BuffManualReq:
      type: object
      required: [slot_index]
      properties:
        slot_index:
          type: integer
        unset_others:
          type: boolean

    BuffSlotResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                slot_index:
                  type: integer
                manual_instance_id:
                  type: string
                buff_speed_bonus:
                  type: number
                breakin_until:
                  type: string
                  format: date-time

    LearnSkillReq:
      type: object
      required: [source_type, source_id]
      properties:
        source_type:
          type: string
        source_id:
          type: string
        custom_name:
          type: string

    SkillResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                skill_instance_id:
                  type: string
                skill_id:
                  type: string
                name:
                  type: string
                source_tag:
                  type: string
                can_copy_to_jade_slip:
                  type: boolean
                proficiency:
                  type: integer
                instance_data:
                  type: object

    JadeSlipReq:
      type: object
      required: [consume_proficiency]
      properties:
        consume_proficiency:
          type: boolean
        copy_count:
          type: integer

    ItemResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                inventory_id:
                  type: string
                item_id:
                  type: string
                name:
                  type: string
                quantity:
                  type: integer
                instance_data:
                  type: object
                proficiency_consumed:
                  type: integer

    CurrencyBalancesResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                balances:
                  type: array
                  items:
                    $ref: '#/components/schemas/CurrencyBalance'

    CurrencyBalance:
      type: object
      properties:
        currency_code:
          type: string
        amount:
          type: string
        total_earned:
          type: string
        total_spent:
          type: string

    MarketOrderReq:
      type: object
      required: [inventory_id, currency_code, unit_price, quantity]
      properties:
        inventory_id:
          type: string
          format: uuid
        currency_code:
          type: string
        unit_price:
          type: string
        quantity:
          type: integer
        duration_hours:
          type: integer

    MarketOrderResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                order_id:
                  type: string
                status:
                  type: string
                listed_at:
                  type: string
                  format: date-time
                expired_at:
                  type: string
                  format: date-time
                tax_rate:
                  type: number

    BuyOrderReq:
      type: object
      required: [quantity]
      properties:
        quantity:
          type: integer

    TradeResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                trade_id:
                  type: string
                order_id:
                  type: string
                quantity:
                  type: integer
                total_price:
                  type: string
                tax:
                  type: string
                currency_code:
                  type: string
                items:
                  type: array
                  items:
                    $ref: '#/components/schemas/ItemAmount'

    AuctionListResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                total:
                  type: integer
                list:
                  type: array
                  items:
                    $ref: '#/components/schemas/AuctionItem'

    AuctionItem:
      type: object
      properties:
        auction_id:
          type: string
        seller_id:
          type: string
        item_id:
          type: string
        category:
          type: string
        currency_code:
          type: string
        start_price:
          type: string
        status:
          type: string
        started_at:
          type: string
          format: date-time
        ended_at:
          type: string
          format: date-time

    BidReq:
      type: object
      required: [amount]
      properties:
        amount:
          type: string
        is_auto_bid:
          type: boolean
        auto_max_amount:
          type: string

    BidResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                bid_id:
                  type: string
                auction_id:
                  type: string
                amount:
                  type: string
                deposit_paid:
                  type: string
                is_auto_bid:
                  type: boolean
                bid_at:
                  type: string
                  format: date-time

    IntelListResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                total:
                  type: integer
                list:
                  type: array
                  items:
                    $ref: '#/components/schemas/IntelItem'

    IntelItem:
      type: object
      properties:
        order_id:
          type: string
        seller_id:
          type: string
        intel_type:
          type: string
        target_world_tier:
          type: integer
        content_summary:
          type: string
        currency_code:
          type: string
        price:
          type: string
        purchase_count:
          type: integer
        max_purchase:
          type: integer

    IntelBuffResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                buff_id:
                  type: string
                order_id:
                  type: string
                detail_data:
                  type: object
                expires_at:
                  type: string
                  format: date-time

    CreateOrgReq:
      type: object
      required: [org_type, name]
      properties:
        org_type:
          type: string
        name:
          type: string
        region_id:
          type: string
          format: uuid
        founding_members:
          type: array
          items:
            type: string
            format: uuid

    OrgResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                guild_id:
                  type: string
                name:
                  type: string
                org_type:
                  type: string
                leader_id:
                  type: string
                level:
                  type: integer
                member_limit:
                  type: integer
                created_at:
                  type: string
                  format: date-time

    UpdateRoleReq:
      type: object
      required: [role, action]
      properties:
        role:
          type: string
        action:
          type: string

    OrgMemberResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                guild_id:
                  type: string
                character_id:
                  type: string
                role:
                  type: string
                joined_at:
                  type: string
                  format: date-time

    RelationReq:
      type: object
      required: [target_character_id]
      properties:
        target_character_id:
          type: string
          format: uuid
        vow_path:
          type: string

    RelationResponseReq:
      type: object
      required: [action]
      properties:
        action:
          type: string

    RelationResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                request_id:
                  type: string
                relation_type:
                  type: string
                from_character_id:
                  type: string
                to_character_id:
                  type: string
                status:
                  type: string

    PublishContractReq:
      type: object
      required: [contract_type, difficulty, currency_code, base_reward]
      properties:
        contract_type:
          type: string
        difficulty:
          type: integer
        currency_code:
          type: string
        base_reward:
          type: string
        target_params:
          type: object
        valid_until:
          type: string
          format: date-time

    AcceptContractReq:
      type: object
      required: [accept_type]
      properties:
        accept_type:
          type: string
        disciple_id:
          type: string
          format: uuid
        party_members:
          type: array
          items:
            type: string
            format: uuid

    ContractResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                contract_id:
                  type: string
                contract_type:
                  type: string
                status:
                  type: string
                publisher_id:
                  type: string
                base_reward:
                  type: string
                currency_code:
                  type: string
                valid_until:
                  type: string
                  format: date-time

    PublishBountyReq:
      type: object
      required: [bounty_type, target_character_id, reward_amount, currency_code]
      properties:
        bounty_type:
          type: string
        target_character_id:
          type: string
          format: uuid
        reward_amount:
          type: string
        currency_code:
          type: string
        valid_days:
          type: integer
        is_anonymous:
          type: boolean

    BountyResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                bounty_id:
                  type: string
                bounty_type:
                  type: string
                target_id:
                  type: string
                reward_amount:
                  type: string
                status:
                  type: string
                valid_until:
                  type: string
                  format: date-time

    RegionResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                region_id:
                  type: string
                world_tier:
                  type: integer
                name:
                  type: string
                is_safe_zone:
                  type: boolean
                pvp_rules:
                  type: object
                weather:
                  type: string
                resource_density:
                  type: integer
                danger_level:
                  type: integer
                nearby_player_count:
                  type: integer

    NearbyResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                players:
                  type: array
                  items:
                    type: object
                events:
                  type: array
                  items:
                    type: object

    EnterInstanceReq:
      type: object
      properties:
        party_members:
          type: array
          items:
            type: string
            format: uuid
        consumable_key_id:
          type: string
          format: uuid
        use_stamina:
          type: boolean

    InstanceRunResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                run_id:
                  type: string
                instance_id:
                  type: string
                status:
                  type: string
                difficulty_coefficient:
                  type: number
                consumed_keys:
                  type: integer
                started_at:
                  type: string
                  format: date-time

    WorldEventListResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                total:
                  type: integer
                list:
                  type: array
                  items:
                    $ref: '#/components/schemas/WorldEventItem'

    WorldEventItem:
      type: object
      properties:
        event_id:
          type: string
        event_type:
          type: string
        world_tier:
          type: integer
        region_id:
          type: string
        title:
          type: string
        content:
          type: string
        expires_at:
          type: string
          format: date-time

    PlayerEventReq:
      type: object
      required: [event_type, region_id]
      properties:
        event_type:
          type: string
        region_id:
          type: string
          format: uuid
        cost_items:
          type: array
          items:
            $ref: '#/components/schemas/MaterialCost'
        description:
          type: string

    WorldEventResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                event_id:
                  type: string
                event_type:
                  type: string
                status:
                  type: string
                created_at:
                  type: string
                  format: date-time

    DispatchReq:
      type: object
      required: [target_type, target_id, duration_minutes]
      properties:
        target_type:
          type: string
        target_id:
          type: string
          format: uuid
        duration_minutes:
          type: integer
        insurance_item_id:
          type: string
          format: uuid

    DiscipleMissionResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                mission_id:
                  type: string
                disciple_id:
                  type: string
                target_type:
                  type: string
                started_at:
                  type: string
                  format: date-time
                ended_at:
                  type: string
                  format: date-time
                status:
                  type: string

    MissionRewardResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                mission_id:
                  type: string
                result:
                  type: string
                rewards:
                  type: object

    TerritoryBidReq:
      type: object
      required: [territory_id, bid_amount]
      properties:
        territory_id:
          type: string
          format: uuid
        bid_amount:
          type: string
        is_renewal:
          type: boolean

    TerritoryBidResp:
      allOf:
        - $ref: '#/components/schemas/CommonResp'
        - type: object
          properties:
            data:
              type: object
              properties:
                bid_id:
                  type: string
                territory_id:
                  type: string
                bid_amount:
                  type: string
                deposit_locked:
                  type: string
                window_end_at:
                  type: string
                  format: date-time

    MaterialCost:
      type: object
      required: [inventory_id, quantity]
      properties:
        inventory_id:
          type: string
          format: uuid
        quantity:
          type: integer

    RealmPoint:
      type: object
      properties:
        realm_tier:
          type: integer
        minor_realm:
          type: integer

    ItemAmount:
      type: object
      properties:
        inventory_id:
          type: string
        item_id:
          type: string
        quantity:
          type: integer