模型、枚举与错误

1. 模型命名

原生端公开模型统一以 XHIM 开头。iOS 与 macOS 使用 Swift struct/enum，Android 使用 Kotlin data class/sealed interface，Windows 使用 C# class/record/enum， HarmonyOS 使用 ArkTS interface/class/enum。字段采用各语言惯例：

text

iOS/macOS  serverMessageID
Android    serverMessageId
Windows    ServerMessageId
HarmonyOS  serverMessageId

同名语义、空值规则和单位保持一致。

2. 生命周期与配置模型

类型	关键字段 / 用途
`XHIMEvent`	状态、消息、会话、社交、媒体、Presence 和 Typing 事件联合类型
`XHIMProjectionChange`	durable 本地投影的轻量失效通知
`XHIMProjectionKind`	message upsert/state、conversation、social、sync
`XHIMProjectionOrigin`	local、remoteSync、outbox、未来值
`XHIMSocialProjectionScope`	friend requests、friendships、groups、members、blocks、join requests
`XHIMClientConfiguration`	appID、账号存储、事件容量、运行策略、部署发现结果
`XHIMRuntimePolicy`	request timeout、sync page size、reconnect backoff/attempts
`XHIMDeployment`	bootstrap URL、Endpoint signing key ID/public key
`XHIMClientMode`	production 或仅测试构建允许的 local preview
`XHIMAuthentication`	development、accessToken、business provider
`XHIMCompatibilitySnapshot`	client/server protocol、最低客户端协议、capabilities
`XHIMDiagnostics`	无敏感信息的容量、队列、请求和回调计数
`XHIMDeviceSessionPolicy`	多端登录策略、设备上限和当前 session

3. 消息与会话模型

类型	关键字段
`XHIMOutgoingMessage`	contentType、contentVersion、payload、fallbackText
`XHIMMessage`	local/server identity、sender、state、内容、mutation revision
`XHIMSendReceipt`	SDK 接受操作的 opaque payload
`XHIMMessagePage`	messages、nextCursor
`XHIMMessageHistoryContinuation`	beforeServerSequence
`XHIMMessageHistoryPage`	messages、continuation、latestServerSequence、view
`XHIMMessageSearchQuery`	text、conversation、sender、content types、时间范围
`XHIMMessageVisibility`	当前账号是否删除、revision、mutation ID
`XHIMMessageVisibilityMutation`	visibility、idempotent replay
`XHIMConversation`	ID、类型/标题、last message、unread、read sequence、revision
`XHIMConversationPage`	conversations、nextCursor
`XHIMConversationView`	cleared/hidden watermark、revision
`XHIMConversationViewMutation`	view、idempotent replay
`XHIMConversationPreference`	pinned、notifications muted、revision
`XHIMConversationDraft`	conversation、optional outgoing message、updated time
`XHIMDirectConversation`	conversationID、participant user IDs
`XHIMConversationReadReceipt`	read sequence、unread count、updated time
`XHIMConversationReadSnapshot`	conversation、read server sequence
`XHIMMarkAllConversationsReadResult`	changed count、changed reads、truncation flags
`XHIMConversationPeerRead`	reader、read sequence、revision、updated time
`XHIMConversationPeerReadPage`	conversation、reads、truncated

消息的 payload 始终保持原始不可变字节。未知 contentType 不能丢弃，必须使用 fallbackText 安全降级。

4. 用户、关系链与群组模型

类型	关键字段
`XHIMUserProfile`	userID、displayName、avatarURL、revision、updated time
`XHIMUserProfileBatch`	profiles、missingUserIDs
`XHIMUserProfileUpdate`	可选 displayName/avatarURL 等更新字段
`XHIMFriendRequest`	requestID、from/to、introduction、state、revision
`XHIMFriendship`	peer profile/remark、revision、created/updated time
`XHIMFriendRequestResolution`	request、friendship、idempotent replay
`XHIMFriendshipDeletion`	peer、deleted、idempotent replay
`XHIMFriendRemarkChange`	peer、remark、revision、idempotent replay
`XHIMGroup`	conversationID、title、avatar、owner、member count、revision
`XHIMGroupMember`	group、user、role、state、mute、revision
`XHIMGroupJoinRequest`	request、group、applicant、state、revision
`XHIMGroupChange`	group、revision、changed member count、idempotent replay
`XHIMGroupLifecycleResult`	group、left/dismissed、idempotent replay
`XHIMGroupJoinMutation`	request、membership result、idempotent replay
`XHIMBlock`	blocked user、active、revision、updated time
`XHIMSocialPage<T>`	items、nextCursor、可选 group revision fence

