iOS 方法与验证范围

以下对应 ios/StarlightSDK/Sources/StarlightSDK 的当前源码。除另有说明，网络方法为主 actor 上的 async throws；类型和标签区分大小写，例如 Swift 参数 requestID 在 JSON 中编码为 requestId。

配置与认证

入口	参数与结果
StarlightConfiguration	appId: String, baseURL: URL, timeout: TimeInterval = 15, allowInsecureHTTPForDevelopment: Bool = false；初始化可抛错
StarlightSDK	configuration、可选 storage、可选 transport 与必需 exchange 闭包
initialize()	返回 PlatformConfiguration，不自动登录
login(_ input: LoginInput)	返回 StarlightSession，内部完成 PKCE/state 与宿主交换
restoreSession()	返回可选会话；候选先验证，前台登录期间直接返回 nil，具体内存缓存行为见会话页
sendSMS(phone:purpose:)	默认 .login，重置用途 .passwordReset；返回 SMSChallenge
resetPassword(phone:challengeID:code:newPassword:)	返回 OKResult；成功后清理本地身份
changePassword(currentPassword:newPassword:)	需登录，返回 OKResult
logout() / switchAccount()	清本地并尝试撤销平台会话
cancelLogin() / clearSession()	同步方法，分别取消登录事务与清本地身份

LoginInput.password(account:password:consentVersion:) 和 LoginInput.sms(account:challengeId:code:consentVersion:) 是两个构造入口。注意短信登录构造器为 challengeId，重置方法标签为 challengeID。

AuthorizationExchange 可编码为 {appId, code, codeVerifier}。宿主交换闭包返回 StarlightSession，其字段为 token、user、role、expiresAt；可信玩家标识是 user.gameUserId。当前 user 含平台 ID 与手机号，不要输出整份响应到日志。

业务方法

分组	方法与结果
玩家中心	center() → CenterResponse，包含角色、钱包、商品、订单、礼包、优惠券、会员与消息
订单读取	orders() → Items<StarlightOrder>；order(_ id:) → StarlightOrder
创建订单	createOrder(_ input: OrderInput) → StarlightOrder
演示交易	payDemoOrder(_ id:requestID:)、refundDemoOrder(_ id:requestID:)、closeOrder(_ id:)
会话设备	sessions() → Items<AccountSession>；revokeSession(_ id:) → RevokeResult；revokeOtherSessions() → RevokeOthersResult
玩家客服	tickets(limit:before:) → TicketPage；ticket(_ id:) → SupportTicket
工单操作	createTicket(subject:category:content:orderID:requestID:)、replyTicket(_ id:content:requestID:)、closeTicket(_ id:requestID:)
玩家权益	claimGift(_ id:roleID:requestID:)、claimCoupon(_ id:requestID:)、claimDaily(requestID:) → JSONValue
消息	readMessage(_ id:) → OKResult

tickets 默认每页 50，允许 1～100；下一页使用返回的 nextCursor 作为 before。TicketCategory 为 .account、.payment、.game、.other。这是现有玩家客服接口，不是新增开发者工单平台。

订单与请求标识

OrderInput(productId:roleId:couponId:paymentMethod:requestID:) 使用服务端商品与当前可信角色；couponId 可省略。DemoPaymentMethod 只有 .demo 和 .wallet。金额使用整数分，钱包单位换算见平台币。

@MainActor
func makeDemoOrder(_ sdk: StarlightSDK, requestID: String) async throws -> StarlightOrder {
    let center = try await sdk.center()
    guard let item = center.products.first(where: { $0.kind == "game_item" }) else {
        throw StarlightError("NO_GAME_PRODUCT", "当前游戏暂无商品")
    }
    return try await sdk.createOrder(OrderInput(
        productId: item.id, roleId: center.role.id,
        paymentMethod: .demo, requestID: requestID
    ))
}

由宿主为一次购买意图生成并保留 UUID().uuidString，重试传相同 requestID 和内容。带 requestID 参数的方法默认生成新值，因此不能依赖反复调用自动复用上次标识。支付与退款同样显式传入保存的标识；超时先 order(id) 查询原订单，再按状态处理。

关闭订单、撤销设备、修改密码与标记消息等方法没有 requestID 参数，不应传入不存在的参数。服务端的权限、状态和版本规则仍然生效。当前平台付款/发货为本地演示事务，真实外部游戏不应由客户端直接加资产。

payDemoOrder、refundDemoOrder 不是 StoreKit 购买或退款，不调用 App Store、不验证 Apple 交易、不向真实渠道退钱。正式 iOS 数字商品需另行设计和接入适用的 Apple 支付、交易验证及履约流程。

错误与验证

StarlightError 提供 code、message、status 并实现 LocalizedError。status = 0 通常代表客户端错误或未收到 HTTP 响应。

错误	宿主处理
INVALID_CONFIG	检查 App ID、HTTPS origin 和超时范围
403 APP_UNAVAILABLE / ACCOUNT_RESTRICTED	应用或账号不可用，受鉴权业务与候选恢复终止旧会话；先处理限制/复审，再重新登录
STATE_MISMATCH / LOGIN_CANCELLED	丢弃当前登录结果，按玩家意图重新登录
SESSION_CHANGED	丢弃旧账号请求结果，不覆盖新账号
UNAUTHENTICATED / SESSION_EXPIRED	清理宿主界面并进入登录流程
NETWORK_ERROR / TIMEOUT / CANCELLED	网络、超时或取消；交易先查原订单
STORAGE_ERROR	检查设备锁定状态、Keychain 与权限；删除失败可能留下旧候选，当前实例不恢复它，但新实例仍可能读到
INVALID_RESPONSE	对照 SDK 类型与服务器响应，提交脱敏诊断

当前交付需要在 Apple 工具链补齐编译、Swift 测试、模拟器/真机网络、Keychain、UI 生命周期和引擎桥接验收。没有交付自动 UI、Sign in with Apple、StoreKit、Unity/Cocos 专用插件或 App Store 审核承诺。

onError 当前覆盖受鉴权请求处理中的错误和存储写入/删除错误。仍须在配置、登录、恢复及宿主交换的调用处捕获异常。403 终止只匹配表中的指定错误码，不能将所有权限拒绝都当作会话失效。

接入路径：快速开始 → 会话管理 → 问题模板。