# nearcade

## API Docs
- 根目录 > clubs [获取社团列表 / Get clubs](https://docs-nearcade.phizone.cn/469165942e0.md): 按关键词和大学筛选社团列表，并返回大学筛选项。
- 根目录 > clubs [获取社团详情 / Get club details](https://docs-nearcade.phizone.cn/469165943e0.md): 获取社团详情、成员摘要、收藏店铺以及当前用户权限。
- 根目录 > clubs [获取社团收藏店铺 / Get club arcades](https://docs-nearcade.phizone.cn/469165944e0.md): 分页获取社团收藏的店铺列表。
- 根目录 > clubs [上传社团头像 / Upload club avatar](https://docs-nearcade.phizone.cn/469165945e0.md): 上传社团头像，并以 NDJSON 事件流返回上传进度与结果。
- 根目录 > clubs [获取社团成员 / Get club members](https://docs-nearcade.phizone.cn/469165946e0.md): 分页获取社团成员列表。未公开大学信息的用户会根据查看者权限被过滤。
- 根目录 > clubs [获取社团帖子 / Get club posts](https://docs-nearcade.phizone.cn/469165947e0.md): 获取社团帖子列表，并按帖子可见性过滤当前用户不可见的帖子。
- 根目录 > clubs [创建社团帖子 / Create club post](https://docs-nearcade.phizone.cn/469165948e0.md): 在社团下创建帖子，可附带图片并指定帖子可见性。
- 根目录 > comments [更新评论。 / Update a comment.](https://docs-nearcade.phizone.cn/469165949e0.md): 更新当前用户自己的评论内容和附图。
- 根目录 > comments [删除评论。 / Delete a comment.](https://docs-nearcade.phizone.cn/469165950e0.md): 删除指定评论及其直接回复，并清理关联图片与投票。
- 根目录 > comments [对评论投票。 / Vote on a comment.](https://docs-nearcade.phizone.cn/469165951e0.md): 对评论投赞成或反对票；重复提交相同投票会撤销该投票。
- 根目录 > discover [获取附近店铺 / Discover nearby shops](https://docs-nearcade.phizone.cn/469165952e0.md): 获取原点附近的店铺，可选择是否包含在勤人数和计算得出的营业时间信息。`radius` 同时表示出行时间预算：每个距离档位都对应一个通常所需的出行时间，服务端据此为每家店铺计算最快的到达方式（步行 / 骑行 / 地铁），因此地铁可达的店铺可能超出半径范围——结果始终按出行时间排序，并按 `limit` 截断。当地铁数据可用时（原点 3 km 内有运营车站），响应还会附带 `metro` 行程块：包含最快方式为地铁的店铺的完整行程（乘车站序、官方线路色与短号），浏览器可直接渲染，无需额外请求。注意：`limit=150` 且命中较多地铁行程时响应可达约 270 KB（gzip 后约 90 KB）。
- 根目录 > images [上传图片资源。 / Upload an image asset.](https://docs-nearcade.phizone.cn/469165953e0.md): 上传一张图片，并可选地将其关联到店铺、评论、帖子、删除申请或草稿上下文；响应为 NDJSON 事件流。事件类型为 `uploading`（进度）、`done`（完成）或 `error`（失败）。
- 根目录 > images [删除图片资源。 / Delete an image asset.](https://docs-nearcade.phizone.cn/469165954e0.md): 删除指定图片资源，并同步清理其与所属实体的关联。
- 根目录 > posts [获取公告列表。 / List announcements.](https://docs-nearcade.phizone.cn/520510246e0.md): 获取已发布的全站公告，并返回当前访问者的未读数量。
- 根目录 > posts [创建公告。 / Create announcement.](https://docs-nearcade.phizone.cn/520510247e0.md): 站点管理员创建全站公告。公告不支持表态。
- 根目录 > posts [更新公告已读状态。 / Update announcement read state.](https://docs-nearcade.phizone.cn/520510248e0.md): 为登录用户持久化已读水位，或为访客写入仅包含已读水位的 Cookie。
- 根目录 > posts [获取帖子详情。 / Get post details.](https://docs-nearcade.phizone.cn/469165956e0.md): 获取帖子详情、评论列表，以及当前用户对帖子的投票状态。
- 根目录 > posts [更新帖子。 / Update post.](https://docs-nearcade.phizone.cn/469165957e0.md): 更新帖子内容、图片、可见性，或管理置顶与锁定状态。
- 根目录 > posts [删除帖子。 / Delete post.](https://docs-nearcade.phizone.cn/469165958e0.md): 删除帖子及其关联评论与投票。
- 根目录 > posts [发表评论到帖子。 / Post a comment.](https://docs-nearcade.phizone.cn/469165959e0.md): 向帖子发表评论或回复，可附带图片。
- 根目录 > posts [更新公告。 / Update announcement.](https://docs-nearcade.phizone.cn/528343002e0.md): 更新公告的标题、内容、图片、发布状态与过期时间。
- 根目录 > posts [为帖子投票。 / Vote on a post.](https://docs-nearcade.phizone.cn/469165960e0.md): 对帖子点赞或点踩；重复提交相同投票会撤销该投票。
- 根目录 > posts [删除公告。 / Delete announcement.](https://docs-nearcade.phizone.cn/528343003e0.md): 删除公告及其关联图片。
- 根目录 > shops [获取店铺列表。 / List shops.](https://docs-nearcade.phizone.cn/469165961e0.md): 获取分页店铺列表。支持查询字符串，并可选择是否包含计算得出的时区与营业状态。
- 根目录 > shops [创建店铺。 / Create shop.](https://docs-nearcade.phizone.cn/469165962e0.md): 创建新店铺。
- 根目录 > shops [获取店铺详情。 / Get shop details.](https://docs-nearcade.phizone.cn/469165963e0.md): 按 ID 获取店铺详情。
- 根目录 > shops [更新店铺。 / Update shop.](https://docs-nearcade.phizone.cn/469165964e0.md): 按 ID 更新店铺字段。
- 根目录 > shops [管理员更新店铺。 / Admin update shop.](https://docs-nearcade.phizone.cn/469165965e0.md): 管理员按 ID 更新店铺的管理字段（如锁定状态）。
- 根目录 > shops [获取在勤人数。 / Get attendance.](https://docs-nearcade.phizone.cn/469165966e0.md): 获取店铺综合、登记和上报的在勤人数。
- 根目录 > shops [登记在勤或上报在勤人数（已弃用）。 / Register or report attendance (deprecated).](https://docs-nearcade.phizone.cn/469165967e0.md): 已弃用：请改用 `POST /api/shops/{id}/attendance/new` 登记在勤，或 `POST /api/shops/{id}/attendance/reports` 上报在勤人数。本接口按请求体形状转发到对应接口，每个分支仍要求该能力对应的 scope。登记在勤仅限已登录用户；机台密钥只能上报在勤人数。
- 根目录 > shops [退勤。 / Leave attendance.](https://docs-nearcade.phizone.cn/469165968e0.md): 从某店铺的当前在勤中移除当前用户。
- 根目录 > shops [登记在勤。 / Register attendance.](https://docs-nearcade.phizone.cn/528343006e0.md): 登记当前用户在勤，出现在所玩机台的玩家列表中。出勤次数达到您自己的阈值后，机厅会自动进入您的常去机厅列表。仅限已登录用户；机台密钥只能上报在勤人数。
- 根目录 > shops [上报在勤人数。 / Report attendance counts.](https://docs-nearcade.phizone.cn/528343007e0.md): 上报某机厅当前各游戏的在勤人数。未被认领的机厅由任何登录用户上报；已被认领的机厅只能由绑定该机厅的代理密钥上报。
- 根目录 > shops [申请玩家登记令牌。 / Create player registration token.](https://docs-nearcade.phizone.cn/469165969e0.md): 为机台槽位创建短期玩家登记令牌。
- 根目录 > shops [获取玩家登记信息。 / Get player registration.](https://docs-nearcade.phizone.cn/469165970e0.md): 通过令牌获取玩家登记信息。调用方需携带机台密钥，而不是用户会话。
- 根目录 > shops [销毁玩家登记令牌。 / Delete player registration token.](https://docs-nearcade.phizone.cn/469165971e0.md): 销毁玩家登记令牌。
- 根目录 > shops [获取店铺更新记录。 / Get shop changelog.](https://docs-nearcade.phizone.cn/469165972e0.md): 分页获取店铺更新记录，包括游戏、照片和删除申请相关的变更。
- 根目录 > shops [删除店铺更新记录。 / Delete a shop changelog entry.](https://docs-nearcade.phizone.cn/469165973e0.md): 删除指定的店铺更新记录，仅站点管理员可用。
- 根目录 > shops [获取店铺评论。 / Get shop comments.](https://docs-nearcade.phizone.cn/469165974e0.md): 获取店铺评论列表，包含作者信息、当前用户对评论的投票，以及已解析的评论图片。
- 根目录 > shops [发表评论到店铺。 / Post a shop comment.](https://docs-nearcade.phizone.cn/469165975e0.md): 向店铺发表评论或回复，可附带图片。
- 根目录 > shops [提交店铺删除申请。 / Submit a shop delete request.](https://docs-nearcade.phizone.cn/469165976e0.md): 为整店或店铺照片提交删除申请。若指定 `photoId`，则表示照片删除申请；否则表示整店删除申请。
- 根目录 > shops [获取在勤历史。 / Get attendance history.](https://docs-nearcade.phizone.cn/469165977e0.md): 分页获取店铺的历史在勤上报记录。
- 根目录 > shops [获取店铺照片。 / Get shop photos.](https://docs-nearcade.phizone.cn/469165978e0.md): 获取店铺照片列表，并包含上传者信息。
- 根目录 > shops [上传店铺照片。 / Upload a shop photo.](https://docs-nearcade.phizone.cn/469165979e0.md): 上传一张店铺照片，并以 NDJSON 事件流返回上传进度与结果：每行一个事件对象，阶段为 uploading、done 或 error。
- 根目录 > shops [删除店铺照片。 / Delete a shop photo.](https://docs-nearcade.phizone.cn/469165980e0.md): 站点管理员和照片上传者可以直接删除照片；其他用户应使用照片删除申请流程。
- 根目录 > shops [获取机台队列。 / Get machine queues.](https://docs-nearcade.phizone.cn/469165981e0.md): 获取店铺当前机台队列数据。
- 根目录 > shops [上报机台队列。 / Report machine queues.](https://docs-nearcade.phizone.cn/469165982e0.md): 上报店铺中一个或多个游戏的机台队列状态。
- 根目录 > shops [获取删除申请列表。 / List delete requests.](https://docs-nearcade.phizone.cn/469165983e0.md): 获取店铺删除申请列表，并可按状态筛选。
- 根目录 > shops [获取删除申请详情。 / Get delete request details.](https://docs-nearcade.phizone.cn/469165984e0.md): 获取单个店铺删除申请详情及其投票汇总。
- 根目录 > shops [审核删除申请。 / Review a delete request.](https://docs-nearcade.phizone.cn/469165986e0.md): 由站点管理员批准或拒绝待处理的店铺删除申请。
- 根目录 > shops [删除或撤回删除申请。 / Delete or retract a delete request.](https://docs-nearcade.phizone.cn/469165985e0.md): 提交者可撤回自己的待处理申请，站点管理员可删除任意删除申请。
- 根目录 > shops [获取删除申请评论。 / Get delete request comments.](https://docs-nearcade.phizone.cn/469165987e0.md): 获取删除申请下的评论列表，包含作者信息、当前用户的评论投票，以及评论作者对该删除申请的投票。
- 根目录 > shops [发表评论到删除申请。 / Post a comment on a delete request.](https://docs-nearcade.phizone.cn/469165988e0.md): 向待处理的删除申请添加评论或回复，可附带图片。
- 根目录 > shops [对删除申请投票。 / Vote on a delete request.](https://docs-nearcade.phizone.cn/469165989e0.md): 对待处理的删除申请投支持或反对票。重复提交相同投票会撤销该投票。
- 根目录 > universities [搜索大学 / Search universities](https://docs-nearcade.phizone.cn/469165990e0.md): 按关键词搜索大学；当查询为空时返回空列表。
- 根目录 > universities [获取大学详情 / Get university details](https://docs-nearcade.phizone.cn/469165991e0.md): 按 ID 或 slug 获取大学详情。
- 根目录 > universities [上传大学头像 / Upload university avatar](https://docs-nearcade.phizone.cn/469165992e0.md): 上传大学头像，并以 NDJSON 事件流返回上传进度与结果。
- 根目录 > universities [获取大学变更记录 / Get university changelog](https://docs-nearcade.phizone.cn/469165993e0.md): 分页获取大学的变更记录。
- 根目录 > universities [获取大学社团 / Get university clubs](https://docs-nearcade.phizone.cn/469165994e0.md): 分页获取属于指定大学的社团列表。
- 根目录 > universities [获取大学成员 / Get university members](https://docs-nearcade.phizone.cn/469165995e0.md): 分页获取大学成员列表。未公开大学信息的用户会根据查看者权限被过滤。
- 根目录 > universities [获取大学帖子 / Get university posts](https://docs-nearcade.phizone.cn/469165996e0.md): 获取大学帖子列表，并按帖子可见性过滤当前用户不可见的帖子。
- 根目录 > universities [创建大学帖子 / Create university post](https://docs-nearcade.phizone.cn/469165997e0.md): 在大学下创建帖子，可附带图片并指定帖子可见性。
- 根目录 > users [获取用户资料。 / Get a user profile.](https://docs-nearcade.phizone.cn/469165998e0.md): 获取用户公开资料；当当前用户有权限时，也会包含受隐私控制的邮箱、学校和机厅信息。
- 根目录 > users [获取用户活动。 / Get user activities.](https://docs-nearcade.phizone.cn/469165999e0.md): 获取用户活动流，并根据隐私设置和当前查看者权限过滤不可见内容。支持按日期范围（YYYY-MM-DD，含两端，按指定时区解释）与活动类型过滤。
- 根目录 > users [获取用户活动热力图。 / Get user activity heatmap.](https://docs-nearcade.phizone.cn/523048656e0.md): 按天统计用户活动数量（用于个人主页的贡献热力图），遵循与活动流一致的隐私过滤。范围最长 400 天。
- 根目录 > users [上传用户头像。 / Upload a user avatar.](https://docs-nearcade.phizone.cn/469166000e0.md): 上传当前登录用户的头像，并以 NDJSON 事件流返回上传进度与结果。事件类型为 `uploading`（进度）、`done`（完成）或 `error`（失败）。
- 根目录 > users [获取当前用户资料。 / Get the current user profile.](https://docs-nearcade.phizone.cn/469166001e0.md): 获取当前已登录用户的完整资料。
- 根目录 > ugc [查询 AI 自动翻译偏好 / Get AI auto-translation preferences](https://docs-nearcade.phizone.cn/511371873e0.md): 返回当前用户开启 AI 翻译的内容类型与首次使用提示状态。未登录时返回 loggedIn=false 且不翻译任何内容。
- 根目录 > ugc [更新 AI 自动翻译偏好 / Update AI auto-translation preferences](https://docs-nearcade.phizone.cn/511371874e0.md): 部分更新当前用户的 AI 自动翻译偏好：可勾选的内容类型，或永久关闭首次使用提示。需要登录。
- 根目录 > ugc [批量查询 UGC 译文缓存 / Batch-look up cached UGC translations](https://docs-nearcade.phizone.cn/511371875e0.md): 按文本内容哈希查询已缓存的译文。仅返回缓存命中的条目；未命中的哈希不会出现在响应中，调用方应继续展示原文。可附带 `sources`（哈希→源文本），缺失的条目将被加入后台翻译队列，客户端轮询本接口即可取回结果。
- 根目录 > rankings [获取地铁站排名 / Get metro station rankings](https://docs-nearcade.phizone.cn/517273612e0.md): 读取持久化的地铁站排名，不触发同步或 API 调用。按所选维度与半径的全局顺序号升序分页（rankOrder 键为 维度_半径）；筛选网络后保留全局名次。每个条目同时携带当前维度下的全局并列名次 rank（指标相同的条目并列）。
- 根目录 > rankings [获取校区排名 / Get campus rankings](https://docs-nearcade.phizone.cn/528343004e0.md): 读取持久化的校区排名，不触发同步。按所选维度与半径的全局顺序号升序分页，筛选半径外的条目。
- 根目录 > rankings [获取地区排名 / Get region rankings](https://docs-nearcade.phizone.cn/528343005e0.md): 读取持久化的地区排名，不触发同步。按所选维度的全局顺序号升序分页；区县层级包含街道级条目。
- 根目录 > game-titles [获取游戏系列列表。 / List the game titles.](https://docs-nearcade.phizone.cn/528343008e0.md): 返回所有机台游戏系列及其座位数，名称按当前语言本地化。
- 根目录 > globe [获取地球视图数据。 / Get the globe data.](https://docs-nearcade.phizone.cn/528343014e0.md): 返回所有店铺的完整地球视图数据（地址、营业时间、机台与在勤人数）。
- 根目录 > globe [获取地球视图标记。 / Get the globe markers.](https://docs-nearcade.phizone.cn/528343015e0.md): 返回匹配筛选条件的店铺标记（ID、名称、坐标与拥挤度）。
- 根目录 > globe [获取地球视图店铺。 / Get the globe shops.](https://docs-nearcade.phizone.cn/528343016e0.md): 按距离、名称或店铺 ID 返回店铺列表，并附带筛选条件。
- 根目录 > home [获取最近的店铺更新记录。 / Get the recent shop changelog.](https://docs-nearcade.phizone.cn/528343017e0.md): 返回最近的店铺更新记录，按时间倒序分页。
- 根目录 > home [获取首页统计。 / Get the home page statistics.](https://docs-nearcade.phizone.cn/528343018e0.md): 返回首页展示的总数与排行榜：地区、校区与地铁站维度的店铺数与机台数。
- 根目录 > notifications [获取通知列表。 / List notifications.](https://docs-nearcade.phizone.cn/528343019e0.md): 按创建时间倒序返回当前用户的通知，可按页码分页或只读取未读通知。
- 根目录 > notifications [标记通知为已读。 / Mark notifications as read.](https://docs-nearcade.phizone.cn/528343020e0.md): 将当前用户的未读通知全部标记为已读。
- 根目录 > notifications [管理 FCM 设备令牌。 / Manage the FCM device token.](https://docs-nearcade.phizone.cn/528343021e0.md): 登记或移除当前用户的 FCM 设备令牌。
- 根目录 > phone [解绑手机号。 / Unbind the phone number.](https://docs-nearcade.phizone.cn/528343022e0.md): 解除当前登录用户绑定的手机号与国家/地区拨号代码，需要登录。
- 根目录 > phone [发送手机验证码。 / Send a phone verification code.](https://docs-nearcade.phizone.cn/528343023e0.md): 向指定手机号发送验证码，或创建 Telegram 验证会话。手机号与拨号代码必填；配置了验证码服务时还需要验证码令牌。
- 根目录 > phone [查询手机号验证状态。 / Get the phone verification status.](https://docs-nearcade.phizone.cn/528343024e0.md): 查询 Telegram 验证会话的状态。验证通过时会把手机号绑定到当前登录用户，需要登录。
- 根目录 > phone [验证手机号。 / Verify a phone number.](https://docs-nearcade.phizone.cn/528343025e0.md): 校验短信验证码；通过后把手机号绑定到当前登录用户，需要登录。
- 根目录 > regions [获取地区选项。 / List region selector options.](https://docs-nearcade.phizone.cn/528343026e0.md): 返回指定父级地区的下级选项；省略 parentId 时返回顶级国家列表。
- 根目录 > regions [获取地区层级。 / Get a region hierarchy.](https://docs-nearcade.phizone.cn/528343028e0.md): 按根到叶的路径返回每个地区的数据以及每一级的选项。
- 根目录 [获取附近店铺](https://docs-nearcade.phizone.cn/357975935e0.md): 
- 根目录 [获取店铺列表](https://docs-nearcade.phizone.cn/350651817e0.md): 
- 根目录 [激活机台](https://docs-nearcade.phizone.cn/407592624e0.md): 
- 根目录 [获取店铺详情](https://docs-nearcade.phizone.cn/350651823e0.md): 
- 根目录 [申请玩家登记令牌](https://docs-nearcade.phizone.cn/407593186e0.md): 
- 根目录 [获取玩家登记信息](https://docs-nearcade.phizone.cn/407593241e0.md): 
- 根目录 [获取在勤人数](https://docs-nearcade.phizone.cn/350651871e0.md): 
- 根目录 [销毁玩家登记令牌](https://docs-nearcade.phizone.cn/407593308e0.md): 
- 根目录 [上报在勤人数](https://docs-nearcade.phizone.cn/350650731e0.md): 
- 根目录 [上报机台队列](https://docs-nearcade.phizone.cn/407593346e0.md): 

## Schemas
- 根目录 [Shop](https://docs-nearcade.phizone.cn/202253312d0.md): 
- 根目录 [User](https://docs-nearcade.phizone.cn/202681168d0.md): 
- 根目录 [Game](https://docs-nearcade.phizone.cn/208831685d0.md):