{
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "schemes": [
    "https"
  ],
  "swagger": "2.0",
  "info": {
    "title": "聚玩用户服务",
    "version": "1.0"
  },
  "basePath": "/",
  "paths": {
    "/api/v1/admin/verifications": {
      "get": {
        "produces": [
          "application/json"
        ],
        "schemes": [
          "https"
        ],
        "summary": "管理员获取认证申请列表 (分页)",
        "operationId": "verificationAdminGetVerifications",
        "parameters": [
          {
            "type": "integer",
            "default": 1,
            "example": 1,
            "name": "page",
            "in": "query",
            "required": true
          },
          {
            "type": "integer",
            "default": 20,
            "example": 20,
            "name": "size",
            "in": "query",
            "required": true
          },
          {
            "type": "string",
            "description": "筛选角色",
            "name": "role",
            "in": "query",
            "allowEmptyValue": true
          },
          {
            "type": "string",
            "description": "筛选状态，默认 pending",
            "name": "status",
            "in": "query",
            "allowEmptyValue": true
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "type": "object",
              "properties": {
                "list": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "id",
                      "userId",
                      "userNickname",
                      "role",
                      "status",
                      "materials",
                      "rejectReason",
                      "createdAt",
                      "reviewedAt"
                    ],
                    "properties": {
                      "createdAt": {
                        "description": "申请时间",
                        "type": "string"
                      },
                      "id": {
                        "description": "认证记录ID (主键，用于管理员操作)",
                        "type": "integer"
                      },
                      "materials": {
                        "description": "核心字段：对应 DB 的 JSONB",
                        "type": "object",
                        "additionalProperties": {
                          "type": "string"
                        }
                      },
                      "rejectReason": {
                        "description": "驳回原因",
                        "type": "string"
                      },
                      "reviewedAt": {
                        "description": "审核时间",
                        "type": "string"
                      },
                      "role": {
                        "description": "申请角色: player, owner",
                        "type": "string"
                      },
                      "status": {
                        "description": "pending, approved, rejected",
                        "type": "string"
                      },
                      "userId": {
                        "description": "申请人ID (外键)",
                        "type": "integer"
                      },
                      "userNickname": {
                        "description": "冗余显示，方便前端展示",
                        "type": "string"
                      }
                    }
                  }
                },
                "total": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/admin/verifications/{id}/approve": {
      "post": {
        "consumes": [
          "application/x-www-form-urlencoded"
        ],
        "produces": [
          "application/json"
        ],
        "schemes": [
          "https"
        ],
        "summary": "管理员通过申请",
        "operationId": "verificationAdminApproveVerification",
        "parameters": [
          {
            "type": "integer",
            "description": "注意：这是 user_verifications.id",
            "name": "id",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "type": "object"
            }
          }
        }
      }
    },
    "/api/v1/admin/verifications/{id}/reject": {
      "post": {
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "schemes": [
          "https"
        ],
        "summary": "管理员驳回申请",
        "operationId": "verificationAdminRejectVerification",
        "parameters": [
          {
            "type": "integer",
            "name": "id",
            "in": "path",
            "required": true
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "required": [
                "reason"
              ],
              "properties": {
                "reason": {
                  "description": "必填：驳回原因",
                  "type": "string"
                }
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "type": "object"
            }
          }
        }
      }
    },
    "/api/v1/auth/login": {
      "post": {
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "schemes": [
          "https"
        ],
        "summary": "用户登录",
        "operationId": "authLogin",
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "required": [
                "username",
                "password"
              ],
              "properties": {
                "password": {
                  "type": "string"
                },
                "phone": {
                  "description": "手机号登录",
                  "type": "string"
                },
                "remember": {
                  "type": "boolean"
                },
                "username": {
                  "description": "或用户名登录",
                  "type": "string"
                }
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "type": "object",
              "properties": {
                "user": {
                  "type": "object",
                  "required": [
                    "id",
                    "username",
                    "nickname",
                    "avatar",
                    "role",
                    "verifiedRoles",
                    "verificationStatus",
                    "phone",
                    "bio",
                    "createdAt"
                  ],
                  "properties": {
                    "avatar": {
                      "type": "string"
                    },
                    "bio": {
                      "type": "string"
                    },
                    "createdAt": {
                      "description": "ISO 8601",
                      "type": "string"
                    },
                    "id": {
                      "type": "string"
                    },
                    "nickname": {
                      "type": "string"
                    },
                    "phone": {
                      "type": "string"
                    },
                    "role": {
                      "description": "consumer, player, owner, admin",
                      "type": "string"
                    },
                    "username": {
                      "type": "string"
                    },
                    "verificationStatus": {
                      "description": "e.g. {\"player\": \"approved\"}",
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "verifiedRoles": {
                      "description": "e.g. [\"consumer\", \"player\"]",
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/logout": {
      "post": {
        "consumes": [
          "application/x-www-form-urlencoded"
        ],
        "produces": [
          "application/json"
        ],
        "schemes": [
          "https"
        ],
        "summary": "退出登录",
        "operationId": "authLogout",
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "type": "object"
            }
          }
        }
      }
    },
    "/api/v1/auth/register": {
      "post": {
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "schemes": [
          "https"
        ],
        "summary": "用户注册",
        "operationId": "authRegister",
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "required": [
                "email",
                "username",
                "password",
                "vcode"
              ],
              "properties": {
                "email": {
                  "type": "string"
                },
                "password": {
                  "type": "string"
                },
                "phone": {
                  "type": "string"
                },
                "username": {
                  "type": "string"
                },
                "vcode": {
                  "description": "验证码",
                  "type": "string"
                }
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "type": "object",
              "properties": {
                "user": {
                  "type": "object",
                  "required": [
                    "id",
                    "username",
                    "nickname",
                    "avatar",
                    "role",
                    "verifiedRoles",
                    "verificationStatus",
                    "phone",
                    "bio",
                    "createdAt"
                  ],
                  "properties": {
                    "avatar": {
                      "type": "string"
                    },
                    "bio": {
                      "type": "string"
                    },
                    "createdAt": {
                      "description": "ISO 8601",
                      "type": "string"
                    },
                    "id": {
                      "type": "string"
                    },
                    "nickname": {
                      "type": "string"
                    },
                    "phone": {
                      "type": "string"
                    },
                    "role": {
                      "description": "consumer, player, owner, admin",
                      "type": "string"
                    },
                    "username": {
                      "type": "string"
                    },
                    "verificationStatus": {
                      "description": "e.g. {\"player\": \"approved\"}",
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "verifiedRoles": {
                      "description": "e.g. [\"consumer\", \"player\"]",
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/reset-password": {
      "post": {
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "schemes": [
          "https"
        ],
        "summary": "重置密码",
        "operationId": "authResetPassword",
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "required": [
                "email",
                "vcode",
                "newPassword"
              ],
              "properties": {
                "email": {
                  "type": "string"
                },
                "newPassword": {
                  "type": "string"
                },
                "phone": {
                  "type": "string"
                },
                "vcode": {
                  "type": "string"
                }
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "type": "object"
            }
          }
        }
      }
    },
    "/api/v1/users/me": {
      "get": {
        "produces": [
          "application/json"
        ],
        "schemes": [
          "https"
        ],
        "summary": "获取当前登录用户信息",
        "operationId": "userGetMe",
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "type": "object",
              "properties": {
                "avatar": {
                  "type": "string"
                },
                "bio": {
                  "type": "string"
                },
                "createdAt": {
                  "description": "ISO 8601",
                  "type": "string"
                },
                "id": {
                  "type": "string"
                },
                "nickname": {
                  "type": "string"
                },
                "phone": {
                  "type": "string"
                },
                "role": {
                  "description": "consumer, player, owner, admin",
                  "type": "string"
                },
                "username": {
                  "type": "string"
                },
                "verificationStatus": {
                  "description": "e.g. {\"player\": \"approved\"}",
                  "type": "object",
                  "additionalProperties": {
                    "type": "string"
                  }
                },
                "verifiedRoles": {
                  "description": "e.g. [\"consumer\", \"player\"]",
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "put": {
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "schemes": [
          "https"
        ],
        "summary": "更新个人资料",
        "operationId": "userUpdateMe",
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "properties": {
                "avatar": {
                  "type": "string"
                },
                "bio": {
                  "type": "string"
                },
                "nickname": {
                  "type": "string"
                }
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "type": "object",
              "properties": {
                "avatar": {
                  "type": "string"
                },
                "bio": {
                  "type": "string"
                },
                "createdAt": {
                  "description": "ISO 8601",
                  "type": "string"
                },
                "id": {
                  "type": "string"
                },
                "nickname": {
                  "type": "string"
                },
                "phone": {
                  "type": "string"
                },
                "role": {
                  "description": "consumer, player, owner, admin",
                  "type": "string"
                },
                "username": {
                  "type": "string"
                },
                "verificationStatus": {
                  "description": "e.g. {\"player\": \"approved\"}",
                  "type": "object",
                  "additionalProperties": {
                    "type": "string"
                  }
                },
                "verifiedRoles": {
                  "description": "e.g. [\"consumer\", \"player\"]",
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/users/me/preferences/notifications": {
      "put": {
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "schemes": [
          "https"
        ],
        "summary": "更新通知偏好",
        "operationId": "userUpdateNotificationSettings",
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "properties": {
                "community": {
                  "type": "boolean"
                },
                "order": {
                  "type": "boolean"
                },
                "system": {
                  "type": "boolean"
                }
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "type": "object"
            }
          }
        }
      }
    },
    "/api/v1/users/me/preferences/theme": {
      "put": {
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "schemes": [
          "https"
        ],
        "summary": "更新主题偏好",
        "operationId": "userUpdateThemeSettings",
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "required": [
                "theme"
              ],
              "properties": {
                "theme": {
                  "description": "dark, light",
                  "type": "string"
                }
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "type": "object"
            }
          }
        }
      }
    },
    "/api/v1/users/me/switch-role": {
      "post": {
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "schemes": [
          "https"
        ],
        "summary": "切换当前激活角色",
        "operationId": "userSwitchRole",
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "required": [
                "role"
              ],
              "properties": {
                "role": {
                  "description": "目标角色",
                  "type": "string"
                }
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "type": "object"
            }
          }
        }
      }
    },
    "/api/v1/users/me/verification": {
      "get": {
        "produces": [
          "application/json"
        ],
        "schemes": [
          "https"
        ],
        "summary": "获取我的所有认证状态",
        "operationId": "verificationUserGetMyVerifications",
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "type": "object",
              "properties": {
                "list": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "id",
                      "userId",
                      "userNickname",
                      "role",
                      "status",
                      "materials",
                      "rejectReason",
                      "createdAt",
                      "reviewedAt"
                    ],
                    "properties": {
                      "createdAt": {
                        "description": "申请时间",
                        "type": "string"
                      },
                      "id": {
                        "description": "认证记录ID (主键，用于管理员操作)",
                        "type": "integer"
                      },
                      "materials": {
                        "description": "核心字段：对应 DB 的 JSONB",
                        "type": "object",
                        "additionalProperties": {
                          "type": "string"
                        }
                      },
                      "rejectReason": {
                        "description": "驳回原因",
                        "type": "string"
                      },
                      "reviewedAt": {
                        "description": "审核时间",
                        "type": "string"
                      },
                      "role": {
                        "description": "申请角色: player, owner",
                        "type": "string"
                      },
                      "status": {
                        "description": "pending, approved, rejected",
                        "type": "string"
                      },
                      "userId": {
                        "description": "申请人ID (外键)",
                        "type": "integer"
                      },
                      "userNickname": {
                        "description": "冗余显示，方便前端展示",
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "schemes": [
          "https"
        ],
        "summary": "提交或修改角色认证申请 (支持幂等更新)",
        "operationId": "verificationUserApplyVerification",
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "required": [
                "role",
                "materials"
              ],
              "properties": {
                "materials": {
                  "description": "证明材料键值对 {\"idCardFront\": \"http...\", \"license\": \"http...\"}",
                  "type": "object",
                  "required": [
                    "idCardFront",
                    "idCardBack"
                  ],
                  "properties": {
                    "gameScreenshots": {
                      "description": "游戏截图URL列表",
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "idCardBack": {
                      "description": "身份证反面照片URL",
                      "type": "string"
                    },
                    "idCardFront": {
                      "description": "身份证正面照片URL",
                      "type": "string"
                    },
                    "voiceDemo": {
                      "description": "语音认证示例URL",
                      "type": "string"
                    }
                  }
                },
                "role": {
                  "description": "申请什么角色",
                  "type": "string"
                }
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "type": "object"
            }
          }
        }
      }
    },
    "/api/v1/users/{id}": {
      "get": {
        "produces": [
          "application/json"
        ],
        "schemes": [
          "https"
        ],
        "summary": "获取指定用户信息",
        "operationId": "userGetUserInfo",
        "parameters": [
          {
            "type": "string",
            "name": "id",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "type": "object",
              "properties": {
                "avatar": {
                  "type": "string"
                },
                "bio": {
                  "type": "string"
                },
                "createdAt": {
                  "description": "ISO 8601",
                  "type": "string"
                },
                "id": {
                  "type": "string"
                },
                "nickname": {
                  "type": "string"
                },
                "phone": {
                  "type": "string"
                },
                "role": {
                  "description": "consumer, player, owner, admin",
                  "type": "string"
                },
                "username": {
                  "type": "string"
                },
                "verificationStatus": {
                  "description": "e.g. {\"player\": \"approved\"}",
                  "type": "object",
                  "additionalProperties": {
                    "type": "string"
                  }
                },
                "verifiedRoles": {
                  "description": "e.g. [\"consumer\", \"player\"]",
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/users/{id}/follow": {
      "post": {
        "consumes": [
          "application/x-www-form-urlencoded"
        ],
        "produces": [
          "application/json"
        ],
        "schemes": [
          "https"
        ],
        "summary": "关注用户",
        "operationId": "userFollowUser",
        "parameters": [
          {
            "type": "string",
            "name": "id",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "type": "object"
            }
          }
        }
      },
      "delete": {
        "consumes": [
          "application/x-www-form-urlencoded"
        ],
        "produces": [
          "application/json"
        ],
        "schemes": [
          "https"
        ],
        "summary": "取消关注用户",
        "operationId": "userUnfollowUser",
        "parameters": [
          {
            "type": "string",
            "name": "id",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "type": "object"
            }
          }
        }
      }
    }
  },
  "x-date": "2026-04-22 22:30:22",
  "x-description": "This is a goctl generated swagger file.",
  "x-github": "https://github.com/zeromicro/go-zero",
  "x-go-zero-doc": "https://go-zero.dev/",
  "x-goctl-version": "1.10.1"
}