311 lines
14 KiB
YAML
311 lines
14 KiB
YAML
|
openapi: 3.1.0
|
|||
|
|
info:
|
|||
|
|
title: 管理端手机号登录
|
|||
|
|
version: 1.1.0
|
|||
|
|
paths:
|
|||
|
|
/api/v1/web/operator/login/session:
|
|||
|
|
get:
|
|||
|
|
operationId: operatorLoginSession
|
|||
|
|
summary: 初始化手机号登录页面
|
|||
|
|
description: HTTPS，同源，不接受查询参数。签发 HttpOnly 登录 Cookie 和 CSRF token，20 分钟后过期，同一 Cookie 重载不会轮换 CSRF。短信不可用时仍可使用密码登录。
|
|||
|
|
security: []
|
|||
|
|
responses:
|
|||
|
|
'200':
|
|||
|
|
description: 页面状态；sms_enabled=false 不代表发送成功
|
|||
|
|
headers:
|
|||
|
|
Set-Cookie:
|
|||
|
|
schema: { type: string }
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema:
|
|||
|
|
type: object
|
|||
|
|
required: [ok, data]
|
|||
|
|
properties:
|
|||
|
|
ok: { type: boolean }
|
|||
|
|
data:
|
|||
|
|
type: object
|
|||
|
|
required: [sms_enabled, password_enabled, csrf_token]
|
|||
|
|
properties:
|
|||
|
|
sms_enabled: { type: boolean }
|
|||
|
|
password_enabled: { type: boolean }
|
|||
|
|
signup_enabled: { type: boolean, const: false }
|
|||
|
|
csrf_token: { type: string }
|
|||
|
|
default: { $ref: '#/components/responses/Failure' }
|
|||
|
|
/api/v1/web/operator/login/sms/send:
|
|||
|
|
post:
|
|||
|
|
operationId: operatorSendLoginSMS
|
|||
|
|
summary: 发送管理端登录验证码
|
|||
|
|
description: 6 位随机验证码，5 分钟有效；每个手机号至少间隔 60 秒、每小时最多 5 次，家庭端和设备绑定入口共用此限额。同一请求号重试不重复发送。手机号加密、验证码仅存 keyed hash；不在响应中返回验证码。
|
|||
|
|
security: [{ OperatorLoginCookie: [] }]
|
|||
|
|
parameters:
|
|||
|
|
- { $ref: '#/components/parameters/RequestID' }
|
|||
|
|
- { $ref: '#/components/parameters/CSRF' }
|
|||
|
|
requestBody:
|
|||
|
|
required: true
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema: { $ref: './onboarding.yaml#/components/schemas/SMSSendInput' }
|
|||
|
|
responses:
|
|||
|
|
'200':
|
|||
|
|
description: 网关已接受发送请求
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema: { $ref: './onboarding.yaml#/components/schemas/SMSResponse' }
|
|||
|
|
default: { $ref: '#/components/responses/Failure' }
|
|||
|
|
/api/v1/web/operator/login/sms/verify:
|
|||
|
|
post:
|
|||
|
|
operationId: operatorVerifyLoginSMS
|
|||
|
|
summary: 验证验证码并创建管理端登录会话
|
|||
|
|
description: 验证码只能在发起发送的浏览器会话使用，最多尝试 5 次，成功后一次性消费。已有短信账号复用原身份；管理端不开放自助注册，必须预先绑定已有有效管理身份。账号 Cookie 24 小时有效，调用家庭写接口还需 CSRF；保留原管理角色，写操作仍按现有角色权限校验。读取 /api/v1/me 或事件流需附带 X-Login-Portal=operator。
|
|||
|
|
security: [{ OperatorLoginCookie: [] }]
|
|||
|
|
parameters:
|
|||
|
|
- { $ref: '#/components/parameters/RequestID' }
|
|||
|
|
- { $ref: '#/components/parameters/CSRF' }
|
|||
|
|
requestBody:
|
|||
|
|
required: true
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema: { $ref: './onboarding.yaml#/components/schemas/SMSVerifyInput' }
|
|||
|
|
responses:
|
|||
|
|
'200':
|
|||
|
|
description: 签发 HttpOnly 账号 Cookie，消费匿名登录会话；前端继续读取 /api/v1/me 校验业务账号
|
|||
|
|
headers:
|
|||
|
|
Set-Cookie:
|
|||
|
|
schema: { type: string }
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema:
|
|||
|
|
type: object
|
|||
|
|
required: [ok, data]
|
|||
|
|
properties:
|
|||
|
|
ok: { type: boolean }
|
|||
|
|
data:
|
|||
|
|
type: object
|
|||
|
|
required: [csrf_token, data]
|
|||
|
|
properties:
|
|||
|
|
csrf_token: { type: string }
|
|||
|
|
data:
|
|||
|
|
type: object
|
|||
|
|
required: [authenticated]
|
|||
|
|
properties:
|
|||
|
|
authenticated: { type: boolean }
|
|||
|
|
default: { $ref: '#/components/responses/Failure' }
|
|||
|
|
/api/v1/web/operator/login/captcha:
|
|||
|
|
post:
|
|||
|
|
operationId: operatorLoginCaptcha
|
|||
|
|
summary: 获取或更换密码登录、发送短信前的图片验证码
|
|||
|
|
description: 返回 PNG 图片和随机 ID，不返回答案。绑定登录 Cookie，2 分钟有效；刷新使旧图失效；每次校验均消费验证码。校验状态保存在 Redis，依赖不可用时拒绝登录。
|
|||
|
|
security: [{ OperatorLoginCookie: [] }]
|
|||
|
|
parameters:
|
|||
|
|
- { $ref: '#/components/parameters/RequestID' }
|
|||
|
|
- { $ref: '#/components/parameters/CSRF' }
|
|||
|
|
requestBody:
|
|||
|
|
required: true
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema: { type: object, additionalProperties: false }
|
|||
|
|
responses:
|
|||
|
|
'200':
|
|||
|
|
description: 图片验证码
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema:
|
|||
|
|
type: object
|
|||
|
|
required: [ok, data]
|
|||
|
|
properties:
|
|||
|
|
ok: { type: boolean }
|
|||
|
|
data:
|
|||
|
|
type: object
|
|||
|
|
required: [captcha_id, mode, expires_at_ms]
|
|||
|
|
properties:
|
|||
|
|
captcha_id: { type: string, format: uuid }
|
|||
|
|
mode: { type: string, enum: [image, tencent, slide] }
|
|||
|
|
captcha_app_id: { type: string, description: 腾讯云模式对应客户端的公开 CaptchaAppId，不含密钥 }
|
|||
|
|
image: { type: string, pattern: '^data:image/(png|jpeg);base64,' }
|
|||
|
|
thumb_image: { type: string, pattern: '^data:image/png;base64,' }
|
|||
|
|
image_width: { type: integer, minimum: 1 }
|
|||
|
|
image_height: { type: integer, minimum: 1 }
|
|||
|
|
thumb_width: { type: integer, minimum: 1 }
|
|||
|
|
thumb_height: { type: integer, minimum: 1 }
|
|||
|
|
thumb_x: { type: integer, minimum: 0, description: 拼图块的初始展示横坐标 }
|
|||
|
|
thumb_y: { type: integer, minimum: 0, description: 拼图块所在水平轨道 }
|
|||
|
|
expires_at_ms: { type: integer, format: int64 }
|
|||
|
|
default: { $ref: '#/components/responses/Failure' }
|
|||
|
|
/api/v1/web/operator/login/captcha/verify:
|
|||
|
|
post:
|
|||
|
|
operationId: operatorVerifyLocalSlideCaptcha
|
|||
|
|
summary: 校验本地滑块位置并换取一次性票据
|
|||
|
|
description: 同源、CSRF 和运营登录会话校验；挑战每次提交即消费。成功票据绑定原会话、客户端、策略版本和原到期时间，只能用于一次短信发送或密码登录。
|
|||
|
|
security: [{ OperatorLoginCookie: [] }]
|
|||
|
|
parameters:
|
|||
|
|
- { $ref: '#/components/parameters/RequestID' }
|
|||
|
|
- { $ref: '#/components/parameters/CSRF' }
|
|||
|
|
requestBody:
|
|||
|
|
required: true
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema: { $ref: './login-captcha.yaml#/components/schemas/SlideCaptchaVerifyInput' }
|
|||
|
|
responses:
|
|||
|
|
'200':
|
|||
|
|
description: 位置正确，返回一次性校验票据
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema: { $ref: './login-captcha.yaml#/components/schemas/SlideCaptchaVerifyResponse' }
|
|||
|
|
default: { $ref: '#/components/responses/Failure' }
|
|||
|
|
/api/v1/web/operator/login/password:
|
|||
|
|
post:
|
|||
|
|
operationId: operatorLoginPassword
|
|||
|
|
summary: 手机号、密码和图片验证码登录
|
|||
|
|
description: 使用与短信登录一致的手机号身份，密码登录不自动注册。每手机号 10 分钟最多 10 次密码尝试；每登录会话最多 20 次。失败返回统一的手机号或密码错误，不暴露手机号是否注册。密码正确但没有该账号的有效设备验证 Cookie 时返回 403 NEW_DEVICE_SMS_REQUIRED，不消费登录会话、不发账号 Cookie；完成现有 LOGIN 短信验证后签发 30 天 HttpOnly 设备验证 Cookie。已验证设备成功消费登录会话，签发 24 小时账号 Cookie。
|
|||
|
|
security: [{ OperatorLoginCookie: [] }]
|
|||
|
|
parameters:
|
|||
|
|
- { $ref: '#/components/parameters/RequestID' }
|
|||
|
|
- { $ref: '#/components/parameters/CSRF' }
|
|||
|
|
requestBody:
|
|||
|
|
required: true
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema:
|
|||
|
|
type: object
|
|||
|
|
additionalProperties: false
|
|||
|
|
required: [phone_e164, password, captcha_id]
|
|||
|
|
anyOf:
|
|||
|
|
- required: [captcha_code]
|
|||
|
|
- required: [captcha_ticket]
|
|||
|
|
properties:
|
|||
|
|
phone_e164: { type: string, pattern: '^\+[1-9][0-9]{7,14}$' }
|
|||
|
|
password: { type: string, minLength: 1, maxLength: 256, writeOnly: true }
|
|||
|
|
captcha_id: { type: string, format: uuid }
|
|||
|
|
captcha_code: { type: string, pattern: '^[0-9]{6}$', writeOnly: true }
|
|||
|
|
captcha_ticket: { type: string, maxLength: 4096, writeOnly: true }
|
|||
|
|
captcha_randstr: { type: string, maxLength: 256, writeOnly: true, description: 腾讯云 Web 模式必填，本地滑块模式无需提供 }
|
|||
|
|
responses:
|
|||
|
|
'200':
|
|||
|
|
$ref: '#/paths/~1api~1v1~1web~1operator~1login~1sms~1verify/post/responses/200'
|
|||
|
|
default: { $ref: '#/components/responses/Failure' }
|
|||
|
|
/api/v1/web/operator/account/password:
|
|||
|
|
get:
|
|||
|
|
operationId: operatorPasswordState
|
|||
|
|
summary: 查看当前手机号和密码设置状态
|
|||
|
|
security: [{ OperatorAccountCookie: [] }]
|
|||
|
|
responses:
|
|||
|
|
'200':
|
|||
|
|
description: 仅返回脱敏手机号、是否已设置密码、是否具有最近 10 分钟内且未消费的短信验证，不返回密码或摘要
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema:
|
|||
|
|
type: object
|
|||
|
|
properties:
|
|||
|
|
ok: { type: boolean }
|
|||
|
|
data:
|
|||
|
|
type: object
|
|||
|
|
required: [available]
|
|||
|
|
properties:
|
|||
|
|
available: { type: boolean }
|
|||
|
|
phone_masked: { type: string }
|
|||
|
|
password_configured: { type: boolean }
|
|||
|
|
sms_verified_recently: { type: boolean }
|
|||
|
|
default: { $ref: '#/components/responses/Failure' }
|
|||
|
|
post:
|
|||
|
|
operationId: operatorSetPassword
|
|||
|
|
summary: 设置、修改或重置当前手机号的密码
|
|||
|
|
description: 需要当前有效账号 Cookie、同源及 CSRF；同时需要最近 10 分钟内且未消费的短信验证，或正确的当前密码。新密码 6–64 个 Unicode 字符且不超过 256 字节。修改后清除短信证明并撤销该身份的其他管理登录会话，保留本次会话。密码使用随机盐 Argon2id 存储。
|
|||
|
|
security: [{ OperatorAccountCookie: [] }]
|
|||
|
|
parameters:
|
|||
|
|
- { $ref: '#/components/parameters/RequestID' }
|
|||
|
|
- { $ref: '#/components/parameters/CSRF' }
|
|||
|
|
requestBody:
|
|||
|
|
required: true
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema:
|
|||
|
|
type: object
|
|||
|
|
additionalProperties: false
|
|||
|
|
required: [password]
|
|||
|
|
properties:
|
|||
|
|
password: { type: string, minLength: 6, maxLength: 64, writeOnly: true }
|
|||
|
|
current_password: { type: string, maxLength: 256, writeOnly: true }
|
|||
|
|
responses:
|
|||
|
|
'200':
|
|||
|
|
description: 密码已保存
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema:
|
|||
|
|
type: object
|
|||
|
|
properties:
|
|||
|
|
ok: { type: boolean }
|
|||
|
|
data:
|
|||
|
|
type: object
|
|||
|
|
properties:
|
|||
|
|
password_configured: { type: boolean }
|
|||
|
|
default: { $ref: '#/components/responses/Failure' }
|
|||
|
|
/api/v1/web/operator/account/session:
|
|||
|
|
get:
|
|||
|
|
operationId: operatorAccountSession
|
|||
|
|
summary: 恢复管理端登录会话并获取 CSRF
|
|||
|
|
security: [{ OperatorAccountCookie: [] }]
|
|||
|
|
responses:
|
|||
|
|
'200':
|
|||
|
|
description: 有效管理账号会话
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema:
|
|||
|
|
type: object
|
|||
|
|
properties:
|
|||
|
|
ok: { type: boolean }
|
|||
|
|
data:
|
|||
|
|
type: object
|
|||
|
|
required: [authenticated, csrf_token]
|
|||
|
|
properties:
|
|||
|
|
authenticated: { type: boolean }
|
|||
|
|
csrf_token: { type: string }
|
|||
|
|
default: { $ref: '#/components/responses/Failure' }
|
|||
|
|
/api/v1/web/operator/auth/logout:
|
|||
|
|
post:
|
|||
|
|
operationId: operatorLogout
|
|||
|
|
summary: 撤销当前管理端会话并清除其 Cookie
|
|||
|
|
description: 同源与 CSRF 校验；家庭端会话不受影响。
|
|||
|
|
security: [{ OperatorAccountCookie: [] }]
|
|||
|
|
parameters:
|
|||
|
|
- { $ref: '#/components/parameters/RequestID' }
|
|||
|
|
- { $ref: '#/components/parameters/CSRF' }
|
|||
|
|
requestBody:
|
|||
|
|
required: true
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema: { type: object, additionalProperties: false }
|
|||
|
|
responses:
|
|||
|
|
'200':
|
|||
|
|
description: 当前管理会话已退出
|
|||
|
|
default: { $ref: '#/components/responses/Failure' }
|
|||
|
|
components:
|
|||
|
|
securitySchemes:
|
|||
|
|
OperatorAccountCookie:
|
|||
|
|
type: apiKey
|
|||
|
|
in: cookie
|
|||
|
|
name: __Host-platform-operator
|
|||
|
|
description: 仅本地 HTTP 模式使用 platform-operator。与家庭端会话、密码独立；写操作需要同源及 CSRF。
|
|||
|
|
OperatorLoginCookie:
|
|||
|
|
type: apiKey
|
|||
|
|
in: cookie
|
|||
|
|
name: __Host-platform-operator-login
|
|||
|
|
description: Secure、HttpOnly、SameSite=Lax；仅本地 HTTP 模式使用 platform-operator-login。
|
|||
|
|
parameters:
|
|||
|
|
RequestID:
|
|||
|
|
in: header
|
|||
|
|
name: X-Request-ID
|
|||
|
|
required: true
|
|||
|
|
schema: { type: string, format: uuid }
|
|||
|
|
description: UUID v4，发送结果未知时用同一 ID 和正文重试。
|
|||
|
|
CSRF:
|
|||
|
|
in: header
|
|||
|
|
name: X-CSRF-Token
|
|||
|
|
required: true
|
|||
|
|
schema: { type: string }
|
|||
|
|
responses:
|
|||
|
|
Failure:
|
|||
|
|
description: 400/401/403/409/413/415/429/500/503；SMS_CODE_INVALID、LOGIN_SESSION_EXPIRED、SMS_RATE_LIMITED、SMS_SEND_UNCERTAIN、SMS_UNAVAILABLE、CAPTCHA_INVALID、CAPTCHA_UNAVAILABLE、PASSWORD_INVALID、PASSWORD_POLICY、CURRENT_PASSWORD_INVALID、SMS_REAUTH_REQUIRED、RATE_LIMITED 等，不返回验证码或密码。
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema: { $ref: './onboarding.yaml#/components/schemas/Failure' }
|