{ "components": { "schemas": { "Envelope": { "properties": { "data": {} }, "required": [ "data" ], "type": "object" }, "Error": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } }, "securitySchemes": { "APIKey": { "bearerFormat": "UUID v4（新），mlp_ID.SECRET 或 mlk_ID.SECRET（旧）", "scheme": "bearer", "type": "http" }, "BotService": { "description": "仅限机器人服务，BOT_SERVICE_SECRET", "scheme": "bearer", "type": "http" }, "PortalSession": { "bearerFormat": "mls_ID.SECRET", "scheme": "bearer", "type": "http" }, "WebService": { "description": "仅限网站OIDC后端，WEB_SERVICE_SECRET", "scheme": "bearer", "type": "http" } } }, "info": { "description": "中文接口文档。个人账户新签发的API凭据为标准UUID v4，仅显示一次；旧版mlp_和mlk_密钥继续可用。新功能使用独立PORTAL_DB，初始化不修改旧排卡库结构。旧API Key可通过CLI签发：reader只读、writer更新、group_admin群管理、superadmin全局管理。Authorize中填写完整密钥，不要额外添加Bearer。非全局管理员仅能访问授权群；排卡和管理写操作使用Idempotency-Key，同一操作24小时内重试复用原键和原正文；账户及内部接口按各自状态校验。默认监听127.0.0.1:8080，需要MongoDB副本集。所有时间字段以ISO 8601表示；维护使用Asia/Shanghai。响应示例均为演示数据。使用指南见 https://mai-doc.blingwang.cn/usage.html。", "title": "Maimai Lineup 独立 HTTP API", "version": "2.0.0", "x-build-commit": "25d6748" }, "openapi": "3.1.0", "paths": { "/readyz": { "get": { "description": "最低角色：`reader`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。", "operationId": "get_readyz", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "ready": true } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "数据库就绪检查", "tags": [ "01 身份与状态" ], "x-group-scoped": false, "x-min-role": "reader" } }, "/v1/admin/active-users": { "get": { "description": "最低角色：`superadmin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。", "operationId": "get_v1_admin_active_users", "parameters": [ { "in": "query", "name": "days", "required": false, "schema": { "default": 7, "maximum": 366, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "_id": "123456", "last_operation": "2026-10-11T08:00:00Z", "operation_count": 7, "operation_types": [ "person_update" ] } ] }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "活跃用户", "tags": [ "07 日志与统计" ], "x-group-scoped": false, "x-min-role": "superadmin" } }, "/v1/admin/announcements": { "post": { "description": "最低角色：`superadmin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。\n\n本服务不会直接发送QQ消息。创建公告后由有群权限的客户端claim领取（2分钟租约），投递QQ后ack确认。ack必须使用领取时的同一把凭据、有效claim_id及非空message_id。领取为空时data.item为null。", "operationId": "post_v1_admin_announcements", "parameters": [ { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "groups": [ "10001" ], "text": "请按现场人数及时报卡" }, "schema": { "additionalProperties": false, "properties": { "groups": { "items": { "type": "string" }, "type": "array" }, "text": { "type": "string" } }, "required": [ "text" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "delivery": "pending", "items": [ { "created_at": "2026-10-11T08:00:00Z", "created_by": "owner", "group_id": "10001", "id": "announcement-id", "status": "pending", "text": "公告内容" } ] } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "创建待投递群公告", "tags": [ "10 群公告队列" ], "x-group-scoped": false, "x-min-role": "superadmin" } }, "/v1/admin/arcades/{arcade}/force-count": { "post": { "description": "最低角色：`superadmin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。\n\n绕过只读、封禁、单次30人和更新频率限制；人数仍为0~1000000。只有superadmin可调用。", "operationId": "post_v1_admin_arcades_arcade_force_count", "parameters": [ { "example": "12345", "in": "path", "name": "arcade", "required": true, "schema": { "type": "string" } }, { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "count": 1, "operation": "add" }, "schema": { "additionalProperties": false, "properties": { "count": { "maximum": 1000000, "minimum": 0, "type": "integer" }, "extra_info": { "maxLength": 200, "type": "string" }, "operation": { "enum": [ "add", "subtract", "set" ], "type": "string" } }, "required": [ "operation", "count" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "arcade": { "address": "上海市示例路", "id": "12345", "last_message": "最近人数更新说明", "lookup_count": 3, "machine_count": 2, "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" }, "operation_id": "latest-operation-id" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "按机厅ID强制更新（无需群别名）", "tags": [ "03 机厅与群别名" ], "x-group-scoped": false, "x-min-role": "superadmin" } }, "/v1/admin/bans/{user}": { "delete": { "description": "最低角色：`superadmin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。\n\nGET返回有效的全局或当前范围封禁，无封禁时data为null。PUT时长单位为小时，支持小数，最大8760小时；reason必填、最多200字。DELETE只解除路径指定范围，不解除其他范围封禁。", "operationId": "delete_v1_admin_bans_user", "parameters": [ { "description": "目标QQ号、服务主体或群ID，保持字符串格式", "example": "123456", "in": "path", "name": "user", "required": true, "schema": { "type": "string" } }, { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "deleted": true } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "解封用户", "tags": [ "06 封禁管理" ], "x-group-scoped": false, "x-min-role": "superadmin" }, "get": { "description": "最低角色：`superadmin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。\n\nGET返回有效的全局或当前范围封禁，无封禁时data为null。PUT时长单位为小时，支持小数，最大8760小时；reason必填、最多200字。DELETE只解除路径指定范围，不解除其他范围封禁。", "operationId": "get_v1_admin_bans_user", "parameters": [ { "description": "目标QQ号、服务主体或群ID，保持字符串格式", "example": "123456", "in": "path", "name": "user", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "by": "owner", "expire_at": "2026-10-11T09:00:00Z", "id": "123456_10001", "issued_at": "2026-10-11T08:00:00Z", "reason": "反复误报", "scope": "10001", "user_id": "123456" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "查询用户封禁", "tags": [ "06 封禁管理" ], "x-group-scoped": false, "x-min-role": "superadmin" }, "put": { "description": "最低角色：`superadmin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。\n\nGET返回有效的全局或当前范围封禁，无封禁时data为null。PUT时长单位为小时，支持小数，最大8760小时；reason必填、最多200字。DELETE只解除路径指定范围，不解除其他范围封禁。", "operationId": "put_v1_admin_bans_user", "parameters": [ { "description": "目标QQ号、服务主体或群ID，保持字符串格式", "example": "123456", "in": "path", "name": "user", "required": true, "schema": { "type": "string" } }, { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "hours": 1, "reason": "反复误报" }, "schema": { "additionalProperties": false, "properties": { "hours": { "exclusiveMinimum": 0, "maximum": 8760, "type": "number" }, "reason": { "type": "string" } }, "required": [ "hours", "reason" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "by": "owner", "expire_at": "2026-10-11T09:00:00Z", "id": "123456_10001", "issued_at": "2026-10-11T08:00:00Z", "reason": "反复误报", "scope": "10001", "user_id": "123456" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "封禁用户", "tags": [ "06 封禁管理" ], "x-group-scoped": false, "x-min-role": "superadmin" } }, "/v1/admin/catalog/refresh": { "post": { "description": "最低角色：`group_admin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。\n\n完整验证上游目录后再更新缓存，不修改机厅当前人数；上游异常返回502并保留原数据。", "operationId": "post_v1_admin_catalog_refresh", "parameters": [ { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "refreshed": 100 } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "官方目录暂不可用或数据无效，已保留原缓存" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "刷新官方目录", "tags": [ "02 搜索机厅与卡数" ], "x-group-scoped": false, "x-min-role": "group_admin" } }, "/v1/admin/clear": { "post": { "description": "最低角色：`superadmin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。\n\n必须confirm=true。清空全部可写机厅人数、历史和说明，所有机厅查询次数归零，只读人数保留。", "operationId": "post_v1_admin_clear", "parameters": [ { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "confirm": true }, "schema": { "additionalProperties": false, "properties": { "confirm": { "const": true, "type": "boolean" } }, "required": [ "confirm" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "readonly_updated": 2, "writable_updated": 10 } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "清空全部可写机厅、重置查询次数", "tags": [ "04 人数维护" ], "x-group-scoped": false, "x-min-role": "superadmin" } }, "/v1/admin/keys": { "get": { "description": "最低角色：`superadmin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。\n\n只返回元数据，不返回明文或摘要。签发仅通过服务器CLI。HTTP不能撤销当前正在使用的管理密钥，请换一把密钥或通过CLI操作。", "operationId": "get_v1_admin_keys", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "created_at": "2026-10-11T08:00:00Z", "expires_at": "2026-11-10T08:00:00Z", "groups": [ "10001" ], "id": "key-id", "nickname": "示例用户", "role": "reader", "subject": "123456" } ] }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "列出密钥元数据（无摘要和明文）", "tags": [ "11 API Key管理" ], "x-group-scoped": false, "x-min-role": "superadmin" } }, "/v1/admin/keys/{key}": { "delete": { "description": "最低角色：`superadmin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。\n\n只返回元数据，不返回明文或摘要。签发仅通过服务器CLI。HTTP不能撤销当前正在使用的管理密钥，请换一把密钥或通过CLI操作。", "operationId": "delete_v1_admin_keys_key", "parameters": [ { "in": "path", "name": "key", "required": true, "schema": { "type": "string" } }, { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "revoked": true } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "撤销API Key", "tags": [ "11 API Key管理" ], "x-group-scoped": false, "x-min-role": "superadmin" } }, "/v1/admin/logs": { "get": { "description": "最低角色：`superadmin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。", "operationId": "get_v1_admin_logs", "parameters": [ { "in": "query", "name": "page", "required": false, "schema": { "default": 1, "maximum": 10000, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "operation", "required": false, "schema": { "type": "string" } }, { "description": "目标QQ号、服务主体或群ID，保持字符串格式", "example": "123456", "in": "query", "name": "user", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "_id": "example-log-id", "arcade_id": "12345", "details": { "count": 1, "operation": "add" }, "group_id": "10001", "operation_type": "person_update", "result": "success", "source": "http_api", "timestamp": "2026-10-11T08:00:00Z", "user_id": "123456" } ], "limit": 20, "page": 1, "total": 1 } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "操作日志", "tags": [ "07 日志与统计" ], "x-group-scoped": false, "x-min-role": "superadmin" } }, "/v1/admin/reports/{kind}/{target}/{year}": { "put": { "description": "最低角色：`superadmin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。\n\nyear范围为2000至当前北京时间年份。kind为user或group，target为对应主体/群ID；导入文本最多256KiB，stats为可选统计对象。generate仅按日志生成基础报告，不调用LLM。无可用报告或生成样本时返回404。", "operationId": "put_v1_admin_reports_kind_target_year", "parameters": [ { "example": "user", "in": "path", "name": "kind", "required": true, "schema": { "enum": [ "user", "group" ], "type": "string" } }, { "description": "目标QQ号、服务主体或群ID，保持字符串格式", "example": "123456", "in": "path", "name": "target", "required": true, "schema": { "type": "string" } }, { "example": 2025, "in": "path", "name": "year", "required": true, "schema": { "minimum": 2000, "type": "integer" } }, { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "llm_analysis": "", "report_text": "2025年度报告正文", "stats": { "lookup": 10 } }, "schema": { "additionalProperties": false, "properties": { "llm_analysis": { "type": "string" }, "report_text": { "type": "string" }, "stats": { "type": "object" } }, "required": [ "report_text" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "_id": "user_123456_2025", "generated_at": "2026-10-11T08:00:00Z", "last_updated": "2026-10-11T08:00:00Z", "llm_analysis": "", "report_text": "2025年度报告正文", "stats": { "lookup": 10 }, "target_id": "123456", "type": "user", "year": 2025 } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "保存/导入年度报告", "tags": [ "08 年度报告" ], "x-group-scoped": false, "x-min-role": "superadmin" } }, "/v1/admin/reports/{kind}/{target}/{year}/generate": { "post": { "description": "最低角色：`superadmin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。\n\nyear范围为2000至当前北京时间年份。kind为user或group，target为对应主体/群ID；导入文本最多256KiB，stats为可选统计对象。generate仅按日志生成基础报告，不调用LLM。无可用报告或生成样本时返回404。", "operationId": "post_v1_admin_reports_kind_target_year_generate", "parameters": [ { "example": "user", "in": "path", "name": "kind", "required": true, "schema": { "enum": [ "user", "group" ], "type": "string" } }, { "description": "目标QQ号、服务主体或群ID，保持字符串格式", "example": "123456", "in": "path", "name": "target", "required": true, "schema": { "type": "string" } }, { "example": 2025, "in": "path", "name": "year", "required": true, "schema": { "minimum": 2000, "type": "integer" } }, { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "_id": "user_123456_2025", "generated_at": "2026-10-11T08:00:00Z", "last_updated": "2026-10-11T08:00:00Z", "llm_analysis": "", "report_text": "2025年度报告正文", "stats": { "lookup": 10 }, "target_id": "123456", "type": "user", "year": 2025 } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "按日志生成基础统计报告（不调用LLM）", "tags": [ "08 年度报告" ], "x-group-scoped": false, "x-min-role": "superadmin" } }, "/v1/admin/statistics": { "get": { "description": "最低角色：`superadmin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。", "operationId": "get_v1_admin_statistics", "parameters": [ { "in": "query", "name": "days", "required": false, "schema": { "default": 7, "maximum": 366, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "_id": "person_update", "count": 7, "success_count": 7 } ] }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "操作统计", "tags": [ "07 日志与统计" ], "x-group-scoped": false, "x-min-role": "superadmin" } }, "/v1/admin/tasks": { "get": { "description": "最低角色：`superadmin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。\n\n任务ID为clear_arc_person（北京时间04点维护）或fetch_api_data（每10分钟刷新目录）。ENABLE_SCHEDULER=false时仅保存配置，不运行任务。", "operationId": "get_v1_admin_tasks", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "catalog_interval_minutes": 10, "daily_clear": "04:00", "tasks": [ { "enabled": true, "id": "clear_arc_person" }, { "enabled": false, "id": "fetch_api_data" } ], "timezone": "Asia/Shanghai", "worker_enabled": false } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "查看定时任务", "tags": [ "09 定时任务" ], "x-group-scoped": false, "x-min-role": "superadmin" } }, "/v1/admin/tasks/{task}": { "patch": { "description": "最低角色：`superadmin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。\n\n任务ID为clear_arc_person（北京时间04点维护）或fetch_api_data（每10分钟刷新目录）。ENABLE_SCHEDULER=false时仅保存配置，不运行任务。", "operationId": "patch_v1_admin_tasks_task", "parameters": [ { "example": "fetch_api_data", "in": "path", "name": "task", "required": true, "schema": { "enum": [ "clear_arc_person", "fetch_api_data" ], "type": "string" } }, { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "enabled": true }, "schema": { "additionalProperties": false, "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "enabled": true, "id": "fetch_api_data", "worker_enabled": false } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "暂停/恢复每日维护或10分钟目录刷新", "tags": [ "09 定时任务" ], "x-group-scoped": false, "x-min-role": "superadmin" } }, "/v1/arcades/counts": { "get": { "description": "一次返回arcades集合中全部匹配结果，不分页；普通凭据仅可查询授权群绑定的机厅，superadmin可查询全库。共享机厅按ID去重。只查询，不增加积分或查询次数。\n\n最低角色：`reader`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。", "operationId": "get_v1_arcades_counts", "parameters": [ { "example": "上海", "in": "query", "name": "keyword", "required": true, "schema": { "description": "去除首尾空白后，在名称、地址、省份或ID中做不区分大小写的字面包含匹配", "maxLength": 80, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "address": "上海市示例路", "id": "12345", "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" } ], "keyword": "上海", "total": 1 } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "address": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "person_count": { "type": "integer" }, "province": { "type": "string" }, "readonly": { "type": "boolean" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "name", "address", "province", "person_count", "readonly" ], "type": "object" }, "type": "array" }, "keyword": { "type": "string" }, "total": { "maximum": 2147483647, "minimum": 0, "type": "integer" } }, "required": [ "keyword", "total", "items" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "全部匹配机厅及当前卡数；无匹配时items为空数组、total为0" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "按关键词查询所有可见机厅的当前卡数", "tags": [ "02 搜索机厅与卡数" ], "x-group-scoped": true, "x-min-role": "reader" } }, "/v1/catalog": { "get": { "description": "最低角色：`reader`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。\n\n只查询官方目录缓存，q为2~80字，空格分隔的多个词取交集。返回的person_count不代表已纳管机厅的当前卡数；当前卡数请使用关键词查卡或群别名查询。", "operationId": "get_v1_catalog", "parameters": [ { "example": "上海", "in": "query", "name": "q", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "page", "required": false, "schema": { "default": 1, "maximum": 10000, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "address": "上海市示例路", "id": "12345", "last_message": "最近人数更新说明", "lookup_count": 3, "machine_count": 2, "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" } ], "limit": 20, "page": 1, "total": 1 } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "搜索官方机厅（q/page/limit）", "tags": [ "02 搜索机厅与卡数" ], "x-group-scoped": false, "x-min-role": "reader" } }, "/v1/groups/{group}/active-users": { "get": { "description": "最低角色：`group_admin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。 `group`必须在凭据授权群中；superadmin可访问任意群。", "operationId": "get_v1_groups_group_active_users", "parameters": [ { "description": "授权群ID（字符串）", "example": "10001", "in": "path", "name": "group", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "days", "required": false, "schema": { "default": 7, "maximum": 366, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "_id": "123456", "last_operation": "2026-10-11T08:00:00Z", "operation_count": 7, "operation_types": [ "person_update" ] } ] }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "活跃用户", "tags": [ "07 日志与统计" ], "x-group-scoped": true, "x-min-role": "group_admin" } }, "/v1/groups/{group}/aliases": { "get": { "description": "最低角色：`reader`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。 `group`必须在凭据授权群中；superadmin可访问任意群。", "operationId": "get_v1_groups_group_aliases", "parameters": [ { "description": "授权群ID（字符串）", "example": "10001", "in": "path", "name": "group", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "aliases": { "main": "12345" }, "group_id": "10001" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "本群别名", "tags": [ "03 机厅与群别名" ], "x-group-scoped": true, "x-min-role": "reader" } }, "/v1/groups/{group}/aliases/{alias}": { "delete": { "description": "最低角色：`group_admin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。 `group`必须在凭据授权群中；superadmin可访问任意群。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。\n\n只删除本群映射，不删除共享机厅。", "operationId": "delete_v1_groups_group_aliases_alias", "parameters": [ { "description": "授权群ID（字符串）", "example": "10001", "in": "path", "name": "group", "required": true, "schema": { "type": "string" } }, { "description": "本群机厅别名；中文等字符需URL编码", "example": "main", "in": "path", "name": "alias", "required": true, "schema": { "type": "string" } }, { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "deleted": true } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "删除本群别名", "tags": [ "03 机厅与群别名" ], "x-group-scoped": true, "x-min-role": "group_admin" }, "put": { "description": "最低角色：`group_admin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。 `group`必须在凭据授权群中；superadmin可访问任意群。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。\n\narcade_id必须已存在于实际机厅或官方缓存中。同名别名覆盖本群映射。别名1~40字，不能含空格、点、美元符或换行。", "operationId": "put_v1_groups_group_aliases_alias", "parameters": [ { "description": "授权群ID（字符串）", "example": "10001", "in": "path", "name": "group", "required": true, "schema": { "type": "string" } }, { "description": "本群机厅别名；中文等字符需URL编码", "example": "main", "in": "path", "name": "alias", "required": true, "schema": { "type": "string" } }, { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "arcade_id": "12345" }, "schema": { "additionalProperties": false, "properties": { "arcade_id": { "type": "string" } }, "required": [ "arcade_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "address": "上海市示例路", "id": "12345", "last_message": "最近人数更新说明", "lookup_count": 3, "machine_count": 2, "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "绑定机厅（别名积分+10）", "tags": [ "03 机厅与群别名" ], "x-group-scoped": true, "x-min-role": "group_admin" } }, "/v1/groups/{group}/aliases/{alias}/clear": { "post": { "description": "最低角色：`superadmin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。 `group`必须在凭据授权群中；superadmin可访问任意群。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。", "operationId": "post_v1_groups_group_aliases_alias_clear", "parameters": [ { "description": "授权群ID（字符串）", "example": "10001", "in": "path", "name": "group", "required": true, "schema": { "type": "string" } }, { "description": "本群机厅别名；中文等字符需URL编码", "example": "main", "in": "path", "name": "alias", "required": true, "schema": { "type": "string" } }, { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "arcade": { "address": "上海市示例路", "id": "12345", "last_message": "最近人数更新说明", "lookup_count": 3, "machine_count": 2, "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" }, "operation_id": "latest-operation-id" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "清空单机厅（保留可回滚状态）", "tags": [ "04 人数维护" ], "x-group-scoped": true, "x-min-role": "superadmin" } }, "/v1/groups/{group}/aliases/{alias}/count": { "get": { "description": "最低角色：`reader`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。 `group`必须在凭据授权群中；superadmin可访问任意群。", "operationId": "get_v1_groups_group_aliases_alias_count", "parameters": [ { "description": "授权群ID（字符串）", "example": "10001", "in": "path", "name": "group", "required": true, "schema": { "type": "string" } }, { "description": "本群机厅别名；中文等字符需URL编码", "example": "main", "in": "path", "name": "alias", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "arcade": { "address": "上海市示例路", "id": "12345", "last_message": "最近人数更新说明", "lookup_count": 3, "machine_count": 2, "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" }, "operation_id": "latest-operation-id" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "查询人数（积分+1）", "tags": [ "04 人数维护" ], "x-group-scoped": true, "x-min-role": "reader" }, "post": { "description": "最低角色：`writer`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。 `group`必须在凭据授权群中；superadmin可访问任意群。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。\n\noperation为add/subtract/set，count必须显式提交，范围0~1000000；add/subtract需大于0。普通更新单次变化不超过30人；减少到负数时按0处理。受只读、封禁和人数更新频率限制。", "operationId": "post_v1_groups_group_aliases_alias_count", "parameters": [ { "description": "授权群ID（字符串）", "example": "10001", "in": "path", "name": "group", "required": true, "schema": { "type": "string" } }, { "description": "本群机厅别名；中文等字符需URL编码", "example": "main", "in": "path", "name": "alias", "required": true, "schema": { "type": "string" } }, { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "count": 1, "operation": "add" }, "schema": { "additionalProperties": false, "properties": { "count": { "maximum": 1000000, "minimum": 0, "type": "integer" }, "operation": { "enum": [ "add", "subtract", "set" ], "type": "string" } }, "required": [ "operation", "count" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "arcade": { "address": "上海市示例路", "id": "12345", "last_message": "最近人数更新说明", "lookup_count": 3, "machine_count": 2, "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" }, "operation_id": "latest-operation-id" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "examples": { "count_limit": { "summary": "60秒内超过15次人数更新，封禁和清零已提交", "value": { "data": { "rate_limited": true, "retry_after": 900 }, "error": { "code": "count_rate_limited", "message": "更新过于频繁，已在当前群封禁15分钟并清零积分" } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "更新人数", "tags": [ "04 人数维护" ], "x-group-scoped": true, "x-min-role": "writer" } }, "/v1/groups/{group}/aliases/{alias}/force-count": { "post": { "description": "最低角色：`superadmin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。 `group`必须在凭据授权群中；superadmin可访问任意群。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。\n\n绕过只读、封禁、单次30人和更新频率限制；人数仍为0~1000000。只有superadmin可调用。", "operationId": "post_v1_groups_group_aliases_alias_force_count", "parameters": [ { "description": "授权群ID（字符串）", "example": "10001", "in": "path", "name": "group", "required": true, "schema": { "type": "string" } }, { "description": "本群机厅别名；中文等字符需URL编码", "example": "main", "in": "path", "name": "alias", "required": true, "schema": { "type": "string" } }, { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "count": 1, "operation": "add" }, "schema": { "additionalProperties": false, "properties": { "count": { "maximum": 1000000, "minimum": 0, "type": "integer" }, "extra_info": { "maxLength": 200, "type": "string" }, "operation": { "enum": [ "add", "subtract", "set" ], "type": "string" } }, "required": [ "operation", "count" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "arcade": { "address": "上海市示例路", "id": "12345", "last_message": "最近人数更新说明", "lookup_count": 3, "machine_count": 2, "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" }, "operation_id": "latest-operation-id" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "强制更新（绕过只读、单次限制和封禁）", "tags": [ "03 机厅与群别名" ], "x-group-scoped": true, "x-min-role": "superadmin" } }, "/v1/groups/{group}/aliases/{alias}/note": { "patch": { "description": "最低角色：`writer`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。 `group`必须在凭据授权群中；superadmin可访问任意群。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。\n\n说明最多50字、不能换行，空字符串可清除。凭据主体必须是最近人数更新者，且operation_id必须匹配最新操作。", "operationId": "patch_v1_groups_group_aliases_alias_note", "parameters": [ { "description": "授权群ID（字符串）", "example": "10001", "in": "path", "name": "group", "required": true, "schema": { "type": "string" } }, { "description": "本群机厅别名；中文等字符需URL编码", "example": "main", "in": "path", "name": "alias", "required": true, "schema": { "type": "string" } }, { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "note": "包含休息的两人", "operation_id": "latest-operation-id" }, "schema": { "additionalProperties": false, "properties": { "note": { "maxLength": 50, "type": "string" }, "operation_id": { "type": "string" } }, "required": [ "note", "operation_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "note": "包含休息的两人" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "本人最新人数更新补充说明", "tags": [ "04 人数维护" ], "x-group-scoped": true, "x-min-role": "writer" } }, "/v1/groups/{group}/aliases/{alias}/readonly": { "patch": { "description": "最低角色：`superadmin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。 `group`必须在凭据授权群中；superadmin可访问任意群。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。", "operationId": "patch_v1_groups_group_aliases_alias_readonly", "parameters": [ { "description": "授权群ID（字符串）", "example": "10001", "in": "path", "name": "group", "required": true, "schema": { "type": "string" } }, { "description": "本群机厅别名；中文等字符需URL编码", "example": "main", "in": "path", "name": "alias", "required": true, "schema": { "type": "string" } }, { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "readonly": true }, "schema": { "additionalProperties": false, "properties": { "readonly": { "type": "boolean" } }, "required": [ "readonly" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "readonly": true } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "设置机厅只读", "tags": [ "04 人数维护" ], "x-group-scoped": true, "x-min-role": "superadmin" } }, "/v1/groups/{group}/aliases/{alias}/rollback": { "post": { "description": "最低角色：`group_admin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。 `group`必须在凭据授权群中；superadmin可访问任意群。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。\n\n只保留一次历史状态，成功后不可重复回滚；只读机厅拒绝回滚。操作者+3分，被回滚的其他主体扣20分（最低0）。", "operationId": "post_v1_groups_group_aliases_alias_rollback", "parameters": [ { "description": "授权群ID（字符串）", "example": "10001", "in": "path", "name": "group", "required": true, "schema": { "type": "string" } }, { "description": "本群机厅别名；中文等字符需URL编码", "example": "main", "in": "path", "name": "alias", "required": true, "schema": { "type": "string" } }, { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "address": "上海市示例路", "id": "12345", "last_message": "最近人数更新说明", "lookup_count": 3, "machine_count": 2, "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "一次回滚（积分+3，目标扣20）", "tags": [ "04 人数维护" ], "x-group-scoped": true, "x-min-role": "group_admin" } }, "/v1/groups/{group}/announcements/claim": { "post": { "description": "最低角色：`group_admin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。 `group`必须在凭据授权群中；superadmin可访问任意群。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。\n\n本服务不会直接发送QQ消息。创建公告后由有群权限的客户端claim领取（2分钟租约），投递QQ后ack确认。ack必须使用领取时的同一把凭据、有效claim_id及非空message_id。领取为空时data.item为null。", "operationId": "post_v1_groups_group_announcements_claim", "parameters": [ { "description": "授权群ID（字符串）", "example": "10001", "in": "path", "name": "group", "required": true, "schema": { "type": "string" } }, { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "item": { "claim_id": "claim-from-response", "claimed_by": "key-id", "created_at": "2026-10-11T08:00:00Z", "created_by": "owner", "group_id": "10001", "id": "announcement-id", "lease_until": "2026-10-11T08:02:00Z", "status": "claimed", "text": "公告内容" } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "QQ投递者领取公告（2分钟租约）", "tags": [ "10 群公告队列" ], "x-group-scoped": true, "x-min-role": "group_admin" } }, "/v1/groups/{group}/announcements/{announcement}/ack": { "post": { "description": "最低角色：`group_admin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。 `group`必须在凭据授权群中；superadmin可访问任意群。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。\n\n本服务不会直接发送QQ消息。创建公告后由有群权限的客户端claim领取（2分钟租约），投递QQ后ack确认。ack必须使用领取时的同一把凭据、有效claim_id及非空message_id。领取为空时data.item为null。", "operationId": "post_v1_groups_group_announcements_announcement_ack", "parameters": [ { "description": "授权群ID（字符串）", "example": "10001", "in": "path", "name": "group", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "announcement", "required": true, "schema": { "type": "string" } }, { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "claim_id": "claim-from-response", "message_id": "qq-message-id" }, "schema": { "additionalProperties": false, "properties": { "claim_id": { "type": "string" }, "message_id": { "type": "string" } }, "required": [ "claim_id", "message_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "sent": true } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "确认QQ投递结果", "tags": [ "10 群公告队列" ], "x-group-scoped": true, "x-min-role": "group_admin" } }, "/v1/groups/{group}/arcades": { "get": { "description": "最低角色：`reader`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。 `group`必须在凭据授权群中；superadmin可访问任意群。", "operationId": "get_v1_groups_group_arcades", "parameters": [ { "description": "授权群ID（字符串）", "example": "10001", "in": "path", "name": "group", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "aliases": { "main": "12345" }, "arcades": [ { "address": "上海市示例路", "id": "12345", "last_message": "最近人数更新说明", "lookup_count": 3, "machine_count": 2, "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" } ] } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "批量查询本群机厅（查询积分+2）", "tags": [ "03 机厅与群别名" ], "x-group-scoped": true, "x-min-role": "reader" }, "post": { "description": "最低角色：`group_admin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。 `group`必须在凭据授权群中；superadmin可访问任意群。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。\n\n名称必填（最多100字），地址必填（最多300字），省份可选（最多60字），机台数0~1000。创建后还需使用返回的ID另行绑定群别名。", "operationId": "post_v1_groups_group_arcades", "parameters": [ { "description": "授权群ID（字符串）", "example": "10001", "in": "path", "name": "group", "required": true, "schema": { "type": "string" } }, { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "address": "上海市示例路", "machine_count": 2, "name": "示例机厅", "province": "上海" }, "schema": { "additionalProperties": false, "properties": { "address": { "type": "string" }, "machine_count": { "maximum": 1000, "minimum": 0, "type": "integer" }, "name": { "type": "string" }, "province": { "type": "string" } }, "required": [ "name", "address" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "address": "上海市示例路", "id": "12345", "last_message": "最近人数更新说明", "lookup_count": 3, "machine_count": 2, "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "创建自定义机厅", "tags": [ "03 机厅与群别名" ], "x-group-scoped": true, "x-min-role": "group_admin" } }, "/v1/groups/{group}/bans/{user}": { "delete": { "description": "最低角色：`group_admin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。 `group`必须在凭据授权群中；superadmin可访问任意群。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。\n\nGET返回有效的全局或当前范围封禁，无封禁时data为null。PUT时长单位为小时，支持小数，最大8760小时；reason必填、最多200字。DELETE只解除路径指定范围，不解除其他范围封禁。", "operationId": "delete_v1_groups_group_bans_user", "parameters": [ { "description": "授权群ID（字符串）", "example": "10001", "in": "path", "name": "group", "required": true, "schema": { "type": "string" } }, { "description": "目标QQ号、服务主体或群ID，保持字符串格式", "example": "123456", "in": "path", "name": "user", "required": true, "schema": { "type": "string" } }, { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "deleted": true } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "解封用户", "tags": [ "06 封禁管理" ], "x-group-scoped": true, "x-min-role": "group_admin" }, "get": { "description": "最低角色：`group_admin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。 `group`必须在凭据授权群中；superadmin可访问任意群。\n\nGET返回有效的全局或当前范围封禁，无封禁时data为null。PUT时长单位为小时，支持小数，最大8760小时；reason必填、最多200字。DELETE只解除路径指定范围，不解除其他范围封禁。", "operationId": "get_v1_groups_group_bans_user", "parameters": [ { "description": "授权群ID（字符串）", "example": "10001", "in": "path", "name": "group", "required": true, "schema": { "type": "string" } }, { "description": "目标QQ号、服务主体或群ID，保持字符串格式", "example": "123456", "in": "path", "name": "user", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "by": "owner", "expire_at": "2026-10-11T09:00:00Z", "id": "123456_10001", "issued_at": "2026-10-11T08:00:00Z", "reason": "反复误报", "scope": "10001", "user_id": "123456" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "查询用户封禁", "tags": [ "06 封禁管理" ], "x-group-scoped": true, "x-min-role": "group_admin" }, "put": { "description": "最低角色：`group_admin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。 `group`必须在凭据授权群中；superadmin可访问任意群。\n\n写操作必须提供8~128字符的 `Idempotency-Key`。每次新操作使用新键；24小时内重试同一操作时复用原键、方法、路径和完全相同的正文。所有写操作在MongoDB事务内提交。\n\nGET返回有效的全局或当前范围封禁，无封禁时data为null。PUT时长单位为小时，支持小数，最大8760小时；reason必填、最多200字。DELETE只解除路径指定范围，不解除其他范围封禁。", "operationId": "put_v1_groups_group_bans_user", "parameters": [ { "description": "授权群ID（字符串）", "example": "10001", "in": "path", "name": "group", "required": true, "schema": { "type": "string" } }, { "description": "目标QQ号、服务主体或群ID，保持字符串格式", "example": "123456", "in": "path", "name": "user", "required": true, "schema": { "type": "string" } }, { "description": "每次逻辑写操作生成唯一键；24小时内重试复用原键和原请求体", "example": "replace-with-new-operation-id", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "hours": 1, "reason": "反复误报" }, "schema": { "additionalProperties": false, "properties": { "hours": { "exclusiveMinimum": 0, "maximum": 8760, "type": "number" }, "reason": { "type": "string" } }, "required": [ "hours", "reason" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "by": "owner", "expire_at": "2026-10-11T09:00:00Z", "id": "123456_10001", "issued_at": "2026-10-11T08:00:00Z", "reason": "反复误报", "scope": "10001", "user_id": "123456" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体最大1MiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "请求体需为application/json" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "封禁用户", "tags": [ "06 封禁管理" ], "x-group-scoped": true, "x-min-role": "group_admin" } }, "/v1/groups/{group}/logs": { "get": { "description": "最低角色：`group_admin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。 `group`必须在凭据授权群中；superadmin可访问任意群。", "operationId": "get_v1_groups_group_logs", "parameters": [ { "description": "授权群ID（字符串）", "example": "10001", "in": "path", "name": "group", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "page", "required": false, "schema": { "default": 1, "maximum": 10000, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "operation", "required": false, "schema": { "type": "string" } }, { "description": "目标QQ号、服务主体或群ID，保持字符串格式", "example": "123456", "in": "query", "name": "user", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "_id": "example-log-id", "arcade_id": "12345", "details": { "count": 1, "operation": "add" }, "group_id": "10001", "operation_type": "person_update", "result": "success", "source": "http_api", "timestamp": "2026-10-11T08:00:00Z", "user_id": "123456" } ], "limit": 20, "page": 1, "total": 1 } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "操作日志", "tags": [ "07 日志与统计" ], "x-group-scoped": true, "x-min-role": "group_admin" } }, "/v1/groups/{group}/me/ban": { "get": { "description": "最低角色：`reader`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。 `group`必须在凭据授权群中；superadmin可访问任意群。", "operationId": "get_v1_groups_group_me_ban", "parameters": [ { "description": "授权群ID（字符串）", "example": "10001", "in": "path", "name": "group", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "by": "owner", "expire_at": "2026-10-11T09:00:00Z", "id": "123456_10001", "issued_at": "2026-10-11T08:00:00Z", "reason": "反复误报", "scope": "10001", "user_id": "123456" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "查询自己的全局/群封禁", "tags": [ "06 封禁管理" ], "x-group-scoped": true, "x-min-role": "reader" } }, "/v1/groups/{group}/reports/{year}": { "get": { "description": "最低角色：`reader`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。 `group`必须在凭据授权群中；superadmin可访问任意群。\n\nyear范围为2000至当前北京时间年份。kind为user或group，target为对应主体/群ID；导入文本最多256KiB，stats为可选统计对象。generate仅按日志生成基础报告，不调用LLM。无可用报告或生成样本时返回404。", "operationId": "get_v1_groups_group_reports_year", "parameters": [ { "description": "授权群ID（字符串）", "example": "10001", "in": "path", "name": "group", "required": true, "schema": { "type": "string" } }, { "example": 2025, "in": "path", "name": "year", "required": true, "schema": { "minimum": 2000, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "_id": "user_123456_2025", "generated_at": "2026-10-11T08:00:00Z", "last_updated": "2026-10-11T08:00:00Z", "llm_analysis": "", "report_text": "2025年度报告正文", "stats": { "lookup": 10 }, "target_id": "123456", "type": "user", "year": 2025 } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "群年度报告", "tags": [ "08 年度报告" ], "x-group-scoped": true, "x-min-role": "reader" } }, "/v1/groups/{group}/statistics": { "get": { "description": "最低角色：`group_admin`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。 `group`必须在凭据授权群中；superadmin可访问任意群。", "operationId": "get_v1_groups_group_statistics", "parameters": [ { "description": "授权群ID（字符串）", "example": "10001", "in": "path", "name": "group", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "days", "required": false, "schema": { "default": 7, "maximum": 366, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "_id": "person_update", "count": 7, "success_count": 7 } ] }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "操作统计", "tags": [ "07 日志与统计" ], "x-group-scoped": true, "x-min-role": "group_admin" } }, "/v1/internal/announcements/ack": { "post": { "description": "机器人确认公告投递。仅机器人受限服务可调用，QQ必须来自真实消息或成员查询结果。禁止将服务密钥提供给浏览器。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。", "operationId": "post_v1_internal_announcements_ack", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "claim_id": { "type": "string" }, "group_id": { "type": "string" }, "id": { "type": "string" }, "message_id": { "type": "string" } }, "required": [ "group_id", "id", "claim_id", "message_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "sent": true } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "BotService": [] } ], "summary": "机器人确认公告投递", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "bot" } }, "/v1/internal/announcements/claim": { "post": { "description": "机器人领取公告。仅机器人受限服务可调用，QQ必须来自真实消息或成员查询结果。禁止将服务密钥提供给浏览器。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。", "operationId": "post_v1_internal_announcements_claim", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "group_id": { "type": "string" } }, "required": [ "group_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "item": { "claim_id": "claim-from-response", "claimed_by": "key-id", "created_at": "2026-10-11T08:00:00Z", "created_by": "owner", "group_id": "10001", "id": "announcement-id", "lease_until": "2026-10-11T08:02:00Z", "status": "claimed", "text": "公告内容" } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "BotService": [] } ], "summary": "机器人领取公告", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "bot" } }, "/v1/internal/membership": { "post": { "description": "提交成员资格证明。仅机器人受限服务可调用，QQ必须来自真实消息或成员查询结果。禁止将服务密钥提供给浏览器。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。", "operationId": "post_v1_internal_membership", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "groups": { "items": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "role": { "enum": [ "member", "admin", "owner" ], "type": "string" } }, "required": [ "id", "role" ], "type": "object" }, "maxItems": 100, "type": "array" }, "qq": { "type": "string" }, "required_qq": { "type": "string" } }, "required": [ "qq", "required_qq", "groups" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "address": "上海市示例路", "id": "12345", "last_message": "最近人数更新说明", "lookup_count": 3, "machine_count": 2, "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "BotService": [] } ], "summary": "提交成员资格证明", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "bot" } }, "/v1/internal/membership/checks": { "get": { "description": "领取资格复核任务。仅机器人受限服务可调用，QQ必须来自真实消息或成员查询结果。禁止将服务密钥提供给浏览器。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。 领取已到24小时复核时间或首次绑定/手动/群事件提交的任务，每批最多30个。领取租约5分钟，避免多机器人重复处理；失败任务在租约到期后重试。成功提交证明后安排下一次24小时复核，不依赖用户在线或ENABLE_SCHEDULER。", "operationId": "get_v1_internal_membership_checks", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "address": "上海市示例路", "id": "12345", "last_message": "最近人数更新说明", "lookup_count": 3, "machine_count": 2, "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "BotService": [] } ], "summary": "领取资格复核任务", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "bot" } }, "/v1/internal/membership/invalidate": { "post": { "description": "群事件使资格立即失效。仅机器人受限服务可调用，QQ必须来自真实消息或成员查询结果。禁止将服务密钥提供给浏览器。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。", "operationId": "post_v1_internal_membership_invalidate", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "all_group": { "description": "仅机器人退出或无法查询此群时，使该群全部证据失效", "type": "boolean" }, "group_id": { "type": "string" }, "qq": { "type": "string" } }, "required": [ "qq", "group_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "address": "上海市示例路", "id": "12345", "last_message": "最近人数更新说明", "lookup_count": 3, "machine_count": 2, "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "BotService": [] } ], "summary": "群事件使资格立即失效", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "bot" } }, "/v1/internal/oidc/session": { "post": { "description": "受信OIDC换取业务会话。仅Next.js服务端可调用；必须先由Logto官方SDK完成OIDC验证。绑定时使用X-Portal-Session传入当前业务会话。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。", "operationId": "post_v1_internal_oidc_session", "parameters": [ { "description": "bind=true时必须是发起绑定的有效网站业务会话", "in": "header", "name": "X-Portal-Session", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "bind": { "type": "boolean" }, "issuer": { "type": "string" }, "sub": { "type": "string" } }, "required": [ "issuer", "sub" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "expires_at": "2026-10-12T00:00:00Z", "token": "mls_DEMO_ID.DEMO_RANDOM_SECRET", "user": { "created_at": "2026-10-11T00:00:00Z", "disabled": false, "qq": "123456789", "uid": 1 } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "WebService": [] } ], "summary": "受信OIDC换取业务会话", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "web_service" } }, "/v1/internal/qq/keys": { "post": { "description": "私聊签发本人凭据。仅机器人受限服务可调用，QQ必须来自真实消息或成员查询结果。禁止将服务密钥提供给浏览器。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。 仅生成普通查询/报数密钥，新签发密钥为标准UUID v4，明文只返回一次；列表中的凭据编号不是密钥。旧密钥继续可用。管理员功能需独立二次验证，不隐式赋予密钥全局管理权限。", "operationId": "post_v1_internal_qq_keys", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "days": { "maximum": 365, "minimum": 1, "type": "integer" }, "name": { "type": "string" }, "qq": { "type": "string" } }, "required": [ "qq" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "credential": { "expires_at": "2026-11-10T00:00:00Z", "id": "mlp_e13e89dd-2b59-4dae-b21e-edbab4b3025c", "kind": "api", "name": "我的查询工具", "uid": 1 }, "key": "52fb8835-a095-43b2-92eb-9173e9acf424" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "BotService": [] } ], "summary": "私聊签发本人凭据", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "bot" } }, "/v1/internal/qq/profiles": { "get": { "description": "领取最近报卡者昵称刷新任务。仅机器人受限服务可调用，QQ必须来自真实消息或成员查询结果。禁止将服务密钥提供给浏览器。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。", "operationId": "get_v1_internal_qq_profiles", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "address": "上海市示例路", "id": "12345", "last_message": "最近人数更新说明", "lookup_count": 3, "machine_count": 2, "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "BotService": [] } ], "summary": "领取最近报卡者昵称刷新任务", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "bot" }, "post": { "description": "提交NcatBot查询的QQ昵称。仅机器人受限服务可调用，QQ必须来自真实消息或成员查询结果。禁止将服务密钥提供给浏览器。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。", "operationId": "post_v1_internal_qq_profiles", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "nickname": { "description": "NcatBot get_stranger_info返回的昵称，查询失败可传空串", "maxLength": 100, "type": "string" }, "qq": { "type": "string" } }, "required": [ "qq", "nickname" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "address": "上海市示例路", "id": "12345", "last_message": "最近人数更新说明", "lookup_count": 3, "machine_count": 2, "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "BotService": [] } ], "summary": "提交NcatBot查询的QQ昵称", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "bot" } }, "/v1/internal/qq/session": { "post": { "description": "取得真实操作者短期会话。仅机器人受限服务可调用，QQ必须来自真实消息或成员查询结果。禁止将服务密钥提供给浏览器。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。", "operationId": "post_v1_internal_qq_session", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "qq": { "type": "string" } }, "required": [ "qq" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "expires_at": "2026-10-12T00:00:00Z", "token": "mls_DEMO_ID.DEMO_RANDOM_SECRET", "user": { "created_at": "2026-10-11T00:00:00Z", "disabled": false, "qq": "123456789", "uid": 1 } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "BotService": [] } ], "summary": "取得真实操作者短期会话", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "bot" } }, "/v1/internal/qq/verify": { "post": { "description": "验证真实QQ发送者。仅机器人受限服务可调用，QQ必须来自真实消息或成员查询结果。禁止将服务密钥提供给浏览器。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。", "operationId": "post_v1_internal_qq_verify", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "code": { "pattern": "^[0-9]{6}$", "type": "string" }, "qq": { "type": "string" } }, "required": [ "qq", "code" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "address": "上海市示例路", "id": "12345", "last_message": "最近人数更新说明", "lookup_count": 3, "machine_count": 2, "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "BotService": [] } ], "summary": "验证真实QQ发送者", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "bot" } }, "/v1/leaderboard": { "get": { "description": "最低角色：`reader`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。", "operationId": "get_v1_leaderboard", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "_id": "123456", "nickname": "示例用户", "points": 35, "total_operations": 7 } ] }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "全局积分排行榜（与原插件一致）", "tags": [ "05 积分与排行榜" ], "x-group-scoped": false, "x-min-role": "reader" } }, "/v1/me": { "get": { "description": "最低角色：`reader`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。", "operationId": "get_v1_me", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "created_at": "2026-10-11T08:00:00Z", "expires_at": "2026-11-10T08:00:00Z", "groups": [ "10001" ], "id": "key-id", "nickname": "示例用户", "role": "reader", "subject": "123456" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "当前凭据身份与授权", "tags": [ "01 身份与状态" ], "x-group-scoped": false, "x-min-role": "reader" } }, "/v1/me/logs": { "get": { "description": "最低角色：`reader`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。", "operationId": "get_v1_me_logs", "parameters": [ { "in": "query", "name": "page", "required": false, "schema": { "default": 1, "maximum": 10000, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "operation", "required": false, "schema": { "type": "string" } }, { "description": "目标QQ号、服务主体或群ID，保持字符串格式", "example": "123456", "in": "query", "name": "user", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "_id": "example-log-id", "arcade_id": "12345", "details": { "count": 1, "operation": "add" }, "group_id": "10001", "operation_type": "person_update", "result": "success", "source": "http_api", "timestamp": "2026-10-11T08:00:00Z", "user_id": "123456" } ], "limit": 20, "page": 1, "total": 1 } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "本人操作日志", "tags": [ "07 日志与统计" ], "x-group-scoped": false, "x-min-role": "reader" } }, "/v1/me/points": { "get": { "description": "最低角色：`reader`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。", "operationId": "get_v1_me_points", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "_id": "123456", "nickname": "示例用户", "points": 35, "rank": 1, "total_operations": 7 } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "个人积分与排名", "tags": [ "05 积分与排行榜" ], "x-group-scoped": false, "x-min-role": "reader" } }, "/v1/me/reports/{year}": { "get": { "description": "最低角色：`reader`（更高角色继承）。所有业务接口需要 `Authorization: Bearer API_KEY`。\n\nyear范围为2000至当前北京时间年份。kind为user或group，target为对应主体/群ID；导入文本最多256KiB，stats为可选统计对象。generate仅按日志生成基础报告，不调用LLM。无可用报告或生成样本时返回404。", "operationId": "get_v1_me_reports_year", "parameters": [ { "example": 2025, "in": "path", "name": "year", "required": true, "schema": { "minimum": 2000, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "_id": "user_123456_2025", "generated_at": "2026-10-11T08:00:00Z", "last_updated": "2026-10-11T08:00:00Z", "llm_analysis": "", "report_text": "2025年度报告正文", "stats": { "lookup": 10 }, "target_id": "123456", "type": "user", "year": 2025 } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "APIKey": [] } ], "summary": "个人年度报告", "tags": [ "08 年度报告" ], "x-group-scoped": false, "x-min-role": "reader" } }, "/v1/portal/admin/announcements": { "get": { "description": "查看公告投递状态。要求已通过QQ二次验证的超级管理员会话，验证有效期10分钟。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。", "operationId": "get_v1_portal_admin_announcements", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "delivery": "pending", "items": [ { "created_at": "2026-10-11T08:00:00Z", "created_by": "owner", "group_id": "10001", "id": "announcement-id", "status": "pending", "text": "公告内容" } ] } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "PortalSession": [] } ], "summary": "查看公告投递状态", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "superadmin" } }, "/v1/portal/admin/arcades/metadata": { "get": { "description": "核对目录城市归属（只读）。要求已通过QQ二次验证的超级管理员会话，验证有效期10分钟。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。", "operationId": "get_v1_portal_admin_arcades_metadata", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "address": "上海市示例路", "id": "12345", "last_message": "最近人数更新说明", "lookup_count": 3, "machine_count": 2, "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "PortalSession": [] } ], "summary": "核对目录城市归属（只读）", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "superadmin" } }, "/v1/portal/admin/arcades/{arcade}/metadata": { "put": { "description": "城市区县标注（新库）。要求已通过QQ二次验证的超级管理员会话，验证有效期10分钟。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。", "operationId": "put_v1_portal_admin_arcades_arcade_metadata", "parameters": [ { "example": "12345", "in": "path", "name": "arcade", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "city": { "type": "string" }, "district": { "type": "string" } }, "required": [ "city" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "address": "上海市示例路", "id": "12345", "last_message": "最近人数更新说明", "lookup_count": 3, "machine_count": 2, "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "PortalSession": [] } ], "summary": "城市区县标注（新库）", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "superadmin" } }, "/v1/portal/admin/audit": { "get": { "description": "安全审计。要求已通过QQ二次验证的超级管理员会话，验证有效期10分钟。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。", "operationId": "get_v1_portal_admin_audit", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "address": "上海市示例路", "id": "12345", "last_message": "最近人数更新说明", "lookup_count": 3, "machine_count": 2, "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "PortalSession": [] } ], "summary": "安全审计", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "superadmin" } }, "/v1/portal/arcades/{arcade}/count": { "post": { "description": "按机厅ID报数。使用网站业务会话或个人API凭据，权限由服务端实时核验。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。 报数人须仍在至少一个合格群内；写操作需Idempotency-Key，按UID在24小时内去重。 set操作必须提供公开查询返回的version；状态变化返回409。add/subtract按事务更新，不要求version。无记录机厅首次成功报数才建立原格式排卡记录。 result.arcade使用安全机厅投影（与公开列表同类字段），不含last_operation、last_state或last_message；updated_by仅含脱敏QQ。历史幂等重放也会经过相同投影。result.operation_id仍用于追加说明。", "operationId": "post_v1_portal_arcades_arcade_count", "parameters": [ { "example": "12345", "in": "path", "name": "arcade", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "count": { "maximum": 1000000, "minimum": 0, "type": "integer" }, "group_id": { "type": "string" }, "operation": { "enum": [ "add", "subtract", "set" ], "type": "string" }, "version": { "type": "string" } }, "required": [ "operation", "count" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "replayed": false, "result": { "arcade": { "id": "demo-arcade", "person_count": 4 }, "operation_id": "opaque-operation-id" } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "examples": { "count_limit": { "summary": "60秒内超过15次人数更新，封禁和清零已提交", "value": { "data": { "rate_limited": true, "retry_after": 900 }, "error": { "code": "count_rate_limited", "message": "更新过于频繁，已在当前群封禁15分钟并清零积分" } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "PortalSession": [] }, { "APIKey": [] } ], "summary": "按机厅ID报数", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "writer" } }, "/v1/portal/arcades/{arcade}/note": { "patch": { "description": "本人最新报数补充说明。使用网站业务会话或个人API凭据，权限由服务端实时核验。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。 报数人须仍在至少一个合格群内；写操作需Idempotency-Key，按UID在24小时内去重。", "operationId": "patch_v1_portal_arcades_arcade_note", "parameters": [ { "example": "12345", "in": "path", "name": "arcade", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "note": { "maxLength": 50, "type": "string" }, "operation_id": { "type": "string" } }, "required": [ "note", "operation_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "note": "包含休息的两人" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "PortalSession": [] }, { "APIKey": [] } ], "summary": "本人最新报数补充说明", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "writer" } }, "/v1/portal/challenges": { "post": { "description": "申请注册或重置验证码。公开接口，不要求登录。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。 验证码6位、有效5分钟，与QQ及用途绑定；真实QQ发送验证消息后，原浏览器凭高强度id完成申请。验证完成前不建立正式账户。本接口的id和登录token由网站服务端转换成HttpOnly Cookie，不回传给浏览器脚本。 先向/v1/public/password-challenge申请同QQ、同用途的一次性挑战和公钥，客户端使用RSA-OAEP-256加密后将password作为{challenge_id,ciphertext}对象提交。挑战5分钟有效且原子消费，不接受明文或固定哈希替代密码。服务端仅短暂解密校验，数据库仅存Argon2id加盐哈希，兼容已有账户。 先读取/v1/public/auth-config。turnstile_enabled=true（默认）时必须提交cf-turnstile-response；Go API向Cloudflare Siteverify校验success、精确hostname与action，时效及一次性使用由Siteverify校验。登录、注册、找回密码共用account_auth操作标记，令牌提交后或过期时需要重新验证；启用期间Secret未配置不会放行。运营者显式设置TURNSTILE_ENABLED=false时不要求令牌。", "operationId": "post_v1_portal_challenges", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "cf-turnstile-response": { "description": "Turnstile account_auth 单次令牌；仅turnstile_enabled=true时必填", "maxLength": 2048, "minLength": 1, "type": "string" }, "password": { "additionalProperties": false, "properties": { "challenge_id": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "ciphertext": { "description": "RSA-OAEP SHA-256/MGF1-SHA256密文，标准Base64；label为UTF-8的maimai-password-v1\\n挑战id\\nQQ\\n用途。禁止传明文密码。", "maxLength": 700, "type": "string" } }, "required": [ "challenge_id", "ciphertext" ], "type": "object" }, "purpose": { "enum": [ "register", "reset" ], "type": "string" }, "qq": { "type": "string" }, "revoke_keys": { "description": "仅重置密码时：同时撤销该UID全部个人API凭据，默认false", "type": "boolean" } }, "required": [ "qq", "password", "purpose" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "code": "012345", "expires_at": "2026-10-11T00:05:00Z", "id": "64-character-random-challenge-id", "message": "请使用本人QQ向机器人发送：验证 012345", "purpose": "register" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [], "summary": "申请注册或重置验证码", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "public" } }, "/v1/portal/challenges/finish": { "post": { "description": "完成QQ验证。公开接口，不要求登录。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。 验证码6位、有效5分钟，与QQ及用途绑定；真实QQ发送验证消息后，原浏览器凭高强度id完成申请。验证完成前不建立正式账户。本接口的id和登录token由网站服务端转换成HttpOnly Cookie，不回传给浏览器脚本。 完成时status=complete，并返回token/expires_at/user；网站BFF隐藏token，写入HttpOnly Cookie。delete用途除外：必须使用发起申请的同一有效web会话，成功返回status=complete、deleted=true，不签发token。删除本人独立账户数据及全部凭据，保留所有旧排卡数据；Logto仅删除本应用身份映射，上游账户保留。", "operationId": "post_v1_portal_challenges_finish", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "id": { "type": "string" } }, "required": [ "id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "deleted": { "summary": "注销完成，排卡数据保留", "value": { "data": { "deleted": true, "status": "complete" } } }, "pending": { "summary": "等待QQ消息验证", "value": { "data": { "expires_at": "2026-10-11T00:05:00Z", "status": "pending" } } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ {}, { "PortalSession": [] } ], "summary": "完成QQ验证", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "public" } }, "/v1/portal/keys": { "get": { "description": "查看自己的会话或凭据。仅网站业务会话可调用，个人API凭据不能管理账户。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。 仅生成普通查询/报数密钥，新签发密钥为标准UUID v4，明文只返回一次；列表中的凭据编号不是密钥。旧密钥继续可用。管理员功能需独立二次验证，不隐式赋予密钥全局管理权限。", "operationId": "get_v1_portal_keys", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "created_at": "2026-10-11T08:00:00Z", "expires_at": "2026-11-10T08:00:00Z", "groups": [ "10001" ], "id": "key-id", "nickname": "示例用户", "role": "reader", "subject": "123456" } ] }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "PortalSession": [] } ], "summary": "查看自己的会话或凭据", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "session" }, "post": { "description": "按需签发API凭据。仅网站业务会话可调用，个人API凭据不能管理账户。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。 仅生成普通查询/报数密钥，新签发密钥为标准UUID v4，明文只返回一次；列表中的凭据编号不是密钥。旧密钥继续可用。管理员功能需独立二次验证，不隐式赋予密钥全局管理权限。", "operationId": "post_v1_portal_keys", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "days": { "maximum": 365, "minimum": 1, "type": "integer" }, "name": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "credential": { "expires_at": "2026-11-10T00:00:00Z", "id": "mlp_e13e89dd-2b59-4dae-b21e-edbab4b3025c", "kind": "api", "name": "我的查询工具", "uid": 1 }, "key": "52fb8835-a095-43b2-92eb-9173e9acf424" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "PortalSession": [] } ], "summary": "按需签发API凭据", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "session" } }, "/v1/portal/keys/{id}": { "delete": { "description": "撤销自己的会话或凭据。仅网站业务会话可调用，个人API凭据不能管理账户。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。", "operationId": "delete_v1_portal_keys_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "revoked": true } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "PortalSession": [] } ], "summary": "撤销自己的会话或凭据", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "session" } }, "/v1/portal/keys/{id}/record": { "delete": { "description": "删除自己已撤销的API凭据记录。仅网站业务会话可调用，个人API凭据不能管理账户。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。 只允许删除本人已撤销的个人API凭据记录；有效凭据须先撤销。删除记录不清除安全审计，也不影响旧排卡数据。", "operationId": "delete_v1_portal_keys_id_record", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "revoked": true } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "PortalSession": [] } ], "summary": "删除自己已撤销的API凭据记录", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "session" } }, "/v1/portal/login": { "post": { "description": "QQ密码登录。公开接口，不要求登录。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。 先向/v1/public/password-challenge申请同QQ、同用途的一次性挑战和公钥，客户端使用RSA-OAEP-256加密后将password作为{challenge_id,ciphertext}对象提交。挑战5分钟有效且原子消费，不接受明文或固定哈希替代密码。服务端仅短暂解密校验，数据库仅存Argon2id加盐哈希，兼容已有账户。 先读取/v1/public/auth-config。turnstile_enabled=true（默认）时必须提交cf-turnstile-response；Go API向Cloudflare Siteverify校验success、精确hostname与action，时效及一次性使用由Siteverify校验。登录、注册、找回密码共用account_auth操作标记，令牌提交后或过期时需要重新验证；启用期间Secret未配置不会放行。运营者显式设置TURNSTILE_ENABLED=false时不要求令牌。", "operationId": "post_v1_portal_login", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "cf-turnstile-response": { "description": "Turnstile account_auth 单次令牌；仅turnstile_enabled=true时必填", "maxLength": 2048, "minLength": 1, "type": "string" }, "password": { "additionalProperties": false, "properties": { "challenge_id": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "ciphertext": { "description": "RSA-OAEP SHA-256/MGF1-SHA256密文，标准Base64；label为UTF-8的maimai-password-v1\\n挑战id\\nQQ\\n用途。禁止传明文密码。", "maxLength": 700, "type": "string" } }, "required": [ "challenge_id", "ciphertext" ], "type": "object" }, "qq": { "type": "string" } }, "required": [ "qq", "password" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "expires_at": "2026-10-12T00:00:00Z", "token": "mls_DEMO_ID.DEMO_RANDOM_SECRET", "user": { "created_at": "2026-10-11T00:00:00Z", "disabled": false, "qq": "123456789", "uid": 1 } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [], "summary": "QQ密码登录", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "public" } }, "/v1/portal/logout": { "post": { "description": "退出当前会话。仅网站业务会话可调用，个人API凭据不能管理账户。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。", "operationId": "post_v1_portal_logout", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "address": "上海市示例路", "id": "12345", "last_message": "最近人数更新说明", "lookup_count": 3, "machine_count": 2, "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "PortalSession": [] } ], "summary": "退出当前会话", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "session" } }, "/v1/portal/me": { "get": { "description": "个人身份与资格。仅网站业务会话可调用，个人API凭据不能管理账户。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。 arcade_groups仅用于展示当前已绑定至少一家机厅的已核验群；groups、admin_groups和can_report保持原有权限含义。 群资格按QQ账户保存并每24小时由机器人定时更新，未登录账户同样更新；登录和身份查询只读取缓存，不触发核查。首次注册或绑定QQ、手动调用membership/refresh以及群关系变更可触发复核，无需再次发送QQ验证码。membership_status为qualified（可报卡）、checking（复核中）、ineligible（不满足条件）、unbound（未绑定QQ）、unconfigured（服务未配置资格规则）或unavailable（复核超过一分钟未完成）。管理员仍需独立二次验证。", "operationId": "get_v1_portal_me", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "admin_groups": [], "admin_verified_until": "0001-01-01T00:00:00Z", "arcade_groups": [ "10001" ], "can_report": true, "groups": [ "10001" ], "local_login_enabled": true, "login_methods": [ "qq", "logto" ], "membership_status": "qualified", "required_qq_configured": true, "role": "writer", "user": { "created_at": "2026-10-11T00:00:00Z", "disabled": false, "qq": "123456789", "uid": 1 } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "PortalSession": [] } ], "summary": "个人身份与资格", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "session" } }, "/v1/portal/membership/refresh": { "post": { "description": "复核报卡资格。仅网站业务会话可调用，个人API凭据不能管理账户。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。", "operationId": "post_v1_portal_membership_refresh", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "address": "上海市示例路", "id": "12345", "last_message": "最近人数更新说明", "lookup_count": 3, "machine_count": 2, "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "PortalSession": [] } ], "summary": "复核报卡资格", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "session" } }, "/v1/portal/sessions": { "get": { "description": "查看自己的会话或凭据。仅网站业务会话可调用，个人API凭据不能管理账户。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。", "operationId": "get_v1_portal_sessions", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "address": "上海市示例路", "id": "12345", "last_message": "最近人数更新说明", "lookup_count": 3, "machine_count": 2, "name": "上海示例机厅", "person_count": 7, "province": "上海", "readonly": false, "updated_at": "2026-10-11T08:00:00Z" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "PortalSession": [] } ], "summary": "查看自己的会话或凭据", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "session" } }, "/v1/portal/sessions/{id}": { "delete": { "description": "撤销自己的会话或凭据。仅网站业务会话可调用，个人API凭据不能管理账户。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。", "operationId": "delete_v1_portal_sessions_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "deleted": true } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "PortalSession": [] } ], "summary": "撤销自己的会话或凭据", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "session" } }, "/v1/portal/verify": { "post": { "description": "绑定QQ、管理员验证或注销账户。仅网站业务会话可调用，个人API凭据不能管理账户。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。 验证码6位、有效5分钟，与QQ及用途绑定；真实QQ发送验证消息后，原浏览器凭高强度id完成申请。验证完成前不建立正式账户。本接口的id和登录token由网站服务端转换成HttpOnly Cookie，不回传给浏览器脚本。 delete用途：仅本人已绑定QQ、有效web会话可申请；验证后由同一会话finish原子注销，待验证不删除。", "operationId": "post_v1_portal_verify", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "purpose": { "enum": [ "bind", "admin", "delete" ], "type": "string" }, "qq": { "type": "string" } }, "required": [ "qq", "purpose" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "code": "012345", "expires_at": "2026-10-11T00:05:00Z", "id": "64-character-random-challenge-id", "message": "请使用本人QQ向机器人发送：验证 012345", "purpose": "register" } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [ { "PortalSession": [] } ], "summary": "绑定QQ、管理员验证或注销账户", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "session" } }, "/v1/public/arcades": { "get": { "description": "青岛全部机厅与卡数（公开只读）。公开接口，不要求登录。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。 机厅列表按山东省青岛市、青岛市、山东青岛市、山东省青岛四种关键词匹配名称或地址，按机厅ID去重，包含尚未上报的机厅；显式城市标注优先。 updated_by格式为昵称（中间脱敏的QQ）；网站会话更新后为昵称（中间脱敏的QQ）通过 Web 更新；昵称由机器人通过NcatBot get_stranger_info查询并同步，短期缓存只在内存，不改写历史排卡记录。缺少昵称时使用QQ用户，没有记录时省略。公开接口不会返回完整QQ或last_operation；供机器人读取的原排卡记录仍保留完整QQ。", "operationId": "get_v1_public_arcades", "parameters": [ { "in": "query", "name": "q", "schema": { "type": "string" } }, { "in": "query", "name": "district", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "city": "青岛", "items": [ { "address": "青岛市示例地址", "district": "市南区", "id": "demo-arcade", "name": "演示机厅", "person_count": null, "readonly": false, "version": "opaque-version" } ], "total": 1 } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [], "summary": "青岛全部机厅与卡数（公开只读）", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "public" } }, "/v1/public/auth-config": { "get": { "description": "账户公开验证配置。公开接口，不要求登录。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。 仅返回turnstile_enabled布尔值，不包含Secret、服务密钥或其他内部配置。获取失败时客户端继续要求验证。", "operationId": "get_v1_public_auth_config", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "turnstile_enabled": true } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [], "summary": "账户公开验证配置", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "public" } }, "/v1/public/password-challenge": { "post": { "description": "取得一次性密码加密挑战与公钥。公开接口，不要求登录。 新增数据保存在独立PORTAL_DB，旧排卡集合不增加账户字段。 返回algorithm=RSA-OAEP-256、id、key_id、expires_at和public_key JWK（n/e为Base64URL无padding）；私钥永不返回。每QQ每分钟最多20次，挑战5分钟有效，与QQ及login/register/reset用途绑定，只可使用一次。该接口不消费Turnstile令牌。", "operationId": "post_v1_public_password_challenge", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "purpose": { "enum": [ "login", "register", "reset" ], "type": "string" }, "qq": { "type": "string" } }, "required": [ "qq", "purpose" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "algorithm": "RSA-OAEP-256", "expires_at": "2026-10-12T08:05:00Z", "id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "key_id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "public_key": { "e": "AQAB", "kty": "RSA", "n": "BASE64URL_RSA_MODULUS" } } }, "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "成功，业务数据位于data；写操作同幂等键可重放" }, "400": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "参数或幂等键无效", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "参数或幂等键无效" }, "401": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "密钥缺失、无效、过期、撤销", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "密钥缺失、无效、过期、撤销" }, "403": { "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "角色、群范围或封禁限制", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "角色、群范围或封禁限制" }, "404": { "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "资源不存在", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "资源不存在" }, "409": { "content": { "application/json": { "example": { "error": { "code": "conflict", "message": "业务冲突或幂等键复用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "业务冲突或幂等键复用" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "验证码已过期" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "限流", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "限流" }, "503": { "content": { "application/json": { "example": { "error": { "code": "unavailable", "message": "数据库不可用", "request_id": "example-request-id" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "数据库不可用" } }, "security": [], "summary": "取得一次性密码加密挑战与公钥", "tags": [ "12 网站账户与资格" ], "x-group-scoped": false, "x-min-role": "public" } } }, "servers": [ { "url": "https://mai-api.blingwang.cn", "description": "正式 API" } ] }