5. Presence、Typing、Push 和设备

类型	关键字段
`XHIMPresenceUpdate`	eventID、userID、status、sequence、expiresAt
`XHIMTypingUpdate`	eventID、conversationID、userID、isTyping、expiresAt
`XHIMPresencePublication`	服务端接受后的 presence 快照
`XHIMTypingPublication`	服务端接受后的 typing 快照
`XHIMPushDevice`	platform、deviceID、秘密 token、environment、locale
`XHIMPushDeviceRegistration`	enabled、token reassigned、device limit/evictions
`XHIMPushDeviceDisableResult`	disabled、changed
`XHIMDeviceSession`	session/device/platform、current/active、时间、revoke reason
`XHIMDeviceSessionPage`	sessions、policy
`XHIMDeviceSessionRevocation`	session、revoked、idempotent replay

Push Token 的 description/debug output 会被替换为 <redacted>。

6. 媒体模型

类型	用途
`XHIMMediaEncryption`	scheme、keyID、nonce、wrappedKey
`XHIMMediaRef`	不可变服务端媒体身份和内容哈希
`XHIMMediaTask`	durable upload/download 状态快照
`XHIMMediaTaskUpdate`	轻量事件载荷；用 taskID 重查完整任务
`XHIMMediaUploadIntent`	本地上传文件和依赖消息元数据
`XHIMMediaDownloadIntent`	media ref、cache key 和下载目的
`XHIMMediaUploadRequest`	兼容旧 uploader 的直接上传请求
`XHIMMediaUploadProgress`	phase、completed bytes、total bytes
`XHIMMediaCacheReader`	SDK 缓存对象的有界读取句柄

Android/HarmonyOS 在文件或 URI 模型上使用平台原生类型，但进入 Core 后语义相同。

7. 自定义消息模型

类型	用途
`XHIMMessagePlugin` / `IXHIMMessagePlugin`	版本校验与展示适配协议
`XHIMMessagePluginRegistry`	注册、反注册、校验和 presentation 查询
`XHIMMessagePresentation`	conversation preview、notification preview、renderer key
`XHIMMentionContent`	标准 @ 消息解码结果
`XHIMForwardItem`	合并转发中一个不可变消息条目

8. 主要枚举值

XHIMClientState

值	含义
`created`	已创建，Core 未启动
`started`	Core 已启动，未登录
`authenticating`	正在认证
`connecting`	正在建立实时连接
`synchronizing`	正在同步本地投影
`ready`	可读写
`credentialRequired`	需要续凭
`loggingOut`	正在退出
`closed`	已不可逆关闭
`fatal`	不可恢复错误

XHIMMessageState

pending、sending、retrying、serverAccepted、failed、cancelled，以及平台用于前向兼容的 unknown。

XHIMMessageContentKind

text(1)、image(2)、audio(3)、video(4)、file(5)、 custom(1000)、unknown。业务判断优先使用 contentType，不要只依赖这个旧式粗粒度 kind。

XHIMMessageMutationKind

none、editText、recall、unknown。

XHIMMediaTaskState

pending、authorizing、transferring、paused、verifying、 completed、failed、cancelled、unknown。

XHIMMediaTaskDirection：upload、download、unknown。

Projection 与短暂状态

XHIMProjectionKind：messageUpserted、messageStateChanged、 conversationChanged、socialChanged、syncApplied、unknown；
XHIMProjectionOrigin：local、remoteSync、outbox、unknown；C ABI 也保留 realtime 原始值供未来 Facade 使用；
XHIMSocialProjectionScope：none、friendRequests、friendships、groups、 groupMembers、blocks、groupJoinRequests、unknown；
XHIMPresenceStatus：online、away、offline、unknown。

