chore:文档补全
This commit is contained in:
Evilom
@@ -0,0 +1,107 @@
|
||||
# Mb7Lw9d8cijSjNky1HPct37Jn3c
|
||||
|
||||
Source: https://dianchukeji.feishu.cn/wiki/Mb7Lw9d8cijSjNky1HPct37Jn3c
|
||||
|
||||
|
||||
# 一.工作内容概述
|
||||
- 初步接入抖音官方云服务链路，用于承接云存档、账号登录、玩法校验和奖励结算等能力。
|
||||
- 搭建客户端云服务调用层，统一处理服务端请求、token 缓存、登录重试、请求失败等逻辑，为后续抖音真机联调和正式云存储接入做准备。
|
||||
- 初步搭建 save-svr 云服务端，用于处理登录、拉取存档、普通关卡结算、体力恢复、抽奖、每日挑战、生存模式、皮肤、道具、拼图奖励等接口。
|
||||
- 将金币、体力、皮肤、道具、拼图碎片、每日挑战次数等账号资源逐步改为云端校验，减少客户端直接修改本地数据带来的风险。
|
||||
# 二.抖音官方云服务接入思路
|
||||
## 为什么要接入云服务
|
||||
之前项目中的账号数据主要由客户端本地维护，例如金币、体力、皮肤、道具、拼图碎片、每日挑战次数等，都是客户端自己计算并写入本地存档。
|
||||
这种方式在单机阶段比较方便，但后续接入抖音平台后会有明显问题。比如玩家换设备后存档无法同步，本地数据也更容易被修改；同时，广告、分享、抽奖、皮肤解锁、拼图奖励等入口都涉及资源发放，如果完全由客户端自己判断，后续会比较难统一校验，也容易出现重复领取或状态不同步的问题。
|
||||
因此本次开始将账号相关逻辑逐步迁移到抖音官方云服务中。客户端不再直接决定最终奖励结果，而是请求云端接口，由云端校验后返回最新账号数据。
|
||||
## 服务来源
|
||||
本次使用的是抖音官方提供的云服务能力：
|
||||
客户端侧通过 tt.login() 获取登录 code，并通过 tt.request() 请求云服务端接口。云服务端负责完成 openid 获取、token 签发、账号存档读取、玩法校验和奖励结算。
|
||||
目前项目中新增的 server/save-svr 就是准备部署到抖音官方云服务中的云端逻辑。它承担的是账号和玩法相关的服务端职责，而不是普通客户端本地逻辑。
|
||||
## 当前 memory 临时存储与后续云存储切换
|
||||
因为抖音云存储还没有通过审核，因此暂时使用 memory 存储方案：玩家的账号数据暂时保存在当前服务进程的内存变量里。链路如下：
|
||||
客户端请求 → 云服务端接收请求 → 云端校验玩法逻辑 → 临时写入 memory → 返回最新账号数据 → 客户端刷新本地状态
|
||||
需要注意的是，memory 只是开发联调阶段的临时方案，不能作为正式上线存档方案。它最大的问题是数据只存在于服务进程内存中。只要云服务端重启、重新部署、进程异常退出，或者平台回收服务实例，内存中的玩家存档就会丢失。
|
||||
也就是说，当前阶段虽然已经能模拟“云端保存和返回存档”的流程，但它还不具备真正的持久化能力。
|
||||
后续等抖音云存储审核通过，并完成数据库权限、环境 ID、AppID、AppSecret 等配置后，会将服务端存储后端从 memory 切换为 douyin 云存储。
|
||||
切换后，玩家存档会真正写入抖音云数据库。即使云服务端重启、重新部署或实例被回收，存档数据也不会丢失。
|
||||
## 整体调用链路
|
||||
当前云服务的基本调用链路是：
|
||||
客户端发起操作 → CloudGameService 统一封装 → tt.request 请求云服务端 → 云服务端校验玩法逻辑 → 写入存储后端 → 返回最新 save → 客户端刷新本地数据
|
||||
这样处理后，业务模块不需要直接关心请求地址、token 是否过期、HTTP 错误、存储后端类型等细节。
|
||||
后续从 memory 切换到抖音云数据库时，客户端和业务层基本不需要大改，只需要调整云服务端的存储后端配置即可。
|
||||
# 三.客户端云服务封装
|
||||
## 统一服务入口
|
||||
新增了客户端统一的云服务调用入口，用于封装登录、拉取存档、关卡结算、体力恢复、抽奖、皮肤、道具、拼图奖励等接口。
|
||||
这样各业务模块不需要各自拼接请求，也不需要重复处理登录、失败、重试等逻辑。后续新增云端接口时，也可以继续放到统一服务层中管理。
|
||||
目前客户端云服务已经覆盖了以下几类流程：
|
||||
- 存档基础接口：登录、拉取存档；
|
||||
- 关卡流程：普通关卡开始和结算；
|
||||
- 体力流程：分享恢复体力；
|
||||
- 玩法流程：每日挑战、生存模式；
|
||||
- 经济系统：抽奖、金币奖励；
|
||||
- 外观系统：皮肤购买、广告进度、切换皮肤；
|
||||
- 道具系统：道具消耗和增加；
|
||||
- 拼图系统：碎片分配、广告获取碎片、海报奖励、主题奖励。
|
||||
## 登录与 token 处理
|
||||
登录流程采用抖音平台链路：
|
||||
tt.login() 获取 code → 请求云服务端 /api/login → 云服务端换取 openid → 云服务端签发 token → 客户端缓存 token
|
||||
客户端会缓存 token 和过期时间。如果 token 仍然有效，就直接复用；如果接口返回 401，则清理旧 token，重新登录后再重试一次。
|
||||
这样可以减少业务模块对登录状态的感知，也避免每个接口都单独写登录逻辑。
|
||||
## 失败降级策略
|
||||
云服务仍然采用 fail-closed 策略。
|
||||
也就是说，如果云服务未启用、服务端地址为空、登录失败、HTTP 请求失败或云端返回错误，客户端不会默认发放奖励，而是返回失败。
|
||||
这和广告 SDK 接入时的策略一致。涉及金币、体力、皮肤、道具、拼图碎片等账号资源的操作，必须以云端确认为准，避免弱网或配置错误时出现“云端没确认但客户端已经给奖励”的问题。
|
||||
# 四.save-svr 云服务端搭建
|
||||
## 云服务端职责
|
||||
搭建了 save-svr 云服务端，用来承接账号和玩法相关接口。
|
||||
它的职责不只是保存存档，而是逐步作为账号资源和玩法结算的统一入口，包括：
|
||||
- 玩家登录和 openid 识别；
|
||||
- token 签发与校验；
|
||||
- 存档读取；
|
||||
- 普通关卡开始和结算；
|
||||
- 每日挑战次数与奖励；
|
||||
- 生存模式次数与成绩；
|
||||
- 体力恢复；
|
||||
- 抽奖；
|
||||
- 皮肤购买和广告解锁；
|
||||
- 道具消耗和获取；
|
||||
- 拼图碎片分配与奖励领取。
|
||||
这一步的意义在于，账号资源不再完全由客户端本地决定，而是逐步交给抖音云服务端统一校验。
|
||||
## 关卡 session 校验
|
||||
普通关卡开始时，客户端会请求云服务端创建关卡 session。云端记录关卡号、模式和开始时间。
|
||||
完成关卡时，客户端再提交 sessionId、关卡号、模式和用时。云端会校验：
|
||||
- session 是否存在；
|
||||
- session 是否属于当前玩家；
|
||||
- 关卡号是否一致；
|
||||
- 模式是否一致；
|
||||
- 是否重复结算。
|
||||
校验通过后，云端才会发放奖励并返回最新存档。
|
||||
这样可以减少重复结算、伪造结算或客户端直接刷奖励的问题。
|
||||
## 账号资源统一处理
|
||||
抽奖、皮肤、道具、拼图等系统也开始接入云端处理。
|
||||
例如：
|
||||
- 抽奖由云端根据免费次数和广告次数判断奖池；
|
||||
- 皮肤购买由云端校验金币是否足够；
|
||||
- 皮肤广告进度由云端记录并判断是否解锁；
|
||||
- 道具消耗由云端校验当前数量；
|
||||
- 拼图奖励由云端判断是否完成、是否已经领取；
|
||||
- 体力恢复由云端处理每日分享次数和体力增加。
|
||||
这样可以让账号资源变化更加集中，避免不同客户端入口各自修改数据导致状态不一致。
|
||||
# 五.验证情况与后续计划
|
||||
## 当前验证情况
|
||||
目前已完成云服务代码侧的基础接入，客户端云服务入口、云服务端基础接口和 memory 存储后端都已经搭建完成。
|
||||
当前已经具备本地联调条件，可以验证客户端请求云服务端、云端处理账号逻辑、返回最新存档这一整条链路。
|
||||
但当前还没有完成真实云存储验证，也没有进入正式测试阶段。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 后续计划
|
||||
- 在抖音云存储审核通过后，将存储后端从 memory 切换为 douyin 云存储，保证云服务端重启后存档不会丢失。
|
||||
- 真机验证普通关卡、每日挑战、生存模式、抽奖、皮肤、道具、拼图奖励等云端结算路径。
|
||||
- 补充异常路径测试，包括重复结算、重复领奖、金币不足、体力不足、非法请求、token 失效等情况。
|
||||
- 明确云服务失败时客户端各入口的表现，例如按钮是否禁用、是否弹 toast、是否允许继续本地流程。
|
||||
Reference in New Issue
Block a user