# 标识符、时间与术语参考

本页统一文档中的名称、数据单位和状态含义。相似名称不一定代表同一对象；集成时应同时核对所属服务、用户、会话范围和有效期。具体字段以 [API 参考](https://document.thestarline.cn/app/api-reference.md)、[本机数据格式](https://document.thestarline.cn/app/local-data-formats.md)和[配置参考](https://document.thestarline.cn/app/configuration-reference.md)为准。

## 产品与组件

| 名称 | 指代 | 容易混淆的内容 |
| --- | --- | --- |
| 星线 App | 当前 iOS 与 Android 原生产品 | 不把共享后台中的全部能力视为已交付前台 |
| 星线 Account | 账户登录、验证与 OIDC 身份授权 | Account 登录态不是聊天 Bearer 会话 |
| 聊天服务 | 用户映射、消息、新事、媒体、位置、事件和通话状态 | 公网基地址可知不等于接口匿名开放 |
| 星企 | 使用共享后台的独立企业产品 | `/enterprise/*` 不等于个人群聊和本机工作台 |
| 工作台 | 星线 App 的个人日常功能入口 | 个人待办与企业待办的存储和权限不同 |
| 新事 | 文字、图片/视频、评论、点赞及可见范围 | 不是所有人可匿名读取的公开网页 |
| 记忆 | 设备上的文字、模板字段与附件记录 | 没有由此推导的云端记忆 CRUD 或自动同步 |
| 城市贴纸 | 固定城市目录与随包分发的城市建筑素材 | 不是从精确实时位置生成任意城市图片 |

## 身份与凭据

| 字段/术语 | 用途 | 保存与传递边界 |
| --- | --- | --- |
| issuer | OIDC 身份签发方 | 按配置精确匹配，不用任意外部发现文档替换 |
| Account sub | Account 对用户的身份标识 | 聊天服务用它映射本地用户；不等同于显示名或手机号 |
| chat user.id | 聊天服务用户标识 | 业务对象引用的用户 UUID 字符串 |
| client ID | 服务端登记的 OIDC 应用标识 | 是应用配置，不是普通消息的 clientId |
| client secret | 机密 OIDC 客户端的认证材料 | 只在受控服务端，不进入 App、静态页面或公开示例 |
| authorization code | Account 授权码 | 聊天服务在 HTTPS 回调后兑换；一次性且有期限 |
| state | 绑定当前授权流程的随机状态 | App 返回状态须与本次 pending 完全匹配，不能跨流程拼接 |
| codeVerifier | 本次 PKCE/原生 proof 的随机证明 | App 与聊天服务→Account 使用不同的 verifier |
| codeChallenge | verifier 的 S256 挑战 | 挑战公开不意味着可以省略最终 verifier 验证 |
| ticket | 聊天服务交给 App 的一次性换票凭据 | 不是可长期调用业务接口的聊天 token |
| chat accessToken | 调用聊天业务的 Bearer 凭据 | 独立 session，不能用 Account 或 LiveKit token 替换 |
| expiresAt | 当前对象的到期时刻 | 先确认属于 flow、ticket、session 还是其他对象 |
| pending | 客户端未完成授权状态 | 双端字段、清理时机与中断恢复不同 |

登录名、显示名、好友号、邮箱和已验证手机号分别有不同职责。修改展示资料不一定修改 Account 安全联系方式；Account 改密也不自动撤销聊天服务已签发的独立 session。详见[登录与会话](https://document.thestarline.cn/app/authentication.md)。

## ID 与游标

| 名称 | 类型/作用 | 使用规则 |
| --- | --- | --- |
| conversationId | 单聊范围的 UUID 字符串 | 不是对方 userId；删除好友的路径也使用该会话 ID |
| groupId | 个人群范围的 UUID 字符串 | 不等同于企业频道 ID |
| mediaId | 上传媒体的 UUID 字符串 | 媒体所有权与当前可见引用决定读/发权限 |
| clientId | 客户端一次发送意图的 UUID 字符串 | 新消息换 ID；相同内容的网络重试保留原 ID |
| message.id | 服务端普通消息整数 ID | 与发送时 clientId 建立映射；不假定全局连续 |
| event.id | 当前普通事件流使用的整数 ID | 是变更通知游标，不是消息正文编号 |
| eventCursor | 普通事件的已知进度 | 用于 `/events?after=...`，不能填 Unix 时间戳 |
| MLS sequence | 特定加密范围中的事件顺序 | 按 MLS 协议处理，不能复用普通 eventCursor |
| before | 读取严格早于边界的数据 | 消息历史常取当前页最小 ID；各资源默认值不同 |
| after | 读取严格晚于边界的数据 | 单聊支持的增量规则不自动适用于群历史 |
| nextBefore | 某些列表响应给出的下一页边界 | 新事、评论、通知各用自己的资源游标 |

服务端可能使用 UUID 生成标识，但部分路径校验采用固定长度的十六进制/短横线模式。验证格式不能代替查成员与权限；客户端也不能因为一个字符串“像 UUID”就信任它来自当前账号。

## 时间、大小与字符

HTTP API 的 createdAt、updatedAt、startedAt、expiresAt 等时间通常为 Unix 毫秒数；`wait`、缓存 max-age 等参数使用秒。原生模型里的 Date、本机字符串及导出容器并不全部沿用同一时间编码，转换前应查看[本机格式](https://document.thestarline.cn/app/local-data-formats.md)。

| 表达 | 含义 | 检查要点 |
| --- | --- | --- |
| 1 秒 | 1,000 毫秒 | 不把服务端毫秒直接当 Unix 秒传入原生时间构造 |
| 1 KiB | 1,024 字节 | 不是1,000字节；文件上限以代码的实际计算为准 |
| 1 MiB | 1,048,576 字节 | 10 MiB 与上传协议里的十进制10MB不同 |
| Unicode 码点数 | 如服务端 `[...text].length` 的计算 | 与UTF-8字节数、UTF-16长度不等价 |
| UTF-16代码单元 | JavaScript字符串length等实现使用的单位 | 非BMP字符可能占两个单元 |
| 原生字符串截取 | Swift/Kotlin各自的限制实现 | 不因中文提示相同就假设两端对所有字符完全同计数 |
| base64 | 二进制的文本编码 | 导出附件base64不是加密，解码即可得到原文件 |
| base64url | 使用URL安全字符的编码变体 | 原生proof与MLS标准base64不能互换 |

所有上限还受请求整体字节限制影响。例如文字未超过字段字符数，不代表包含其他字段后的 JSON 一定未超过请求体上限。某些二进制接口有独立最大值；图片宽高和文件头校验也是额外条件。

## 加密与信任范围

| 术语 | 当前语境 | 不能据此推出 |
| --- | --- | --- |
| TLS/HTTPS | 客户端与服务之间的传输保护 | 服务器无法读取普通消息正文 |
| 本机AES-GCM | 记忆索引与附件等设备文件加密 | 已解锁设备或导出的明文文件也天然受同一保护 |
| Keychain/Keystore | 设备安全存储机制 | 换机后所有密钥与文件一定自动恢复 |
| AAD | GCM认证附加数据，绑定密文上下文 | AAD是另一个密码或可以被任意换成别的purpose |
| MLS | 设备群组的密钥与加密事件协议 | 当前双端所有普通聊天与附件都已经接入 |
| KeyPackage | MLS设备可被加入群的公开密钥材料 | 公开材料里可以包含私钥，或可以无限次重复领取 |
| Welcome | MLS新成员获得群状态的协议消息 | 代表所有成员均已确认并允许发应用密文 |
| Commit | MLS群状态变化消息 | 提交HTTP成功即可忽略终端认证与确认 |
| ciphertext | 密文载荷 | 只要JSON字段名叫payload就必然是端到端加密 |
| 签名公钥固定 | 记住已见设备的签名身份 | 已提供用户可线下核对的完整安全号码系统 |

当前主聊天与附件边界见[安全与隐私](https://document.thestarline.cn/app/security-and-privacy.md)，MLS各阶段见[MLS协议](https://document.thestarline.cn/app/mls-protocol.md)。本机记忆加密、资料字段加密和加密事件协议分别属于不同数据集，不能用一个“已加密”标签覆盖全部情况。

## 操作名称与状态

| 表达 | 应理解为 | 常见误读 |
| --- | --- | --- |
| 隐藏/删除本人消息 | 修改本人可见结果 | 对方也撤回同一消息 |
| 恢复会话 | 取消当前隐藏标记 | 自动恢复被历史边界排除的旧内容 |
| 屏蔽 | 影响当前联系与可见范围的关系状态 | 完成账号删除或物理擦除所有历史数据 |
| 退出群 | 结束当前成员资格，可能转移群主 | 群在所有成员处被解散 |
| 解散群 | 群主执行的群级清理路径 | 本人删除聊天列表项 |
| 本机退出 | 客户端清理当前账号状态 | 远端logout一定成功、Account全站和其他设备均退出 |
| 转出 | 本机生成可携带的明文JSON与附件编码 | 当前已经提供导入、无损换机恢复或跨端自动互换 |
| 恢复 | 针对某个明确数据与密钥组合验证回读 | 有一份任意文件就保证恢复所有业务 |
| 上传成功 | 文件/构建到达目标服务 | 相关消息发送、审核提交或公开发布已完成 |
| 正式发布 | 有可核对公开版本与分发入口 | 页面写了版本号或存在Debug包 |

技术状态应说明对象、阶段和证据。例如“HTTP健康”只指该探针检查的依赖，“客户端源码已实现”只指代码存在，“历史真机授权通过”只指保存记录覆盖的那一次环境。完整交付条件见[发行检查](https://document.thestarline.cn/app/release-checklist.md)，故障阶段划分见[故障处置](https://document.thestarline.cn/app/incident-runbooks.md)。

## 源码与查阅顺序

普通服务对象参考 `chat-service/src/server.mjs` 和 `chat-service/src/database.mjs`；新事、加密、通话由各自仓储与适配器定义。原生术语需同时查看平台模型、序列化与安全存储，不能仅对照翻译后的界面文字。源码入口和变更验证映射见[模块地图](https://document.thestarline.cn/app/module-map.md)，首次集成可按[协议示例](https://document.thestarline.cn/app/protocol-recipes.md)逐步核对。