第三方账号登录#

验证状态：已源码核验、未联调（无 app 调用图）；services 基线：源码归纳 @ 2026-09-14

用途与场景#

用已绑定的第三方账号标识（类型 + 账号）免密换取平台登录态：返回加密 JWT（data.authorization）、落定的租户（data.tenantId）与用户资料。第三方账号须先经绑定第三方账号落入平台（绑定需登录态），本端点是匿名可调的登录入口——四族登录入口的第三方族，共享语义见用户中心业务 · user 用户。

App 现役依据#

判定证据	内容
旧 app 文档收录记录	旧 app 文档仓在 docs/api/main-service/system-api/user-center/third-party-account/login/ 收录本端点（含 web 前端登录调用代码片断），属 App 既有调用面
两代分工语义	/v1/retail 第二代无第三方登录对应物；第三方登录的现役通道只有本端点
后端持续维护迹象	登录 claims 决策已重构为四族登录入口共享的 UserLoginClaimsFunction，controller 2026-08-27 仍有维护提交

端点#

POST /main-service/system-api/user-center/third-party-account/login — 用已绑定的第三方标识免密登录。

端点全量事实（参数、请求/响应字段、错误码、权限点）见清单层 user-center · third-party-account 第三方账号；code 占位 wire 惯例、频控与租户落定语义见用户中心业务 · third-party-account 第三方账号。

动线与完成判据#

前置业务条件：标识已绑定、其绑定的用户仍存在、该用户名下至少有一个租户。status=200 且 data.authorization 非空表示登录成功；App 持久化 authorization/username/tenantId 并以该 token 调用后续接口。data.tenantId 即后续请求的当前租户（admin 固定 default；普通用户恢复上次登录租户），无需再切换。thirdPartyAccountType 是调用方自行维护的不透明类型标识（服务端不解析语义、不限定具体平台）。

错误与边界#

频控按（类型， 账号）组合计而非用户名计：3 秒内重复调用拒绝、24 小时滚动窗口高频后进入冷却（extraData 带剩余秒数与未插值模板，App 可自行本地化渲染倒计时，见用户中心业务 · third-party-account 第三方账号）。无绑定记录、绑定用户已不存在、名下无租户分别业务拒绝。业务失败均为 HTTP 200 + status=422 族，参数缺失或超长走请求校验出口，判定口径见错误响应差异。

调用关系与资源清理#

成功登录会在服务端写该用户的 MQTT 用户/ACL 缓存（供后续 MQTT 连接鉴权，与三族 logind 下发静态 App MQTT 账号的机制不同），App 侧无需清理；登录前若持有旧 token，应在成功后替换。绑定操作见绑定第三方账号（需登录态）；账号注销时第三方绑定随个人空间数据一并删除，见注销账号（零售端）。

已知缺口#

未执行真实联调：code 不被服务端校验，「拿到第三方平台授权」与「平台登录」之间的真实鉴权链条完全在 App 侧——App 必须自行保证 thirdPartyAccount 来源可信（例如第三方平台 OAuth 成功后取其用户标识），否则任何人持知晓的（类型， 账号）组合即可登录该用户，这是本端点当前契约的已知安全边界。登录租户缓存的恢复语义（多租户用户落定到上次租户）无 App 实测佐证。