关系链与群组

XHIMFriendRequestState：pending、accepted、rejected、unknown；
XHIMFriendRequestDecision：accept、reject；
XHIMGroupMemberRole：owner、administrator、member、unknown；
XHIMGroupMemberState：joined、removed、unknown；
XHIMGroupJoinRequestState：pending、accepted、rejected、unknown；
XHIMGroupJoinDecision：accept、reject；
XHIMMultiLoginPolicy：由服务端 capability snapshot 给出稳定策略名。

XHIMPushPlatform

apns(1)、fcm(2)、huawei(3)、web(4)。

XHIMDevicePlatform：iOS、Android、macOS、Windows、HarmonyOS、Web、Linux 和 unknown。

XHIMUserAction

none、retry、updateCredential、checkNetwork、contactSupport。

9. 稳定错误模型

iOS/macOS/HarmonyOS 暴露 XHIMNativeError，Android/Windows 暴露 XHIMException。业务分支使用这些字段：

字段	稳定性	用途
`code`	ABI 稳定	粗粒度状态
`domain` + `stableCode`	跨语言稳定	推荐的业务判断键
`nativeCode`	透传	HTTP、系统或服务端原始码
`retryable`	稳定	是否允许自动/手动重试
`retryAfterMilliseconds`	稳定	最早重试等待
`userAction`	稳定	UI 建议动作
`operationID` + `traceID`	稳定诊断	服务端链路排查
`message`	不稳定文本	仅日志和开发提示，禁止业务字符串匹配

ABI code：

数值	名称	常见处理
0	OK	成功
1	INVALID_ARGUMENT	修正调用参数，不重试
2	INVALID_STATE	等待 ready 或修正生命周期
3	NOT_INITIALIZED	先 start/connect
4	ALREADY_CLOSED	新建 Client
5	BACKEND_NOT_CONFIGURED	当前发行包缺少 Product Adapter
100	STORAGE_ERROR	检查空间/数据库 Key，必要时联系支持
101	IDEMPOTENCY_CONFLICT	重查实体，不盲目换 mutation ID
102	NOT_FOUND	刷新列表或提示对象不存在
103	UNSUPPORTED	检查 capability/version
104	FORBIDDEN	按服务端权限提示
200	CANCELLED	调用被取消
201	SDK_SHUTDOWN	Client 正在/已经关闭
202	CALLBACK_QUEUE_FULL	降低请求洪峰并收集诊断
203	CREDENTIAL_REQUIRED	由账号层 Provider 续凭
900	INTERNAL_ERROR	记录 operation/trace ID 并联系支持

推荐处理：

swift

catch let error as XHIMNativeError {
    switch (error.domain, error.stableCode, error.userAction) {
    case (_, _, .updateCredential):
        accountSession.requireLogin()
    case (_, _, .checkNetwork):
        banner.showOffline()
    default:
        logger.error("XHIM \(error.operationID) \(error.traceID)")
    }
}

10. 一键连接错误

一键连接异常专用于 Server URL 验证、公开发现和首个凭证获取：iOS、macOS 和 HarmonyOS 为 XHIMConnectionError，Android 为 XHIMConnectionException， Windows 为 XHIMConnectionException。其错误类别包括：

invalid server URL / identity / server configuration；
insecure transport not allowed；
development login disabled；
credential unavailable；
server rejected（含 HTTP status）；
response too large。

它发生在 Client 完全建立之前，与运行期 XHIMNativeError 分开处理。

模型、枚举与错误 ​

1. 模型命名 ​

2. 生命周期与配置模型 ​

3. 消息与会话模型 ​

4. 用户、关系链与群组模型 ​

5. Presence、Typing、Push 和设备 ​

6. 媒体模型 ​

7. 自定义消息模型 ​

8. 主要枚举值 ​

XHIMClientState ​

XHIMMessageState ​

XHIMMessageContentKind ​

XHIMMessageMutationKind ​

XHIMMediaTaskState ​

Projection 与短暂状态 ​

关系链与群组 ​

XHIMPushPlatform ​

XHIMUserAction ​

9. 稳定错误模型 ​

10. 一键连接错误 ​