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。金额使用整数分，钱包单位换算见平台币。

下面是 local 演示角色示例。external 模式必须先由游戏服务器绑定角色，再使用 roles() 返回的绑定 id，不能直接使用 center.role.id 或任意外部角色号。

@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 参数，不应传入不存在的参数。服务端的权限、状态和版本规则仍然生效。local 模式在本地事务内发放演示资产；external 模式通过持久化队列等待可信游戏服确认。真实外部游戏不应由客户端直接加资产。

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

外部订单与礼包结果

v0.2.1 的 StarlightOrder 保留以下可选字段；旧本地订单缺少这些字段仍能解码。Unity/Cocos iOS 门面再次 JSON 编码时也会保留它们。

字段	含义
fulfillmentMode: String?	local 或 external，区分本地资产与游戏服发货
externalRole: ExternalRoleTarget?	包含 bindingId、serverId、externalRoleId 的可信目标快照
source: String?	purchase 或 gift；礼包奖励不应计为充值购买
giftId: String?	礼包奖励订单对应的礼包标识

status == "paid" 表示已接受付款或奖励，"fulfilled" 才表示确认发放；"refund_pending" 表示仍等待游戏服确认撤回。claimGift 使用 JSONValue 保留完整结果，外部模式返回 {"ok":true,"orderId":"gift_order_…","deliveryStatus":"pending"} 时，应展示「已领取，等待游戏服发放」，并用 order(orderId) 查询。ok 不代表到账；旧本地结果仍可能只有 {"ok":true}。幂等重试返回初始领取结果，不要用它推断当前发货状态。

错误与验证

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 生命周期和引擎桥接验收。已提供 Unity/Cocos 适配器与 iOS 门面源码，但尚未完成 Apple 工具链链接与引擎设备验收。没有交付自动 UI、Sign in with Apple、StoreKit 或 App Store 审核承诺。

当前 Swift Package 的 7 个 Swift 文件通过 tree-sitter 语法检查。源码包含 17 个 XCTest，新增覆盖外部订单重新编码、旧本地订单兼容与礼包待发货结果；Windows 没有执行 Swift 编译器类型检查或这些 XCTest，不能把语法检查计为 17 项测试通过。

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

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

多区服与账号生命周期接口

capabilities、realms、roles、deletionPreview、exportAccount 和 deleteAccount 已随四端接入能力提供。响应纯数据模型支持 Codable，以供引擎门面序列化；短信用途新增 account_deletion。上述属于交付源码，当前 Windows 环境未执行 Swift 编译、XCTest 或设备测试。