# 在线登录与进度门禁

## 适用范围

微信小游戏（含微信内及桌面图标入口）、TapTap内H5、TapTap桌面发行端及桌面快捷入口适用。入口位置或打开方式不能绕过认证和在线进度。独立App保持登录名密码，本次不新增App云存档；TapTap小游戏原有平台登录要求不变。

在线入口门禁（强制适用于微信小游戏及其桌面图标、TapTap内H5、TapTap桌面发行端及桌面快捷入口）：优先自动登录；需要用户操作时走对应平台官方登录/授权，返回后由后端验证凭据并建立有效业务会话，成功读取本人在线进度后才能进入游戏。需要授权是合法中间状态，允许显示官方登录入口；不能把打开授权页或前端声称成功当作认证完成。取消/拒绝授权、认证失败或读档失败时留在门禁外，显示真实状态和重新登录/重试，禁止本机试玩、游客、离线降级、缓存或默认空档绕过，所有路由与快捷入口都受同一门禁约束。读档失败不等于新玩家；仅服务端确认新玩家后完成受控幂等在线初始化，确认在线初始进度可用后进入。会话失效停止依赖身份的玩法和进度写入，重新认证并读取/核对在线进度后恢复，不无限重试或反复初始化。独立App仍使用登录名密码，本次不为App新增云存档。详见共享目录docs/在线登录与进度门禁.md。规则发布不代表具体游戏已完成联调。

## 状态与进入条件

| 状态 | 能否进入 | 允许的用户操作 |
|---|---|---|
| 自动登录中 | 否 | 等待或显示实际错误 |
| 无可用登录态或需要用户授权 | 否 | 对应平台官方登录/授权，不强迫无意义重试 |
| 官方授权页/客户端中或等待返回 | 否 | 完成授权或取消，返回后继续后端认证 |
| 取消/拒绝授权、回调失败、凭据无效或认证失败 | 否 | 显示真实状态，重新登录或受控重试 |
| 认证成功但在线读档超时、失败、无权限或归属错误 | 否 | 显示实际错误并重试，不用缓存或空档进入 |
| 认证成功、会话有效且本人在线进度读取成功 | 是 | 使用在线进度进入游戏 |
| 服务端成功确认新玩家无进度 | 初始化完成前否 | 受控幂等在线初始化，确认初始在线进度可用后进入 |
| 游戏中会话失效 | 恢复前停止依赖身份的玩法及进度写入 | 重新登录/必要官方授权、后端认证并重新读取/核对进度 |

## 官方授权与运行环境

登录交互规则：微信小游戏（含桌面图标）、TapTap内H5、TapTap桌面发行端与桌面快捷入口优先校验/复用有效登录态并自动登录；无有效登录态或平台要求授权时，允许走对应平台官方流程。TapTap可按实际运行环境跳转TapTap客户端或官方登录页，完成后回到游戏；微信小游戏使用其实际微信运行环境允许的官方登录/授权，不擅自改成网站扫码OAuth。需要官方授权不等于登录失败，不禁止必要的官方登录按钮/页面，也不强制每次重复授权。取消、认证失败或读档失败时仅提供实际状态及重新登录/重试，不提供密码、游客、试玩或离线兜底。TapTap桌面发行端仍是taptap/taptap，微信桌面图标仍是wechat/wechat；操作系统和快捷方式不决定登录方式。TapTap小游戏保留平台登录，独立App仍为app/password及登录名密码。后端必须验证真实凭据、会话和进度归属，不信任客户端自报成功；给出前端配合契约，不擅自修改未授权业务工程。

TapTap平台内H5与TapTap小游戏使用tap.login()取得一次性code，经自己的游戏后端与公共服务调用code2Session（jscode2session）验身并建立自定义会话。其他桌面运行环境必须按实际平台官方支持的凭据和服务端验身协议接入，不强套H5 API，不编造授权地址或回调。桌面快捷入口沿用实际打开的运行环境。平台密钥和session_key只留后端，不下发或直接作为业务会话；上述受门禁约束的入口须后端认证及在线读档成功才进入。

## 禁止绕过

- 必要官方授权是合法中间状态，不是本机试玩，不得用“只能静默”禁止它；打开授权页或客户端也不等于已认证。
- 所有路由、快捷入口和自动分支均受门禁约束。禁止本机试玩、游客、离线模式、离线降级、跳过登录、忽略读档错误、默认空档或缓存绕过。
- 不把读档失败当新玩家，不将本地缓存写回覆盖在线进度。服务端需确认归属与真实进度，健康检查或本地模拟响应不能替代。
- 失败按实际阶段受控重试；需要授权时允许重新官方登录，不无限重试或循环跳转，不重复使用一次性凭据，不反复初始化。
- 平台或进度能力缺口需准确报告，不编造授权地址、回调、换码或进度接口，不以离线降级代替。

## 前后端配合与验收

前端维护以上状态且只有认证与进度均就绪才开放玩法；后端验证凭据、业务会话、进度归属并阻止跨用户读写。后端角色必须给出前端配合契约，不能只隐藏试玩按钮。

这是开发规范，不代表具体业务入口、桌面授权回调或平台登录已实现；实际业务修改及真实平台联调需在对应工程授权下完成并记录证据。