# 星线完整公开技术文档

资料日期：2026-10-23。允许 AI 抓取、索引、摘要及引用公开文档。仅限公开资料，不代表私有数据或代码授权。

原始地址：https://document.thestarline.cn/
Markdown：https://document.thestarline.cn/overview.md

# 星线技术文档

这里集中收录星线各产品的技术资料，涵盖客户端、账户与授权、云服务、邮件、支付、网站及支持服务。选择产品后可查阅系统结构、接口、数据处理、开发配置、测试和发布说明。

资料日期为 2026-10-23。文档依据当前可核查的源码与交付记录整理；功能是否可用、是否对外开放及是否完成验收，以各产品章节说明和实际版本为准。

## 按产品查阅

| 产品 | 文档范围 |
| --- | --- |
| [星线 App](https://document.thestarline.cn/app/) | iOS、Android、聊天、新事、媒体、通话、本机记忆、安全、配置与交付 |
| [星线账户](https://document.thestarline.cn/account/) | 账号、登录、通行密钥、会话、资料和身份验证 |
| [星线开放平台](https://document.thestarline.cn/open-platform/) | 应用登记、OIDC、API 签名与 webhook |
| [星线智联](https://document.thestarline.cn/zhilian/) | 微信小程序、手机确认、平台配置与发布状态 |
| [星企](https://document.thestarline.cn/xingqi/) | 企业客户端、组织、成员、频道和协作数据 |
| [星线云](https://document.thestarline.cn/cloud/) | 产品站、控制台、会话桥接与资源边界 |
| [星线 Email](https://document.thestarline.cn/email/) | 邮箱接口、收发协议、队列、配置和运维 |
| [星线 Pay](https://document.thestarline.cn/pay/) | 支付接入、订单、通知、幂等和部署 |
| [星线 Trade](https://document.thestarline.cn/trade/) | 模拟行情、地区选择与实现范围 |
| [星线游戏](https://document.thestarline.cn/game/) | 展示页面、图形渲染和浏览器兼容 |
| [星线社](https://document.thestarline.cn/shop/) | 目录结构、商品数据与交易能力范围 |
| [星线官网与建站](https://document.thestarline.cn/website/) | 公司官网、建站入口、网站与 App 开发服务 |
| [星职](https://document.thestarline.cn/careers/) | 招聘系统、职位、申请、简历和邮件通知 |
| [星线 Support](https://document.thestarline.cn/support/) | 帮助文章、搜索、回电申请与站点发布 |
| [星线法律](https://document.thestarline.cn/legal/) | 协议文件、版本、链接与发布规则 |
| [星线隐私](https://document.thestarline.cn/privacy/) | 产品政策、数据处理说明及维护边界 |

## 从任务出发

接入统一登录，先阅读[星线账户](https://document.thestarline.cn/account/)与[开放平台](https://document.thestarline.cn/open-platform/)。开发原生客户端，进入[星线 App](https://document.thestarline.cn/app/)或[星企](https://document.thestarline.cn/xingqi/)。维护网站、服务与用户支持，可从对应产品的架构、配置、故障处理和发布说明开始。

产品展示页、测试夹具、模块源码与正式服务具有不同的验证范围。文档会在相关章节说明演示数据、未连接的后台、尚未完成的验收以及平台限制。不要仅凭页面能够打开就推断订单、支付、云实例、邮件收发或应用发布已经完成。

## 文档格式与引用

每篇文章提供静态 HTML 和 Markdown 原文。可通过[完整目录](https://document.thestarline.cn/catalog.json)取得文章地址、产品归属、资料日期及 SHA-256 内容摘要；[完整文本](https://document.thestarline.cn/llms-full.txt)汇总全部公开文章。站内搜索覆盖各产品的标题与正文，支持接口名称和配置变量。

星线 App 原有文档完整归入 [App 目录](https://document.thestarline.cn/app/)。本域名是各产品技术文档的统一入口，产品官网、登录服务和业务 API 继续使用各自的服务域名。

引用请使用具体文章的原始地址，并保留资料日期、实现状态和适用范围。公开访问与引用规则见[访问与引用](https://document.thestarline.cn/reference/access/)。


原始地址：https://document.thestarline.cn/reference/access/
Markdown：https://document.thestarline.cn/reference/access.md

# 文档访问与引用

document.thestarline.cn 提供星线各产品的公开技术文档，无需登录。允许自动化工具和 AI 访问、抓取、索引、摘要与引用本站公开文章。引用应保留产品名称、文章标题、原始 URL、资料日期和相关限制。

## 内容入口

| 地址 | 内容 |
| --- | --- |
| [产品目录](https://document.thestarline.cn/) | 所有产品的阅读入口 |
| [catalog.json](https://document.thestarline.cn/catalog.json) | 产品、文章、HTML 与 Markdown 地址、资料日期和 SHA-256 |
| [search-index.json](https://document.thestarline.cn/search-index.json) | 本站公开标题与正文检索数据 |
| [llms.txt](https://document.thestarline.cn/llms.txt) | 产品与文章索引 |
| [llms-full.txt](https://document.thestarline.cn/llms-full.txt) | 所有公开文章的完整 Markdown |
| [sitemap.xml](https://document.thestarline.cn/sitemap.xml) | HTML 文章的 canonical 地址 |
| [robots.txt](https://document.thestarline.cn/robots.txt) | 本域名的自动抓取规则 |

每个产品目录还提供独立的 catalog.json。App 的路由元数据位于 [app/api-index.json](https://document.thestarline.cn/app/api-index.json)，其中独立星企接口具有各自范围标记，不应当作 App 账号下的公共接口直接调用。

所有正文均已生成在 HTML 中，关闭 JavaScript 仍能阅读、展开章节和点击原文链接。搜索脚本只在浏览器内查询公开静态索引；阅读不需要创建账号或提交个人信息。

## 抓取规则

robots.txt 对普通爬虫开放，并显式允许 OAI-SearchBot、GPTBot、ChatGPT-User。抓取者应合理控制并发、缓存已取得的资源，在遇到 HTTP 429 或临时服务错误时退避。可比较文章的 SHA-256 判断正文是否变化；该摘要用于内容辨识，并不是数字签名。

允许抓取不保证第三方会实际收录、训练或引用。llms.txt 是内容发现入口，不能代替平台自身的索引机制；站点地图也不构成已收录证明。本次部署与页面验证的结论只涵盖文档站可访问性，不自动代表业务系统已经验收。

## 许可范围

本站允许读取、摘要和引用公开文档。这个许可不授予源码、软件包、商标或第三方素材的开源许可，也不授予用户聊天、账号资料、邮箱、支付记录、本机记忆、简历、日志、服务配置或数据库的访问权。

文档中描述的身份验证、授权、成员关系、票据和签名规则仍然有效。文档可公开阅读，不意味着业务 API 可以匿名调用。产品政策与服务协议以各自正式发布的[法律文件](https://legal.thestarline.cn/)和[隐私文件](https://privacy.thestarline.cn/)为准。

## 引用与更新

优先引用具体文章的 canonical URL，而不是搜索结果、本地预览地址或登录回跳链接。区分已实现功能、历史验收、当前限制与待完成事项；涉及安全、数据保留或支付时，应保留原文的适用范围。

资料日期为 2026-10-23。正文、Markdown、搜索索引、产品目录和完整文本来自同一批构建输入。产品版本、部署配置和第三方平台状态可能随后变化；技术文档不构成服务等级或平台审批承诺。


原始地址：https://document.thestarline.cn/app/
Markdown：https://document.thestarline.cn/app/overview.md

# 星线 App 技术文档

星线 App 的技术文档涵盖 iOS、Android、账号授权、聊天服务、本地数据、媒体与通话、安全、开发、测试和部署。资料日期为 2026-10-23；接口与操作说明依据可检查的源码和已有记录整理，实际可用范围以所安装版本和对应验收结果为准。

## 从这里开始

首次了解产品，先读[快速开始](https://document.thestarline.cn/app/getting-started.md)与[功能及平台范围](https://document.thestarline.cn/app/features.md)。开发者可沿[系统架构](https://document.thestarline.cn/app/architecture.md)、[登录与会话](https://document.thestarline.cn/app/authentication.md)、[API 参考](https://document.thestarline.cn/app/api-reference.md)进入协议；维护者可从[开发配置](https://document.thestarline.cn/app/development.md)、[测试验收](https://document.thestarline.cn/app/testing.md)、[运维](https://document.thestarline.cn/app/operations.md)和[故障排查](https://document.thestarline.cn/app/troubleshooting.md)进入实际流程。

| 主题 | 阅读入口 |
| --- | --- |
| 原生客户端 | [iOS](https://document.thestarline.cn/app/ios.md)、[Android](https://document.thestarline.cn/app/android.md)、[权限与无障碍](https://document.thestarline.cn/app/permissions-accessibility.md) |
| 消息与在线能力 | [消息及媒体](https://document.thestarline.cn/app/messaging-and-media.md)、[实时同步与通话](https://document.thestarline.cn/app/realtime-and-calls.md)、[城市贴纸](https://document.thestarline.cn/app/city-stickers.md) |
| 本机个人资料 | [本地记忆](https://document.thestarline.cn/app/local-memory.md)、[医疗健康记录](https://document.thestarline.cn/app/medical-records.md) |
| 服务与数据 | [数据模型](https://document.thestarline.cn/app/data-model.md)、[安全和隐私](https://document.thestarline.cn/app/security-and-privacy.md)、[配置与环境](https://document.thestarline.cn/app/configuration.md) |
| 交付与公开访问 | [版本发布](https://document.thestarline.cn/app/releases.md)、[文档访问与引用](https://document.thestarline.cn/app/ai-access.md) |

## 按具体工作查阅

| 需要完成的工作 | 建议顺序 | 应得到的结论 |
| --- | --- | --- |
| 接入一次完整登录 | [登录与会话](https://document.thestarline.cn/app/authentication.md) → [协议示例](https://document.thestarline.cn/app/protocol-recipes.md) → [客户端生命周期](https://document.thestarline.cn/app/client-lifecycle.md) | 两层 proof、回调校验、pending 恢复及会话失效如何处理 |
| 接入消息和附件 | [好友与群](https://document.thestarline.cn/app/contacts-and-groups.md) → [消息与媒体](https://document.thestarline.cn/app/messaging-and-media.md) → [API](https://document.thestarline.cn/app/api-reference.md) | 关系权限、上传引用、重复发送、分页及本人删除的含义 |
| 开发新事与定位 | [新事](https://document.thestarline.cn/app/moments.md) → [位置共享](https://document.thestarline.cn/app/location-sharing.md) → [权限](https://document.thestarline.cn/app/permissions-accessibility.md) | 可见范围、媒体处理、开始/更新/停止及拒绝权限后的状态 |
| 调整本机记忆或工作台 | [工作台](https://document.thestarline.cn/app/workbench.md) → [本机格式](https://document.thestarline.cn/app/local-data-formats.md) → [记忆转出](https://document.thestarline.cn/app/memory-export.md) | 哪些数据按设备保存、如何兼容旧字段、失败时如何保留原库 |
| 分析加密能力 | [安全与隐私](https://document.thestarline.cn/app/security-and-privacy.md) → [MLS协议](https://document.thestarline.cn/app/mls-protocol.md) | 当前普通消息链路、独立加密协议与本机加密的准确范围 |
| 准备联调环境 | [模块地图](https://document.thestarline.cn/app/module-map.md) → [开发](https://document.thestarline.cn/app/development.md) → [配置参考](https://document.thestarline.cn/app/configuration-reference.md) | 当前权威源码、依赖、配置校验及隔离测试的限制 |
| 执行回归或发行 | [测试矩阵](https://document.thestarline.cn/app/qa-matrix.md) → [发行检查](https://document.thestarline.cn/app/release-checklist.md) → [运维](https://document.thestarline.cn/app/operations.md) | 每个场景的前置条件、预期结果、证据与回滚对象 |
| 排查已有故障 | [故障排查](https://document.thestarline.cn/app/troubleshooting.md) → [处置步骤](https://document.thestarline.cn/app/incident-runbooks.md) → [限制与错误](https://document.thestarline.cn/app/limits-and-errors.md) | 失败发生在哪一层、能否重试、怎样核对恢复结果 |

阅读接口时先确认对象所属产品、当前账号和会话范围。阅读本机格式时先确认平台与安装环境。名词、ID、时间单位和删除状态可随时对照[术语参考](https://document.thestarline.cn/app/glossary.md)，避免把同名字段跨服务或跨资源使用。

## 产品和系统入口

星线 App 将联系、分享与本机日常记录放在一起。iOS 使用 SwiftUI，Android 使用 Jetpack Compose；聊天服务负责在线会话、消息、媒体、新事与相关权限，星线 Account 提供身份认证与授权。本机记忆、个人任务和收藏有独立的设备端存储边界。

| 公开入口 | 用途 |
| --- | --- |
| [App 官网](https://app.thestarline.cn/) | 产品介绍与真实下载状态 |
| [星线 Account](https://account.thestarline.cn/) | 账户登录、授权与账号管理 |
| `https://chat.thestarline.cn` | 客户端聊天 API 基地址，受保护接口需要聊天会话 |
| [App 隐私说明](https://privacy.thestarline.cn/app-privacy.html) | 对用户生效的 App 隐私说明 |
| [支持](https://support.thestarline.cn/) | 产品支持入口 |

本技术文档解释实现，不替代法律文本、正式服务承诺或对某个账号的访问授权。公开聊天 API 地址不是匿名读取他人数据的入口。

## 怎样理解实现状态

文档区分源码中可确认的实现、历史保存的测试记录，以及仍需要当前环境验证的事项。代码中有路由说明服务端存在该契约；客户端有调用说明该构建包含相应路径；真实设备、跨网络、推送与渠道状态需要各自证据。文档整理不会替代这些业务验收。

当前下载站仍将 iOS 与 Android 标为准备中。没有可据此宣称已公开上架的 App Store 链接或正式稳定 APK。Android 存在历史真实授权和冷启动恢复记录；iOS 真实账号完整链路、iPad 可用性、跨网络通话与后台来电等仍有独立验收要求。watchOS 独立应用尚未交付，星线智联小程序发布流程已暂停。详情见[发布状态](https://document.thestarline.cn/app/releases.md)。

新增专题写到具体约束与差异：例如临时好友码的消费顺序、群主退出后的转移、客户端视频缓存方式、位置停止失败、本地字段兼容和记忆转出依赖。源码中发现的差异会标明核对位置与待验场景，不把“建议实现的行为”写成“当前必然如此”。

## 数据与加密的重要边界

本机记忆主体和附件使用设备端加密保存；它们目前没有跨设备云同步。退出账号、卸载、删除记忆和转出文件是不同操作，不能互相推断。

聊天服务存在 MLS 加密核心和独立加密事件协议，但当前默认客户端聊天发送仍使用普通消息接口，附件也没有完整的客户端密文封装链路。因此不承诺所有当前聊天和附件已经完成端到端加密。阅读[安全和隐私](https://document.thestarline.cn/app/security-and-privacy.md)了解 TLS、本机加密、服务端字段加密与 MLS 的不同范围。

## 文档中的示例与配置

JSON 中的 UUID、消息编号、时间和文字是合成示例；配置只给变量名、用途、默认与启用条件，不给运行凭据。命令默认用于已隔离的开发或测试环境，涉及写入的步骤需使用授权测试账号。完整返回字段、分页边界、权限和错误状态应结合相邻表格阅读，不从单个成功响应推导全链路可用。

Account 与 App 使用独立维护来源。App 工作树附带的历史 Account 文件可能落后于当前身份服务，配置和迁移以当前 Account 权威源码为依据；模块归属和核对方法见[源码模块地图](https://document.thestarline.cn/app/module-map.md)。

## 文档格式与引用

每篇文章提供 HTML 页面与 Markdown 原文，正文不依赖 JavaScript。可通过[文档清单](https://document.thestarline.cn/app/catalog.json)查看目录，或下载[完整文本](https://document.thestarline.cn/llms-full.txt)。引用时请注明文章标题、原始地址和资料日期，具体规则见[文档访问与引用](https://document.thestarline.cn/app/ai-access.md)。


原始地址：https://document.thestarline.cn/app/getting-started/
Markdown：https://document.thestarline.cn/app/getting-started.md

# 快速开始

本页帮助用户、开发者和测试人员找到正确入口。星线 App 当前处于开发与发布准备阶段；先核对你正在使用的版本和环境，再进行登录、存储或协议测试。

## 查看可用版本

到 [App 官网](https://app.thestarline.cn/#downloads)查看 iOS 和 Android 的发布状态。没有真实公开下载地址时，页面显示准备中。开发预览截图、源码中的版本号、签名成功或商店草稿都不能证明可公开下载。

取得开发预览包时，应确认提供方、平台、构建版本、签名与服务器环境。不要把未经核对的第三方 APK 当作正式发行版，也不要为了复现问题卸载保存个人记忆的现有 App。正式发布条件见[版本发布](https://document.thestarline.cn/app/releases.md)。

## 一次正常的使用路径

1. 打开 App，查看聊天、工作台和我的等主要入口；具体布局以平台和构建为准。
2. 使用聊天功能时进入星线账户登录；系统浏览器承载 Account 身份认证与授权，App 不应自己模拟 Account 登录页。
3. 确认授权应用名称为“星线 App”，授权说明为：正在为“星线 App”授权您的账号信息数据。
4. 完成授权后返回 App，客户端换取聊天会话并恢复用户资料。
5. 在已有权限的会话发送消息，或在本机建立记忆、个人任务与收藏。

账号授权成功、返回 App 成功和聊天会话建立成功是三个需要分别观察的步骤。授权码和一次性 ticket 不能重复使用，回调失败时应重新发起登录，不复制带参数的完整回跳链接给他人。协议说明见[登录与会话](https://document.thestarline.cn/app/authentication.md)。

## 登录停在某一步时

| 看到的状态 | 先检查什么 | 后续动作 |
| --- | --- | --- |
| App 尚未打开 Account | 当前构建的聊天地址、网络和授权开始响应 | 先定位请求是否成功，不反复改账号密码 |
| 浏览器仍停在验证或授权页面 | 用户是否完成当前步骤，页面是否报错或要求补充验证 | 按页面完成必要验证；取消后从 App 重新发起 |
| 浏览器结束但 App 未回到前台 | 回调 scheme、系统是否允许返回、对应构建是否仍安装 | 记录平台与停留页面；不要将回跳 URL 公开发送 |
| App 收到回调但显示失败 | state、到期、pending、ticket 和换票请求 | 同一次流程必须匹配；重新开始，而不是混用旧参数 |
| 已登录后重开变为未登录 | 聊天会话到期、安全存储与恢复读取结果 | 区分会话失效和读取失败，不清空记忆作为修复 |

Android 当前信任正式 Account HTTPS 授权来源；将聊天服务切到本地不等于已经完成本地原生授权配置。开发人员应先阅读[开发配置](https://document.thestarline.cn/app/development.md)，不要按端口连通推断整个原生流程可用。

## 先区分在线与本机功能

| 使用内容 | 依赖 | 需要注意 |
| --- | --- | --- |
| 聊天、新事、媒体和通话 | 聊天会话、网络与对应服务 | 对方关系、群成员或媒体权限决定可见范围 |
| 记忆主体和记忆附件 | 当前设备的本地存储与密钥 | 当前没有云同步，另一设备不会自动获得内容 |
| 个人任务、收藏 | 客户端本地数据 | 不等同于独立星企产品的企业待办 |
| 城市定位选择 | 操作触发的位置权限或允许的城市来源 | 拒绝权限不应阻止选择其他适用城市 |

重要记忆在卸载、换机或清理应用数据前需要单独处理。转出 JSON 不等于已有完整导入恢复；本机加密也不能保护已经转出的明文文件。详见[本地记忆](https://document.thestarline.cn/app/local-memory.md)。医疗健康模板是个人记录工具，不提供诊断、健康平台自动同步或已交付的用药提醒，详见[医疗记录](https://document.thestarline.cn/app/medical-records.md)。

## 第一次发送与记录

聊天应先确认好友或群成员关系，再发送一条没有敏感内容的测试文字。附件分成上传和发送引用两个阶段，上传成功但第二步失败时，不能按对方已收到处理。重复点击或网络重试应对应同一个发送意图，客户端通过 clientId 与服务端消息 ID 合并，见[消息与媒体](https://document.thestarline.cn/app/messaging-and-media.md)。

建立记忆时可先用合成标题、正文和一个小附件检查保存、列表、搜索、编辑与重开。确认原文件和预览都能读取后，再使用个人资料。选择了主题但所有内容均为空时不会保存一条空记录。附件名参与搜索，附件正文当前不等于已执行 OCR 或全文索引。

工作台的个人任务和收藏也保存在设备上。两端的筛选与时间展示有差异，例如 iOS 有任务标题/备注搜索和独立逾期筛选，Android 当前不能按同一界面能力假定完全对等。完整字段、操作及排序说明见[个人工作台](https://document.thestarline.cn/app/workbench.md)。

## 权限在对应操作中处理

选择城市、扫码、视频和实时位置分别需要不同系统能力。拒绝相机后可用的图片/粘贴路径、拒绝定位后的城市选择、仅音频入会，以及系统设置重新授权，都应按实际入口判断。不要将一种权限拒绝解释为账号失效。

实时位置开始后要分别确认本机持续采集状态和服务端共享状态。停止失败时仍需读取和确认远端是否已移除；简单离开页面不等于共享已终止。详细步骤见[位置共享](https://document.thestarline.cn/app/location-sharing.md)和[权限说明](https://document.thestarline.cn/app/permissions-accessibility.md)。

## 更新、退出与换机前

更新前核对构建来源与签名兼容，优先保留既有应用数据。记录保存在当前设备不等于按聊天账号分别隔离；修改 Account 密码、退出或切换账号不会自动删除、重加密本机记忆。退出界面完成也不一定证明远端 logout 请求已经成功。

换机或清理前先查[记忆转出](https://document.thestarline.cn/app/memory-export.md)和[本机格式](https://document.thestarline.cn/app/local-data-formats.md)。转出还依赖额外许可流程，当前跨服务闭环仍需核验；不能在未经验证的前提下把它作为唯一备份，更不能因已有 JSON 就认定当前版本一定支持导入恢复。读取损坏或密钥不可用时保留原安装和原文件，避免覆盖式修复。

## 开发者的最短阅读路线

先读[系统架构](https://document.thestarline.cn/app/architecture.md)了解职责，再按目标平台阅读 [iOS](https://document.thestarline.cn/app/ios.md)或 [Android](https://document.thestarline.cn/app/android.md)。准备构建和隔离联调时使用[开发配置](https://document.thestarline.cn/app/development.md)，核对[环境及配置](https://document.thestarline.cn/app/configuration.md)。接口实现以[API 参考](https://document.thestarline.cn/app/api-reference.md)为入口，尤其注意聊天 token 与 Account token 的区别。

公开文档不提供生产客户端密钥、受保护数据库或实际用户测试账号。API 表格是协议说明，不代表第三方 App 自动获得注册、访问或生产接入许可。测试应使用明确隔离的合成数据，验收清单见[测试](https://document.thestarline.cn/app/testing.md)。

接口调用可按[协议示例](https://document.thestarline.cn/app/protocol-recipes.md)先核对 `/me`、分页、幂等发送、媒体引用和事件游标，再处理附加能力。开发测试与真实分发的检查项不同；需要准备发行包时，使用[发行检查清单](https://document.thestarline.cn/app/release-checklist.md)，逐项记录签名、版本、安装、授权、数据兼容及渠道状态。

## 遇到问题时记录什么

保留平台、系统版本、App 构建版本、发生时间、网络类型、操作步骤和已脱敏的错误提示。涉及回调时只描述停留在哪一步；涉及记忆时先区分保存失败、列表未刷新、文件权限或密钥不可用。不要把验证码、token、病历正文、聊天内容或含敏感参数的 URL 写入公开问题。

前端可打开、API 健康、短信/邮件到达和双端消息可用分别验证。[故障排查](https://document.thestarline.cn/app/troubleshooting.md)提供定位顺序，[支持站](https://support.thestarline.cn/)提供后续联系入口。


原始地址：https://document.thestarline.cn/app/features/
Markdown：https://document.thestarline.cn/app/features.md

# 功能及平台范围

本页把星线 App 的主要能力与交付边界放在一起比较。表格表示截至 2026-10-23 可从当前源码确认的入口或模块，不表示每个版本、设备和生产账号都已完成端到端验收。实际发布条件见[版本发布](https://document.thestarline.cn/app/releases.md)。

## 功能矩阵

| 能力 | iOS | Android | 边界与后续核验 |
| --- | --- | --- | --- |
| 星线账户登录 | 原生发起、系统授权浏览器、回跳换票 | 原生发起、系统授权浏览器、回跳换票 | 两端有 PKCE 及会话恢复；iOS 真实账号完整链路仍需独立验收 |
| 单聊与群聊 | 会话、消息和状态界面 | 会话、消息和状态界面 | 网络、成员权限和服务状态决定可用性 |
| 消息媒体 | 图片与普通文件上传引用 | 图片与普通文件上传引用 | 专用视频选择与播放属于新事；附件 E2EE 尚未闭环 |
| 新事 | 发布、阅读及互动入口 | 发布、阅读及互动入口 | 与聊天媒体有独立的数据及权限边界 |
| 城市贴纸 | 素材、选择和位置适配 | 素材、选择和位置适配 | 44 城素材三端一致；真实定位与网络场景另验 |
| 本地记忆 | 本机加密主体与附件、主题模板 | 本机加密主体与附件、主题模板 | 没有跨设备云同步；转出与恢复能力分开核验 |
| 医疗健康记录 | 结构化模板和关联记录 | 结构化模板和关联记录 | 个人归档，不是诊断、健康平台接入或提醒服务 |
| 本地任务与收藏 | 个人日常入口 | 个人日常入口 | 本机功能，不是星企企业组织/频道功能 |
| 语音与视频通话 | LiveKit、系统通话相关接入 | LiveKit、通话界面相关接入 | 两台真机跨网络、后台与锁屏来电尚需验收 |
| MLS 加密协议 | 有独立传输模块及设备密钥准备 | 未发现原生 OpenMLS 主消息接入 | 默认聊天路径不能标为全量已验收 E2EE |

双端共享产品方向，但界面组织、系统权限、后台执行和安全存储分别使用平台机制。不能用 Android 一次历史成功替代 iOS 验收，也不能用模拟器截图代替实体设备权限与推送结果。

## 双端差异应怎样核对

| 场景 | 当前需要区分的实现 | 详细说明 |
| --- | --- | --- |
| 原生登录中断 | iOS 保存 API 基地址与待换票 ticket；Android pending 字段及清理时机不同 | [登录](https://document.thestarline.cn/app/authentication.md)、[生命周期](https://document.thestarline.cn/app/client-lifecycle.md) |
| 个人任务筛选 | iOS 有今天/逾期/完成及搜索；Android 当前待办/已完成/全部，首页今日统计另有截止条件 | [工作台](https://document.thestarline.cn/app/workbench.md) |
| 记忆序列化 | iOS 与 Android 的记录字段、日期表示和加密文件封装不同 | [本机格式](https://document.thestarline.cn/app/local-data-formats.md) |
| 新事视频 | 服务端支持单个Range，但当前客户端先完整下载后播放 | [新事](https://document.thestarline.cn/app/moments.md) |
| 实时位置停止 | 页面操作与持续通知停止分支的本机/远端顺序不同 | [位置共享](https://document.thestarline.cn/app/location-sharing.md) |
| MLS阻塞恢复 | 服务端有重建与确认契约，不等于客户端会自动完成所有重键 | [MLS协议](https://document.thestarline.cn/app/mls-protocol.md) |

这些差异影响测试步骤与失败恢复。改进任一端时应先明确目标行为，再核对相同字段在另一端如何保存、搜索、展示和转出，不能仅以同一功能名称认定数据格式互换。

## 哪些功能需要账号

在线聊天服务以聊天 Bearer token 识别用户，再按会话成员、好友关系、群成员、媒体所属和通话参与者检查权限。Account 负责身份认证，聊天服务负责在线业务授权；知道公开 API 地址或对象 ID 不赋予访问权。

好友申请、临时码、删除、屏蔽和群成员变化有各自的消费与清理顺序。新事的 public 指已登录 API 用户可见；媒体还要通过帖子或消息可见性检查。个人群的群主退出、本人隐藏聊天、退群和完整解散不属于同一种操作，见[好友与群](https://document.thestarline.cn/app/contacts-and-groups.md)与[新事](https://document.thestarline.cn/app/moments.md)。

记忆主体存于设备，个人任务和收藏也有本地数据边界。登录、退出、清理本机和服务端账号处理需要分别理解，详见[数据模型](https://document.thestarline.cn/app/data-model.md)与[本地记忆](https://document.thestarline.cn/app/local-memory.md)。

## 网络与离线

在线消息和新事需要后端。事件流帮助客户端重新获取状态，但它不是聊天正文的永久备份。发送队列、重试与去重用于恢复操作，不等于所有离线操作都会自动成功。

本机记忆可以在设备上保存与读取；涉及服务器识别、转出授权或其他网络功能时仍需要相应服务。服务器识别与本地规则提取是不同路径，提交到模型的字段与隐私边界需按[本地记忆](https://document.thestarline.cn/app/local-memory.md)和[安全和隐私](https://document.thestarline.cn/app/security-and-privacy.md)核对。

## 按数据类型比较上限

聊天文件、聊天贴纸、新事图片/视频与本机记忆附件由不同入口控制。普通聊天上传文件为10MiB级限制，本机单个记忆附件为20MiB级限制，新事视频另有30MiB级限制；具体字节值、数量、账号总量和宽高要求见[限制与错误](https://document.thestarline.cn/app/limits-and-errors.md)。在界面显示“附件过大”时，需要指出当前是哪一种附件，而不是用一个通用大小覆盖所有功能。

同样，消息正文、医疗长字段、标题和 JSON 请求整体都有各自限制。原生字符串长度与服务端码点计数也可能不同，前端通过不代表服务端一定通过。字段长度、类型与迁移细则见[本机格式](https://document.thestarline.cn/app/local-data-formats.md)和[医疗健康记录](https://document.thestarline.cn/app/medical-records.md)。

## 检查一个功能是否完整可用

先检查代码入口和运行依赖，再验证正常路径、权限拒绝、重复操作、断网、中断恢复和升级后的数据兼容。网络功能还需核对服务端实际状态，本机功能还需核对重新打开与密钥可用性。音视频与推送必须补充两台真实设备及跨网络场景。

每个结论应包含平台、构建、系统版本、环境、操作步骤和证据。详细矩阵见[测试场景](https://document.thestarline.cn/app/qa-matrix.md)，出现异常后按[故障处置](https://document.thestarline.cn/app/incident-runbooks.md)分阶段处理。仅有源码或历史记录的能力继续标明范围，不因本页文字增加而自动改变交付状态。

## 单独列出的未交付事项

- watchOS 独立联网应用尚未交付，当前 iOS 工程不能作为 watchOS 成品说明。
- iPad 可用性与 App Store 审核需单独处理；已进入审核流程不等于已公开上架。
- 当前记忆没有设备间云同步，没有可据转出 JSON 推导的完整导入恢复。
- 没有已交付的系统健康平台自动写入、医疗诊断或用药推送提醒。
- 全量聊天与附件 E2EE、跨网络音视频和后台来电不能仅凭模块存在认定完成。

## 与其他星线产品的关系

星线 Account 是共享身份系统。星企是独立企业产品；同一聊天服务存在的 `/enterprise/*` 接口不表示星线 App 前台已经提供企业组织、企业频道、审批或企业待办。星线智联小程序有独立上传与发布状态，当前流程已暂停。各产品共享组件时，仍按各自的客户端、权限和发布记录判断可用性。


原始地址：https://document.thestarline.cn/app/architecture/
Markdown：https://document.thestarline.cn/app/architecture.md

# 系统架构

星线 App 由 iOS、Android 原生客户端、聊天服务、星线 Account 身份服务及通话媒体服务组成。本页依据当前源码说明组件责任、请求路径与实现边界；源码中存在的模块不自动代表客户端已经接入，也不代表生产环境已经完成验收。

## 组件与责任

| 组件 | 责任 | 主要技术 |
| --- | --- | --- |
| iOS 客户端 | 原生登录、聊天、新事、记忆、位置与通话界面；会话和本地加密状态管理 | Swift、SwiftUI、Keychain、CryptoKit、LiveKit |
| Android 客户端 | 原生登录、聊天、新事、记忆、位置与通话界面；本地安全存储 | Kotlin、Jetpack Compose、Android Keystore、LiveKit |
| 聊天服务 | 将 Account 身份映射为聊天用户；会话、好友、群、消息、媒体、新事、事件与通话状态 | Node.js 24 及以上、ES modules、HTTP、内置 SQLite |
| Account | 登录、注册、身份验证、授权页面、OIDC 授权码与用户信息 | 独立身份系统，OIDC issuer 为 `https://account.thestarline.cn/oidc` |
| 加密核心 | MLS 设备、密钥包、群状态、消息验证与加密状态持久化 | Rust、OpenMLS，C ABI 与 WebAssembly 适配 |
| 媒体与推送 | 音视频房间、短期加入凭证、iOS VoIP 来电唤醒 | LiveKit、APNs VoIP |

公开聊天 API 基地址是 `https://chat.thestarline.cn`。下载站及本技术文档位于 `https://app.thestarline.cn`，它们与鉴权 API 分属不同入口。客户端不持有 Account 的机密客户端凭据、LiveKit 服务端密钥或 APNs 签名私钥。

![系统架构：iOS 与 Android 经 HTTPS 访问聊天服务，使用系统浏览器授权；聊天服务连接 Account、SQLite、LiveKit 与 APNs；MLS 核心目前仅有 iOS 独立适配及服务端 WASM 校验器。](https://document.thestarline.cn/app/architecture.svg)

两端通过系统浏览器进入 Account，经聊天服务的授权码回调完成换票；聊天 API 使用 HTTPS JSON、二进制及事件长轮询。通话媒体由客户端直接连接 LiveKit，聊天服务只负责状态、房间控制和短期凭证。图中 MLS 是独立模块能力，不代表默认消息路径已启用。

## 一次登录怎样变成聊天会话

原生客户端生成本机 `codeVerifier`，向 `/auth/native/start` 发送 S256 `codeChallenge`。聊天服务保存挑战并另行生成 Account 授权所用的 verifier、state；浏览器完成 Account 授权后回到 `https://chat.thestarline.cn/auth/callback`。服务端使用机密客户端认证及自己的 verifier 换取 Account 访问令牌，再读取用户信息，将 `sub` 映射到本地聊天用户。

最终返回 App 的是一次性聊天 ticket。App 必须向 `/auth/exchange` 同时提交 ticket、原 state 和本机 verifier，才能获得聊天 Bearer token。Account 访问令牌不会作为聊天 token 下发。详见[登录与会话](https://document.thestarline.cn/app/authentication.md)。

## 数据与同步路径

聊天服务使用 `node:sqlite` 的同步连接，启用外键、WAL 和 5 秒 busy timeout。消息写入、去重和事件生成通常在 `BEGIN IMMEDIATE` 事务中完成，因此客户端可以用同一个 `clientId` 安全重试同一条发送。这个实现模型适合单个服务进程与其数据库协作；当前进程内的长轮询等待器不会在多个实例间自动广播，扩展部署需要另行设计通知和数据一致性方案。

`/events` 是按用户过滤的增量变更通知，携带事件 ID、会话或群 ID 和可选消息 ID，不携带完整聊天正文。客户端收到事件后重新获取列表、消息或通话状态。消息 ID、普通事件 ID、MLS sequence 是不同序列，不能混用。

媒体以 BLOB 保存，客户端先上传取得 `media.id`，随后发送引用该 ID 的消息。下载会重新检查当前用户对媒体的可见性。新事媒体使用单独的数据表、配额和权限规则。记忆主体主要由原生客户端管理，聊天服务提供识别和转出许可桥接，并不存在一组可据此推导的“云端记忆 CRUD”接口。详见[数据模型](https://document.thestarline.cn/app/data-model.md)与[消息和媒体](https://document.thestarline.cn/app/messaging-and-media.md)。

## 加密模块与当前主链路

Rust 核心支持 MLS 1.0，固定使用 `MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519` 套件。聊天服务提供设备密钥包、会话准备、Welcome、Commit、应用密文事件和确认接口。iOS 有独立 `ChatEncryptedTransport` 处理文字密文同步、设备签名密钥固定、离线队列及确认恢复。

当前 iOS `ChatStore` 主聊天发送与 Android 发送仍走普通 `/messages` 路径；iOS 会准备设备密钥包，但不能仅凭此认定某个聊天已启用 MLS。普通媒体上传没有独立附件密钥、客户端封装密文或附件解密路径。文档因此将“加密模块能力”“实际主聊天路径”“生产验收结果”分别说明。已准备的 MLS 会话会拒绝继续通过普通接口发送明文，不能通过回退接口绕过模式约束。

## 产品边界与验收

共享后台还包含 `/enterprise/*` 企业组织、成员、企业频道、待办、公告和服务接口。这些服务于独立的星企产品，使用企业成员与角色校验；不能把它们列为星线 App 的前台工作台功能，也不能把个人聊天群等同于企业频道。

通话 HTTP 状态机、LiveKit SDK 接入和 APNs 发布器均可从源码确认。真实双设备跨网络音视频、后台来电、锁屏接听和生产 APNs 到达率需要单独验收。服务健康返回 `ok` 只说明 HTTP 服务可响应，不证明 Account、模型、MLS 校验器、媒体或推送全部可用。继续阅读[实时同步与通话](https://document.thestarline.cn/app/realtime-and-calls.md)、[测试](https://document.thestarline.cn/app/testing.md)、[运维](https://document.thestarline.cn/app/operations.md)与[安全和隐私](https://document.thestarline.cn/app/security-and-privacy.md)。

深入流程见[联系人与个人群](https://document.thestarline.cn/app/contacts-and-groups.md)、[新事](https://document.thestarline.cn/app/moments.md)、[位置共享](https://document.thestarline.cn/app/location-sharing.md)和[MLS协议](https://document.thestarline.cn/app/mls-protocol.md)；数值与失败处理集中在[限制与错误](https://document.thestarline.cn/app/limits-and-errors.md)。


原始地址：https://document.thestarline.cn/app/authentication/
Markdown：https://document.thestarline.cn/app/authentication.md

# 登录、授权与会话

星线 App 使用星线 Account 完成身份验证，再由聊天服务签发独立的聊天会话。原生客户端通过系统浏览器参与授权，不把 Account 密码交给聊天服务；当前原生协议同时保护 Account 授权码交换和 App 聊天票据交换。

## 地址与身份边界

| 项目 | 地址或规则 |
| --- | --- |
| 聊天 API | `https://chat.thestarline.cn` |
| Account issuer | `https://account.thestarline.cn/oidc` |
| 正式 HTTPS 授权回调 | `https://chat.thestarline.cn/auth/callback` |
| 星线 App 返回入口 | `starlineworkbench://chat-auth` |
| 星企返回入口 | `xingqiworkbench://auth`，仅用于独立星企产品 |
| 授权范围 | `openid email profile phone` |

聊天服务通过 issuer 的 `/.well-known/openid-configuration` 获取授权、令牌和用户信息端点，检查返回 issuer 完全一致，且这三个端点位于配置 issuer 的同源范围。生产启动还要求正式 Account issuer、HTTPS 公网 URL 和服务端机密 OIDC 客户端配置。具体客户端 ID、密钥和注册记录不属于公开示例。

## 原生登录的两层证明

1. App 使用系统安全随机源生成 32 字节随机值，编码为不带填充的 base64url verifier，并计算 `BASE64URL(SHA256(verifier))`。
2. App 调用 `POST /auth/native/start`，发送 `{app:"starline",codeChallenge,screen:"login"}`。注册入口可把 `screen` 设为 `register`。
3. 聊天服务验证挑战是规范的 43 字符 base64url，创建有效期 10 分钟的登录 flow。响应包含 `authorizationURL`、`state`、`expiresAt`。客户端须保存本次 verifier、state 和到期时间，再打开返回 URL；iOS 还保存 API 基地址。
4. 聊天服务另行生成自己的 verifier，与 S256 挑战发送给 Account。原生入口设置 `prompt=login`；注册入口额外设置 `screen_hint=signup`。这层 verifier 留在聊天服务端。
5. Account 将授权码和 state 回调到正式 HTTPS 地址。聊天服务一次性消费 flow，使用 `client_secret_basic`、授权码和服务端 verifier 请求令牌，随后请求用户信息。
6. 聊天服务要求 `sub` 非空，并要求邮箱已验证或手机号已验证。已验证手机号会规范化；显示名按 name、邮箱前缀和默认名称取值，最多保存 80 个 UTF-16 代码单元。
7. 服务端创建有效期 60 秒的一次性 ticket，将 ticket 与原 state 放入 App 返回 URL。App 对返回入口和参数做校验后，调用 `POST /auth/exchange`，提交 `{ticket,state,codeVerifier}`。
8. 服务端核对 state 哈希与 App verifier 的 S256 值，消费 ticket，签发聊天会话；响应为 `{accessToken,expiresAt,user,eventCursor}`。

两层 verifier 是不同随机值：服务端的一层保护 Account 授权码，App 的一层让仅截获自定义 scheme ticket 的程序无法单独换取聊天会话。客户端不能直接拿 Account access token 调用聊天业务接口。

## 到期、消费与失败语义

| 对象 | 默认有效期 | 重放处理 |
| --- | --- | --- |
| 原生登录 flow | 10 分钟 | HTTPS 回调读取时删除；过期或错误回调返回 `login_failed` |
| 兼容 `/auth/start` flow | 40 分钟 | 仅为兼容浏览器入口，不能替代原生证明流程 |
| 聊天 ticket | 60 秒 | 成功换取后删除；错误原生 proof 不签发会话 |
| 聊天 device session | 24 小时 | 每次 Bearer 请求检查哈希与到期时间 |

`expiresAt` 是 Unix 毫秒时间戳。不要把 Account OIDC token 的期限当成聊天会话期限；当前 Account 源码的访问令牌和 ID token TTL 为 900 秒，授权码为 60 秒。它们用于身份协议，不是 App 业务会话的刷新机制。聊天服务当前没有公开 refresh-token 路由。

原生开始接口可能返回 `INVALID_APP`、`INVALID_CHALLENGE`、`INVALID_SCREEN` 或 `LOGIN_UNAVAILABLE`。票据缺失、过期、已消费、state 不匹配或 verifier 不匹配会导致 `INVALID_TICKET`。客户端应重新开始授权；不能删除 proof 参数去尝试兼容 ticket 模式。错误响应形状见[API 参考](https://document.thestarline.cn/app/api-reference.md)。

## 客户端回调和持久化

iOS 只接受预期 scheme 与 host，拒绝用户名、密码、端口、fragment、异常 path、重复 state、重复 ticket/error，以及 ticket 与 error 同时出现。回调 state 必须等于当前未到期 flow，且必须属于同一 API 基地址。iOS 在交换前保存 ticket，支持进程中断后恢复；成功后先持久化 session，再清理 pending 状态，避免清理失败把已成功登录改成失败。

Android 的 pending 仅保存 verifier、state、expiresAt，没有 iOS 的 API 基地址和 ticket 字段；回调通过校验后会先清除 pending，再发起换票。它不能据此获得与 iOS 相同的“换票中进程中断后持久恢复”能力，失败时需重新开始授权。两端的实现与调试方法分别见[iOS](https://document.thestarline.cn/app/ios.md)和[Android](https://document.thestarline.cn/app/android.md)。登录 token 不应写入普通 URL、截图、日志、分析事件或静态网站。iOS 使用 Keychain，Android 使用 Keystore 支持的本地加密存储。

## 使用与退出

除健康检查和授权入口外，聊天 API 使用 `Authorization: Bearer <chat_access_token>`。服务端接受规定格式的 Bearer token，并将其 SHA-256 摘要与未过期 session 记录匹配。`GET /me` 返回当前聊天用户与该用户最新 `eventCursor`，可用于恢复登录后的状态同步。

`POST /auth/logout` 成功时删除当前聊天会话；它不等于 Account 全站退出或撤销其他设备。两端都会清除本机状态，并忽略远端退出请求失败；Android 先清本机再尝试服务端退出，iOS 尝试释放通话、注销推送和服务端退出后清本机。所以“已退出界面”不能证明服务端撤销成功：网络失败时，旧 session 可能持续到 24 小时到期。Account 修改密码或撤销 Account 会话也没有自动联动撤销聊天 session 的实现。

VoIP 设备与具体 session 摘要关联，服务端注销或到期后不会继续被查询为该会话的有效推送目标。本机退出还会停止轮询、释放媒体连接并清理当前账号界面状态；这些本机动作与远端 token 撤销应分别验证。

## 记忆转出许可的独立边界

聊天服务还有 `/memory-export/start` 与 `/memory-export/exchange`，用于当前登录用户的额外转出验证，不能用于普通登录。开始流程有效期 5 分钟；服务端向 Account 的 redeem 接口验证 ticket、state、verifier，并检查返回用户与当前 Account subject 一致。

当前作为权威依据的 Account 主源码未包含对应 redeem 路由；App 工作树随附的历史 Account 副本虽然有实现，也不能替代当前主源码或证明其已部署。因此只能确认聊天侧桥接契约，不能认定该跨服务流程当前可用。客户端本地导出和 Account 验证是否完整闭环，应按照[测试](https://document.thestarline.cn/app/testing.md)取得实际结果后再更新状态。


原始地址：https://document.thestarline.cn/app/api-reference/
Markdown：https://document.thestarline.cn/app/api-reference.md

# 聊天服务 API 参考

本页列出当前聊天服务源码的 HTTP 契约，包括星线 App 使用的个人业务接口、独立 MLS 接口及共享后台中属于星企的企业接口。基地址为 `https://chat.thestarline.cn`。路由存在仅代表代码实现，不能证明生产依赖已经配置、客户端已经接入或真实设备路径已经验收。

## 通用约定

除 `GET /health`、`GET /auth/start`、`POST /auth/native/start`、`GET /auth/callback` 和 `POST /auth/exchange` 外，以下接口均要求 `Authorization: Bearer <chat_access_token>`。这是聊天服务签发的 token，不能用 Account access token、OIDC ID token 或 LiveKit 媒体 token 替代。星企接口还要求相应企业成员和角色权限。

JSON 请求使用 `Content-Type: application/json`，根必须为对象，默认请求体上限为 16,384 字节；本文标注的接口有单独上限。二进制上传直接发送文件字节，不是 multipart。JSON 响应为 UTF-8，使用 `Cache-Control: no-store` 与 `X-Content-Type-Options: nosniff`。媒体下载使用单独响应头。

时间值是 Unix 毫秒时间戳。UUID 字段用字符串；普通消息、事件、新事、评论等 ID 为安全整数；企业消息 ID 对外为字符串。分页游标均作用于指定资源，不能互换。下表中的 `{id}` 表示路径参数，不含字面花括号。

错误响应统一为：

```json
{"error":{"code":"INVALID_CURSOR","message":"游标无效"}}
```

| HTTP 状态 | 常见代码与含义 |
| --- | --- |
| 400 | INVALID_JSON、INVALID_CURSOR、INVALID_MESSAGE 等；请求字段或格式无效 |
| 401 | UNAUTHORIZED、INVALID_TICKET；登录失效或票据证明无效 |
| 403 | FORBIDDEN、CONTACT_BLOCKED、NOT_FRIENDS、UNKNOWN_DEVICE；无权执行 |
| 404 | NOT_FOUND、PROFILE_NOT_FOUND、NOT_MEMBER；资源不存在或当前不可访问 |
| 409 | CLIENT_ID_REUSED、E2EE_REQUIRED、CALL_BUSY、CALL_STATE 及 MLS 状态冲突 |
| 413 | TOO_LARGE、STORAGE_LIMIT；单次请求或账号配额超限 |
| 415 | CONTENT_TYPE；JSON 接口未发送 JSON 内容类型 |
| 416 | INVALID_RANGE；新事媒体 Range 无效 |
| 429 | TOO_MANY_LOOKUPS、TOO_MANY_CODES、TOO_MANY_RECOGNITIONS |
| 503 | LOGIN_UNAVAILABLE、E2EE_UNAVAILABLE、CALL_MEDIA_UNAVAILABLE、MEMORY_MODEL_UNAVAILABLE 等依赖不可用 |
| 500 | INTERNAL；未映射的服务异常 |

错误码必须与 HTTP 状态和具体路由一起判断。例如 NOT_FRIENDS 在联系动作中可为403，而建群/邀请成员返回400，邀请还可能是总人数超过50人；不能只按代码名推断唯一原因。详见[限制与错误](https://document.thestarline.cn/app/limits-and-errors.md)。

未支持的路由通常为 404，不保证返回 405。`/__preview/enterprise/session` 被明确禁用，始终返回 404，不是登录或测试会话入口。

## 健康与授权

这些接口无需聊天 Bearer token；授权完成后才获得业务会话。完整信任与到期语义见[登录与会话](https://document.thestarline.cn/app/authentication.md)。

| Method 与路径 | 参数 | 成功响应与限制 |
| --- | --- | --- |
| GET `/health` | 无 | 200 `{status:"ok"}`；仅 HTTP 存活性，不检查全部下游 |
| GET `/auth/start` | query：app 可选 starline/xingqi；screen=register 可进入注册 | 302 Account 授权地址；兼容流程约 40 分钟，原生客户端应使用下一接口 |
| POST `/auth/native/start` | JSON：app 默认 starline；codeChallenge 必填，规范 43 字符 base64url；screen 可选 login/register | 200 `{authorizationURL,state,expiresAt}`；flow 10 分钟，Account PKCE 另由服务端生成 |
| GET `/auth/callback` | Account 回传 query：state、code；授权失败可含 error | 302 App 返回 URL，携带 ticket 与原生 state，或 error=login_failed；正式地址 `https://chat.thestarline.cn/auth/callback` |
| POST `/auth/exchange` | JSON：ticket 字符串最多 128；原生必须另有 state、codeVerifier，verifier 为 43–128 字符 base64url | 200 `{accessToken,expiresAt,user,eventCursor}`；ticket 60 秒且一次性；session 默认 24 小时 |
| POST `/auth/logout` | Bearer；无需业务字段 | 200 `{status:"signed_out"}`；撤销当前聊天 session |

native/start 的 app 不合法返回 INVALID_APP，挑战错误返回 INVALID_CHALLENGE，screen 错误返回 INVALID_SCREEN。服务端 Account token 交换使用机密客户端认证与服务端 PKCE verifier，App 不发送客户端 secret。原生 proof 失败不会签发会话；兼容票据不能携带原生 proof 伪装成新流程。两端本机退出都可能忽略远端logout失败，本机已清除不证明服务端撤销；Account密码变化也不自动撤销独立聊天session。

以下仅示意请求形状。占位挑战、ticket、state 和 verifier 必须由同一次测试授权流程产生，不能照抄为生产凭据：

```sh
curl -X POST 'https://chat.thestarline.cn/auth/native/start' \
  -H 'Content-Type: application/json' \
  --data '{"app":"starline","screen":"login","codeChallenge":"<S256_BASE64URL_43>"}'

curl -X POST 'https://chat.thestarline.cn/auth/exchange' \
  -H 'Content-Type: application/json' \
  --data '{"ticket":"<ONE_USE_TICKET>","state":"<SAME_STATE>","codeVerifier":"<LOCAL_VERIFIER>"}'
```

## 当前用户与资料

所有接口要求 Bearer。`User` 形状为 `{id,displayName,friendId}`。`Profile` 形状为 `{user,bio,contactPhone}`，本人读取时另含 phoneVisibility、visibleToUserIds；不可见手机号为 null。

| Method 与路径 | 参数与权限 | 成功响应 |
| --- | --- | --- |
| GET `/me` | 当前 session | 200 `{user,eventCursor}` |
| GET `/profiles/{userId}` | 目标用户 UUID；按当前用户可见性过滤联系方式 | 200 `{profile}`；用户不存在为 PROFILE_NOT_FOUND |
| PUT `/me/profile` | bio 必填字符串，trim 后 ≤160 字；contactPhone 必填字符串，空字符串清除；phoneVisibility 必填 private/selected/friends/everyone；visibleToUserIds 默认 [] | 200 `{profile}`；指定可见用户最多 100 位、不得重复，必须当前好友，非 selected 不得传非空列表 |
| GET `/blocks` | 当前用户 | 200 `{users:[User...]}` |
| PUT `/blocks/{userId}` | 不能是自己；目标需存在 | 200 `{status:"blocked",conversationId}`；有进行中的单聊通话时先处理媒体与通话状态 |
| DELETE `/blocks/{userId}` | 目标需存在，不能是自己 | 200 `{status:"unblocked",conversationId}` |

手机号删除空格与短横线，11 位中国大陆手机号补 `+86`，其他形式需符合 `+` 开头的 8–15 位国际号码。资料手机号可见性不等于 Account 安全手机号设置。错误包括 INVALID_BIO、INVALID_PHONE、INVALID_VISIBILITY、INVALID_VIEWERS、SELF_BLOCK；屏蔽中媒体服务失败可返回 CALL_MEDIA_UNAVAILABLE。

## 好友与单聊

### 好友建立

| Method 与路径 | 请求或查询 | 成功响应与限制 |
| --- | --- | --- |
| POST `/friend-codes` | JSON `{}` | 201 `{code,expiresAt}`；12 位十六进制临时码，10 分钟；生成新码替换旧码；每用户每 10 分钟最多 10 次生成 |
| GET `/friend-requests` | 无 | 200 `{incoming:[{id,peer,createdAt}],outgoing:[...]}` |
| POST `/friend-requests` | JSON 中 friendId、phone、temporaryCode 三种字符串恰选一种 | 新申请 201、已有同向申请 200；`{status,peer,requestId}` |
| POST `/friend-requests/{requestId}/accept` | 当前用户必须为接收者 | 200 `{status:"accepted",conversationId}` |
| DELETE `/friend-requests/{requestId}` | 当前用户必须为申请双方之一 | 200 `{status:"deleted"}` |
| DELETE `/friends/{conversationId}` | 路径是会话 UUID，当前仍是好友；不是用户 UUID | 200 `{status:"deleted"}`；处理进行中的通话、好友关系与加密阻塞 |

friendId 去空格/短横线并转大写后须 11 位字母数字；temporaryCode 同样规范化后须 12 位 A–F/0–9。手机号和临时码查找分别按用户、方法每 10 分钟最多 20 次。错误包括 INVALID_INPUT、INVALID_FRIEND_ID、INVALID_FRIEND_CODE、SELF_FRIEND、ALREADY_FRIENDS、INCOMING_REQUEST、CONTACT_BLOCKED 和 TOO_MANY_LOOKUPS。未知或过期临时码返回 NOT_FOUND；收到对方申请时应处理 incoming，而不是重复反向申请。

### 单聊列表与消息

| Method 与路径 | 参数与行为 | 成功响应 |
| --- | --- | --- |
| GET `/conversations` | query includeHidden=1 可包含本人隐藏聊天 | 200 `{conversations:[...]}` |
| DELETE `/conversations/{conversationId}` | 会话参与者；推进本人历史边界并隐藏 | 200 `{status:"deleted"}` |
| POST `/conversations/{conversationId}/restore` | 会话参与者；只取消隐藏 | 200 `{status:"restored"}` |
| GET `/conversations/{conversationId}/messages` | query after 默认0；before 可选；limit 默认50、1–100；非零 after 与 before 不可同时使用 | 200 `{messages:[...]}`，按消息 ID 升序 |
| POST `/conversations/{conversationId}/messages` | JSON clientId UUID；text 与 mediaId 恰选一个；当前好友、未屏蔽且模式为 legacy | 首次 201，重复 200，`{message}` |
| DELETE `/conversations/{conversationId}/messages/{messageId}` | 会话参与者；只对本人隐藏指定消息 | 200 `{status:"deleted"}` |
| POST `/conversations/{conversationId}/read` | JSON `{lastMessageId}`；非负安全整数且必须是本会话消息 | 200 `{status:"read"}`，已读位置只前进 |

会话对象含 id、peer、lastMessage、unreadCount、peerReadMessageId、createdAt、isFriend、isBlocked、isHidden。普通消息含 id、senderId、clientId、body、media、createdAt；发送回执另含 conversationId、duplicate。media 不存在时为 null。文字 trim 后须非空且 ≤2000 Unicode 码点；媒体必须属于当前发送者。

相同发送者的 clientId 在普通单聊消息表中唯一；不同会话、正文或媒体复用同一 ID 返回 CLIENT_ID_REUSED。preparing/active/blocked 的 MLS 会话拒绝普通明文发送并返回 E2EE_REQUIRED。读取仍受个人历史边界和隐藏消息过滤。恢复聊天不恢复被历史边界排除的内容。

```sh
CHAT_TOKEN='<AUTHORIZED_TEST_SESSION>'
CONVERSATION_ID='11111111-1111-4111-8111-111111111111'
curl "https://chat.thestarline.cn/conversations/${CONVERSATION_ID}/messages?limit=50" \
  -H "Authorization: Bearer ${CHAT_TOKEN}"
curl -X POST "https://chat.thestarline.cn/conversations/${CONVERSATION_ID}/messages" \
  -H "Authorization: Bearer ${CHAT_TOKEN}" -H 'Content-Type: application/json' \
  --data '{"clientId":"22222222-2222-4222-8222-222222222222","text":"这是合成测试消息"}'
```

示例 UUID 是合成值，必须换成测试账号实际有权访问的范围；发送属于写操作，请仅在授权测试会话中使用。

## 个人群聊

企业频道使用另一组 enterprise 路由，不能与以下个人群互换。

| Method 与路径 | 请求或查询、权限 | 成功响应 |
| --- | --- | --- |
| POST `/groups` | JSON name trim 后1–40字；memberIds 为1–49个不同好友 UUID，不含自己 | 201 `{group}`；加发起者后最多50人 |
| GET `/groups` | query includeHidden=1 | 200 `{groups:[...]}` |
| GET `/groups/{groupId}` | 当前群成员 | 200 `{group,members:[User...]}` |
| DELETE `/groups/{groupId}` | 当前群成员，删除本人视图并推进历史边界 | 200 `{status:"deleted"}` |
| POST `/groups/{groupId}/restore` | 当前群成员 | 200 `{status:"restored"}` |
| POST `/groups/{groupId}/mute` | 当前群成员；JSON `{muted:boolean}` | 200 `{group}` |
| POST `/groups/{groupId}/name` | 群主；JSON name为1–40字 | 200 `{group}` |
| POST `/groups/{groupId}/members` | 群主；JSON memberIds为1–49个不同好友UUID、不含自己；总人数≤50 | 200 `{group,members}`；已有加密范围进入blocked |
| DELETE `/groups/{groupId}/members/{userId}` | 群主；不能移除自己；目标必须为成员 | 200 `{group,members}`；有通话先清理媒体与状态 |
| POST `/groups/{groupId}/leave` | 当前成员 | 200 `{status:"left"}`；有通话处理成员变化；加密范围blocked |
| POST `/groups/{groupId}/disband` | 群主 | 200 `{status:"disbanded"}`；解散群与相关数据 |
| GET `/groups/{groupId}/messages` | 当前成员；query before可选，limit默认50、1–100 | 200 `{messages:[...]}`，升序；不支持单聊的after增量契约 |
| POST `/groups/{groupId}/messages` | 当前成员且legacy；JSON clientId、text/mediaId与单聊相同 | 201/200 `{message}`，返回groupId及duplicate |
| DELETE `/groups/{groupId}/messages/{messageId}` | 当前成员；对本人隐藏 | 200 `{status:"deleted"}` |
| POST `/groups/{groupId}/read` | JSON lastMessageId必须属于本群 | 200 `{status:"read"}` |

group 对象含 id、name、ownerId、createdAt、memberCount、lastMessage、unreadCount、allReadMessageId、isMuted、isHidden。群消息额外含 senderDisplayName。常见错误是 INVALID_GROUP_NAME、INVALID_GROUP_MEMBERS、NOT_FRIENDS、FORBIDDEN、SELF_REMOVE、INVALID_MESSAGE、CLIENT_ID_REUSED、E2EE_REQUIRED；媒体处理失败可使成员操作返回503。

## 聊天文件、贴纸与城市

| Method 与路径 | 请求、权限和限制 | 成功响应 |
| --- | --- | --- |
| POST `/media` | query kind=file/sticker、name；Content-Type为实际MIME；body原始字节 | 201 `{media}` |
| GET `/media/{mediaId}` | 所有者或当前可见消息的接收用户 | 200 原始字节；attachment下载；private缓存3600秒；无Range契约 |
| GET `/stickers` | 当前用户 | 200 `{stickers:[Media...]}`；仅自定义贴纸 |
| POST `/stickers/city` | JSON恰有一个字段cityId，须来自随客户端分发的城市目录 | 200 `{media}`；按当前账号与城市素材去重 |
| GET `/location/city` | 无业务参数；按可信请求来源粗略定位 | 200 `{city:string或null,countryCode:string或null,source:"ip"}` |

`Media={id,kind,name,mimeType,size,createdAt}`。file最大10 MiB，sticker最大512 KiB；账号聊天媒体总量100 MiB，自定义贴纸最多100个。文件名trim后1–120码点，禁止控制字符与路径分隔符。MIME需符合类型格式；贴纸必须有效PNG或JPEG，PNG宽高均≤2048。城市ID格式为小写字母开头、随后小写字母/数字/短横线、总长≤64，还必须存在于实际目录。

错误包括 INVALID_KIND、INVALID_NAME、INVALID_TYPE、EMPTY_FILE、INVALID_STICKER、TOO_LARGE、STORAGE_LIMIT、INVALID_CITY、CITY_STICKER_UNAVAILABLE、NOT_FOUND。普通上传保存原始字节，没有自动附件加密；上传后仍需发送引用mediaId的消息。下载的owner分支独立，非所有者的单聊可见消息分支不重查is_friend/block；群消息分支要求当前成员。因此删好友或屏蔽不保证撤销原先仍可见普通媒体。依据：`chat-service/src/database.mjs:239-254`。文件头校验不等于病毒扫描。

```sh
curl -X POST 'https://chat.thestarline.cn/media?kind=file&name=example.txt' \
  -H "Authorization: Bearer ${CHAT_TOKEN}" \
  -H 'Content-Type: text/plain' --data-binary '合成附件内容'
```

## 新事与互动

所有新事接口均需Bearer。visibility可为friends、selected、public、private，默认friends；public指已登录API用户可见，不是匿名网页。selected必须指定当前好友，屏蔽和个人隐藏会进一步过滤。

| Method 与路径 | 请求或查询 | 成功响应与限制 |
| --- | --- | --- |
| POST `/moments/media` | query name；原始字节；MIME仅image/jpeg、image/png、video/mp4、video/quicktime | 201 `{media}`；图片≤10MiB，视频≤30MiB；每账号500MiB |
| GET `/moments/media/{mediaId}` | 按帖子可见性；可选单个Range：bytes=start-end，end可空 | 200/206二进制；支持Accept-Ranges；private缓存300秒 |
| POST `/moments` | JSON text可选且≤2000字；visibility；viewerIds默认[]；mediaIds默认[] | 201 `{post}`；JSON≤20000字节；文字或媒体至少一项 |
| GET `/moments/feed` | query before默认最大安全整数；limit默认20、1–50 | 200 `{posts,nextBefore}` |
| GET `/moments/users/{userId}` | 同上，且目标用户存在 | 200 `{posts,nextBefore}`，按作者及可见性过滤 |
| GET `/moments/{postId}` | 当前用户可见 | 200 `{post}` |
| DELETE `/moments/{postId}` | 仅帖子作者 | 200 `{status:"deleted"}` |
| PUT `/moments/{postId}/like` | 当前用户可见 | 200 `{post}`；重复点赞幂等 |
| DELETE `/moments/{postId}/like` | 当前用户可见 | 200 `{post}` |
| GET `/moments/{postId}/comments` | before默认0；后续用nextBefore | 200 `{comments,nextBefore}`；每页30条，按ID倒序 |
| POST `/moments/{postId}/comments` | JSON text为1–500字；replyToId可选，须本帖评论正整数ID | 201 `{comment}` |
| DELETE `/moments/{postId}/comments/{commentId}` | 评论作者或帖子作者 | 200 `{status:"deleted"}` |
| POST `/moments/{postId}/hide` | 对本人隐藏 | 200 `{status:"hidden"}` |
| POST `/moments/{postId}/report` | JSON reason为1–200字 | 200 `{status:"reported"}` |
| GET `/moments/notifications` | before默认最大安全整数 | 200 `{notifications,nextBefore,unreadCount}`；每页30条可见通知 |
| POST `/moments/notifications/read` | 标记当前用户全部未读通知 | 200 `{status:"read"}` |

帖子输入viewerIds最多100、不重复、UUID，非selected时必须为空；selected至少一位有效未屏蔽好友。mediaIds最多9、不重复、UUID；必须为自己尚未绑定其他帖子的媒体。图片最多9张，或仅1段视频，不得混发。未绑定媒体超过24小时清理。PNG仍执行宽高≤2048校验，视频检查ftyp标识。

post含id、authorId、text、visibility、createdAt、author、media、likeCount、commentCount、liked、recentComments；作者读取selected帖子可得到viewerIds。comment含id、postId、authorId、replyToId、text、createdAt、authorName。通知含actorId、actorName、postId、commentId、kind、createdAt、readAt，kind为like/comment/reply。

错误包括INVALID_POST、INVALID_COMMENT、INVALID_REPORT、INVALID_MEDIA、INVALID_RANGE、INVALID_LIMIT、NOT_FOUND、FORBIDDEN。某些输入被权限过滤后得到404；不能仅因知道帖子或媒体ID就访问内容。

## 实时位置

以下路径模板中的 `{resource}` 必须替换为 `conversations` 或 `groups`，两类范围各实现相同四个Method。

| Method 与路径 | 请求与权限 | 成功响应 |
| --- | --- | --- |
| GET `/live-locations/mine` | 当前用户 | 200 `{sessions:[{scopeKind,scopeId}]}` |
| GET `/{resource}/{scopeId}/live-locations` | 当前范围成员 | 200 `{locations:[...]}` |
| POST `/{resource}/{scopeId}/live-locations` | JSON latitude、longitude、accuracy；单聊需好友且未屏蔽 | 201 `{location}`，显式开始或更新已有共享 |
| PUT `/{resource}/{scopeId}/live-locations` | 同上，且已存在自己的共享 | 200 `{status:"updated"}`；未开始为409 NOT_SHARING |
| DELETE `/{resource}/{scopeId}/live-locations` | 当前范围成员，停止本人 | 200 `{status:"stopped"}` |

经纬度与精度需有限数字，latitude为-90–90，longitude为-180–180，accuracy为0–100000。位置对象含userId、displayName、latitude、longitude、accuracy、startedAt、updatedAt。当前没有服务端自动到期字段，也没有位置写入普通events的契约。此数据不是MLS密文。

## 普通变更长轮询

| Method 与路径 | 查询参数 | 成功响应 |
| --- | --- | --- |
| GET `/events` | after默认0；wait默认20、0–25秒；Bearer | 200 `{events,cursor}`，每批最多100条 |

`GET /events` 的query为after（默认0，非负安全整数）、wait（默认20，0–25秒）。响应200 `{events,cursor}`，每批最多100条、按ID升序；空批次保持原cursor。event为`{id,conversationId,groupId,kind,messageId,createdAt}`，可选引用可能null。客户端收到事件后重新获取对应业务资源，不应把它当完整消息内容。

```sh
curl 'https://chat.thestarline.cn/events?after=0&wait=20' \
  -H "Authorization: Bearer ${CHAT_TOKEN}"
```

客户端应连续维护轮询和断线重连。更多游标和客户端恢复行为见[实时同步与通话](https://document.thestarline.cn/app/realtime-and-calls.md)。

## MLS 设备与加密事件

这些接口要求Bearer且服务器已加载可用MLS校验器，否则503 E2EE_UNAVAILABLE。deviceId格式为`[A-Za-z0-9_-]{1,80}`；keyPackage与payload用规范标准base64，不是base64url。服务端验证MLS封装，终端负责完整消息认证与解密。

| Method 与路径 | 参数与限制 | 成功响应 |
| --- | --- | --- |
| GET `/e2ee/devices/{deviceId}/key-packages` | 当前用户的设备 | 200 `{registered,available}` |
| POST `/e2ee/devices/{deviceId}/key-packages` | JSON keyPackage；解码1–65536字节，JSON≤100000字节 | 201或已领取重复包200，`{keyPackageId}`；每设备最多25个未用包 |

下表 `{resource}` 为conversations或groups，每种各有8条Method+path。范围必须属于当前用户；除state只查范围外，其余需相应已注册设备。单聊prepare、events POST、activate还需当前好友且未屏蔽。

| Method 与路径 | JSON或query | 成功响应与状态限制 |
| --- | --- | --- |
| GET `/e2ee/{resource}/{scopeId}/state` | 无额外字段 | 200 `{mode,creatorUserId,creatorDeviceId}`；无范围记录时mode=legacy |
| GET `/e2ee/{resource}/{scopeId}/devices` | query deviceId必填 | 200 `{devices:[{userId,deviceId,signatureKey,keyPackageId,keyPackage,invited,joined}]}`；公钥与包base64，包可null |
| POST `/e2ee/{resource}/{scopeId}/prepare` | JSON deviceId | 201 `{mode:"preparing"}`；仅legacy，每参与者至少一个注册设备 |
| GET `/e2ee/{resource}/{scopeId}/events` | query deviceId、after默认0 | 200 `{events,cursor}`；立即查询，最多100条按sequence升序，仅当前设备收件 |
| POST `/e2ee/{resource}/{scopeId}/events` | JSON deviceId、clientId UUID、kind、payload；Welcome另需targetUserId、targetDeviceId、keyPackageId | 首次201、相同重试200，`{sequence}`；kind为welcome/commit/application；payload≤1048576字节，JSON≤1500000字节 |
| POST `/e2ee/{resource}/{scopeId}/welcome-acks` | JSON deviceId、sequence安全整数 | 200 `{status:"acknowledged"}`；必须是发给本设备的Welcome |
| POST `/e2ee/{resource}/{scopeId}/commit-acks` | JSON deviceId、sequence安全整数 | 200 `{status:"acknowledged"}`；必须是本设备收到的Commit |
| POST `/e2ee/{resource}/{scopeId}/activate` | JSON deviceId | 200 `{mode:"active"}`；仅创建者、所有当前设备完成必要Welcome/Commit确认 |

加密event含sequence、kind、clientId、senderUserId、senderDeviceId、payload、createdAt、targetUserId、targetDeviceId。服务端按发送者、设备、clientId去重，检查范围、类型、payload摘要、收件人和包ID完全相同。Welcome定向单设备并消费相应密钥包；application仅active可发；preparing阶段仅创建者建立群；后续Commit协调及activate受创建者限制。

关键错误包括INVALID_KEY_PACKAGE、DEVICE_KEY_CHANGED、TOO_MANY_PACKAGES、NOT_MEMBER、UNKNOWN_DEVICE、MISSING_DEVICE、ALREADY_PREPARED、INVALID_EVENT、NOT_PREPARED、CLIENT_ID_REUSED、NOT_ACTIVE、PREPARING、NOT_CREATOR、INVALID_RECIPIENT、PACKAGE_USED、INVALID_WELCOME、INVALID_COMMIT、AWAITING_WELCOME、AWAITING_COMMIT、AWAITING_REKEY、INVALID_SCOPE。HTTP映射为NOT_MEMBER→404，UNKNOWN_DEVICE→403，INVALID_KEY_PACKAGE/INVALID_EVENT/INVALID_RECIPIENT/INVALID_WELCOME→400，其余具名MLS错误通常409。

当前iOS独立MLS传输器实现文字payload，Android与主聊天尚未完成同等接入；本节不提供虚构密文可直接发送的curl。联调需调用真实加密核心生成有效TLS字节，随意base64字符串会被拒绝。完整顺序见[消息与媒体](https://document.thestarline.cn/app/messaging-and-media.md)。

## 通话与 VoIP 设备

| Method 与路径 | 参数与权限 | 成功响应 |
| --- | --- | --- |
| POST `/calls` | JSON scopeKind=conversation/group、scopeId UUID、mode=audio/video、clientId UUID；范围成员，单聊另需好友且未屏蔽 | 201 `{call}`；媒体未配置503、冲突409 CALL_BUSY |
| GET `/calls/active` | 当前用户 | 200 `{call}`，无则null |
| GET `/calls/current` | query scopeKind、scopeId；当前范围成员 | 200 `{call}`，无则null |
| GET `/calls/history` | 同上 | 200 `{calls}`，最近100条终态记录 |
| POST `/calls/{callId}/accept` | JSON `{}`；当前受邀者，单聊需仍可联系 | 200 `{call}`；状态冲突409 CALL_STATE |
| POST `/calls/{callId}/decline` | JSON `{}`；当前仍在响铃的受邀者 | 200 `{call}` |
| POST `/calls/{callId}/end` | JSON `{}`；响铃时仅发起者取消；active需实际参与者 | 200 `{call}`；群离开不必结束整场 |
| POST `/calls/{callId}/join` | JSON `{}`；仅active群通话的当前群成员 | 200 `{call}` |
| POST `/calls/{callId}/media-token` | JSON `{}`；active且尚未离开的参与者 | 200 `{url,token}`；TTL30秒，当前房间发布订阅，禁止data发布 |
| POST `/voip/devices` | JSON deviceId为UUID，pushToken为64–512个十六进制字符；绑定当前session | 200 `{status:"registered"}` |
| DELETE `/voip/devices` | JSON deviceId为UUID | 200 `{status:"unregistered"}` |

Call对象含id、scopeKind、scopeId、callerId、mode、state、createdAt、startedAt、endedAt、endedReason，不含内部roomName及请求clientId。state为ringing/active/ended/missed/cancelled；startedAt和endedAt可null。所有其他成员忙时，POST也可返回201且state=ended、endedReason=busy；必须检查对象状态。

媒体token不是聊天会话，不能公开缓存、写入静态站或长期复用。错误包括INVALID_CALL、INVALID_CALL_SCOPE、INVALID_VOIP_DEVICE、CALL_BUSY、CALL_STATE、CALL_MEDIA_UNAVAILABLE。状态机、空房回收与真实跨网络验收边界见[实时同步与通话](https://document.thestarline.cn/app/realtime-and-calls.md)。

## 记忆识别与转出桥接

| Method 与路径 | 参数与限制 | 成功响应 |
| --- | --- | --- |
| POST `/memory/recognize` | JSON text，trim后2–2000字；每用户每10分钟最多10次；需模型配置 | 200 `{schema}`；失败503 MEMORY_MODEL_UNAVAILABLE，限流429 TOO_MANY_RECOGNITIONS |
| GET `/memory-export/start` | 当前登录用户；需Account配置 | 200 `{url,state}`；5分钟转出flow，打开Account额外验证 |
| POST `/memory-export/exchange` | JSON state、ticket，均32–128个字母/数字/下划线/短横线 | 200 `{authorized:true}`；一次性flow，校验当前Account subject一致 |

schema含category、icon、fields；字段含id、title、type、options，type为服务端归一化的表单字段类型，签证和宠物疫苗主题还会补充专用字段。请求的text会发送至聊天服务及配置模型，用于生成结构；这不形成持久记忆库或云同步，不能把“未持久保存”理解为“没有上传”。当前权威Account主源码没有`/api/memory-export/redeem`路由；App工作树的历史Account副本虽有实现，也不能证明当前服务支持。因此聊天侧转出桥接不能当成已验收能力。错误包括EXPORT_UNAVAILABLE、INVALID_EXPORT_TICKET、ACCOUNT_MISMATCH、INVALID_MEMORY_TEXT。

## 共享后台：独立星企企业接口

本节用于解释共享服务的完整路由范围。这些是星企接口，不是星线 App 个人前台功能。全部要求聊天Bearer；进入指定企业路径先验证企业成员，随后按操作检查manager（admin/owner）或owner。企业ID与个人群ID不能互换。

令以下表格的`{org}`表示`/enterprise/organizations/{organizationId}`，仅为排版缩写，实际请求必须展开完整路径。

| Method 与完整路径或展开规则 | 参数与权限 | 成功响应 |
| --- | --- | --- |
| GET `/enterprise/organizations` | 当前用户 | 200 `{organizations}` |
| POST `/enterprise/organizations` | JSON name为1–80字 | 201 `{organization}`，创建者为owner并建立全员群 |
| POST `/enterprise/invitations/preview` | JSON code为43字符base64url，有效未撤销邀请码 | 200 `{invitation}`，含organizationId、organizationName、expiresAt、joinMode、membership |
| GET `/enterprise/join-requests` | 当前用户 | 200 `{requests}`，最多100条本人申请 |
| POST `/enterprise/join-requests` | JSON code，有效邀请 | 200 `{status,organizationId,organizationName}`，status为pending或joined |
| GET `{org}` | 当前企业成员 | 200企业快照：organization、members、departments、channels、tasks、announcements、services、joinRequests、invitations；最后两项对普通member为空 |
| PATCH `{org}/members/me/card` | JSON恰含name，单行1–80字或null；本人 | 200 `{member}` |
| POST `{org}/invitations` | JSON `{}`；manager | 201 `{invitation:{id,code,expiresAt}}`，3日有效；原始code仅创建响应给出 |
| DELETE `{org}/invitations/{invitationId}` | manager | 200 `{ok:true}` |
| POST `{org}/join-requests/{requestId}` | JSON approve为boolean；manager且不能审批自己 | 200 `{ok:true}`；重复相同决定幂等，冲突409 DECISION_CONFLICT |
| POST `{org}/departments` | JSON name为1–80字；manager | 201 `{department}` |
| PATCH `{org}/departments/{departmentId}` | JSON name；manager | 200 `{department}`；同企业重名409 DUPLICATE_DEPARTMENT |
| DELETE `{org}/departments/{departmentId}` | manager | 200 `{ok:true}`，关联成员部门置null |
| PATCH `{org}/members/{userId}` | 可传role=admin/member、departmentId、jobTitle≤80字、cardName单行1–80字或null | 200 `{ok:true}`；manager，角色调整仅owner且不能修改owner角色 |
| DELETE `{org}/members/{userId}` | manager；不能移除owner，admin不能移除admin | 200 `{ok:true}` |
| POST `{org}/channels` | JSON kind=direct/group、memberIds非空≤200个不重复同企业ID；group需name≤80字 | 201 `{channel}`；direct最终双方必须恰为2人，重复同事单聊复用频道 |
| GET `{org}/channels/{channelId}/messages` | query before可选正安全整数；企业和频道成员 | 200 `{messages}`，最多100条，返回升序；受入群历史边界限制 |
| POST `{org}/channels/{channelId}/messages` | JSON body为1–2000字、clientId为1–128字母/数字/下划线/短横线；JSON≤32768字节 | 201/200 `{message}`；同频道同发送者重试去重 |
| POST `{org}/channels/{channelId}/read` | JSON `{}`；企业和频道成员 | 200 `{ok:true}`，读到当前最新消息 |
| POST `{org}/tasks` | JSON title≤120、notes≤4000（可空）、dueAt为null或非负安全整数、assigneeId为当前同企业成员；JSON≤65536字节 | 201 `{task}`，初始未完成 |
| PATCH `{org}/tasks/{taskId}` | 更新上述字段及isCompleted；JSON≤65536字节 | 200 `{task}`；manager或创建者可管理，其他受指派者只能改isCompleted |
| DELETE `{org}/tasks/{taskId}` | manager或创建者 | 200 `{ok:true}` |
| POST `{org}/announcements` | JSON title≤120字、body≤10000字；JSON≤131072字节；manager | 201 `{announcement}` |
| DELETE `{org}/announcements/{announcementId}` | manager | 200 `{ok:true}` |
| PUT `{org}/announcements/{announcementId}/read` | JSON `{}`；当前企业成员 | 200 `{ok:true}` |
| POST `{org}/services` | JSON name≤80字、url≤2000；manager；只允许无用户名密码的HTTPS URL | 201 `{service:{id,name,url}}` |
| DELETE `{org}/services/{serviceId}` | manager | 200 `{ok:true}` |

企业常见错误为FORBIDDEN、INVALID_INPUT、NOT_FOUND、INVALID_INVITATION、INVITATION_ALREADY_USED、DECISION_CONFLICT、INVALID_DEPARTMENT、INVALID_MEMBER、INVALID_ASSIGNEE、INVALID_URL与CLIENT_ID_REUSED。邀请被撤销或过期不可批准加入；已被决定的同一邀请不能复活旧申请。企业频道保存服务端可读文字，不属于个人聊天MLS范围，也没有据此推导的企业附件路由。

## 调用与联调顺序

建议先在受控测试账号完成native/start→Account→callback→exchange，再调用/me确认身份与事件游标；之后读取列表，使用合成文字及小文件验证发送、重试、下载与已读。MLS联调必须使用真实生成的测试密钥包和密文；通话联调要在API状态之外验证双设备媒体与后台来电。

本页所有示例为合成或占位内容，没有生产凭据。接口细节与文档不一致时，以当前源码和可复核测试结果更新契约；不要通过去掉proof、改用旧接口或绕过成员检查“修复”失败。继续阅读[数据模型](https://document.thestarline.cn/app/data-model.md)、[安全和隐私](https://document.thestarline.cn/app/security-and-privacy.md)、[测试](https://document.thestarline.cn/app/testing.md)及[运维](https://document.thestarline.cn/app/operations.md)。

按业务流程联调时可结合[联系人与个人群](https://document.thestarline.cn/app/contacts-and-groups.md)、[新事](https://document.thestarline.cn/app/moments.md)、[位置共享](https://document.thestarline.cn/app/location-sharing.md)、[MLS协议](https://document.thestarline.cn/app/mls-protocol.md)和[限制与错误](https://document.thestarline.cn/app/limits-and-errors.md)读取状态与失败分支。


原始地址：https://document.thestarline.cn/app/protocol-recipes/
Markdown：https://document.thestarline.cn/app/protocol-recipes.md

# 协议示例与集成步骤

本页把分散的接口串成可检查的流程，说明调用顺序、需要保留的状态、重复请求及失败处理。请求契约来自聊天服务当前源码；这些示例不代表所有客户端已经采用相同实现。路由逐项定义见 [API 参考](https://document.thestarline.cn/app/api-reference.md)，状态和限制见[限制与错误](https://document.thestarline.cn/app/limits-and-errors.md)。

## 示例环境与约定

命令使用隔离开发服务，测试账号、会话、消息和附件均应为合成数据。`CHAT_TOKEN` 必须由该环境内已经完成的测试登录获得。生产地址与本地地址的票据不能互换；原生授权还受系统回调与平台信任规则约束，尤其 Android 当前只允许正式 Account HTTPS 来源。

```sh
CHAT_BASE_URL='http://127.0.0.1:4210'
: "${CHAT_TOKEN:?请先在同一测试环境完成授权并设置聊天会话}"
CONVERSATION_ID='11111111-1111-4111-8111-111111111111'
CLIENT_MESSAGE_ID='22222222-2222-4222-8222-222222222222'
```

上面的两个 UUID 只表示字段格式。会话必须换成当前测试账号有权访问的真实测试会话；每条新消息需要新的 clientId。同一条消息的网络重试则继续使用原 clientId。不要把 Account access token、ID token、LiveKit token 或文档访问地址当作 `CHAT_TOKEN`。

`curl --silent --show-error` 保留失败信息且不输出传输进度。不要为排错启用会回显 Authorization 的详细网络日志；只需保存 HTTP 状态、错误码和请求阶段。示例 JSON 中的用户、编号和时间都是合成值。

## 一、恢复会话并取得同步起点

```sh
curl --silent --show-error --fail-with-body \
  "${CHAT_BASE_URL}/me" \
  -H "Authorization: Bearer ${CHAT_TOKEN}"
```

正常响应形状如下：

```json
{
  "user": {
    "id": "33333333-3333-4333-8333-333333333333",
    "displayName": "合成测试用户",
    "friendId": "A1B2C3D4E5F"
  },
  "eventCursor": 42
}
```

| 结果 | 集成端动作 |
| --- | --- |
| 200 | 记录当前用户及 eventCursor，继续加载会话、群和其他有权资源 |
| 401 UNAUTHORIZED | 本聊天会话不可用，进入重新授权；没有公开 refresh-token 接口可供直接续期 |
| 网络超时 | 区分网络状态与登录失效；未收到 HTTP 响应不能直接解释为密码错误 |
| 500 或 503 | 保留错误码并检查相关服务，不循环创建授权 flow 代替定位依赖故障 |

一种可采用的集成顺序是先取得 eventCursor，再读取业务列表，随后从该 cursor 拉事件。列表加载期间产生的变化可能再次触发读取；通过对象 ID 合并即可避免重复。该顺序是集成建议，并非两端全部状态管理的逐行描述，实际实现见[客户端生命周期](https://document.thestarline.cn/app/client-lifecycle.md)。

## 二、构造原生授权证明

App→聊天服务的 verifier 由 32 字节安全随机值编码为无填充 base64url，challenge 为 verifier 的 SHA-256 摘要再做同样编码。下面只在本机生成挑战，不执行授权：

```sh
CODE_VERIFIER="$(python3 -c 'import base64,secrets; print(base64.urlsafe_b64encode(secrets.token_bytes(32)).decode().rstrip("="))')"
CODE_CHALLENGE="$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')"
```

这两个值在该生成方式下都是 43 字符。只把 challenge 放进开始请求，verifier 保存在当前设备的本次授权状态中。开始请求为：

```sh
curl --silent --show-error --fail-with-body \
  -X POST "${CHAT_BASE_URL}/auth/native/start" \
  -H 'Content-Type: application/json' \
  --data "{\"app\":\"starline\",\"screen\":\"login\",\"codeChallenge\":\"${CODE_CHALLENGE}\"}"
```

服务端返回 `authorizationURL`、`state`、`expiresAt`。App 先保存 pending，再交系统浏览器打开授权地址；用户完成 Account 流程后，聊天服务通过 HTTPS 回调换码，再把一次性 ticket 和原 state 交回 App。最终换票 JSON 为：

```json
{
  "ticket": "ONE_USE_TICKET_FROM_CALLBACK",
  "state": "EXACT_PENDING_STATE",
  "codeVerifier": "VERIFIER_FROM_THE_SAME_FLOW"
}
```

该对象发送到 `POST /auth/exchange`。占位文本不能直接用于测试；ticket、state、verifier 必须来自同一未到期流程。回调解析失败、state 不同、重复参数或 ticket 过期时重新开始授权，不删除 proof 字段尝试兼容模式。iOS 与 Android 的 pending 持久化和换票中断恢复并不相同，见[登录与会话](https://document.thestarline.cn/app/authentication.md)。

## 三、发送文字并安全重试

```sh
curl --silent --show-error --fail-with-body \
  -X POST "${CHAT_BASE_URL}/conversations/${CONVERSATION_ID}/messages" \
  -H "Authorization: Bearer ${CHAT_TOKEN}" \
  -H 'Content-Type: application/json' \
  --data "{\"clientId\":\"${CLIENT_MESSAGE_ID}\",\"text\":\"合成测试消息\"}"
```

发送前需确认当前用户仍是好友、双方未屏蔽，且该会话的加密模式为 legacy。text 与 mediaId 恰选一种，文字 trim 后非空，最多 2,000 Unicode 码点。普通接口不能把文字与附件合并成一次发送。

| 请求情况 | 预期结果 | 需要保留的状态 |
| --- | --- | --- |
| 首次有效发送 | 201，message.duplicate 为 false | 服务端 message.id 与本地 clientId 对应关系 |
| 同发送者、同会话、同 clientId、同正文与媒体重复发送 | 200，duplicate 为 true | 合并已有消息，不再新增一条气泡 |
| 已使用的 clientId 换正文、附件或会话 | 409 CLIENT_ID_REUSED | 不自动换 ID 继续盲发，先核对原发送意图 |
| 服务端已准备/启用/阻塞 MLS | 409 E2EE_REQUIRED | 不能降级为另一普通接口绕过模式 |
| 服务端可能已经写入，但客户端没收到响应 | 网络失败，结果未知 | 保留原 clientId 与相同内容，允许后续重试核对 |

唯一性在普通单聊消息表中按 senderId、clientId 检查。群消息使用独立消息表，集成端仍应为每个新发送意图生成独立 ID，不依赖不同表碰巧可以重复使用。权限变化后重试可能得到 403/404，并不意味着原消息从未写入。

## 四、上传附件再发送引用

先准备一份没有个人信息的 15 字节测试文件：

```sh
printf 'synthetic-data\n' > synthetic-note.txt
curl --silent --show-error --fail-with-body \
  -X POST "${CHAT_BASE_URL}/media?kind=file&name=synthetic-note.txt" \
  -H "Authorization: Bearer ${CHAT_TOKEN}" \
  -H 'Content-Type: text/plain' \
  --data-binary '@synthetic-note.txt'
```

上传使用原始字节，不能用 multipart 表单替代。成功 201 的 `media` 包括 id、kind、name、mimeType、size、createdAt；将返回 ID 放入下一条消息：

```json
{
  "clientId": "44444444-4444-4444-8444-444444444444",
  "mediaId": "55555555-5555-4555-8555-555555555555"
}
```

此时不带 text。mediaId 必须属于发送者；上传成功并不代表已经向接收者发出消息。第二步失败时应明确呈现“文件已上传、消息未确认”的阶段，不能显示为双方都已收到。

文件下载路径是 `GET /media/{id}`。上传者可以读取自己的媒体；非所有者需要符合个人历史边界且未被本人隐藏的消息引用，群消息还要求当前成员资格。普通单聊媒体的读取分支不重新检查好友或屏蔽，因此删好友、屏蔽不等于过去仍可见的媒体立即不可读。本人隐藏、历史边界或退群可能改变引用授权；存在其他可见引用时也不能笼统认定该文件一定不可读。普通聊天媒体没有 Range 契约，不要把新事视频接口的分段能力套用到这里。

上传原始数据不等于客户端附件加密。服务器保存的字节与上传字节一致，附件 E2EE 边界见[消息与媒体](https://document.thestarline.cn/app/messaging-and-media.md)。聊天文件、贴纸、新事媒体与本机记忆附件的上限分别不同，见[限制与错误](https://document.thestarline.cn/app/limits-and-errors.md)。

## 五、翻页、增量与消息合并

```sh
curl --silent --show-error --fail-with-body \
  "${CHAT_BASE_URL}/conversations/${CONVERSATION_ID}/messages?limit=50" \
  -H "Authorization: Bearer ${CHAT_TOKEN}"
```

没有 after/before 时，服务端取最新一页，再以 ID 升序返回。例如可见消息为 11、18、25；显示顺序就是 11→18→25，ID 不要求连续。

| 需求 | 下一请求 | 合并规则 |
| --- | --- | --- |
| 继续向前加载历史 | before=11 | 只取 ID 小于 11 的消息，按 ID 合并到前方 |
| 拉取 25 之后的新单聊消息 | after=25 | 只取 ID 大于 25 的消息，按 ID 去重追加 |
| 初始加载最新页 | 不带 after/before，或 after=0 | 不是从最早历史开始遍历 |
| 群历史翻页 | `/groups/{id}/messages?before=...` | 使用群 before 规则，不假定支持单聊 after 增量契约 |

非零 after 与 before 不可同时传。before 是严格排除边界，传 0 不表示“从最新开始”，通常得到空结果。空页只能说明当前权限和边界下没有该方向结果，不证明数据库从未有过消息。个人隐藏和历史清理会过滤记录。

服务端分页 ID、客户端 clientId 和普通事件 ID 用途不同。不要以时间戳作为这些游标，也不要把旧页里最后一条消息 ID 当作加载更早历史的 before。

## 六、长轮询与业务刷新

```sh
EVENT_CURSOR=42
curl --silent --show-error --fail-with-body \
  "${CHAT_BASE_URL}/events?after=${EVENT_CURSOR}&wait=20" \
  -H "Authorization: Bearer ${CHAT_TOKEN}"
```

服务端每批最多返回 100 个当前用户可见事件，按 ID 升序，并返回 cursor。空批次保持原 cursor。事件携带 kind、conversationId/groupId、可选 messageId 和 createdAt，不是消息正文的完整替代物。

集成端依次处理该批事件、刷新对应资源并保存 cursor；消费失败时不要只推进游标而丢弃需要恢复的业务状态。一次返回满批可继续用 `wait=0` 消费积压，再恢复正常等待。重连时复用已确认游标，允许对象 ID 去重，不把网络重连等同于清空历史。

普通事件游标与 MLS sequence 属于不同协议。实时位置也没有自动写入普通 events 的契约；不能仅通过等待普通消息事件完成位置更新。消息轮询、MLS 同步、位置读取和通话房间连接应分别处理，见[实时同步](https://document.thestarline.cn/app/realtime-and-calls.md)与[位置共享](https://document.thestarline.cn/app/location-sharing.md)。

## 七、已读与删除的语义

`POST /conversations/{id}/read` 使用 `{lastMessageId:25}`。消息必须属于该会话；已读位置只前进，不因客户端提交更小 ID 回退。UI 应在真实展示/阅读策略满足后更新，不在仅收到通知时直接把对方消息全部标为已读。

`DELETE /conversations/{id}/messages/{messageId}` 是本人隐藏，不能当双方撤回。`DELETE /conversations/{id}` 会隐藏本人会话并推进历史边界，restore 只取消隐藏，不恢复该边界之前的内容。删除好友、屏蔽、退出群和解散群又是其他操作。有关成员转移和数据清理顺序，见[好友与群](https://document.thestarline.cn/app/contacts-and-groups.md)。

## 八、检查失败而不改变业务数据

可在隔离环境检验以下只读或不成立请求，不需要创建真实内容：

| 请求 | 应观察的结果 |
| --- | --- |
| 无 Bearer 请求 `/me` | 401，而不是匿名返回用户 |
| `GET /events?after=-1&wait=0` | 400 INVALID_CURSOR |
| 单聊 `?after=25&before=11` | 400 INVALID_CURSOR |
| 单聊 `?limit=0` | 400 INVALID_LIMIT |
| 对未授权媒体 ID 发 GET | 404，不返回媒体正文 |

这些是待执行的契约检查清单，不是本文已经向真实服务发出请求的验收回执。多账号权限、并发发送、掉线恢复与资源回收需结合[测试矩阵](https://document.thestarline.cn/app/qa-matrix.md)检查；发生实际故障时按[故障处置](https://document.thestarline.cn/app/incident-runbooks.md)先定位阶段，再处理状态。

## 源码入口

请求解析、状态码和权限入口位于 `chat-service/src/server.mjs`；普通消息事务、去重、可见历史与事件位于 `chat-service/src/database.mjs`。原生封装分别在 `ios-app/Sources/Features/Chat/ChatAPI.swift` 与 `android-app/app/src/main/java/cn/thestarline/workbench/AppData.kt`。修改流程时同时检查请求体、事务语义、客户端重试和[API 参考](https://document.thestarline.cn/app/api-reference.md)，不能只修改示例。


原始地址：https://document.thestarline.cn/app/data-model/
Markdown：https://document.thestarline.cn/app/data-model.md

# 数据模型与一致性

聊天服务以 SQLite 保存身份映射、联系人关系、聊天内容、媒体、新事、事件和通话状态。原生记忆数据另有客户端本地模型。本页描述源码中的逻辑实体与约束，帮助调用方理解 ID、可见性、重试和删除语义；不提供任何用户数据库或生产记录。

## 标识符、时间和对外对象

聊天用户、会话、群、媒体、好友申请和通话主要使用 UUID 字符串。普通消息、新事、评论、通知和事件使用各自的自增整数；企业消息的对外 `id` 被转换成字符串。MLS 使用自增 `sequence`，设备 ID 允许 1 至 80 个字母、数字、下划线或短横线。多数接口路径的 UUID 正则只校验字符集合与长度，客户端仍应产生合法 UUID。

时间字段如 `createdAt`、`updatedAt`、`expiresAt` 是 Unix 毫秒值。API 通常使用 camelCase，数据库使用 snake_case。`null` 表示暂无值，例如尚未接通的 `startedAt`、没有最新消息的 `lastMessage`、无权查看的手机号。调用方不得把 null 当空字符串，也不能跨不同实体比较 ID 大小判断全局时间顺序。

## 身份与资料

| 实体 | 核心关系与约束 |
| --- | --- |
| `users` | 本地 `id`；唯一 Account `issuer_sub`；显示名；唯一好友 ID `chat_code`；手机号查找摘要及有效期 |
| `user_profiles` | 每用户一条；简介、加密联系方式、手机号可见范围、更新时间 |
| `user_profile_phone_viewers` | 指定可见者的 owner/viewer 复合键；不能指定自己 |
| `oauth_flows` | state 摘要、服务端 verifier、到期时间、产品标识、原生挑战 |
| `login_tickets` | ticket 摘要、用户、到期时间、原生挑战及 state 摘要 |
| `device_sessions` | token 摘要、用户、到期时间 |

公开 `User` 只含 `{id,displayName,friendId}`，不会返回 Account subject、token 摘要或查找摘要。手机号查找使用带服务端密钥的 HMAC-SHA256，并在登录时刷新为 24 小时有效；个人资料中的可展示联系电话是另一字段，使用 AES-256-GCM 保存，由资料可见性控制。两者用途和存储形式不同。

## 好友、单聊与个人视图

`friend_requests` 保存申请双方及时间，禁止自己申请自己，同方向双方组合唯一。`friend_codes` 每用户只保留一个当前临时码摘要；`friend_lookup_attempts` 按用户与查找方法记录 10 分钟窗口内次数。

`conversations` 保存排序后的 `user_a` 与 `user_b`，要求前者小于后者并且双方组合唯一；`is_friend` 表示好友关系是否仍有效。删除好友不会仅靠删一条消息实现。`user_blocks` 是有方向的屏蔽关系，但发送、通话和部分资料检查使用任一方向屏蔽的联合条件。

`conversation_preferences` 为每个用户保存 `is_hidden` 和 `visible_after_message_id`。删除聊天会把个人可见边界推进到当时最后一条消息并隐藏列表项；恢复只取消隐藏，不回退边界。`hidden_messages` 为用户、范围与消息建立单条隐藏记录。因此“删除消息”是当前用户视图删除，不能解释为对方撤回、数据库物理擦除或备份销毁。

## 消息、群与已读

`messages` 与 `group_messages` 分别保存所属范围、发送者、`client_id`、正文、可选媒体引用和时间。二者各自要求 `(sender_id,client_id)` 唯一；同一发送者不能在该表内把同一 clientId 改用于其他范围或其他内容。服务端发现完全相同重试返回既有消息，内容变化返回 `CLIENT_ID_REUSED`。

`read_positions` 保存单聊用户最后已读消息，群的已读位置位于 `group_members`。更新只前进，且目标消息必须属于当前范围。未读数还受个人可见边界、单条隐藏和发送者过滤影响，不能只用最新 ID 减已读 ID 计算。

`groups` 保存名称、群主与创建时间；`group_members` 复合键保存加入时间、最后已读、历史可见边界、隐藏和静音设置。个人群最多 50 人。新成员的历史边界、退出或移除成员后的范围权限，均由服务端当前成员记录决定。群主可邀请、改名、移除成员或解散；群主退出时的归属处理由服务端事务完成，不能由客户端只删本地列表代替。

## 媒体、新事与位置

聊天 `media` 保存所有者、sticker/file、文件名、MIME、字节数、BLOB 和创建时间；城市内置贴纸还有用于按账号去重的 builtin key。消息通过 `media_id` 引用。下载权限来自所有者或当前用户可见消息，不能只凭 UUID 下载。

新事数据单独保存于 `moments_posts`、`moments_audience`、`moments_media`、`moments_likes`、`moments_comments`、`moments_notifications`、`moments_hidden` 和 `moments_reports`。可见性为 friends、selected、public、private；selected 另存指定好友列表，public 仍需登录访问 API。点赞是用户与帖子的唯一组合；评论可引用同帖评论。未绑定帖子的媒体超过 24 小时会被清理。新事不是 MLS 加密聊天数据。

`live_locations` 以范围类型、范围 ID、用户为复合键，保存经纬度、精度、开始和更新时间。POST 显式开启共享，PUT 只更新既有共享，DELETE 停止。服务端没有在本表中设置自动过期字段，调用方应展示更新时间并明确停止共享。

## MLS、通话与变更通知

MLS 表包括设备签名公钥、一次性密钥包、范围模式、加密事件和按设备收件确认。`e2ee_scopes` 的 preparing/active/blocked 与没有记录时的 legacy 共同构成状态机。密钥包以内容 SHA-256 作为 ID；事件唯一键为发送用户、设备和 clientId，payload 摘要用于检查重试一致性。

`calls` 保存通话范围、发起者、audio/video、状态、时间和结束原因；内部房间名不会出现在普通公开 call 对象中。`call_invites` 描述每位邀请者的响应，`call_participants` 描述实际加入和离开。`voip_devices` 将设备、推送 token 与登录 session 摘要关联。

`events` 是用户收件范围内的变更索引，含可空的 conversationId/groupId/messageId。MLS sequence 可作为 e2ee 通知的 messageId，但不因此变成普通消息 ID。长轮询默认每批最多 100 条。详见[实时同步](https://document.thestarline.cn/app/realtime-and-calls.md)。

## 存储与产品边界

数据库启用外键及 WAL，写操作通过事务维护去重、消息和事件一致性。备份与恢复必须同时考虑数据库、媒体 BLOB、加密配置、MLS 客户端状态和 Account 身份映射，不能只复制某一个消息表。

`enterprise_*` 表属于共享后台的独立星企领域，组织、部门、成员角色、企业频道、企业待办、公告与服务均以企业 ID 隔离，不属于星线 App 个人聊天数据模型的前台功能承诺。更多接口字段见[API 参考](https://document.thestarline.cn/app/api-reference.md)，数据保护边界见[安全和隐私](https://document.thestarline.cn/app/security-and-privacy.md)。

状态操作的具体影响见[联系人与个人群](https://document.thestarline.cn/app/contacts-and-groups.md)、[新事](https://document.thestarline.cn/app/moments.md)及[位置共享](https://document.thestarline.cn/app/location-sharing.md)，尤其注意个人视图删除、关系移除和完整解散使用不同清理分支。


原始地址：https://document.thestarline.cn/app/mls-protocol/
Markdown：https://document.thestarline.cn/app/mls-protocol.md

# MLS 设备与加密事件协议

仓库已实现Rust MLS核心、服务端交付接口和iOS独立传输器。当前iOS主ChatStore与Android主聊天仍发送普通text/media，附件也未接入客户端密文封装。本页解释协议状态与恢复要求，不把模块存在等同于全量端到端加密或生产安全审计通过。

## 身份、编码与职责

Rust固定使用MLS 1.0与`MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519`。设备credential串联聊天用户ID与设备ID，签名公钥32字节；会话scopeId的UTF-8字节用作MLS GroupId。

| 对象 | 关键字段与约束 |
| --- | --- |
| Device | userId、deviceId、signatureKey；deviceId为1–80位字母数字/下划线/短横线 |
| KeyPackage | TLS编码MLS字节；1–65536字节；标准base64放入JSON；id为包内容SHA-256 |
| Scope | scopeKind、scopeId、mode、creatorUserId、creatorDeviceId；blocked内部另记blocked_after_sequence |
| Event | sequence、clientId、kind、senderUserId、senderDeviceId、payload、createdAt、可选targetUserId/targetDeviceId |
| Recipient | sequence、userId、deviceId、acknowledgedAt；服务器按设备决定收件与确认 |

服务端验证密钥包的协议签名、套件和账号/设备匹配，以及非Welcome封装的消息类型和群ID；终端负责真正的MLS认证与解密。Welcome封装服务器检查类型、声明收件设备与包可用性；加入终端还必须验证群ID、邀请者credential和签名公钥，不能仅信任HTTP元数据。依据：`chat-crypto/src/lib.rs:15-16,48-98,270-309`。

MLS内容密文并不隐藏全部交付元数据。服务端仍保存范围ID、发送账号和设备、收件设备、事件种类、密文字节数、时间与确认状态，并利用当前成员目录决定谁能领取事件。协议中的加密内容保护不能推导出匿名通信、隐藏社交关系或服务器完全不知道消息活动；公开文档也不应将这些可见元数据称为已加密正文的一部分。依据：`chat-service/src/e2ee-delivery.mjs:36-52,235-255`。

## 注册、目录与claim

设备POST `/e2ee/devices/{deviceId}/key-packages`注册自己的包。相同用户与deviceId已存在时，签名公钥必须相同，否则DEVICE_KEY_CHANGED；每设备最多25个未用包。GET本设备key-packages返回registered、available。iOS登录后通常补到3个可用包，但注册本身不建立加密聊天，也不允许仅据此显示锁标记。

目录`GET /e2ee/{conversations|groups}/{id}/devices?deviceId=...`给出当前参与者的全部已注册设备，并为每设备挑最早可用包。目录读取不预留、不claim包；发起者必须准备应对另一个请求先使用同一包。只有成功写入定向Welcome的事务，才把该包claimed_sequence设为对应事件序号。

同一Welcome的完全相同重试先命中事件去重，仍返回原sequence，不会再次消费包；改新clientId却引用已claim的包得到PACKAGE_USED。不能把公开目录返回的keyPackageId当永久可复用邀请凭证。新设备首次注册会把该用户已有active范围改blocked，记录当时边界；此操作没有另写普通事件提醒，客户端需要重查模式。依据：`chat-service/src/e2ee-delivery.mjs:76-145,187-255`。

## 初次建立的次序

1. 每位当前参与者至少注册一个设备，发起设备调用prepare。仅legacy允许，成功后进入preparing并固定协议创建者账号和设备。
2. 创建者在本机建立MLS群；对每个尚未joined且未invited的目标读取包，核对或固定已知签名公钥。
3. Rust add_member生成Commit与Welcome；先以独立clientId提交Commit并确认本机pending commit，再提交定向Welcome及包ID。
4. 目标设备按sequence读取自己的Welcome，验证邀请者和群ID，持久化本地状态，然后发welcome-acks。
5. 已加入设备处理其收到的后续Commit并持久化，发送commit-acks；创建者发送的Commit由本机完成后推进自己的sequence。
6. 创建者调用activate。服务器确认所有当前注册设备均已加入并处理必要Commit，返回mode=active；此前不能发送application。

preparing只能由创建者建立群。目录中的joined不等于界面在线：它是创建者身份或Welcome已有确认的结果。一个用户有多台已注册设备时，不是只等每用户任意一台确认；离线旧设备也可能阻止激活。依据：`ios-app/Sources/Features/Chat/ChatEncryptedTransport.swift:76-150`、`chat-service/src/e2ee-delivery.mjs:159-172,301-354`。

## 状态迁移与成员变化

| 当前状态 | 允许推进 | 被禁止或要求等待的动作 |
| --- | --- | --- |
| legacy | prepare→preparing | prepare前application为NOT_PREPARED |
| preparing | 创建者Commit/Welcome；收件设备ack；创建者activate→active | application为NOT_ACTIVE，其他设备不得建立群 |
| active | application；创建者新Commit可使其blocked | 直接新Welcome会AWAITING_COMMIT |
| blocked | 创建者新Commit、必要Welcome和ack；完成后activate→active | application首先得到NOT_ACTIVE；不能回退普通消息发送 |

群成员增加、移除或退出、删除好友、屏蔽以及新设备注册会阻塞已有范围。blocked恢复需要边界之后的新Commit；每个剩余设备必须处理该Commit，或通过边界之后的新Welcome加入。activate还检查每设备后续未确认Commit。AWAITING_REKEY、AWAITING_WELCOME和AWAITING_COMMIT是不同等待条件，不该通过循环activate掩盖缺失步骤。

协议创建者设备与个人群owner不同，群主转移不会自动转移创建者权限；当前没有公开创建者迁移或设备注销路由。iOS独立prepare遇blocked直接返回模式，未自动实施完整重键协调，不能把服务端恢复契约描述成已交付的客户端自动恢复。依据：`chat-service/src/e2ee-delivery.mjs:201-211,301-363`、`ios-app/Sources/Features/Chat/ChatEncryptedTransport.swift:78-94`。

## 应用消息、游标与去重

POST events的payload最多1048576字节，JSON最多1500000字节，kind只允许welcome/commit/application。事件幂等键为发送用户+设备+clientId，同一次重试还要保持范围、kind、payload摘要、目标与包ID不变，否则CLIENT_ID_REUSED。重新加密同一业务文字会产生不同密文，不能再用原clientId提交。

GET events按当前设备收件、sequence升序、每页最多100。sequence是全表自增值，并非每会话连续无缺口；其他范围和不发给本设备的事件会造成合法跳号。普通`/events`的id是另一游标，e2ee通知中的messageId可能引用MLS sequence，但仍不能拿它替换普通事件id。

iOS独立文字payload含version=1、kind=text、clientID、text，最多65536个UTF-8字节。设备先把待发送原密文保存，再HTTP提交；响应成功后转为本地已发送消息。接收先验证MLS发送者，再与服务端senderUserId/senderDeviceId比对，解析payload并保存消息与sequence。处理或保存失败不得跳过并推进游标。

Welcome/Commit ack先保存在本地，HTTP确认成功才移出pending；确认丢失可重复提交。自身application回显不会再用接收棘轮解密，而是确认排队消息并推进序号；若既无排队项也无已确认本地消息，按状态异常处理。依据：`ios-app/Sources/Features/Chat/ChatEncryptedTransport.swift:153-263`、`ios-app/Sources/Features/Chat/ChatCryptoDevice.swift:442-510`。

## 信任固定与本地保存失败

iOS把远端账号、设备和签名公钥的对应关系固定在本机Keychain；已知设备的公钥变化时拒绝继续，首次见到设备则返回firstSeen标识。仓库有根据双方身份和公钥生成安全码的函数，但不能把这个辅助函数等同于主聊天已提供完整的用户核对流程，更不能等同于服务端目录透明性或独立身份审计。依据：`ios-app/Sources/Features/Chat/ChatCryptoTrustStore.swift:8-81`。

加密设备操作通过persisted包装：执行后保存checkpoint，若处理或落盘失败则重新读取上次磁盘状态；连恢复也失败，就把设备标为unusable并拒绝继续使用，避免在内存状态与已保存游标不一致时继续发送。checkpoint同时包含原生MLS状态、消息、游标、待发密文、待确认记录和未完成邀请。不能只备份一个sequence数字再丢掉加密群状态；重新生成设备也不能解开旧状态。依据：`ios-app/Sources/Features/Chat/ChatCryptoDevice.swift:553-605`。

## 正常与失败例

正常：甲设备创建preparing，提交C1与发给乙的W1；乙验证W1、保存并ack；甲activate成功后提交A1，响应丢失则沿用同一clientId与同一密文重试，服务端返回原sequence。序号可能为101、104、109，不要求连续。

失败：乙尚未ack Welcome就activate，得到409 AWAITING_WELCOME；换一个已经注册的deviceId却使用不同签名密钥，得到409 DEVICE_KEY_CHANGED；成员变化后直接继续application，得到409 NOT_ACTIVE；把base64编码的普通JSON冒充MLS payload会INVALID_EVENT。错误并不授权回退text/media明文路径。

本页仅说明源码协议。iOS主ChatStore目前只准备包、实际send仍普通messages；Android未接入同等MLS传输；普通文件、新事、位置和音视频均不能据此声明已使用MLS。详见[消息与媒体](https://document.thestarline.cn/app/messaging-and-media.md)、[本地数据格式](https://document.thestarline.cn/app/local-data-formats.md)、[安全和隐私](https://document.thestarline.cn/app/security-and-privacy.md)与[验收矩阵](https://document.thestarline.cn/app/qa-matrix.md)。

源码核对范围：2026-10-23 的当前实现。本轮未执行生产业务请求或原生设备验收。


原始地址：https://document.thestarline.cn/app/limits-and-errors/
Markdown：https://document.thestarline.cn/app/limits-and-errors.md

# 限制、错误码与重试规则

本页按当前聊天服务与客户端源码列出限制。数值是具体字段或路由的约束，不代表全局容量承诺；反向代理、操作系统和外部供应商还可能有独立限制，但本页不臆测未实现的策略。错误判断应结合HTTP状态、error.code和当前业务阶段。

## 单位与计数

MiB=1048576字节，KiB=1024字节。界面显示“10 MB”时，当前服务实际检查10×1024×1024字节。JSON上限计算传输字节，包含字段名、引号、转义与base64膨胀；不能仅计算正文字符。base64约为原字节数的4/3，必须规范标准编码，base64url不适用MLS payload。

多数服务端文字使用`[...text].length`计Unicode码点；iOS的String.count计字素簇，Android的length/take计UTF-16代码单元。组合重音和多码点表情等会产生不同计数。客户端允许输入不代表服务端一定接受，应保留服务端错误说明。依据：`chat-service/src/server.mjs:50-78,135-142`、`ios-app/Sources/Features/Moments/MomentComposerView.swift:97-100`、`android-app/app/src/main/java/cn/thestarline/workbench/MomentsScreens.kt:513-514`。

## 服务端大小与数量

| 对象 | 实际限制 | 超限表现 |
| --- | --- | --- |
| 默认JSON | 16384字节，根必须对象 | 413 TOO_LARGE；非JSON为415 CONTENT_TYPE |
| 普通消息 | trim后文字≤2000码点；text与一个mediaId二选一 | 400 INVALID_MESSAGE |
| 文件/聊天照片 | 单项10 MiB，非空 | 413 TOO_LARGE；空为400 EMPTY_FILE |
| 自定义贴纸 | 512 KiB；PNG/JPEG；PNG宽高1–2048 | INVALID_STICKER或TOO_LARGE |
| 聊天媒体账号配额 | 合计100 MiB；自定义贴纸100个 | 413 STORAGE_LIMIT；没有公开清理媒体配额的DELETE接口 |
| 文件名 | trim后1–120码点；无控制字符或路径分隔符 | 400 INVALID_NAME |
| 新事 | text≤2000码点；发布JSON≤20000字节；9图或单视频 | 400 INVALID_POST或413 TOO_LARGE |
| 新事媒体 | 图片10 MiB、视频30 MiB；每账号500 MiB | TOO_LARGE或STORAGE_LIMIT |
| 简介/资料受众 | bio≤160码点；selected最多100个不同当前好友 | INVALID_BIO或INVALID_VIEWERS |
| 个人群 | name为1–40码点；创建/邀请1–49个不同好友；全群≤50人 | INVALID_GROUP_NAME、INVALID_GROUP_MEMBERS或NOT_FRIENDS |
| 新事评论/举报 | 评论1–500码点，举报1–200码点 | INVALID_COMMENT或INVALID_REPORT |
| 记忆识别 | text为2–2000码点 | INVALID_MEMORY_TEXT |
| MLS密钥包 | TLS字节1–65536；JSON≤100000字节；每设备未用包≤25 | INVALID_KEY_PACKAGE、TOO_MANY_PACKAGES或TOO_LARGE |
| MLS事件 | payload 1–1048576字节；JSON≤1500000字节 | INVALID_EVENT、INVALID_CIPHERTEXT或TOO_LARGE |
| iOS独立MLS文字 | 非空、≤65536 UTF-8字节 | 本地invalidState；不适用于普通消息接口 |

依据：`chat-service/src/server.mjs:350-365,416-474,498-558,662-680,775-817,916-925`、`chat-service/src/database.mjs:219-226`、`chat-service/src/moments-repository.mjs:102-137`、`ios-app/Sources/Features/Chat/ChatCryptoDevice.swift:442-457`。

## 分页、有效期与已有频率计数

| 类型 | 值与边界 |
| --- | --- |
| 单聊/群消息 | 默认50、最多100；limit最少1；before与非零after不能混用，群不支持单聊after契约 |
| 普通events | 每批最多100，wait默认20秒、0–25秒；游标非负安全整数 |
| MLS events | 每批100、立即查询；sequence可合法跳号 |
| 新事feed | 默认20、最多50；comments和notifications每页30 |
| 通话历史 | 最近100条终态；无公开该路由分页游标 |
| 原生登录/聊天ticket/session | 10分钟/60秒/24小时；Account OIDC token期限另算 |
| 临时好友码/转出flow/媒体token | 10分钟/5分钟/30秒 |
| 呼叫与空房 | 约60秒未接超时；默认每10秒检查媒体空房，连续空约90秒结束 |
| 未绑定新事媒体 | 超过24小时可清理，不是所有已发布媒体24小时到期 |

当前`allowFriendLookup`按用户+method维护10分钟固定窗口：phone与temporary-code各最多20次，generate-code最多10次，memory-recognition最多10次。窗口从该方法当前计数周期第一次请求起计算；达到上限后不会因持续失败自动延长窗口。格式验证失败一般在计数前拒绝；格式正确但查不到目标也会计数，模型调用开始后失败可能已经计数。

未见对普通messages发送、全部GET、群操作或新事发布统一应用此计数器，也没有该代码自动返回Retry-After或剩余额度头的契约。不能把10分钟20次写成全站限流。依据：`chat-service/src/database.mjs:386-400`、`chat-service/src/server.mjs:775-790,832-898,1186-1190`。

## HTTP错误的触发条件

| HTTP / error.code | 典型触发条件 | 下一步 |
| --- | --- | --- |
| 400 INVALID_JSON / INVALID_INPUT | JSON无效、数组根、联系人添加方式不唯一、字段类型错误 | 修正请求结构，不能原样重试 |
| 400 INVALID_CURSOR / INVALID_LIMIT | 非安全整数、负游标、数量为0、混合前后游标 | 使用正确资源游标；最少1条 |
| 400 INVALID_PHONE / INVALID_FRIEND_ID / INVALID_FRIEND_CODE | 手机号、好友ID或临时码格式错误 | 本机规范化后再提交 |
| 400 INVALID_MESSAGE / INVALID_CLIENT_ID | text和media互斥失败、文字过长、UUID不合规、read目标不属于聊天 | 修正字段，不生成空消息 |
| 400 INVALID_POST / INVALID_COMMENT | 受众不符、媒体被绑定、图视频混传、回复不属于帖子 | 重读关系/资源；不要盲重发 |
| 400 NOT_FRIENDS | 建群成员未满足好友条件；邀请成员也可因加入后超过50人失败 | 分别检查目标用户UUID、当前好友关系与群容量，不能仅按“已断交”解释 |
| 400 INVALID_LOCATION / 409 NOT_SHARING | 坐标无效，或PUT前未开启共享 | 修正坐标；共享必须由用户显式开始 |
| 401 UNAUTHORIZED / INVALID_TICKET | 聊天session失效，或ticket过期、重放、proof错误 | 重新登录；不能删除proof降级 |
| 403 CONTACT_BLOCKED / NOT_FRIENDS | 联系动作中任一方屏蔽或当前不再是好友；建群/邀请的同码400例外见上行 | 刷新关系，停止发送/位置/通话动作 |
| 403 FORBIDDEN | 非群主或非企业授权角色等 | 使用真实有权身份，不绕过UI校验 |
| 404 NOT_FOUND / PROFILE_NOT_FOUND / NOT_MEMBER | 无记录、资源不可见、已退出范围等 | 刷新列表；不要枚举ID探测 |
| 409 CLIENT_ID_REUSED | 同幂等ID改了范围、正文、媒体或MLS密文 | 恢复原请求；新用户动作才用新ID |
| 409 ALREADY_FRIENDS / INCOMING_REQUEST | 已有好友关系或反向申请 | 进入既有会话或接受incoming |
| 409 E2EE_REQUIRED / NOT_ACTIVE | 非legacy尝试普通发送，或MLS尚未激活 | 走正确协议并补必要确认，不退回明文 |
| 409 CALL_BUSY / CALL_STATE | 另有通话或邀请、参与状态已变化 | 重查active/current，再决定动作 |
| 413 TOO_LARGE / STORAGE_LIMIT | 单次请求过大或账号媒体配额满 | 减小输入；重试不增加可用配额 |
| 415 CONTENT_TYPE / 416 INVALID_RANGE | JSON类型错误，或新事媒体Range语法/起止无效 | 改Content-Type或合法单段范围 |
| 429 TOO_MANY_LOOKUPS / TOO_MANY_CODES / TOO_MANY_RECOGNITIONS | 对应用户method计数达到上限 | 停止密集重试，等该窗口结束 |
| 503 LOGIN_UNAVAILABLE / E2EE_UNAVAILABLE / CALL_MEDIA_UNAVAILABLE / MEMORY_MODEL_UNAVAILABLE / CITY_STICKER_UNAVAILABLE | 缺配置、校验器/媒体/模型/素材不可用等 | 保留本机状态，检查具体依赖，适度重试 |
| 500 INTERNAL | 未被路由映射的异常 | 保留脱敏上下文，先确认是否实际写入 |

MLS错误映射存在细节：NOT_MEMBER→404、UNKNOWN_DEVICE→403，INVALID_KEY_PACKAGE/INVALID_EVENT/INVALID_RECIPIENT/INVALID_WELCOME→400，其余具名错误通常409。因此INVALID_COMMIT当前是409，不能只按“INVALID前缀都400”分类；缺devices查询deviceId的INVALID_DEVICE为400，而包可用性内部的同名错误走409映射。依据：`chat-service/src/server.mjs:1193-1203`。

发送权限与历史读取权限并不对称。CONTACT_BLOCKED/NOT_FRIENDS约束相关发送、位置或通话动作，不能推导普通旧附件必然404；普通单聊媒体凭仍可见消息读取时没有重新查好友/屏蔽，所有者还可独立下载。新事媒体则重新按帖子可见性过滤。依据：`chat-service/src/database.mjs:239-254`、`chat-service/src/moments-repository.mjs:117-123`。

## 重试必须区分是否有幂等键

正常幂等例：普通消息POST使用相同clientId和相同内容，第一次响应丢失后重试返回200及原message；MLS沿用同clientId、同密文和同目标重试返回原sequence。不能重新加密后沿用旧ID。GET可恢复查询，已读只前进，PUT like设置同一状态可重复。

失败风险例：新事POST、评论POST与媒体上传没有同等clientId契约，响应丢失后直接重发可能重复内容或额外占用配额；先查询最新记录确认。生成好友码重试会替换旧码；申请接受重试可能因原申请已删除而404，此时应查会话而非认为好友建立必失败。换票响应丢失后ticket可能已消费，重试401需重新发起授权，不能恢复出未收到的token。

不要将401自动重试成无限登录循环，也不要把所有503视为无副作用：关系操作在媒体调用阶段失败与消息提交后刷新失败有不同边界。本机退出成功也不能证明远端logout成功；Account改密不自动撤销聊天session。依据：`chat-service/src/database.mjs:524-551,635-652`与[登录与会话](https://document.thestarline.cn/app/authentication.md)。

## 当前客户端差异

Android新事先选selected好友再切到其他visibility时，仍可能携带非空viewerIds，服务端返回400 INVALID_POST；iOS发布前在非selected时发送空列表。iOS独立MLS prepare遇blocked只返回模式，不自动完成重键，继续应用发送会因未active而拒绝。这些是本轮源码核出的失败路径，未运行或修复原生代码，不能标成验收通过。对应依据见[新事](https://document.thestarline.cn/app/moments.md)和[MLS协议](https://document.thestarline.cn/app/mls-protocol.md)。

## 客户端时限与验收

通用iOS JSON请求通常15秒、普通/events为32秒；聊天媒体60秒，新事媒体90秒。Android连接15秒，普通JSON读20秒、events读35秒、上传下载读90秒。它们是网络调用时限，不是文档或媒体预览的自动关闭时间，也不代表服务器一定在时限内取消已提交操作。依据：`ios-app/Sources/Features/Chat/ChatAPI.swift:45-96`、`ios-app/Sources/Features/Moments/MomentsStore.swift:186-227`、`android-app/app/src/main/java/cn/thestarline/workbench/AppData.kt:26-94`。

当前两端错误包装主要保留HTTP状态与message，并非都向业务层保留error.code；排错应记录已脱敏的状态、阶段与资源类型，不能记录Bearer、ticket、verifier或用户正文。字段全表见[API参考](https://document.thestarline.cn/app/api-reference.md)，恢复步骤见[故障处理](https://document.thestarline.cn/app/incident-runbooks.md)，场景验证见[验收矩阵](https://document.thestarline.cn/app/qa-matrix.md)。本轮为源码与文档核对，未执行生产业务或原生验收。

源码核对范围：2026-10-23 的当前实现。本轮未执行生产业务请求或原生设备验收。


原始地址：https://document.thestarline.cn/app/contacts-and-groups/
Markdown：https://document.thestarline.cn/app/contacts-and-groups.md

# 联系人、好友申请与个人群

好友关系、屏蔽关系、聊天可见性和群成员是四类独立状态。删除聊天不等于删除好友，群静音不等于屏蔽群成员，个人删除消息也不是全员撤回。本页给出这些状态的操作顺序、权限与恢复边界；全部业务请求使用聊天 Bearer 会话。

## 三种添加方式

`POST /friend-requests` 的 JSON 在下列三个字符串字段中恰选一个。不要同时发送空字符串的备用字段，因为服务端按字段是否为字符串计数。

| 字段 | 规范化与验证 | 额外条件 |
| --- | --- | --- |
| friendId | 删除空格、短横线并大写；11位字母数字 | 查找唯一聊天好友ID；不是Account用户ID |
| phone | 删除空格、短横线；大陆11位号码补+86；国际号码带+ | 只查登录时取得、尚未过期的已验证手机号摘要 |
| temporaryCode | 删除空格、短横线并大写；12位十六进制 | 对方用`POST /friend-codes`生成，10分钟有效 |

临时码按账号保存HMAC摘要，生成新码替换旧码；生成每用户每10分钟最多10次。手机号与临时码查找各自每10分钟最多20次，好友ID路径没有在该层调用同一计数器。不能由此推导全部联系人请求都有统一限流。依据：`chat-service/src/server.mjs:832-898`、`chat-service/src/database.mjs:371-400`。

临时码不是“成功成为好友才消费”：服务端找到有效码，排除添加自己和双方屏蔽后就删除该码，然后执行申请状态判断。因此同向pending、已是好友、存在反向申请，也可能已经消费临时码。重试前先刷新申请和会话列表，不应反复提交同一码。依据：`chat-service/src/database.mjs:500-509`。

## 申请与接受的完整顺序

1. 发送申请前展示目标添加方式，提交单一字段。
2. `201 {status:"requested",peer,requestId}`表示新建申请；当前还不是好友。接收者收到friend_request事件，刷新`GET /friend-requests`。
3. 同向申请已存在返回`200 {status:"pending",...}`，requestId可能为null，应从outgoing列表取得现有记录。
4. 对方已有反向申请返回409 INCOMING_REQUEST，转到incoming列表接受；已是好友为409 ALREADY_FRIENDS，任一方屏蔽为403 CONTACT_BLOCKED。
5. 接收者调用`POST /friend-requests/{requestId}/accept`。服务端在事务中验证接收者、删除申请、建立或恢复双方唯一会话，并返回conversationId。
6. 双方按friend_accepted事件重读会话。取消或拒绝统一用DELETE申请，双方才有权限，响应status=deleted。

重新成为好友会复用原有双方会话ID，不重新建立另一份单聊；原来的个人历史可见边界也不会因此自动重置。依据：`chat-service/src/database.mjs:476-564`。

合成成功例：`{"temporaryCode":"A1B2C3D4E5F6"}`对应一次申请，随后由对方按返回requestId接受。合成失败例：同时提交`{"friendId":"ABC123DEF45","phone":""}`会得到400 INVALID_INPUT，不能把空phone当作未传。票据、好友码和用户ID示例仅用于解释数据形状，不应拿真实用户资料排错。

## 手机号、资料与竞争更新

手机号添加使用Account最近登录返回的已验证号码摘要，当前聊天服务将可查找期限设为24小时；它与个人资料中自行填写、按private/selected/friends/everyone显示的contactPhone是不同字段。隐藏资料联系电话并不等同于关闭上述已验证号码查找路径，修改资料电话也不更新Account身份号码。界面应按实际字段解释行为，不能从一个开关推断另一个功能已经关闭。依据：`chat-service/src/database.mjs:279-287,324-375`。

申请列表只是快照：在用户点击接受前，对方可能取消申请，或任一方完成屏蔽。服务端事务重新校验并决定结果，客户端不能仅凭卡片曾显示就假定成功。接受请求若响应丢失，重试可能404，因为原申请已经删除；此时重读conversations确认双方关系。正常情况下，同一对用户始终复用唯一会话，客户端应按conversationId合并，而不是给每次接受创建重复条目。

## 屏蔽与删除好友

`PUT /blocks/{userId}`是有方向的本人屏蔽；业务检查会合并任一方向屏蔽。成功后清掉双方未完成申请及对应单聊的全部实时位置记录，写入block_changed事件，但不将is_friend改为false，也不删除已有聊天正文。`DELETE /blocks/{userId}`只解除本人的屏蔽，不恢复已删除的申请或位置共享，也不能解除对方对自己的屏蔽。

若存在该单聊通话，屏蔽路由先删除媒体房间并结束通话；媒体处理失败返回503，不能把界面按钮点击当作已完成屏蔽。已有MLS范围会被阻塞。依据：`chat-service/src/server.mjs:845-864`、`chat-service/src/database.mjs:672-725`。

`DELETE /friends/{conversationId}`中的路径参数是会话ID。它将is_friend改false、清理双方申请与单聊实时位置，并通知双方；历史消息与会话记录继续存在。恢复联系需重新申请并接受。非好友不能继续普通发送、开始或接听单聊通话、开始或更新单聊实时位置。

历史读取需要单独判断：普通聊天媒体的所有者可直接下载；非所有者凭仍可见的消息授权，受个人历史边界和单条隐藏过滤。单聊媒体查询不重新检查is_friend或block，因此屏蔽、删好友不保证旧的可见媒体立即失效。群消息授权分支要求当前群成员，但媒体所有者分支仍独立存在。删除本人消息也不会物理删除自己上传的文件。依据：`chat-service/src/database.mjs:239-254`。

## 个人群权限与成员历史

| 动作 | 请求字段 | 权限与结果 |
| --- | --- | --- |
| 创建群 | name为1–40字；memberIds为1–49个不同好友用户id（UUID），不含自己；不是11位friendId | 发起者成为群主；包含自己后最多50人 |
| 邀请成员 | memberIds为1–49个不同好友用户id（UUID），不是11位friendId | 仅群主；只把不在群中的对象当新增，总数最多50 |
| 改名 | name为1–40字 | 仅群主；产生group_renamed事件 |
| 移除成员 | 路径目标用户ID | 仅群主；不能移除自己，应走leave |
| 退出群 | 无业务字段 | 当前成员；群主退出会自动转移归属 |
| 解散群 | 无业务字段 | 仅群主；先处理进行中的通话，再清理群相关数据 |

创建时所有成员从新群开始；后续加入者的visible_after_message_id及last_read_message_id都设为加入当时最新群消息ID，所以不能阅读入群前历史。群主退出时，服务端按joined_at、user_id排序选最早剩余成员为新群主；最后成员退出删除群核心记录。leave与disband是不同清理分支，不能将最后成员退出描述成执行了完整解散清理。依据：`chat-service/src/database.mjs:764-777,950-1033`。

移除成员、退出与解散会处理相应通话及位置共享；移除或退出使当前MLS范围blocked。群主的个人身份与MLS创建者设备是不同角色，群主转移并不自动转移MLS创建者权限。企业组织和企业频道另见[工作台](https://document.thestarline.cn/app/workbench.md)，不是此处的个人群功能。

## 隐藏、删除与恢复

| 操作 | 服务端变化 | 能否恢复旧历史 |
| --- | --- | --- |
| DELETE某条messages/{messageId} | 给当前用户插入hidden_messages | 没有公开单条取消隐藏接口；其他人仍可见 |
| DELETE单聊 | 本人is_hidden=true，历史边界推进到当时最后消息 | restore只取消隐藏，不倒退边界 |
| DELETE个人群视图 | 本人隐藏、历史边界与已读位置都推进 | restore不恢复边界前消息，也不等于重新入群 |
| POST群mute | 只修改本人is_muted | 可再次设false；不改变成员关系、正文或已读 |

`includeHidden=1`用于获取自己仍有资格访问的隐藏会话或群。普通新消息会重新显示隐藏聊天，但旧历史边界仍有效。群静音更新没有在该方法中写入普通events，不能把它承诺为通过事件即时同步的跨设备设置。依据：`chat-service/src/database.mjs:635-652,730-760,855-880,904-925`。

## 已读与异常处理

单聊`/read`和群`/read`发送`{lastMessageId}`，位置只前进；目标消息必须属于当前聊天，群还要求消息晚于该成员历史边界。0虽然通过整数格式检查，但并不对应实际消息，仍会INVALID_MESSAGE。单聊用peerReadMessageId表示对方已读，群用其他成员已读位置最小值allReadMessageId；不能通过未读数算出逐人阅读时间。

正常例：连续提交同一有效lastMessageId均可返回status=read，第二次不重复推进；失败例：把单聊消息ID提交给群read得到400 INVALID_MESSAGE。收到404时先刷新当前成员和申请状态，403先处理权限与屏蔽，409 CLIENT_ID_REUSED不得更改内容后继续沿用原发送ID。完整参数见[API参考](https://document.thestarline.cn/app/api-reference.md)，错误与重试见[限制与错误](https://document.thestarline.cn/app/limits-and-errors.md)。本页依据源码阅读，未构成真实双端验收。

源码核对范围：2026-10-23 的当前实现。本轮未执行生产业务请求或原生设备验收。


原始地址：https://document.thestarline.cn/app/messaging-and-media/
Markdown：https://document.thestarline.cn/app/messaging-and-media.md

# 消息、媒体与 MLS 数据流

星线 App 当前主聊天界面通过普通消息 API 发送文字或媒体引用。仓库另外实现了 Rust MLS 核心、服务端加密事件流和 iOS 独立加密传输器。本页分别说明实际消息路径与 MLS 协议，尤其明确附件是否经过客户端加密，避免把已有加密模块扩大描述为所有聊天数据已经端到端加密。

## 当前普通消息路径

客户端在单聊调用 `/conversations/{id}/messages`，在群聊调用 `/groups/{id}/messages`。请求必须包含合法 UUID `clientId`，并在非空 `text` 和一个 `mediaId` 中二选一。文字会 trim，最多 2000 个 Unicode 码点。消息写入后返回 `{message}`；首次写入为 201，完全相同的重试为 200。

客户端应为一次用户发送动作生成一次 clientId，失败重试沿用该 ID。服务端不仅检查 ID，还检查范围、正文和媒体是否一致；复用 ID 发送不同内容得到 409 `CLIENT_ID_REUSED`。客户端可先展示 sending，再按回执或同步结果合并，网络失败展示 failed 并提供重试。HTTP 成功代表服务端已接受，不能单凭它显示“对方已读”。

单聊发送要求当前仍是好友且双方均未屏蔽；群发送要求当前是成员。普通消息表保存服务端可读正文和媒体引用。当前 iOS 主 `ChatStore` 与 Android 发送路径均使用这些接口；注册 MLS 密钥包不会自动改变这条链路。

## 分页、已读与删除

单聊列表支持 `after` 增量或 `before` 旧消息分页，非零 after 不能与 before 同时使用；群消息只支持 before。默认 50 条、最多 100 条，返回顺序为时间线升序。最新页和 before 页内部从数据库倒序取数后再反转，因此界面不需要额外反转。第一页不要传 `before=0` 代替“没有游标”。

已读接口发送 `{lastMessageId}`，必须指向当前范围的实际消息，已读位置只前进。单聊回执使用对方 `peerReadMessageId`，群的已读信息按群模型处理。删除消息只对当前用户隐藏；删除聊天还会推进个人历史可见边界。恢复聊天不会恢复已越过的旧历史，也不会向其他参与者发起撤回。

## 附件实际上传与访问

先用原始二进制请求体调用 `POST /media?kind=file&name=...`，成功返回 `{media:{id,kind,name,mimeType,size,createdAt}}`，再把 mediaId 放入消息发送请求。请求体不是 multipart，也不是 base64 JSON。当前实现直接保存上传字节；客户端未生成独立附件密钥，未先把照片或文件封装为密文，也没有下载后的附件解密步骤。因此不能将这些附件称为 MLS 加密附件。

| 类型 | 单项限制 | 其他限制 |
| --- | --- | --- |
| 普通文件、聊天照片 | 10 MiB，即 `10*1024*1024` 字节 | 非空；MIME 需符合类型格式 |
| 自定义贴纸 | 512 KiB | 有效 PNG/JPEG；PNG 宽高均为 1–2048；每账号最多 100 个自定义贴纸 |
| 聊天媒体总量 | 每账号 100 MiB | 普通文件与贴纸共同计入字节配额 |
| 文件名 | 最多 120 个 Unicode 码点 | 禁止控制字符、斜杠与反斜杠 |

`GET /media/{id}` 要求 Bearer token。所有者可下载，其他用户必须能看到引用该媒体的消息，且不能越过个人历史边界或单条隐藏记录。返回 `Content-Disposition: attachment`、`nosniff` 和私有缓存头。当前普通附件下载不实现 Range 分片。UUID 不是访问许可。普通单聊媒体的可见消息授权分支不重新检查好友或屏蔽，因此删好友、屏蔽不等于撤销全部历史媒体访问；群消息授权分支要求当前成员，媒体所有者分支则独立存在。依据：`chat-service/src/database.mjs:239-254`。

iOS 上传照片会先缩放到最长边不超过 2048 像素并转 JPEG，普通文件检查是否为非空规则文件及大小；这属于客户端预处理，不改变服务端可读性。城市贴纸通过 `/stickers/city` 选择服务器内置素材，按账号与素材键去重；`GET /stickers` 列出自定义贴纸，不包含所有内置城市贴纸。

## 新事媒体使用另一套契约

新事图片允许 JPEG/PNG，最大 10 MiB；视频允许 MP4/MOV，最大 30 MiB，检查 `ftyp` 文件标识。每账号新事媒体配额为 500 MiB。一个帖子最多 9 张图片，或仅 1 个视频，不能混发图片和视频。媒体必须属于当前用户、尚未绑定其他帖子。

新事媒体读取依据帖子可见性，支持单个 `bytes=start-end` Range，返回 206 或 416；未绑定帖子的媒体仅所有者可读，超过 24 小时会清理。新事图文与评论保存在服务端，不属于 MLS 聊天事件流。

## MLS 设备与会话建立

加密核心使用 MLS 1.0 和固定套件 `MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519`。设备身份包含聊天用户 ID、设备 ID 和签名公钥，密钥包必须通过 OpenMLS 签名、有效性及套件检查，并与已认证用户和路径设备匹配。相同设备不能静默替换签名公钥，每设备最多保存 25 个未使用密钥包。

1. 设备注册密钥包，服务端保存可验证的公钥材料；私钥留在设备。
2. 范围当前是 legacy 时，创建者调用 prepare。每位当前参与者至少要有一个已注册设备，范围变为 preparing。
3. 创建者在本机创建 MLS 群，按设备获取可用密钥包，生成 Commit 与定向 Welcome，使用不同 clientId 依次提交。
4. 目标设备处理 Welcome、核对邀请者身份并固定签名公钥，完成本地持久化后提交 welcome-ack；已有设备处理后续 Commit 并提交 commit-ack。
5. 创建者 activate。服务端确认当前所有设备已加入并处理所需 Commit，范围才变为 active。
6. active 范围接受 application 密文事件。客户端处理 MLS 消息，核对加密层认证的发送用户、设备与服务端元数据一致，然后解析应用载荷。

密钥包 TLS 字节最大 65,536 字节，事件 MLS payload 最大 1,048,576 字节，使用规范标准 base64 置于 JSON。事件 JSON 请求体上限为 1,500,000 字节。iOS 独立文字加密载荷为 version=1、kind=text、clientID、text，文字上限另为 65,536 UTF-8 字节；这不等于普通文字接口的 2000 字限制，也不构成大附件传输方案。

## 模式、重试与恢复

一旦存在 preparing、active 或 blocked 范围，旧 POST messages 接口就返回 `E2EE_REQUIRED`，防止改走明文。注册新设备、群成员变化、删除好友或屏蔽可使已存在加密范围 blocked；完成新的成员 Commit、Welcome 和必要确认后，创建者才可再次 activate。不要把等待设备上线解释成消息已经交付。

服务端对每个发送用户、设备、clientId 去重，并比较密文摘要、类型和目标。iOS 把待发送密文、pending invite、ack 和 sequence 连同 MLS 状态保存，重试时使用原密文，不重新加密同一排队消息。独立传输器存在不代表主聊天界面已完成接入；Android 当前未见相应 MLS 发送链路。

当前不能宣称所有文字、附件、新事、实时位置或音视频均已端到端加密，也不能宣称已完成生产安全审计。接口细节见[API 参考](https://document.thestarline.cn/app/api-reference.md)，密钥与威胁边界见[安全和隐私](https://document.thestarline.cn/app/security-and-privacy.md)。

密钥包claim、设备确认、非连续sequence与blocked恢复的详细次序见[MLS协议](https://document.thestarline.cn/app/mls-protocol.md)；重试边界见[限制与错误](https://document.thestarline.cn/app/limits-and-errors.md)。


原始地址：https://document.thestarline.cn/app/moments/
Markdown：https://document.thestarline.cn/app/moments.md

# 新事的发布、可见性与媒体

新事是服务端保存的图文与短视频内容，使用独立于聊天消息的表、媒体配额和通知机制。它没有接入MLS；可见范围由每次读取时的当前关系决定。服务端支持媒体Range，但当前iOS与Android播放器路径都先完整下载后播放。

## 模型与响应字段

| 对象 | 字段与含义 |
| --- | --- |
| Post | id、authorId、text、visibility、createdAt、author、media、likeCount、commentCount、liked、recentComments；作者读selected帖子另有viewerIds |
| Media | id、name、mimeType、kind=image/video、size、createdAt；原始字节另存BLOB |
| Comment | id、postId、authorId、replyToId、text、createdAt、authorName |
| Notification | id、actorId、actorName、postId、commentId、kind、createdAt、readAt；kind为like/comment/reply |

帖子、评论、通知ID为各自的整数序列，媒体和用户为UUID；createdAt/readAt是Unix毫秒，readAt可null。完整表定义及模型组装见`chat-service/src/moments-repository.mjs:8-71,149-164,204-231,277-301`。

## 可见范围不是发布时冻结的好友快照

| visibility | 作者之外的读取规则 |
| --- | --- |
| friends | 当前仍是好友、没有任一方向屏蔽 |
| selected | 上述好友条件成立，且用户在该帖moments_audience中 |
| public | 已登录聊天API用户，双方未屏蔽；不是匿名公开网页 |
| private | 只有作者 |

个人hide优先过滤，包括作者本人隐藏自己的帖子后也不会通过普通post读取。作者通常可读自己的帖子，其他用户还会结合屏蔽与当前好友关系。selected发布须有至少一位当前未屏蔽好友，最多100、不重复，不含自己；其他范围viewerIds必须为空。删除好友后selected对象即使仍在受众表，也不再满足当前好友条件。依据：`chat-service/src/moments-repository.mjs:80-89,126-145`。

没有公开PATCH帖子或调整既有visibility的路由。若页面因失去可见资格而返回404，应按不可再读取处理，不应在客户端继续展示缓存为“公开可见”。

## 两阶段上传与发布

1. 客户端先准备媒体，按每个文件调用`POST /moments/media?name=...`，Content-Type为实际MIME，body为原始字节。
2. 上传成功得到media.id，暂时尚未绑定帖子，仅所有者可读取。
3. 客户端收齐mediaIds后调用`POST /moments`：text、visibility、viewerIds、mediaIds。
4. 服务端在事务中确认媒体为当前用户拥有、尚未绑定其他帖子，插入帖子与受众，并绑定全部媒体。
5. 返回201 `{post}`后更新列表；上传成功但未发帖不等于发布成功。

| 项目 | 服务端限制 |
| --- | --- |
| text | trim后最多2000个Unicode码点；文字或媒体至少一项 |
| 图片 | JPEG或PNG，单项10 MiB；PNG宽高1–2048 |
| 视频 | MP4或MOV，单项30 MiB；检查ftyp标识 |
| 单帖媒体 | 最多9图，或仅1段视频；不能图视频混合 |
| 账号媒体 | 新事独立500 MiB配额；未绑定媒体超过24小时清理 |
| JSON与文件名 | 发布JSON最多20000字节；name为1–120码点，无控制字符或路径分隔符 |

这些值见`chat-service/src/server.mjs:350-365,416-434`、`chat-service/src/moments-repository.mjs:97-145`。媒体原始字节和帖子内容都能被服务端读取；文件头检查不等于完整转码、恶意文件扫描或编解码器兼容性验收。

发布和上传没有clientId去重契约。若响应丢失，先查询自己的最新新事确认结果；重新上传可能额外占用空间，重复发帖也可能产生第二条。若上次实际发布成功，相同mediaIds再次发布会因已绑定返回INVALID_POST，而不是返回上次帖子。不能套用聊天消息的“相同clientId安全重试”。

## Range读取与客户端实际行为

`GET /moments/media/{mediaId}`先按当前帖子权限检查，随后处理一个可选Range。支持`bytes=0-1023`或`bytes=1024-`，不支持`bytes=-1024`、多段或其他语法。合法范围返回206、Content-Range和Content-Length；不带Range返回200。结束位置超出文件末尾会截到末尾，起点超出大小、起点大于终点或非安全整数返回416 INVALID_RANGE。缓存为private、max-age=300，不是公开CDN许可。

合成例：对大小2048字节的有权访问媒体，请求`Range: bytes=0-1023`返回前1024字节；`bytes=2048-`返回416。首次未绑定媒体仅本人能下载，即使另一个用户知道媒体UUID也返回404。依据：`chat-service/src/server.mjs:367-392`、`chat-service/src/moments-repository.mjs:117-123`。

iOS `MomentsStore.mediaData`只接受200，把完整Data缓存，视频写临时mp4/mov再交AVPlayer；Android下载也只接受200，按图片10 MiB、视频30 MiB有界读取，点击视频后才下载并写缓存文件交VideoView。因此“后端支持Range”不代表当前两端已实现边下载边播放。依据：`ios-app/Sources/Features/Moments/MomentsStore.swift:186-206`、`android-app/app/src/main/java/cn/thestarline/workbench/MomentsScreens.kt:380-438`。

## 点赞、评论、删除和通知

PUT like为幂等点赞，DELETE like为取消；只有首次新增点赞产生通知，给自己的内容点赞不通知自己。评论1–500字，可带同帖replyToId，成功后产生comment或reply通知；回复对象缺失为INVALID_COMMENT。作者可删除自己评论，帖子作者可删除其帖下任意评论。删除被回复评论会把后续评论的replyToId置null，不会一并删掉所有回复。

只有帖子作者可DELETE帖子，数据库外键级联删除其媒体、评论、点赞与相关通知。hide只对本人隐藏，report以帖子+举报者去重并更新原因，不能举报自己的帖子。report成功只证明记录写入，不证明已有审核处理工作流。依据：`chat-service/src/moments-repository.mjs:188-267`。

Feed默认20、最多50条；before指向更旧帖子，返回nextBefore，不能把缺省替换成0。评论与通知固定每页30，通常倒序，nextBefore=null表示该次查询没有下一页。通知列表动态过滤屏蔽和不可见帖子，unreadCount按当前可见通知计算；mark read会将当前账号全部未读通知标记已读。新事没有在这些方法中写普通/events，客户端靠进入页面或显式刷新同步。

## 分页合并、互动历史与账号切换

feed在内部每次扫描最多100条候选，再逐条检查当前可见性，累积到请求数量加一才决定下一页。因此返回ID不连续、帖子数量少于候选数量都是正常情况；分页应使用nextBefore，不应自行减ID或认为被过滤内容不存在。客户端追加下一页还按帖子ID去重，避免刷新与分页重叠产生重复卡片。依据：`chat-service/src/moments-repository.mjs:166-185`、`ios-app/Sources/Features/Moments/MomentsStore.swift:67-77`。

通知记录的是过去发生的互动。取消赞只删除like关系，没有同步删除原来的点赞通知；取消后再点赞可能产生新的互动通知。当前liked状态应以帖子响应为准，不能由“收到过点赞通知”推断。评论者、帖子作者和被回复者相同时，会避免给同一人重复生成自己参与的通知；通知可见性仍在读取时重新过滤。

iOS在refresh检测到账号变化或退出时清空帖子、通知和内存媒体缓存，并删除其登记的视频临时文件；这不等于整个操作系统缓存已擦除。下载完成与刷新之间若账号发生变化，还需通过客户端生命周期测试验证旧响应不会影响新账号。本轮只记录源码机制，没有执行切换账号或缓存清除验收。依据：`ios-app/Sources/Features/Moments/MomentsStore.swift:31-63`。

## 双端差异与失败样例

| 场景 | iOS当前实现 | Android当前实现 |
| --- | --- | --- |
| 图片准备 | 最长边缩到2048，以0.82质量重编码JPEG | 读取选择器原始JPEG/PNG字节，最多读上限+1；不做同等重编码 |
| 文字计数 | Swift String.count，按字素簇提示和禁用发布 | Kotlin take(2000)/length，按UTF-16代码单元截取 |
| 指定受众 | 候选过滤isFriend与非isBlocked；非selected强制发送[] | 候选从conversations取peer；发布固定带selected列表 |
| 发布后刷新 | 将返回post插入当前列表 | 确认提交后切回新事，再刷新列表 |

服务端计数是Unicode码点，包含组合字符的输入可能与两端计数不同，以服务端判定为准。Android还有源码可推导的失败场景：先选指定好友，再切到friends/public/private，selected列表未清空仍随请求发出，服务端因非selected带viewerIds拒绝400 INVALID_POST；iOS发送前清空该字段。该场景本轮未运行原生验收，不能写成已修复。依据：`ios-app/Sources/Features/Moments/MomentComposerView.swift:36-62,194-236`、`ios-app/Sources/Features/Moments/MomentsStore.swift:91-108`、`android-app/app/src/main/java/cn/thestarline/workbench/MomentsScreens.kt:458-500,513-554`。

正常例：friends+viewerIds=[]+一张刚上传的本人图片返回post。失败例：混传一图一视频、引用别人媒体、复用已绑定媒体或selected列表含已删除好友，均不会完成新帖子写入。详见[API参考](https://document.thestarline.cn/app/api-reference.md)、[限制与错误](https://document.thestarline.cn/app/limits-and-errors.md)及[验收矩阵](https://document.thestarline.cn/app/qa-matrix.md)。

源码核对范围：2026-10-23 的当前实现。本轮未执行生产业务请求或原生设备验收。


原始地址：https://document.thestarline.cn/app/location-sharing/
Markdown：https://document.thestarline.cn/app/location-sharing.md

# 城市提示与实时位置共享

城市贴纸推荐、一次性地点消息和实时位置共享是不同功能。城市识别只为推荐素材；实时共享会把精确坐标和时间持续写入聊天服务，必须由用户显式开始，并在停止、权限变化、断网和退出账号时分别处理本机采集与远端记录。

## 三条位置路径

| 路径 | 数据与用途 | 是否自动开始实时共享 |
| --- | --- | --- |
| 城市提示`GET /location/city` | 请求来源公网地址映射到city、countryCode、source=ip；可返回null | 否 |
| 城市贴纸设备定位 | 前台取一次定位并经系统地理编码得到城市，再匹配本地目录 | 否 |
| `/conversations/{id}/live-locations`或`/groups/{id}/live-locations` | 当前范围用户的经纬度、精度、开始和更新时间 | 只有POST显式开始 |

城市接口不返回街道或坐标。服务端仅在连接对端属于可信代理allowlist时接受代理覆盖的单个X-Real-IP，不读取X-Forwarded-For；非公网来源、目录缺失、校验失败或查不到城市时返回null而非伪造结果。依据：`chat-service/src/city-location.mjs:99-124`。

iOS城市定位期望约三公里精度、10秒取值超时，不启用后台更新；iOS选择器并行尝试设备与IP，设备结果优先，10分钟内可复用结果，手动选择会使旧自动任务失效。Android城市定位只做一次前台fix，地理编码前把经纬度量化到0.02度网格。系统地理编码仍有其系统服务的数据边界，不应把“坐标不传聊天城市接口”扩大成“整个定位过程不接触外部服务”。依据：`ios-app/Sources/Features/Chat/CityStickerDeviceLocator.swift:18-108`、`ios-app/Sources/Features/Chat/CityStickerSelection.swift:36-113`、`android-app/app/src/main/java/cn/thestarline/workbench/CityStickerLocation.kt:44-90`。

## 实时共享的数据与权限

| 字段 | 类型与约束 |
| --- | --- |
| scopeKind、scopeId | conversation/group与对应聊天ID；用不同路径区分 |
| userId、displayName | 由已登录会话决定；请求不能替别人上传 |
| latitude、longitude | 有限数字；纬度-90至90，经度-180至180 |
| accuracy | 有限数字，0–100000，单位米；不是“误差越大越可信” |
| startedAt、updatedAt | 服务端Unix毫秒；前者首次开始时间，后者最近成功写入时间 |

所有操作都要求Bearer与当前范围成员资格。单聊POST/PUT还要求仍是好友且任一方均未屏蔽；DELETE只停止自己的共享。群GET/POST/PUT/DELETE要求当前成员，不要求每两位群成员互为好友。服务端存储可读坐标，不是MLS密文；同范围有权成员能读取全部当前共享者。

依据：`chat-service/src/server.mjs:101-109,582-610`、`chat-service/src/database.mjs:1037-1085`。

## 从开始到恢复的操作次序

1. 用户明确选择共享并确认，客户端请求系统位置权限；Android当前界面还要求通知权限，用于持续共享通知。
2. 获得有效坐标后POST范围路径，请求只包含latitude、longitude、accuracy。成功201 `{location}`后才登记本机共享范围并启动持续定位。
3. 后续位置更新使用PUT，同一用户、范围只更新一条记录；首次startedAt不重置，updatedAt更新为本次服务端时间。
4. 页面单独GET范围位置，当前两端聊天面板约每4秒刷新；位置写入没有普通/events通知，不应等待message事件才刷新地图。
5. 登录或恢复时GET `/live-locations/mine`取得本人的共享范围，然后与权限和本机定位状态协调。
6. 用户结束该范围时DELETE，成功200 `{status:"stopped"}`后从本机集合和界面移除；没有其他共享范围才停止持续采集。

POST会upsert既有自己的记录，PUT不会创建新共享：未POST就PUT返回409 NOT_SHARING。客户端不能在PUT失败时自动POST恢复，因为这可能在用户已结束共享后重新开启。依据：`chat-service/src/database.mjs:1063-1085`、`ios-app/Sources/Features/Chat/ChatStore.swift:577-645`。

合成正常请求：`{"latitude":0,"longitude":0,"accuracy":25}`是合法测试坐标值，不代表用户真实位置。POST后GET应出现当前用户并有两个时间字段；DELETE后GET不再出现。合成失败请求：`{"latitude":91,"longitude":0,"accuracy":25}`返回400 INVALID_LOCATION；不应因缺少定位结果而把用户默认为零坐标发送。

同一个账号可同时向多个聊天范围共享，同一条本机定位会依次PUT到ownLiveScopes中的各范围。停止一个聊天不会停止其他范围；只有本机剩余范围为空才释放持续监听。确认“全部结束”时应重新读取mine，而不是只看当前聊天面板为空。范围内没有自己的记录，也不表示同账号在另一个群没有共享。依据：`ios-app/Sources/Features/Chat/ChatStore.swift:607-645`、`android-app/app/src/main/java/cn/thestarline/workbench/AppState.kt:387-449`。

## 持续定位的双端实现

| 场景 | iOS | Android |
| --- | --- | --- |
| 采集设置 | best accuracy、distanceFilter=10米，禁止系统自动暂停，允许后台更新 | GPS/NETWORK provider更新，最小间隔5秒、距离10米，前台定位服务 |
| 上传节流 | 至少间隔5秒，同一时刻仅一轮上传 | 单调时钟间隔至少5秒、AtomicBoolean避免并行上传 |
| 过旧fix | 接收精度非负且时间不旧于约60秒的定位 | 精度0–100000、时间不旧于60秒 |
| 范围恢复 | 按mine重建ownLiveScopes | 服务约30秒同步范围，持续通知显示状态 |
| 普通页面停止 | 先等DELETE成功，再改本机范围集合 | 同样先等DELETE成功，再停止相应本机状态 |

这些是程序配置与调度目标，不保证操作系统每5秒交付一次定位，也不代表锁屏、后台权限和省电模式已完成设备验收。iOS仅在至少一个共享范围存在时持续更新；Android服务返回START_NOT_STICKY，不保证被系统终止后自动复活。依据：`ios-app/Sources/Features/Chat/ChatLiveLocation.swift:41-107`、`android-app/app/src/main/java/cn/thestarline/workbench/LiveLocationService.kt:54-171`。

## 时间、可信程度与页面一致性

updatedAt由服务器在成功接收POST/PUT时生成，协议没有单独的定位fix时间字段。因此“刚刚更新”仅表示刚收到坐标，不能单独证明坐标刚由卫星测得、用户仍在原地或后台采集持续正常。当前官方客户端会过滤部分过旧定位，但服务端并不验证设备传感器来源。展示accuracy和最后更新时间比只显示一个地图标记更有依据。

Android刷新当前范围时会保存请求前的scope与session，响应返回后再次核对，避免原聊天的结果覆盖用户新打开的聊天。iOS当前refreshLiveLocations方法没有同等响应后scope/token核对，需要把换账号、切换聊天时旧请求晚到加入验收，不能直接承诺两端异步隔离行为完全一致。依据：`android-app/app/src/main/java/cn/thestarline/workbench/AppState.kt:374-384`、`ios-app/Sources/Features/Chat/ChatStore.swift:577-586`。

## 停止失败、权限关闭与数据保留

停止本机传感器不会自动删除服务器最后坐标，服务器删除成功也不等于系统定位监听必定已释放。两端普通页面的结束动作若DELETE失败，会保留共享状态并展示或传播错误，不应显示“已经结束”。Android持续通知的“结束全部”是另一个分支：先停止本机采集，随后DELETE所有范围，网络失败约每10秒重试，通知显示正在重试。

系统权限关闭后，本机停止或无法继续采集，但远端记录不会因此自动消失；Android明确提示打开App结束原有共享。网络暂时不可用时保留最后成功位置和updatedAt，地图应标明最后更新时间，而不是宣称仍在实时移动。依据：`android-app/app/src/main/java/cn/thestarline/workbench/LiveLocationService.kt:54-65,91-130`、`ios-app/Sources/Features/Chat/ChatStore.swift:607-645`。

当前live_locations没有expiresAt或自动过期清理字段，也不保存一张连续轨迹历史表：同一范围用户更新覆盖该行的当前坐标。DELETE停止会删除该行；屏蔽或删除好友清理对应单聊双方的位置，退出/移除群成员清理该成员的位置，解散群清理该范围全部位置。备份、日志和系统缓存的生命周期不等同于该表行删除，不能据此承诺所有副本立即销毁。依据：`chat-service/src/database.mjs:693-725,928-934,990-1033,1063-1085`。

退出账号也需区分：Android先停止本机，再尽力清理服务器共享；iOS本机退出先停止manager，但其signOut路径没有同等逐范围DELETE共享流程。聊天session到期不会自动清掉live_locations，仍有权的其他成员可能读到旧位置，直至显式停止或关系清理。此为源码边界，未据此执行真实定位请求。详见[客户端生命周期](https://document.thestarline.cn/app/client-lifecycle.md)、[限制与错误](https://document.thestarline.cn/app/limits-and-errors.md)与[安全和隐私](https://document.thestarline.cn/app/security-and-privacy.md)。

源码核对范围：2026-10-23 的当前实现。本轮未执行生产业务请求或原生设备验收。


原始地址：https://document.thestarline.cn/app/realtime-and-calls/
Markdown：https://document.thestarline.cn/app/realtime-and-calls.md

# 实时同步、位置与音视频通话

聊天变更通过 HTTP 长轮询通知，音视频使用独立的 LiveKit 媒体连接，iOS 来电可通过 APNs VoIP 唤醒。三者承担不同责任：事件告诉客户端刷新什么，通话 API 维护参与状态，媒体服务承载实际音视频。任何单一环节成功都不能代表整个通话已经可用。

## 普通事件游标

`GET /events?after=0&wait=20` 要求聊天 Bearer token。`after` 是当前用户已经处理到的普通事件 ID，必须为非负安全整数；`wait` 为 0–25 秒，默认 20。服务端先查已存在事件；有结果立即返回，没有结果才在进程内登记等待者。登记后再次查询以补上查询与注册之间的竞争窗口。

响应为 `{events:[...],cursor}`。每批最多 100 条、按 ID 升序；空批次的 cursor 保持请求 after。事件包含 `id,conversationId,groupId,kind,messageId,createdAt`，具体引用可能为 null。常见 kind 包括 message、message_read、group_message、group_message_read、friend_request、friend_accepted、friend_removed、block_changed、group_members_changed、call_changed 和 e2ee。

登录交换及 `/me` 会返回用户最新 eventCursor，供初始化增量监听。客户端先获取当前列表快照，再连续消费事件；断线后沿用已处理游标重连，并按事件刷新对应资源。不要把消息 ID 当事件游标，也不要直接用 e2ee sequence 调用普通 `/events`。

iOS 当前循环使用 wait=20，收到事件后刷新会话、群、好友申请及相关消息；call_changed 触发通话重查。401 清理该会话，其他错误约等待 3 秒再重试，且核对异步响应仍属于原 token。事件是刷新信号，消息正文仍从资源接口读取。等待器保存在单进程 Map，当前没有跨实例唤醒或 WebSocket 订阅路由。

## MLS 的另一种游标

`GET /e2ee/{conversations|groups}/{id}/events?deviceId=...&after=...` 返回按设备收件的加密事件，每批最多 100 条，用 `sequence` 推进 cursor。它是立即查询接口，不使用普通事件的 wait 参数。普通 events 中的 e2ee 通知可以触发该查询，但两种游标必须分别保存。

客户端应在 MLS 验证及本地状态持久化成功后推进 sequence，Welcome 与 Commit 需要各自确认。iOS 独立传输器限制单次同步最多处理 100 批，超过后提示继续同步。若解密、发送者校验或状态保存失败，不应跳过密文并永久推进游标。详见[消息与媒体](https://document.thestarline.cn/app/messaging-and-media.md)。

## 实时位置是显式会话

单聊和群聊分别使用 `/conversations/{id}/live-locations`、`/groups/{id}/live-locations`。POST 显式开始，PUT 更新已经开启的共享，GET 查询当前参与者位置，DELETE 停止当前用户共享。`GET /live-locations/mine` 用于恢复自己的共享范围。

位置数据为 latitude、longitude、accuracy，必须是有限数字；纬度 -90–90、经度 -180–180、精度 0–100000 米。未先开始就 PUT 返回 409 `NOT_SHARING`。单聊开始和更新还要求仍是好友且未屏蔽，群操作要求当前成员。返回 startedAt、updatedAt，界面应展示更新时间，不能把静态最后坐标当实时移动。

当前服务端位置表没有自动到期字段，位置变更也未写入普通 events；客户端需单独刷新并在退出、停止共享和权限变化时处理生命周期。坐标是服务端可读数据。`GET /location/city` 仅提供基于请求公网地址的粗略城市与国家代码，不等于 GPS 定位，无法判断时返回 null。

## 通话创建与状态机

创建调用 `POST /calls`，发送 scopeKind（conversation/group）、scopeId、mode（audio/video）、UUID clientId。服务端要求当前成员；单聊额外要求好友及未屏蔽。同一个范围最多一场 ringing/active 通话，发起者不能同时占用另一场。相同发起者与 clientId 的相同请求返回同一通话；不同内容或冲突可能得到 `CALL_BUSY`。

| 状态 | 含义与转移 |
| --- | --- |
| ringing | 等待邀请者响应；发起者可 end 取消；接听后 active |
| active | 至少已完成接听状态；媒体仍需单独连接 |
| cancelled | 发起者在响铃阶段取消，原因 caller_cancelled |
| missed | 响铃达到约 60 秒无人接听，原因 unanswered |
| ended | 挂断、全员忙、拒接、成员变化或空媒体房间等终态 |

邀请另有 ringing/accepted/declined/busy/missed/cancelled 状态。若其余所有成员都忙，创建请求可以返回 201 但 call 已是 ended、原因 busy，因此客户端必须读取响应 state。首位受邀者 accept 使通话 active，并登记发起者与接听者为参与者；后续群成员可 accept 或在 active 时 join。join 仅支持群通话。

`GET /calls/active` 查询当前用户正在响铃或实际参与的通话；`/calls/current` 按聊天范围查询；`/calls/history` 返回该范围最近 100 条终态记录。普通 call 响应不含内部房间名及请求 clientId。旧事件只能触发重查，不应把旧 state 覆盖新的终态。

## 媒体加入与退出

接听或加入成功后，参与者调用 `/calls/{id}/media-token` 获取 `{url,token}`。服务端只为 active 且尚未离开的当前参与者签发凭证，TTL 为 30 秒，权限限定当前房间、发布音视频与订阅，不允许发布 data。客户端必须及时连接，过期后重新获取；不能把聊天 Bearer token 当媒体 token。

active 单聊结束时删除媒体房间；群成员离开则移除该媒体参与者，只有群里无人继续参与时才结束整场并清理房间。删除好友、屏蔽、群解散或成员移除等路径会先处理相关媒体权限；媒体服务故障可能使动作返回 `CALL_MEDIA_UNAVAILABLE`，客户端需展示失败并可重试。

服务端约每秒检查响铃超时；默认约每 10 秒检查 active 房间人数，连续空房达到默认 90 秒宽限后结束通话并记录 connection_lost。检查媒体人数失败时不会据此认定空房。状态机的 active 仍不证明麦克风、摄像头、远端轨道或网络质量正常。

## VoIP 推送与验收边界

iOS 通过 `POST /voip/devices` 注册设备 UUID 与十六进制 pushToken，记录绑定当前有效聊天 session。`DELETE /voip/devices` 注销设备。来电仅发给仍有有效 session 的待接听邀请者；APNs 返回 410、BadDeviceToken、Unregistered 或 DeviceTokenNotForTopic 时移除该 token。

推送载荷包含 aps 空对象，以及 callId、scopeKind、scopeId、mode、callerName，群通话另有 groupName。它没有聊天正文或媒体 token，但姓名、群名与通话关系仍属于元数据。推送类型为 voip、优先级 10、到期约 60 秒；缺少配置时不发送。APNs 的 HTTP 成功也不证明设备已经展示系统来电或成功接听。

仓库已有通话信令、媒体 SDK、系统通话桥接与推送发布器。真实双设备跨网络音视频、断线重连、后台与锁屏来电、生产 APNs、权限拒绝后的恢复仍需逐场景验收。请结合[测试](https://document.thestarline.cn/app/testing.md)、[运维](https://document.thestarline.cn/app/operations.md)、[iOS](https://document.thestarline.cn/app/ios.md)和[Android](https://document.thestarline.cn/app/android.md)读取具体结果。

城市定位与精确共享、两端停止失败及最后坐标保留的具体区别见[位置共享](https://document.thestarline.cn/app/location-sharing.md)。


原始地址：https://document.thestarline.cn/app/ios/
Markdown：https://document.thestarline.cn/app/ios.md

# iOS 客户端

星线 iOS 是使用 SwiftUI 编写的原生 iPhone 客户端。本文说明工程入口、状态管理、本机数据与系统能力接入，面向需要运行、维护或扩展客户端的开发者。

## 工程与系统要求

`ios-app/project.yml` 是 XcodeGen 工程配置来源，生成的工程名和主 scheme 都是 `StarlineWorkbench`。配置声明 Swift 6.0、最低 iOS 17.0、设备族为 iPhone，Bundle ID 为 `cn.thestarline.workbench`。当前没有 iPad 专用或 watchOS target；独立手表版仍属待办。

项目直接导入 `FoundationModels`，开发环境需要包含该框架的 SDK；仓库 README 的开发流程使用 Xcode 27 和 XcodeGen。最低运行系统与编译 SDK 是不同要求：iOS 17 可以运行基础功能，系统模型识别仅在 iOS 26 及以上且模型可用时启用。

主要外部依赖为 LiveKit Swift SDK（`from: 2.17.0`）和本仓库 `chat-crypto/dist/StarlineChatCrypto.xcframework`。Swift Package 版本声明允许兼容版本解析，不能将下限当作每次构建的实际锁定版本。加密核心需按仓库构建流程准备，详见[消息与媒体](https://document.thestarline.cn/app/messaging-and-media.md)。

## 启动与状态架构

`StarlineWorkbenchApp` 在启动时创建 `ChatStore`，并将其交给 `CallSystemBridge`。根视图分别持有 `LocalWorkspaceStore`、`MemoryStore`、`MomentsStore` 和附近地点状态，通过 SwiftUI Observation、`@State` 与环境传递给功能视图。

默认底部为“聊天、工作台、我的”；记忆可以通过设置加入底部导航。默认页面和扫码按钮开关使用 `@AppStorage` 保存。工作台路由使用 `NavigationStack`，任务编辑、扫码和账号确认使用独立展示状态。界面 locale 当前固定为简体中文。

启动异步恢复待处理登录与聊天会话，回到前台重新检查会话。`onOpenURL` 先尝试身份回调，再处理好友链接，避免把登录回调当作普通扫码内容。身份流程与回调限制见[认证](https://document.thestarline.cn/app/authentication.md)。

## 数据与网络流

任务、网站收藏和最近访问由 `LocalWorkspaceStore` 写入 App 私有的 `workspace.json`。记忆由单独的 `MemoryStore` 管理，其索引、附件和密钥策略见[本地记忆](https://document.thestarline.cn/app/local-memory.md)。这两类本机数据不因聊天登录而自动同步。

聊天通过 `ChatAPI`、`URLSession` 和模型解码访问聊天服务；默认地址为 `https://chat.thestarline.cn`。Debug 可用 `STARLINE_CHAT_BASE_URL` 指定测试地址，代码只接受 HTTPS 或 HTTP 回环主机，并拒绝包含用户信息、查询或片段的覆盖值；Release 不读取该环境覆盖。不要把测试地址或真实凭据写进源码。

新事状态由 `MomentsStore` 复用聊天身份管理；音视频使用 LiveKit，系统来电使用 CallKit/PushKit。扫码使用 VisionKit 的二维码识别，相册图片识别和手动输入保留为替代入口。普通网页与账号确认网页分别管理浏览会话。

## 运行与扩展

在仓库的 `ios-app` 目录执行：

```sh
xcodegen generate
open StarlineWorkbench.xcodeproj
```

选择 `StarlineWorkbench` scheme 运行；新增源文件或修改系统能力后同步 `project.yml` 与工程。新增领域数据应先明确属于本机工作台、加密记忆还是服务端聊天，随后在对应 Store 增加操作，再由视图呈现错误和加载状态，避免直接在视图中混合网络和持久化。

真机签名须使用维护者自己的开发团队与描述文件。工程声明相机、麦克风、使用期间定位，以及 location/audio/voip 后台模式；APNs 环境按 Debug/Release 区分。配置存在不能证明推送、后台定位或通话已完成真机验收，详见[权限与可访问性](https://document.thestarline.cn/app/permissions-accessibility.md)。

## 模块边界与排错入口

| 现象或需求 | 优先检查 | 不能据此推断 |
| --- | --- | --- |
| 本机任务或网站读取失败 | `LocalWorkspaceStore` 的快照解码与原子写入 | 聊天账号重新登录会恢复工作台 |
| 记忆库无法读取 | `MemoryStore.loadError`、Keychain 可用性和文件认证 | 空列表就是原来没有记忆，或改账号密码能恢复密钥 |
| 浏览器成功但账号为空 | `ChatNativeAuth` 的 pending、回调和 exchange | 打开 Account 页面已经取得聊天 token |
| 消息一直 sending／failed | `ChatStore` pending 与 clientId 合并 | 普通队列具备持久离线发件箱 |
| 通话 active 但无画面 | `ChatCallCoordinator` 的 Room、权限与远端轨道 | 信令 active 等于媒体接通 |
| 后台位置未更新 | `ChatLiveLocationManager`、权限、共享范围与更新时间 | 城市贴纸识别会自动开启持续共享 |

会话和 pending 使用聊天 Keychain service，属性为首次解锁后仅本设备可用；记忆密钥使用另一 service，要求当前设备解锁。`LocalWorkspaceStore` 的普通快照不因此共享记忆加密。普通聊天队列属于当前 Store 内存；独立 MLS 传输器才有自己的加密 checkpoint，当前主界面不能继承它的全部恢复能力。

新增功能时需区分主线程状态与异步响应。当前多个关键路径会在 await 后检查 token、用户、聊天目标或 operation，防止迟到结果污染新状态；这不表示所有新增请求可以省掉检查。把页面隐藏、后台暂停、网络重试、进程重建和明确退出各自测试，生命周期细节见[客户端生命周期](https://document.thestarline.cn/app/client-lifecycle.md)。

个人任务的截止筛选和网站去重见[工作台](https://document.thestarline.cn/app/workbench.md)，Date 编码和 vault 格式见[本机数据格式](https://document.thestarline.cn/app/local-data-formats.md)，记忆打包与 Account 对接缺口见[记忆转出](https://document.thestarline.cn/app/memory-export.md)。客户端当前只保存转出契约；权威 Account 版本缺少对应 redeem 路由，不能由分享代码存在推断多因素转出已可用。

## 验证边界

仓库包含领域、存储、加密、聊天、城市贴纸及 UI 测试。本篇依据当前源码编写，本轮未重新构建或启动模拟器，也未核验商店发行版本。历史测试与本次执行结果应分别记录；公网登录、两台真机跨网络通话、后台来电及实际权限恢复仍须走真实路径，参考[测试](https://document.thestarline.cn/app/testing.md)与[发布](https://document.thestarline.cn/app/releases.md)。


原始地址：https://document.thestarline.cn/app/android/
Markdown：https://document.thestarline.cn/app/android.md

# Android 客户端

星线 Android 使用 Kotlin 与 Jetpack Compose 实现聊天、工作台、记忆和个人设置。当前工程版本标记为预览版；本文说明源码组织、构建配置、数据流和平台能力边界。

## 工具链声明

| 配置 | 当前源码值 |
| --- | --- |
| applicationId / namespace | `cn.thestarline.workbench` |
| 最低系统 | Android 8.0，API 26 |
| compileSdk / targetSdk | 35 / 35 |
| Java / Kotlin JVM target | 17 / 17 |
| Kotlin 与 Compose 编译插件 | 2.0.21 |
| Android Gradle Plugin | 8.7.3 |
| Gradle Wrapper | 9.2.1 |
| versionName / versionCode | `1.0.6-preview` / `7` |

这些是仓库配置声明。本轮没有执行构建，Gradle 与 AGP 的兼容性、开发机 JDK 和最终产物版本需在发布环境核对；不能仅凭配置表认定工具链已验证。Compose BOM 声明为 `2024.12.01`，通话使用 LiveKit Android `2.29.0`，扫码使用打包式 ML Kit、CameraX 与 ZXing。

## 入口与页面状态

`MainActivity` 创建 `AppState`，接收初始 Intent 和后续深链，再通过 `StarlineApp` 组合页面。`AppState` 集中维护当前 tab、page、会话、聊天列表、新事、任务、收藏和记忆状态，使用 Compose 可观察状态与协程更新界面。

页面由 `tab:page` 状态映射到聊天、账号、任务、浏览器、记忆编辑、转出和扫码等 Composable。主布局处理状态栏、导航栏与输入法 inset，内容宽度上限为 720dp；底部导航按当前页面显示。页面切换和新事卡片过渡会读取系统动画开关。Activity 销毁时调用状态清理，停止所属任务和资源。

修改现有功能时应沿用 `AppState` 的操作入口和页面状态，避免在独立 Composable 中再建一套会话或持久化状态。新数据模型应明确字段兼容规则；当前大量服务对象使用 `JSONObject`，新增字段应防止缺失值导致崩溃。

## 网络与认证

`ServiceApi` 在 IO 协程中使用 `HttpURLConnection`，负责 JSON 请求、媒体上传、受大小限制的下载以及服务端错误转换。普通请求、事件轮询和媒体操作使用不同超时。`AppState` 的事件循环调用 `/events` 并刷新当前会话与页面数据。

`starlineChatBaseUrl` Gradle 属性生成 `BuildConfig.CHAT_BASE_URL`，默认指向 `https://chat.thestarline.cn`。Release 清单禁止明文流量，Debug 清单单独允许本地 HTTP 联调。即使构建属性接受 HTTP，正式包仍受清单限制；测试服务和账号服务应使用同一环境。

登录使用本机 PKCE 事务，打开 Account 返回的验证页面，经 `starlineworkbench://chat-auth` 回到 App。待处理事务和会话使用本机加密文件保存。配置与安全约束见[认证](https://document.thestarline.cn/app/authentication.md)。

## 本机数据与系统能力

`LocalData` 将任务、收藏、最近访问和偏好保存在私有 SharedPreferences；会话、记忆索引和附件经过 `SecureFile` 加密写入私有文件。密钥由 Android Keystore 生成，算法为 256 位 AES-GCM，写入先落临时文件并同步后重命名。清单设置 `allowBackup=false`。任务和普通偏好并未因此变成 AES-GCM 加密数据，数据分类见[安全与隐私](https://document.thestarline.cn/app/security-and-privacy.md)。

扫码相机由 CameraX 绑定生命周期，ML Kit 在本机解析二维码；也可选择图片或手动输入。实时位置通过 `LiveLocationService` 前台服务和持续通知维持，城市贴纸识别采用另一条短时定位路径。文件预览使用私有 FileProvider 与临时 URI 授权。权限细节见[权限与可访问性](https://document.thestarline.cn/app/permissions-accessibility.md)。

## 与 iOS 的具体差异

| 范围 | Android 当前行为 |
| --- | --- |
| 个人任务 | 待办／已完成／全部，无独立任务搜索与逾期筛选；日期选到当天末尾 |
| 首页今日待办 | 包含正数到期且不晚于今天末尾的未完成项，实际也包含历史逾期 |
| 网站去重 | 比较完整 URL 字符串，不复用 iOS 去 fragment、默认端口的规范化 |
| 记忆主题 | 固定模板和关键词；不调用 iOS FoundationModels |
| 原生 pending | 保存 verifier/state/到期时间，不持久化 API 基址或换票 ticket |
| 授权来源 | 当前仅信任正式 Account HTTPS，覆盖聊天地址不会自动放行本地 Account |
| 普通发送重试 | 未确认 clientId 保存在进程内映射，按账号、聊天范围和具体提交内容绑定 |
| 记忆转出 | 授权后先选目标 URI，再本机生成文件；无通用导入入口 |

这些差异需要在调用方和测试预期中体现，不能用 iOS 的页面、持久化策略或测试结果代替 Android 验收。任务和浏览器实现见[工作台](https://document.thestarline.cn/app/workbench.md)，存储字段与兼容见[本机数据格式](https://document.thestarline.cn/app/local-data-formats.md)。

`MainActivity` 销毁会 dispose 当前 AppState、停止所属协程并释放通话资源；持续位置共享另由前台服务管理。切到后台与 Activity 销毁不同，关闭聊天页也不自动结束位置或通话。普通事件轮询不是后台通知服务，短时重连、进程恢复和锁屏来电需分别验证，见[客户端生命周期](https://document.thestarline.cn/app/client-lifecycle.md)。

## 开发与验收

在 `android-app` 目录可执行：

```sh
./gradlew :app:testDebugUnitTest :app:assembleDebug
```

设备测试放在 `app/src/androidTest`，本地单元测试放在 `app/src/test`。本轮只审阅源码，没有执行以上命令或安装 APK。已有测试文件不表示当前提交已经通过。

Android 预览客户端与 iOS 并非所有能力对等：iOS 系统模型主题生成没有移植，Android 使用本机关键词推荐；Rust OpenMLS 加密聊天尚未接入。后台来电推送、真机跨网络音视频、真实相机与完整多因素转出应分别验收，不能由模拟器页面或 `active` 信令状态推断完成。参见[本地记忆](https://document.thestarline.cn/app/local-memory.md)、[消息与媒体](https://document.thestarline.cn/app/messaging-and-media.md)、[测试](https://document.thestarline.cn/app/testing.md)和[发布](https://document.thestarline.cn/app/releases.md)。


原始地址：https://document.thestarline.cn/app/client-lifecycle/
Markdown：https://document.thestarline.cn/app/client-lifecycle.md

# 客户端启动、恢复与资源生命周期

客户端生命周期包含本机数据加载、登录事务、已登录会话、增量刷新、消息重试、媒体连接和持续位置共享。它们的恢复条件不同：重新打开 App 不等于重新登录，关闭聊天页不等于结束通话或位置共享，进程内队列也不等于已持久化的离线发件箱。

## 启动入口与状态所有权

| 状态 | iOS 所有者 | Android 所有者 |
| --- | --- | --- |
| 本机任务／收藏 | 根视图持有 `LocalWorkspaceStore` | `AppState` 中可观察列表与 `LocalData` |
| 记忆 | 根视图持有 `MemoryStore` | `AppState.memories/memoryLocked` |
| 聊天 token 与用户 | `ChatStore`，token 来自 Keychain | `AppState`，token 来自加密文件 |
| 原生登录事务 | `ChatNativeAuth` 与独立 pending 存储 | `NativeAuthCoordinator` 与加密 pending |
| 普通事件刷新 | `ChatStore.pollingTask` | `AppState.pollJob` |
| 通话 | `ChatCallCoordinator`、系统来电桥接 | `AppState`、LiveKit Room 与轨道任务 |
| 位置持续采集 | `ChatLiveLocationManager` | 独立 `LiveLocationService` |

iOS App 初始化 `ChatStore` 并绑定 `CallSystemBridge`；根视图清理旧记忆转出和预览临时文件，加载记忆与工作台快照。工作台读取失败会显示保护性错误，而不是空数据首页。随后 `.task` 先尝试恢复有 ticket 的原生登录，再恢复聊天会话。记忆加载失败有独立错误状态，不应触发卸载或重置。

Android `MainActivity.onCreate` 创建 `AppState`、处理初始 Intent，再组合页面；`onNewIntent` 负责已运行时的深链。状态初始化先加载普通本机列表和加密记忆，记忆读取异常会设置 `memoryLocked`；若已有 token，异步请求 `/me` 恢复资料、列表和轮询。授权回调与本机数据加载不应相互清除。

## 已登录会话恢复

正常恢复是：读取设备凭据，请求 `/me`，核对响应仍属于发起请求的 token，设置当前用户和 eventCursor，再刷新会话等快照并启动监听。服务端返回 401 表示凭据无效，客户端清理该聊天会话；断网、超时或 503 不足以证明 token 已失效，应保留凭据并显示错误。

iOS `restore` 在同一 Store 生命周期内只自动执行一次；回到 active 时会调用 `resumePendingSignIn` 和 `recheckSession`。后者主要在当前用户为空、Keychain 仍有 token 时恢复，不是每次前台切换都强制重新登录。Android 恢复在 AppState 初始化触发，普通网络操作的 401 清理也会核对发起会话，防止旧响应退出新账号。

设备聊天会话默认有效 24 小时，没有 refresh token 或永久登录保证。Account 浏览器 Cookie 与聊天 token 各自到期。修改 Account 密码没有本机记忆重加密逻辑；是否撤销已有聊天 token 还需按聊天服务自身会话机制判断，不能将 Account 会话撤销自动扩大到所有业务凭据。

## pending 登录：两端的持久化差异

| 阶段 | iOS | Android |
| --- | --- | --- |
| 打开浏览器前 | 持久化 verifier、state、expiresAt、API 基址 | 持久化 verifier、state、expiresAt |
| 回调校验 | 预期 scheme/host、参数唯一、state、期限、API 基址 | 预期 scheme/host、无异常 URL 部件、唯一参数、state、期限 |
| 换票前 | 把 ticket 写回 pending | 先清除 pending，再在内存中携带 ticket 换票 |
| 换票中进程终止 | 在 ticket 和 flow 仍有效时可尝试 `resume()` | 当前没有持久 ticket 的恢复入口，需要重新发起授权 |
| 成功替换会话 | 先保存 session，再尽力清 pending | 先加密保存新 token，再替换旧账号界面状态 |
| 取消或旧请求迟到 | generation 和当前 pending 复核 | generation、operation 和 exchanging 复核 |

iOS 的 pending `expiresAt` 与 Android 相同，是协议 Unix 毫秒，不是 Swift Date 默认编码。冷启动恢复仍受一次性票据和服务端期限约束；如果服务端已经消费 ticket 而响应丢失，保存过 ticket 也不代表总能无损重放。网络恢复与服务端幂等能力需分别看待。

两端授权入口信任规则也不同：iOS Debug 在明确使用回环聊天服务时允许回环 Account HTTP；Android 原生授权地址当前只允许正式 Account HTTPS，没有同等 Debug 本地例外。修改聊天 base URL 或转发端口不会自动增加授权来源。登录详细协议见[认证](https://document.thestarline.cn/app/authentication.md)，隔离条件见[配置参考](https://document.thestarline.cn/app/configuration-reference.md)。

## 普通事件游标与断线重试

| 项目 | iOS | Android |
| --- | --- | --- |
| 长轮询 | `/events?after=<eventCursor>&wait=20` | `/events?after=<cursor>&wait=20` |
| 客户端请求超时 | 事件 32 秒、普通 JSON 15 秒 | 连接 15 秒；事件读取 35 秒、普通读取 20 秒 |
| 非 401 失败等待 | 约 3 秒 | 约 4 秒 |
| 成功响应 | 更新 cursor，再按事件类型刷新相关资源 | cursor 取不倒退的最大值，并刷新聊天、通话及当前相关页面 |
| 状态期限 | Store 实例中的内存游标 | AppState 实例中的内存游标 |

事件不是完整聊天数据库。iOS 在 message/group_message 后重新读当前会话并标记已读，call_changed 后查当前通话，成员和屏蔽变化触发相应资源重查；Android 每轮刷新聊天，当前是聊天页时刷新消息，新事相关页面时刷新动态。响应迟到时需核对原 token 或当前 thread 版本，避免旧会话覆盖新页面。

普通 cursor、消息 ID 与 MLS sequence 是不同序列。两端普通轮询没有持久化为一份可恢复的消息总账；冷启动先读服务器最新快照和 `/me` 的游标。iOS 独立 MLS 传输器另有加密 checkpoint 和 sequence 规则，不能把其持久离线能力归到普通聊天界面。协议见[MLS](https://document.thestarline.cn/app/mls-protocol.md)与[实时与通话](https://document.thestarline.cn/app/realtime-and-calls.md)。

## 消息发送、失败与队列寿命

iOS 为一次发送生成 `clientId`，在当前账号和会话范围的 pending 列表中显示 sending。收到响应后按服务端消息合并，并删除对应 pending；请求失败则标 failed。若轮询已经收到相同 clientId，迟到的失败不会再显示一条假失败。用户重试 failed 时复用原 clientId 和原正文／媒体引用；退出账号会清空这些内存队列。

Android `MessageSendIdCoordinator` 按 `accountId + scopeKind + scopeId + text + mediaId` 保存未确认请求的 ID。相同提交在不确定结果后重试时沿用 ID，明确响应成功后清除此映射；账号退出会清空。聊天输入草稿可由 `rememberSaveable` 管理，但 ID 映射仍是进程内状态，不构成磁盘发件箱。进程被系统销毁后，不应宣称所有待发消息都会自动继续发送。

维护者处理超时应区分：服务端未接受、已接受但响应丢失、消息已同步回来。继续使用原重试入口和 clientId，避免再建一条同内容请求。修改正文或媒体改变请求身份；使用同 ID 提交不同内容会触发服务端冲突。普通消息上限和幂等见[消息与媒体](https://document.thestarline.cn/app/messaging-and-media.md)。

## 前后台、通话与位置

源码中的普通轮询没有仅因切到后台就自动改成可永久运行的系统服务。iOS／Android 对后台执行各有限制，事件循环存在不表示锁屏时仍能持续联网；当前 Android 也没有完整后台来电推送交付。系统唤醒、媒体后台和一般消息刷新应分别验收。

通话媒体不是某个聊天页面的临时子视图。iOS 记录本机参与的 call ID，恢复 active 状态时避免自动接入另一设备才参与的通话；连接媒体先取短期 token，再连 LiveKit，开启轨道后反复核对连接 attempt 和当前 call。断开会取消订阅任务、释放 Room 引用并恢复音频输出；Android 用媒体 generation 与 call revision 防迟到，断开并 release Room，取消半秒级轨道观察任务。收起通话页面只是隐藏界面，结束需要走相应信令。

位置共享在显式开始后独立于聊天页面。iOS 启用后台位置更新，按至少约五秒间隔向仍共享的范围上传，断网时保留范围并显示最后更新时间；重启后查询 `/live-locations/mine` 再恢复。Android 前台服务带持续通知，约每 30 秒重查范围，位置上传至少约五秒间隔；权限撤销、无范围或 401 会停止或提示。服务返回 `START_NOT_STICKY`，不能承诺进程被杀后自动恢复服务。

停止位置采集与删除服务端最后坐标是两件事。Android 通知“结束共享”先停止采集，再尽力向服务器删除并重试；本机退出也会停止服务后尝试远端清理。iOS 退出先停止本机跟踪，但不能仅凭本机退出视为所有远端共享记录已删除。具体权限与位置语义见[位置共享](https://document.thestarline.cn/app/location-sharing.md)。

## 退出与资源检查步骤

1. 取消原生 pending，阻止迟到登录结果覆盖状态；保留个人任务、收藏和记忆。
2. 停止轮询，释放通话媒体、当前消息缓存和账号界面状态。Android 先清本机，随后尽力远端清理；iOS 尝试服务端注销后清本机。
3. 成功的 `/auth/logout` 只撤销当前聊天 session；请求失败时，本机退出仍可能完成，不能声称已撤销服务器凭据。
4. Activity 销毁时 Android 调用 `dispose`，取消所属协程和通话资源；独立位置服务按自己的生命周期清理。浏览器、扫码相机与附件预览也需各自释放。
5. 重开后分别验证本机数据仍在、无效会话需登录、短时离线未抹掉凭据，以及旧请求不写入新账号。

本页依据 iOS `StarlineWorkbenchApp`、`ChatStore`、`ChatNativeAuth`、`ChatCallCoordinator`、`ChatLiveLocation`，以及 Android `MainActivity`、`AppState`、`NativeAuth`、`MessageSendIdCoordinator`、`LiveLocationService`。本轮仅静态核对，未执行杀进程、后台、跨网或双设备测试；具体回归组合见[QA矩阵](https://document.thestarline.cn/app/qa-matrix.md)。


原始地址：https://document.thestarline.cn/app/workbench/
Markdown：https://document.thestarline.cn/app/workbench.md

# 个人工作台、任务与网站

工作台集中展示本机个人任务、网页收藏和最近访问。它不要求先加入企业组织，也没有把任务提交到共享企业后台。iOS 与 Android 共用产品方向，但当前筛选、日期、网址保存和持久化实现存在差异，应按平台理解实际行为。

## 责任与数据边界

| 内容 | iOS | Android |
| --- | --- | --- |
| 任务状态 | `LocalWorkspaceStore.tasks` | `AppState.tasks` 与 `LocalData.tasks()` |
| 收藏 | `bookmarks: [SavedSite]` | `bookmarks` JSON 数组 |
| 最近访问 | `recentSites: [SavedSite]` | `recents` JSON 数组 |
| 落盘方式 | 一份 `workspace.json` 快照，原子替换 | SharedPreferences 中的 JSON 字符串 |
| 是否采用记忆库 AES-GCM | 否 | 否 |
| 账号切换 | 不清除个人工作台数据 | 不清除个人工作台数据 |

上述文件或偏好属于 App 私有存储，但不能据此称为记忆 vault 的加密内容。它们不自动同步到另一台设备，不属于记忆转出 JSON，也不会因为聊天账号退出而删除。设备丢失、清除应用数据或卸载后的恢复不由聊天服务保证。字段和时间编码见[本机数据格式](https://document.thestarline.cn/app/local-data-formats.md)。

共享后台中的 `/enterprise/*` 管理组织、企业成员、频道、企业待办和公告，是独立星企产品的领域。个人任务没有组织 ID、负责人、协作评论、分派、共享或企业审计字段。当前工作台也没有第三方任务自动汇聚；不能由后台路由存在推导出这些前台功能已经可用。

## 任务模型与编辑

| 概念 | iOS 字段 | Android 字段与差异 |
| --- | --- | --- |
| 标识 | `id: UUID` | `id: String`，新建时生成 UUID |
| 标题 | `title: String`，保存前去首尾空白 | `title`，编辑器限制 160 个 UTF-16 代码单元并 trim |
| 说明 | `notes: String` | `notes`，编辑器限制 2,000 个 UTF-16 代码单元并 trim |
| 截止 | `dueDate: Date?`，可选具体日期和时间 | `dueAt`，Unix 毫秒；缺失或 0 表示未设截止 |
| 完成 | `isCompleted: Bool` | `isCompleted: Boolean`，读取缺省 false |
| 关联网页 | `sourceURL: URL?`，有完整输入校验 | 浏览器新建任务时写 `sourceURL` 和网址备注；任务弹窗不提供独立网址编辑框 |
| 创建／修改 | `createdAt`、`updatedAt` | `createdAt`；编辑和勾选完成时写 `updatedAt`，某些初次创建路径可能尚无该键 |

iOS 编辑器要求非空标题，允许补充说明、设置或清除截止时间、调整完成状态及关联 HTTP/HTTPS 网站。初次建任务保留创建时间，后续编辑更新修改时间；保存失败时编辑页保持打开，原输入仍可重试。当前 iOS 编辑器没有 Android 对应的 160／2,000 长度截取，不应把两者当统一协议上限。

Android 用可滚动弹窗编辑名称、备注和到期日。日期选择器把所选日期设为设备时区的 23:59:59、毫秒为 0；清除后保存 `dueAt=0`。保存基于原 JSON 的副本修改可见字段，因此浏览器任务已有的 `sourceURL` 不会仅因打开弹窗而丢失。已存在任务可通过删除确认框移除；取消编辑不提交本次表单。

## 筛选、排序与“今天”

| 行为 | iOS 当前实现 | Android 当前实现 |
| --- | --- | --- |
| 全部待办 | `isCompleted == false` | “待办”同样按完成布尔值过滤 |
| 已完成 | 只包含已完成项 | 同左 |
| 包含已完成与未完成 | 无独立“全部”范围 | “全部”范围 |
| 今天 | 未完成，且截止与设备当前日历为同一天 | 首页按未完成、正数 `dueAt` 不晚于当天末尾选择，包含以前逾期任务 |
| 已逾期 | 未完成且 `dueDate < now`，有独立入口 | 行内可显示逾期颜色，没有独立逾期筛选 |
| 搜索 | 在当前范围内查标题或说明，使用本地标准字符串匹配 | 当前任务页没有搜索框 |
| 列表排序 | 截止时间升序，无截止放末尾；截止相同按创建时间倒序 | 保留内存列表顺序；新任务插前，编辑不重新排序 |

iOS 的“今天”和“已逾期”可以重叠：今天上午截止而尚未完成的任务同时符合两者。没有截止时间的任务仅出现在全部待办或已完成中。工作台今日任务按截止时间排序，最近访问只预览前三项，逾期待办入口进入相应任务范围；从编辑页保存回来不会重建任务页的搜索和筛选状态。

Android 首页最多展示三个上述“今日待办”，另有待处理和网页收藏等计数。当天末尾在 Composable 中通过 `remember` 计算，长时间停留跨过午夜时不能假定立即重新计算；刷新与跨日行为需要独立回归。其任务页“全部”只是完成状态范围，不表示来自企业或云端的全部任务。

## 收藏和访问记录

iOS 的 `SavedSite.normalizedURL` 会小写 scheme 和 host、去掉 HTTP 80／HTTPS 443 默认端口和 fragment。收藏按规范化 URL 去重：重复收藏更新标题并移到前面，保留既有标识；最近访问按规范化地址合并并只留 30 项。删除收藏和删除历史是两个操作，不会互相代替。

Android 以完整 URL 字符串比较收藏和历史：相同字符串的重复收藏替换原位置，最近访问则移到前面并截为 30 项。大小写、默认端口或 fragment 不会自动套用 iOS 的去重规则。网页标题为空时界面可退回显示主机名。两端保存的只是标题、网址与访问元数据，不是网页全文离线副本。

## 从浏览到任务的步骤

1. 在工作台打开网站入口、收藏或最近访问；输入地址时没有 scheme 可按页面逻辑补成 HTTPS。
2. 确认实际主机和页面加载结果。iOS 对 HTTP 显示继续确认；Android 显示 HTTP 提示，并受 Release 明文网络禁用规则约束。遇到证书错误不能继续放行。
3. 选择收藏，或选择“存为任务”。iOS 打开任务编辑器并预填页面标题和网址，由用户保存；Android 在加载成功后直接创建任务，把网址同时写入备注与 `sourceURL`。
4. 在任务列表调整内容或完成状态。网页任务只是保留来源，不会解析页面待办、登录 Cookie 或企业任务状态。

iOS 普通浏览器使用 `WKWebView`，账号确认模式使用独立非持久网站数据存储并限制为 Account HTTPS 来源；原生登录另走系统授权浏览器。Android 工作台使用 WebView，启用 JavaScript 和 DOM storage，禁止混合内容，SSL 错误调用取消；离开其组合界面时停止加载并销毁 WebView。系统浏览器中的账号身份不应与工作台网页数据混为一谈。

## 正常与失败结果

| 场景 | 应如何理解 |
| --- | --- |
| 标题为空 | 两端阻止确认保存；不是创建一项无名任务 |
| iOS 关联 URL 不是完整 HTTP/HTTPS | 留在编辑器并显示地址错误 |
| iOS 快照读取失败 | 根视图提示本机数据无法读取；不使用空快照覆盖 |
| iOS 写文件失败 | Store 先持久化再替换内存，编辑保留输入 |
| Android 普通数组解析失败 | `LocalData.array` 对非加密数据退回空数组，没有记忆库的锁定保护；不可据此宣称旧文件已经修复 |
| Android 内存已修改但持久化失败 | 当前操作不是跨内存与偏好的数据库事务；界面状态不能作为磁盘写入回执 |
| 网络失败 | 已有个人任务和收藏仍属于本机数据；网页和聊天的网络错误分别处理 |

扩展工作台时，先确定数据是否仍属个人本机；再明确字段、默认值、筛选含义、写入失败策略和旧数据兼容。若新增协作，应另接服务端权限，而不是在个人 JSON 增加一个“企业”标签就宣称支持团队。改变日期规则还需检查时区、午夜、无截止、已完成和逾期的交集。

## 源码与静态核验

iOS 入口为 `Sources/Domain/WorkTask.swift`、`SavedSite.swift`、`TaskQuery.swift`、`Data/LocalWorkspaceStore.swift` 及 `Features/Tasks`、`Features/Browser`；Android 入口为 `WorkScreens.kt`、`AppState.kt` 与 `AppData.kt`。已有领域和存储测试可供回归选用，详见[QA矩阵](https://document.thestarline.cn/app/qa-matrix.md)。本篇仅完成源码与文档静态核对，没有执行构建、模拟器、真实网页或产品流程。


原始地址：https://document.thestarline.cn/app/local-memory/
Markdown：https://document.thestarline.cn/app/local-memory.md

# 本地记忆与加密存储

“记忆”用于保存个人文字、结构化选项、图片与文件，核心读写、搜索和模板推荐在设备本机完成，不要求先登录。账号退出不会自动清除记忆；当前没有跨设备自动同步或通用导入恢复能力。

## 模型与数据流

iOS 的 `MemoryEntry` 包含 UUID、标题、正文、附件数组、创建和更新时间、`MemoryKind`、字段值字典以及可选的 `generatedSchema`。附件元数据记录标识、原名称、存储名称、字节数与图片标记。视图将编辑结果交给 `MemoryStore.save`，存储层清理字段、加密新增附件、原子写索引，成功后再删除不再引用的旧附件；失败时清理本次新增文件。

Android 使用 JSON 记录，常见键包括 `id`、`title`、`body`、`kind`、时间戳及 `attachments`，模板字段直接位于记录对象中。`MemoryScreens` 处理编辑和附件选择，`AppState` 更新记录列表，`LocalData` 写入加密索引。两端转出容器相同，但内部记录字段与时间表示不同，不应假设可以直接互换。

固定主题包括自由记录、医疗健康、签证、证件、预约和订阅；宠物接种有专用字段。签证目的地使用本地国家地区目录，类别引导不自动推算有效期。医疗字段见[医疗健康记录](https://document.thestarline.cn/app/medical-records.md)。

## 限制与兼容

| 内容 | 当前约束 |
| --- | --- |
| 标题 | 最多 80 字符，空标题可由正文首行或模板名补全 |
| 正文 | 最多 20,000 字符 |
| 单个附件 | 最多 20 × 1024 × 1024 字节 |
| 每条附件数 | 最多 20 个 |
| 每条附件总量 | 最多 50 × 1024 × 1024 字节 |
| 一般字段 | 最多 200 字符 |
| 诊断结果、用药与医嘱 | 各最多 2,000 字符 |

这些限制由各端原生字符串截取实现，不能理解为跨语言一致的字节长度。iOS 存储层拒绝空附件；Android 文档选择路径允许 0 字节附件，扩展时需保留这一实现差异。仅选择模板但没有标题、正文、字段或附件，不会保存空记忆。

旧版兼容由两端分别处理：iOS 缺少主题字段时按自由记录解码，并支持旧明文库迁移；Android 保留旧键别名，同主题编辑只替换当前可见字段，保留未展示的历史字段。切换主题可能清空原主题选项，界面先要求确认。

## 加密与错误保护

iOS 采用 CryptoKit AES-GCM，加密文件以 `SLMV2` 标识版本；索引与每个附件使用不同 purpose 作为认证附加数据。随机 256 位密钥放入 Keychain，属性为设备解锁时可用且仅限本设备。索引与附件使用 complete 文件保护。旧明文数据先在暂存目录加密并回读核验，再移入正式 vault，随后清理旧文件。

Android 采用 Android Keystore 生成的 256 位 AES 密钥，以 `AES/GCM/NoPadding` 加密索引和附件，文件保存 IV 与密文，GCM 标签为 128 位；写入采用临时文件、同步和重命名。两端文件格式并不相同。

本机记忆使用设备级随机密钥，不由 Account 密码派生，也不按聊天账号隔离。同一安装中的不同聊天账号访问同一本机记忆库；修改 Account 密码、退出或切换聊天账号，都不会删除记忆或重新加密其内容。账号身份验证与设备上的记忆存储是独立边界。

索引损坏、认证失败或密钥不可用时，iOS 设置 `loadError`，Android 设置 `memoryLocked`，均禁止覆盖原记忆。不能把读取失败当成一个可写的空库，也不应引导用户通过卸载处理读取错误。卸载或清除应用数据会失去私有记录；密钥与文件需共同可用。

## 搜索与本机推荐

搜索覆盖标题、正文、主题、结构化字段值和附件名。空白分隔的多个词必须全部命中，但可命中不同字段；不读取附件正文，不是 OCR 或向量检索。

推荐最多读取 2,000 字符输入。Android 使用关键词和固定字段；iOS 在 iOS 26 及以上、系统模型可用时尝试 `FoundationModels` 生成主题与字段，失败则回退到本机基础选项。明确医疗内容直接采用稳定医疗字段，宠物疫苗保留专用识别。模型结果是待用户确认的记录结构，不会自动填入未提供的个人信息。

聊天“保存到记忆”提取消息正文；iOS 明确排除位置消息，并标记未捕获的媒体。不能将保存文字理解为自动备份整段聊天或附件。

## 模板字段与识别后的编辑

| 模板 | 固定字段 ID |
| --- | --- |
| 医疗健康 | `healthRecordType, healthSubject, healthRecordDate, medicalInstitution, departmentDoctor, medicalResult, medicationInstructions, followUpOn` |
| 签证 | `destination, visaType, status, entries, validFrom, validUntil, reference` |
| 证件 | `documentType, number, issuedOn, expiresOn` |
| 预约 | `subject, location, startsAt, status` |
| 订阅 | `service, plan, amount, renewsOn, status` |
| 宠物接种 | `pet_species, pet_name, pet_life_stage, pet_age, dose_number, vaccine_valency, vaccine_name, vaccinated_on, next_vaccination` |
| 通用推荐 | `subject, date, place, status, remark` |

自由记录没有必填模板字段。签证的 destination 保存目的地值，界面可解析为国家或地区名称；签证类型和有效期由用户按实际文件确认，类型候选不会替用户推算截止日期。预约的 startsAt 含本地时间，日期型字段只保存日历日期。订阅金额仍为用户输入字符串，没有币种换算或自动扣款。宠物针次、联数与下次日期也只是记录，不构成接种计划或提醒。

iOS 手动医疗模板使用 kind=health；从识别建议应用生成 schema 时，编辑器使用 kind=note 加 generatedSchema 保存主题与选项。需要寻找全部医疗主题时不能只筛原始 kind。Android 的固定医疗模板保持 health，开放主题则使用 suggested 与 suggestedCategory。原始结构和字段类型见[本机数据格式](https://document.thestarline.cn/app/local-data-formats.md)。

新建 iOS 自由记忆时，至少两个字符输入会触发延迟建议：少于五字符等待约 2.5 秒，其他约 1.5 秒；自动建议有次数和输入状态保护，页面离开会取消请求。建议出现不会保存记录，用户仍需确认选项并保存；修改输入后的迟到识别结果会被核对后丢弃。Android 通过按钮按文字推荐当前固定或通用选项。

iOS 重新应用生成 schema 时，按稳定字段 ID、相同显示标题及少量签证旧标题别名搬移已有值；这不是任意语义迁移。手动更换类型会确认清除原选项，正文和附件保留。Android 同主题编辑保留未展示旧键，更换类型则清理相关选项。业务扩展应稳定字段 ID，分别测试“清空字段”“换类型”“重选建议”和“编辑旧记录”，不能只验证新建成功。

附件预览需临时解密为明文。iOS 使用受保护预览文件并在结束后清理；Android 在缓存中写明文，通过 FileProvider 临时读权限交给用户选择的查看应用，离开详情时尽力删除预览文件。临时文件清理不撤回外部应用已经复制的内容。图片、文件的读取和导出也会占内存，单条附件上限不等于任意数量记录都能一次处理。

## 转出与验证

以下描述客户端已编写的转出实现契约。当前作为维护基线的 Account 主目录版本尚缺 `/api/memory-export/redeem` 路由，跨服务真实闭环仍待核对和验收，不能将客户端入口或本地文件生成代码视为当前可用的完整转出服务。

按该契约，转出需要登录并通过 Account 的一次性许可流程。客户端发送的是验证状态和票据，记忆正文与附件由本机生成；具体身份校验见[认证](https://document.thestarline.cn/app/authentication.md)。本地输出格式定义为明文 JSON，容器含 `format=cn.thestarline.memory-export`、`version=1`、`entries`；每项含原记录和按附件 ID 编码的原始附件数据。

iOS 在验证成功后创建受保护临时文件，交给系统分享页，并在结束后清理；Android 在授权和保存位置选择后生成临时文件，流式复制到目标 URI，取消或失败时清理未完成输出。转出文件中的 Base64 不是加密，保存位置和接收方由用户选择。

仓库测试覆盖重开、字段限制、损坏保护、加密附件与完整转出等路径。本轮未重跑测试，也未完成真实账号多因素转出验收；完整容器、平台取消阶段和清理限制见[记忆转出](https://document.thestarline.cn/app/memory-export.md)，回归范围见[测试](https://document.thestarline.cn/app/testing.md)与[安全与隐私](https://document.thestarline.cn/app/security-and-privacy.md)。源码主要位于 iOS `MemoryStore/MemoryLocalRecognizer/MemoryEditorView` 与 Android `MemoryTemplates/MemoryScreens/AppData`。


原始地址：https://document.thestarline.cn/app/local-data-formats/
Markdown：https://document.thestarline.cn/app/local-data-formats.md

# 双端本机数据格式与兼容

本页记录任务、网站、记忆、附件和本机授权状态在当前源码中的形状。示例均为合成值，只用于解释字段；不提供读取用户私有数据或导出密钥的操作。原生磁盘格式是实现细节，没有通用跨平台导入承诺，修改前应保留旧数据兼容和失败保护。

## 数据分类

| 类别 | iOS | Android |
| --- | --- | --- |
| 工作台 | `workspace.json`，JSON 对象快照 | SharedPreferences 名称 `starline_settings` 中的 JSON 字符串 |
| 记忆索引 | 逻辑文件 `vault/index.enc`，解密后为记录数组 | `memories.bin`，解密后为 JSON 数组 |
| 记忆附件 | `vault/files/<UUID>.enc` | `memory-<id>.bin` |
| 聊天会话 | 独立 Keychain 项 | `session.bin`，解密后为会话字符串 |
| 原生登录 pending | Keychain 内 JSON | `native-auth.bin`，解密后为 JSON |
| 开关与默认页 | UserDefaults / `@AppStorage` | 同一个私有 SharedPreferences |

这里的文件名是程序中的逻辑名称，不表示部署目录。任务、收藏和普通偏好不使用记忆 AES-GCM 容器；聊天 token、记忆正文和附件不能写回普通偏好或日志。记忆密钥为设备级随机值，同一安装中的聊天账号共用记忆库；改 Account 密码、退出或切换账号不会删除或重加密记忆。

## iOS 工作台快照

`LocalWorkspaceStore.Snapshot` 的三个顶层键是 `tasks`、`bookmarks`、`recentSites`。`tasks` 解码时必需；旧快照缺少后两项时按空数组兼容。当前没有单独的 schemaVersion。示例：

```json
{
  "tasks": [{
    "id": "11111111-1111-4111-8111-111111111111",
    "title": "示例任务",
    "notes": "合成说明",
    "dueDate": 3600,
    "sourceURL": "https://example.test/task",
    "isCompleted": false,
    "createdAt": 0,
    "updatedAt": 0
  }],
  "bookmarks": [{
    "id": "22222222-2222-4222-8222-222222222222",
    "title": "示例网站",
    "url": "https://example.test/",
    "createdAt": 0
  }],
  "recentSites": []
}
```

默认 `JSONEncoder` 把 Swift `Date` 编为从 2001-01-01 00:00:00 UTC 起算的秒数，可含小数；这里的 0 不是 1970 年，3600 也不是 Unix 毫秒。`URL` 编为字符串，UUID 编为字符串。可选 `dueDate`、`sourceURL` 为空时通常省略键。后端聊天时间使用 Unix 毫秒，不能把相同数字直接复制到本机 Date 字段。

快照一次编码三个数组，`.atomic` 写文件成功后再替换 Store 内存。损坏或缺少必需字段会抛出读取错误，根界面不会把它当新安装。它没有单记录日志、数据库事务回放或云端副本。具体筛选与网址规范化见[工作台](https://document.thestarline.cn/app/workbench.md)。

## iOS 记忆明文模型

加密索引解开后是 `[MemoryEntry]`。医疗示例只填写一个自定义输入值：

```json
{
  "id": "33333333-3333-4333-8333-333333333333",
  "title": "合成医疗记录",
  "text": "用于格式说明",
  "attachments": [{
    "id": "44444444-4444-4444-8444-444444444444",
    "name": "sample.txt",
    "storedName": "44444444-4444-4444-8444-444444444444",
    "byteCount": 6,
    "isImage": false
  }],
  "createdAt": 0,
  "updatedAt": 0,
  "kind": "health",
  "fields": {"healthSubject": "合成对象"}
}
```

| 字段 | 类型与语义 |
| --- | --- |
| `id` | UUID，编辑保持不变 |
| `title`、`text` | 字符串；正文名是 text，不能套用 Android 的 body |
| `attachments` | 元数据数组，附件正文另存；`byteCount` 是原始字节数 |
| `createdAt`、`updatedAt` | Swift Date 默认参考日期秒数 |
| `kind` | `note/health/visa/document/appointment/subscription` |
| `fields` | 字符串到字符串字典，日期和数字型表单值仍是字符串 |
| `generatedSchema` | 可选主题对象：`category`、`icon`、`fields`；每个生成字段含 `id/title/type/options` |

生成字段 `type` 可为 `text/choice/date/dateTime/number`。表单日期为 `yyyy-MM-dd`，带时间为 `yyyy-MM-dd'T'HH:mm`，不含时区；不能等同为 UTC 瞬间。旧记录缺少 kind 时取 note，缺少 fields 时取空字典；旧生成 schema 缺 icon 时按主题选择兼容图标。保存层只接受当前模板或生成 schema 允许的字段 ID，因此未知字段不会自动透传到新 iOS 记录。

## iOS vault 封装与密钥项

当前容器是 ASCII `SLMV2` 头加 CryptoKit `AES.GCM.SealedBox.combined`。combined 含 nonce、密文与认证标签；正文与索引不采用 JSON 内 Base64 封装。索引与附件使用同一随机 256 位密钥，但附加认证数据 AAD 分别是 UTF-8 的 `index` 与 `attachment:<附件UUID的uuidString>`，UUID 的具体字符串必须与保存时一致。换附件名不改变其绑定 ID；拿另一附件的密文替换而不匹配 purpose 会认证失败。

Keychain service 为 `cn.thestarline.workbench.memory`，account 为 `device-vault-v2`，属性为 `WhenUnlockedThisDeviceOnly`。这些名字不是密钥值，也没有基于账号密码的密钥推导或在线找回。正常写入使用 complete 文件保护；读取需设备安全存储与文件共同可用。文件头提供格式识别，真正的内容完整性由 GCM 认证负责。

## Android JSON 与加密容器

工作台偏好键 `tasks/bookmarks/recents` 对应 JSON 数组字符串。任务字段常见为 `id/title/notes/isCompleted/createdAt`，编辑时增加 `dueAt/updatedAt`；网址任务还含 `sourceURL`。日期是 `System.currentTimeMillis()` 的 Unix 毫秒，`dueAt=0` 或缺失表示无到期。收藏和历史含 `id/title/url/createdAt`。数组的元素是 JSON 对象，不是 Swift Snapshot。

Android 医疗记忆的真实形状为：

```json
{
  "id": "55555555-5555-4555-8555-555555555555",
  "title": "合成医疗记录",
  "body": "用于格式说明",
  "kind": "health",
  "createdAt": 978307200000,
  "updatedAt": 978307200000,
  "healthSubject": "合成对象",
  "attachments": [{
    "id": "66666666-6666-4666-8666-666666666666",
    "name": "sample.txt",
    "mimeType": "text/plain",
    "size": 6
  }]
}
```

正文为 `body`，模板字段直接位于记录对象中，没有 iOS 的 `fields` 外层。类型包含 `general/pet/health/visa/document/appointment/subscription`，本机通用推荐使用 `suggested` 加 `suggestedCategory`；旧 `travel/calendar` 仍可显示。附件使用 `size`、`mimeType`，没有 iOS 的 `byteCount/isImage/storedName`。`JSONObject` 的键顺序不是契约，未知历史键可能存在，不能按示例重建并丢弃其他字段。

`SecureFile` 从 Android Keystore 读取或生成别名 `starline_android_data_v1` 的 AES-256 密钥，使用 `AES/GCM/NoPadding`。磁盘字节为 `IV || ciphertext-and-tag`，读取按前 12 字节 IV、128 位 GCM 标签处理，至少 28 字节；当前没有 SLMV2 头，也没有 `updateAAD` 的索引／附件 purpose 绑定。格式上不与 iOS 互通，不能通过换后缀或复用 iOS key 读取。

写入先保存到同名 `.tmp` 文件，调用文件描述符同步，再重命名替换。这个流程不意味着多份附件与索引构成完整数据库事务。加密数组读失败会抛“原文件已保留”，`AppState` 将记忆设为 locked；普通工作台数组解析失败则回退空数组，两者保护级别不同。

## 偏好、会话与 pending

| 内容 | iOS 键或结构 | Android 键或结构 |
| --- | --- | --- |
| 默认页面 | `workbench.defaultTab` | `default_tab` |
| 底部记忆入口 | `workbench.memoryInTabBar` | `show_memory_tab` |
| 页面扫码开关 | `workbench.scanOnChat/scanOnHome/scanOnProfile` | `scan_on_chat/scan_on_work/scan_on_profile` |
| 聊天安全存储 | service `cn.thestarline.workbench.chat`；account `device-session` | 加密 `session.bin` |
| 登录 pending | `codeVerifier/state/expiresAt/apiBaseURL/ticket?` | `verifier/state/expiresAt` |

聊天 Keychain 的可访问属性为 `AfterFirstUnlockThisDeviceOnly`，与记忆密钥的 WhenUnlocked 不同。pending 的 expiresAt 两端都是协议 Unix 毫秒，不能套用 Swift Date 的默认 JSON 日期规则。Android 不持久化换票 ticket，也没有 pending API 基址字段；恢复边界详见[客户端生命周期](https://document.thestarline.cn/app/client-lifecycle.md)。本页不展示任何实际 token、verifier 或密钥。

## 旧数据迁移与失败处理

iOS 检测旧 `memories.json` 时先加载旧记录，在暂存 vault 中逐附件加密并回读验证，再写入并验证加密索引，随后移动成正式 vault，最后清理旧明文。旧附件 `storedName` 必须是安全单段文件名，不能包含路径穿越。清理旧明文失败有独立错误，不应描述为所有数据都已安全清理。

已有加密索引时不会为了读取失败而生成新密钥；出现无有效索引的残留 vault、认证失败或缺失密钥会留下错误状态，禁止覆盖。附件删除使用尽力清理，不能从索引删除成功推断闪存物理擦除。Android 兼容宠物和签证旧字段别名；同主题编辑保留未展示旧键，切换主题则明确替换相关字段。原子索引写入、旧格式解析和字段迁移需分别测试。

## 解析与扩展检查顺序

1. 先确认数据类别。一个带有相同记录标题的工作台任务和记忆没有共享 ID 或自动关联；一个 Base64 字符串也不能据此判断是密钥、附件还是密文。按容器与字段定义解释，不猜测内容。
2. 确认时间单位、基准和是否含时区。Swift 快照参考日期秒数、Android Unix 毫秒、协议 expiresAt 和表单日期分属不同规则。转换测试至少覆盖参考日期、非整秒、缺失截止、设备时区变化和日期型空值。
3. 确认空值策略。iOS 的可选键可省略，但必需数组或 UUID 损坏会使解码失败；Android `optString/optLong/optBoolean` 可能给出空串、0 或 false。缺键不应自动解释为用户主动清空，也不能用默认值覆盖已经读错的数据。
4. 确认元数据与文件一致。附件数、ID 和原字节大小应吻合；扩展名是名称信息，不能替代 MIME、图片解码或 GCM 认证。转出包附带的原始字节需要按记录关联；磁盘 vault 只靠元数据不能恢复丢失密钥。
5. 用独立合成夹具验证旧版读取、新版保存、进程重开和错误保护。添加字段时明确默认值和未知字段保留策略，不能将 Android 的宽松 JSON 行为推到 Swift Codable；改变 AAD 或密钥别名须有明确版本迁移，不能只改字符串。

检查成功也只说明该类夹具符合当前解析器，不构成通用导入器、跨端转换器或断电恢复保证。当前没有自动修复受损 vault 的流程；应保留原文件和可复核错误，避免直接编辑加密字节、复制安全存储、生成新密钥或用空库覆盖作为修复。

代码入口包括 iOS `LocalWorkspaceStore`、`MemoryStore`、`MemoryVaultCrypto`、`MemoryGeneratedSchema` 与 Android `AppData`、`MemoryScreens`、`MemoryTemplates`。2026-10-23 本轮仅静态核对，未读取用户磁盘数据、运行迁移或执行产品测试。


原始地址：https://document.thestarline.cn/app/memory-export/
Markdown：https://document.thestarline.cn/app/memory-export.md

# 记忆转出容器、许可与失败处理

客户端已经编写记忆转出的许可桥接和本机打包代码。当前作为维护基线的 Account 主目录源码没有对应记忆转出模块与 `/api/memory-export/redeem` 路由，因此本页描述实现契约与本机文件格式，不代表当前跨服务转出已经可用。App 工作树中的历史 Account 副本不能代替权威 Account 的运行版本与真实验收。

## 转出包含什么

转出目标是当前安装的本机记忆列表及其原始附件。它不包含工作台任务、网页收藏、浏览器 Cookie、聊天历史、聊天 token、MLS 私钥或设备 vault 密钥。记忆中用户自己录入的敏感信息仍会作为记录原文进入文件。

本机记忆不按聊天账号分库，同一安装中不同账号看到同一库。Account 许可验证的是当前账号完成了额外验证，不能据此证明每条本机记忆属于该账号，也不是为该账号分发某份云备份。改 Account 密码、退出或切换账号不会删除或重加密记忆；设备密钥和账号凭据的责任见[本地记忆](https://document.thestarline.cn/app/local-memory.md)。

## 外层 JSON 契约

| 字段 | 类型 | 语义 |
| --- | --- | --- |
| `format` | 字符串 | 固定 `cn.thestarline.memory-export` |
| `version` | 整数 | 当前为 `1`，表示转出容器版本 |
| `entries` | 数组 | 每条转出记录；不是按用户 ID 分组 |
| `entries[].record` | 对象 | 该平台的完整记录数据 |
| `entries[].attachmentData` | 对象 | 附件 ID 到原始字节标准 Base64 字符串的映射 |

下面是一个完整的合成 Android 容器，附件明文仅为六个 ASCII 字节 `sample`：

```json
{
  "format": "cn.thestarline.memory-export",
  "version": 1,
  "entries": [{
    "record": {
      "id": "11111111-1111-4111-8111-111111111111",
      "title": "格式示例",
      "body": "合成说明",
      "kind": "general",
      "createdAt": 978307200000,
      "updatedAt": 978307200000,
      "attachments": [{
        "id": "22222222-2222-4222-8222-222222222222",
        "name": "sample.txt",
        "mimeType": "text/plain",
        "size": 6
      }]
    },
    "attachmentData": {
      "22222222-2222-4222-8222-222222222222": "c2FtcGxl"
    }
  }]
}
```

容器没有创建时间、平台名称、账号归属、签名、文件摘要、加密算法或自动恢复指令字段。version=1 也不表示 iOS 与 Android 内层记录完全一样。JSON 对象键顺序不能用于判断相同内容；iOS 对逐条编码对象启用 sortedKeys，Android 保留原记录 JSON 字符串，不能依赖字节级排序一致。

## 平台内层差异

| 概念 | iOS `record` | Android `record` |
| --- | --- | --- |
| 正文 | `text` | `body` |
| 自由记录类型 | `kind=note` | `kind=general` |
| 模板字段 | `fields` 字符串字典 | 直接在记录顶层保存各字段 |
| 动态主题 | 可选 `generatedSchema`，含主题、图标及字段定义 | 固定模板，或 `suggestedCategory` 与通用字段 |
| 创建与修改时间 | Date 默认编码：2001-01-01 起算秒，可含小数 | Unix 毫秒 |
| 附件元数据 | `id/name/storedName/byteCount/isImage` | `id/name/mimeType/size` |
| 历史未知键 | 按 Codable 已知模型编码 | 原 JSON 可保留未展示的历史键 |

表单日期如 `followUpOn` 仍是 `yyyy-MM-dd` 字符串，预约时间如 `startsAt` 为不带时区的本地日期时间字符串；它们不是 createdAt 的另一种写法。iOS 附件映射键使用 `UUID.uuidString`，应与该 record 的附件标识关联。Android 对同一记录的附件 ID 去重后写映射。记录级附件清单与 attachmentData 需要一起检查，不能仅看文件名判断附件是否完整。

打包读取的是通过本机密钥解开的原始附件，文件中的 Base64 不再保留原 vault 加密层。它不是客户端缓存图、缩略图或服务器媒体链接。两端格式细节和示例见[本机数据格式](https://document.thestarline.cn/app/local-data-formats.md)。

## 许可桥接的请求步骤

1. 用户从“设置／数据与隐私”发起；客户端要求已登录且记忆可读取，Android 还阻止空列表开始。
2. 客户端携带聊天 Bearer token 请求 `GET /memory-export/start`。聊天服务要求身份桥接配置可用，创建绑定当前用户的 state 和服务端 verifier，本地 flow 有效五分钟。
3. 响应含 `url`、`state`；URL 指向 Account 的 `/memory-export`，参数包括 `state`、`code_challenge`、`client_id`。客户端预期 Account 完成主验证与邮箱二次验证，随后返回 `starlineworkbench://memory-export` 的 state 与一次性 ticket。这部分需要在权威 Account 版本完成对接。
4. 客户端将回调 state 与本机操作匹配，再调用 `POST /memory-export/exchange`，JSON 仅含 `state`、`ticket`。
5. 聊天服务消费匹配当前用户的 flow，以服务端机密客户端认证请求 Account `/api/memory-export/redeem`，发送 state、ticket 和保存的 verifier，并检查返回用户与当前 Account subject 一致。
6. 客户端只有收到 `authorized=true` 才进入本机打包或保存位置选择阶段。记忆正文和附件不在这些许可请求中上传。

客户端没有 Account 机密客户端 secret，不能跳过兑换、将普通登录 ticket 改作转出票据或因网页显示成功而直接生成文件。聊天服务先消费本地 flow 再访问 redeem，后续失败不能假设同一 flow 还可重复使用，应重新开始许可流程。当前缺失 Account 对接意味着文件格式单测通过仍不足以完成第 3–6 步。

## iOS：验证后生成，再交系统分享

iOS `DataPrivacyView.exportMemories` 等待 `ChatStore.authorizeMemoryExport`。系统授权会话返回后，代码核对 state、原 token 与用户，再向聊天服务兑换许可。成功后 `MemoryExportDocument.write` 创建带随机后缀的临时目录，将其排除系统备份，并创建 complete 文件保护的“星线记忆.json”。

写入先输出容器头，再逐条编码 record；每条先从 MemoryStore 解密其全部附件为 Data 字典，JSONEncoder 将 Data 编成 Base64。完成后同步文件，再交 `UIActivityViewController`。代码避免先把整个输出拼成一段巨大字符串，但单条的附件和编码结果仍占内存，不是常量内存的备份引擎。

验证取消或失败发生在写文件之前。系统分享页出现时，临时明文文件已经生成；取消分享只结束该次分享，不能描述为“从未生成过明文”。分享完成或页关闭时清理临时目录，下次启动也会清理残留的转出目录。清理使用尽力删除，不保证收件应用或用户已保存副本同时消失。

## Android：授权、选位置、打包复制

Android 的操作阶段为 `IDLE → STARTING → VERIFYING → EXCHANGING → READY → CHOOSING → SAVING → COMPLETE`。状态对象绑定启动时的 token 和 userId，并用 operation 序号阻止旧操作继续。回调 state 不属于当前等待操作时忽略；账号切换、退出、离开转出页或主动取消都会使旧许可失效。

READY 后通过 `CreateDocument(application/json)` 请求用户选保存位置。没有选择目标 URI 就取消，不调用本机 writer。选择后捕获当前记录 JSON 与附件 ID，后台逐条写临时容器，再以 64 KiB 缓冲复制到目标 URI。写入记录、附件与复制循环之间都会检查当前协程、账号和许可仍有效。完成后才显示已保存数量并使本机许可失效。

Android writer 对缺失附件或无效 ID 抛错，防止静默输出缺附件的“成功”文件；失败或取消会删临时目录，并尽力通过 DocumentsContract 删除未完成目标文档。第三方文档提供者可能拒绝删除，因此清理是尝试，不是对任意云盘的无条件保证。成功后临时目录在 finally 中删除，启动也清理旧残留。

## 失败结果与排查

| 场景 | 当前含义与处理 |
| --- | --- |
| 未登录、账号资料未恢复 | 先完成正常聊天登录，不用本机伪造身份 |
| vault 损坏或缺密钥 | 原数据保护锁仍生效，转出不能绕过解密失败 |
| 开始接口不可用 | 检查桥接配置和当前 Account 对接，不能只重试分享页 |
| state、账号或 ticket 不匹配 | 当前操作无效，重新完整验证 |
| redeem 缺失、失败或超时 | 无有效许可；当前基线确有缺口，不标“已转出” |
| 某附件读取失败 | 整次 writer 失败并尝试清理，不跳过该附件冒充完整 |
| 目标位置不可写、空间不足 | 保留源记忆，报告保存失败，重新选择位置 |
| 进程在验证或写入时被终止 | 本轮没有断电／杀进程验收；不能假设自动续传或目标文件完整 |

正常路径也需检查 JSON 可解析、entries 数量、每条元数据和附件映射的关系，以及原始附件字节。检查使用合成资料，不把真实记录、票据、verifier 或输出全文写入公开报告。Base64 长度约为原始字节数的 4/3，另有 JSON 元数据开销；足够的原附件空间不保证目标空间也足够。

## 明文、换机与恢复边界

输出 JSON 可直接被能读到文件的程序解析，Base64 是编码而非加密。保存到外部文档提供者或发送给其他应用后，接收方的权限、同步、保留和删除策略由相应服务决定；App 清理临时文件不能撤回那些副本。源码没有为转出包设置密码、接收人密钥或自动过期机制。

当前没有把该文件导回 App 的通用入口，也没有自动云同步、自动恢复、冲突合并或跨端 schema 转换。因此“转出原始资料”不等于“换机后可在 App 恢复”。复制加密 vault 文件也不能代替迁移：文件还依赖设备安全存储中的密钥。卸载前应先确认需要保留的资料已安全取得，不能仅凭一份文件名或未完成的许可页判断备份可用。

## 源码依据与本轮范围

客户端实现位于 iOS `Features/Profile/MemoryExportDocument.swift`、`ProfileView.swift`、`ChatStore.authorizeMemoryExport` 和 Android `MemoryExport.kt`、`MemoryExportDocument.kt`；聊天侧为 `src/server.mjs` 的 memory-export 路由与 `database.mjs` 的五分钟 flow。Account 能力按当前维护主目录核对。本轮只审阅这些源码和文档，未调用许可 API、生成真实数据包、运行模拟器或执行多因素流程；后续验收见[QA矩阵](https://document.thestarline.cn/app/qa-matrix.md)与[协议操作示例](https://document.thestarline.cn/app/protocol-recipes.md)。


原始地址：https://document.thestarline.cn/app/medical-records/
Markdown：https://document.thestarline.cn/app/medical-records.md

# 医疗健康记录

医疗健康记录是本地记忆的一种结构化模板，用于整理就诊、检查检验、用药、疫苗与复诊资料。它沿用本机加密、附件、编辑、搜索与转出机制，内容由用户输入和确认。

## 模型与字段

手动选择固定模板时，两端使用稳定类型标识 `health`。iOS 在 `MemoryKind.health` 中定义字段，Android 在 `MemoryTemplates` 中定义对应模板，八个字段 ID 保持一致。iOS 若应用识别生成的医疗 schema，编辑器会以 `kind=note` 加 `generatedSchema` 保存主题与固定字段；程序不能仅按 kind=health 判断所有医疗主题。

| 字段 ID | 显示名称 | 输入与限制 |
| --- | --- | --- |
| `healthRecordType` | 记录类型 | 就诊、检查检验、用药、疫苗接种、其他 |
| `healthSubject` | 记录对象 | 文本，最多 200 字符 |
| `healthRecordDate` | 记录日期 | 可选日期 |
| `medicalInstitution` | 医疗机构 | 文本，最多 200 字符 |
| `departmentDoctor` | 科室与医生 | 文本，最多 200 字符 |
| `medicalResult` | 诊断／检查结果 | 多行文本，最多 2,000 字符 |
| `medicationInstructions` | 用药与医嘱 | 多行文本，最多 2,000 字符 |
| `followUpOn` | 复诊日期 | 可选日期 |

标题、正文和附件仍是独立内容：标题最多 80 字符，正文最多 20,000 字符；单附件最多 20 MiB，每条最多 20 个、合计 50 MiB。日期按明确格式保存，未选择日期时保持为空，选择模板不会自动把当天写成记录或复诊日期。

## 输入、保存与检索

用户进入“记忆”后新建或编辑记录，选择“医疗健康记录”，填写所需字段并添加图片或文件，再明确保存。字段均可留空；仅选中模板不会生成空记录。长文本编辑器保留换行；缩写、检验指标名称和英文原文按输入保存，不进行语义改写。

iOS 将字段放入 `MemoryEntry.fields`，保存时仅接受模板允许的字段 ID，并清理首尾空白、执行长度限制。Android 将字段放入记录 JSON，同主题编辑会替换可见字段，同时保留未展示的旧键和未知字段，防止编辑新表单时丢失历史内容。两端都沿用记忆加密存储；加密失败或原库无法读取时禁止覆盖，见[本地记忆](https://document.thestarline.cn/app/local-memory.md)。

详情页展示已填写字段，列表可用前两项有效字段形成摘要。搜索可命中医疗机构、医生、记录对象、结果、医嘱、日期、正文和附件名；它不会分析附件中的检查内容，也不会自动从图片提取指标。

## 本机推荐的约束

输入出现“医疗、就诊、检查报告、用药、复诊”等关键词时，客户端可以推荐健康模板。iOS 对明确人类医疗输入直接返回固定健康字段，不调用系统模型生成新的诊断选项；Android 使用本机关键词匹配。宠物与疫苗词共同出现时仍优先进入宠物接种字段，英文动物匹配采用单词边界，避免把其他单词误识别为猫或狗。

推荐只决定记录类型与可填写结构，不推断诊断、处方、药量或用户尚未提供的信息。用户仍需确认模板，并按原始资料填写。

## 编辑、搜索与关联规则

每条记录以 UUID 区分，不以医院、姓名或日期作为唯一键。同一对象在同一天可有多条独立记录，保存不会自动合并；更改记录对象或机构不会创建另一位“患者档案”。当前没有患者实体、医院目录关联、药品知识库、检验参考值模型，也没有记录之间的关系索引。附件只按附件 ID 关联该条记忆，不会自动解释为某项检验。

iOS 保存时把同 ID 的旧记录替换为更新后的记录并移到列表前端，保留 createdAt，更新 updatedAt；Android 修改已有 JSON 保持当前列表位置，新建插到前面。两端都能在列表显示字段摘要，但摘要只取已填写字段中的前两项，不是按医学重要性排序。未显示在摘要中的医嘱仍可在详情和搜索中访问。

例如合成检验值“TSH 2.0; ALT 30”会作为文本保存，大小写或标点不会被改为医学解释；字段值首尾空白可被清理，内部换行保留。普通搜索使用字符串匹配，多个空白分词须全部命中但可以分布在不同字段；搜“机构名 检查”并不保证两词位于同一个字段。日期字段可按其原始格式被匹配，不能把关键词搜索结果称为临床全文分析。

删除正文、清空某个可见字段、移除附件与删除整条记录是不同操作。Android 同主题编辑会明确移除已清空的可见字段，保留未展示旧键；iOS 按当前允许字段重新保存。删除整条记忆先更新索引，再清理其文件，两端的清理失败策略不同，不能承诺闪存安全擦除或撤回已经转出的明文副本。

## 扩展方式

新增医疗字段时应同步更新两端模板、展示、搜索和字段长度规则，保持已有 ID 稳定；新类型不能覆盖旧记录。若计划引入 OCR、提醒、健康平台或云端能力，需要分别设计用户授权、数据来源、删除和失败恢复路径，不能仅增加一个日期字段就宣称已经支持提醒。

## 当前范围与验证

当前实现不包含自动复诊通知、医院系统对接、HealthKit、Health Connect、云端病历同步或自动医学判断；复诊日期只是可选记录值。记忆转出需走账号许可流程，输出包含原文与附件的明文 JSON，详见[认证](https://document.thestarline.cn/app/authentication.md)和[安全与隐私](https://document.thestarline.cn/app/security-and-privacy.md)。

仓库中 iOS 存储测试覆盖医疗长字段截断、重开、编辑、附件加密及空记录；Android 单元和设备测试包含固定字段、多行文本、临床缩写、搜索、旧字段保留与加密附件。测试代码存在不等于本次已执行通过：本篇编写未运行构建、模拟器或真实医疗数据。回归应使用虚构资料，并按[测试](https://document.thestarline.cn/app/testing.md)记录当前设备和结果。


原始地址：https://document.thestarline.cn/app/city-stickers/
Markdown：https://document.thestarline.cn/app/city-stickers.md

# 城市建筑贴纸

城市建筑贴纸根据用户识别或手选的城市提供一张本地建筑插画，再通过聊天服务登记成系统贴纸媒体。它与自定义图片贴纸分开管理，不占用户自定义贴纸数量。

## 目录与素材架构

源素材位于 `city-stickers`：`catalog.json` 为版本 1 的城市白名单，`svg` 保存程序化矢量源，`images` 保存运行时 PNG，`SHA256.json` 为输出摘要，`contact-sheet.png` 供整体检查。当前目录共 44 城，包括北京、上海、香港、澳门、台北、东京、巴黎、伦敦、纽约等，覆盖以目录为准。

每个 `CitySticker` 含 `id`、`countryCode`、中文城市名、`nameEn`、`aliases`、`landmark` 和固定 `asset` 文件名。地标示例包括北京天坛祈年殿、成都安顺廊桥、济南超然楼、巴黎埃菲尔铁塔。素材是风格化建筑插画，不应当作测绘或地理证明。

`build.py` 定义城市、别名和独立建筑构图，使用 320×320 SVG 画布、统一色板和基础描边；构建时用 PyMuPDF 与 Pillow 导出 512×512 透明 RGBA PNG，并断言每张小于 512 KiB。客户端运行无需这些生成库。

## 城市识别与选择

贴纸面板第一格固定为城市入口，后面保持自定义贴纸顺序。打开面板会尝试设备城市解析与已登录服务的 `/location/city` IP 粗略城市。较快的 IP 可以先显示，设备城市成功后优先替换。界面分别标示“系统定位／城市级”“IP 粗略定位”与“手动选择”。

iOS 使用前台单次 `CLLocationManager` 请求，精度目标为三公里，经系统逆地理服务解析城市，十秒超时后结束。Android 在已有粗略定位权限时使用短时设备请求，在送系统 Geocoder 前将坐标量化到 0.02 度；未授权时保留 IP，并提供主动申请粗略定位入口。两端都可刷新或搜索手选，城市结果在进程内约缓存十分钟。

城市与别名匹配结合国家地区代码，香港、澳门的行政区域返回值有专门处理。不同国家的同名城市不应混用；未收录城市保持选择入口，不拿附近城市替代。两端名称规范化实现略有差异，新增别名应双端回归。

这条城市识别路径不会开启实时位置共享或后台定位，也不会把设备坐标发送给星线聊天服务；系统定位和逆地理服务按系统自身规则处理请求。实时共享属于用户明确开启的另一条数据流，见[消息与媒体](https://document.thestarline.cn/app/messaging-and-media.md)。

## 发送流程与竞态处理

用户选择城市后，客户端向 `/stickers/city` 发送 `cityId`，获得系统贴纸 `media`，再经正常单聊或群聊发送。iOS 校验媒体类型为 `sticker`、MIME 为 `image/png` 且大小在限制内；客户端只从打包目录加载预览，不接收任意素材路径。

准备请求绑定当前账号和目标聊天。用户离开原会话、退出账号、关闭面板或手动选择新城市时，旧请求的迟到结果应被取消或丢弃。iOS 使用操作 generation 与账号／会话复核，Android resolver 也使用 generation、协程取消和当前面板校验，防止把旧定位或旧媒体发入新会话。

## 新增城市与资产发布

新增城市时在 `build.py` 添加稳定 ID、国家地区码、别名、建筑名和对应构图，再执行素材构建。脚本会同步到 iOS `Sources/CityStickers`、Android `assets/city-stickers` 与聊天服务 `assets/city-stickers`。发布必须保持三端目录、ID 和 PNG 一致，并检查实际透明图与联系表；只改名称、复用不相关建筑不能算作新城市覆盖。

## 当前目录与跨端匹配差异

以下清单按2026-10-23工作区的版本1目录整理，城市ID是发送与资产去重使用的稳定标识。它不是覆盖所有城市的声明。

| cityId | 城市 | 国家或地区代码 | 建筑 |
| --- | --- | --- | --- |
| `beijing` | 北京 | `CN` | 天坛祈年殿 |
| `shanghai` | 上海 | `CN` | 东方明珠 |
| `guangzhou` | 广州 | `CN` | 广州塔 |
| `shenzhen` | 深圳 | `CN` | 平安金融中心 |
| `chengdu` | 成都 | `CN` | 安顺廊桥 |
| `chongqing` | 重庆 | `CN` | 洪崖洞 |
| `hangzhou` | 杭州 | `CN` | 雷峰塔 |
| `nanjing` | 南京 | `CN` | 中华门 |
| `suzhou` | 苏州 | `CN` | 虎丘塔 |
| `wuhan` | 武汉 | `CN` | 黄鹤楼 |
| `xian` | 西安 | `CN` | 钟楼 |
| `tianjin` | 天津 | `CN` | 天津之眼 |
| `qingdao` | 青岛 | `CN` | 圣弥厄尔教堂 |
| `xiamen` | 厦门 | `CN` | 世茂双子塔 |
| `changsha` | 长沙 | `CN` | 天心阁 |
| `harbin` | 哈尔滨 | `CN` | 圣索菲亚教堂 |
| `zhengzhou` | 郑州 | `CN` | 二七纪念塔 |
| `jinan` | 济南 | `CN` | 超然楼 |
| `lhasa` | 拉萨 | `CN` | 布达拉宫 |
| `fuzhou` | 福州 | `CN` | 三坊七巷 |
| `quanzhou` | 泉州 | `CN` | 开元寺双塔 |
| `dali` | 大理 | `CN` | 崇圣寺三塔 |
| `guilin` | 桂林 | `CN` | 日月双塔 |
| `guiyang` | 贵阳 | `CN` | 甲秀楼 |
| `hongkong` | 香港 | `HK` | 中银大厦 |
| `macau` | 澳门 | `MO` | 大三巴牌坊 |
| `taipei` | 台北 | `TW` | 台北101 |
| `tokyo` | 东京 | `JP` | 东京塔 |
| `osaka` | 大阪 | `JP` | 大阪城 |
| `kyoto` | 京都 | `JP` | 清水寺 |
| `seoul` | 首尔 | `KR` | N首尔塔 |
| `singapore` | 新加坡 | `SG` | 滨海湾金沙 |
| `kualalumpur` | 吉隆坡 | `MY` | 双子塔 |
| `bangkok` | 曼谷 | `TH` | 郑王庙 |
| `paris` | 巴黎 | `FR` | 埃菲尔铁塔 |
| `london` | 伦敦 | `GB` | 伊丽莎白塔 |
| `newyork` | 纽约 | `US` | 帝国大厦 |
| `sydney` | 悉尼 | `AU` | 悉尼歌剧院 |
| `dubai` | 迪拜 | `AE` | 哈利法塔 |
| `sanfrancisco` | 旧金山 | `US` | 金门大桥 |
| `seattle` | 西雅图 | `US` | 太空针塔 |
| `toronto` | 多伦多 | `CA` | 加拿大国家电视塔 |
| `rome` | 罗马 | `IT` | 斗兽场 |
| `istanbul` | 伊斯坦布尔 | `TR` | 加拉塔塔 |

iOS 对名称执行大小写、变音符和全半角折叠，再去空格，主要依靠目录中的明确别名；Android 另会移除空白及标点、末尾的 city／市，并要求最终只匹配一项。相同国家地区内的歧义别名可能使 Android 返回空，而 iOS 采用首先匹配的条目，新增素材时应在目录层避免歧义，不用修改匹配器去猜用户位置。

香港、澳门可由国家地区代码直接归入对应行政城市，也兼容系统返回CN且城市为明确已知别名的情况；“香港路”或“澳门附近”不应算香港澳门。国家地区代码缺失时仅靠名称可能不足以确认现实位置，UI保留来源提示和手选。系统城市更准确也不意味着其城市一定已收录。

城市结果只保留在进程内，账号退出会重置当前选择；Android 还按账号键及权限状态检查缓存，手选可使待完成定位失效。十分钟是复用选择的条件，不是持续采集位置的间隔。关面板、切账号、切聊天和点击刷新分别改变请求的当前性，扩展时应测试较慢设备结果和较快IP结果的相反到达顺序。

源码入口包括 `city-stickers/build.py`、iOS `CitySticker/CityStickerSelection/CityStickerDeviceLocator/ChatEmojiPicker` 以及 Android `CitySticker/CityStickerLocation/CityStickerSheet`。发送媒体与消息引用的边界另见[消息与媒体](https://document.thestarline.cn/app/messaging-and-media.md)。

## 验证范围

本次文档编写做了只读资产核验：主目录为 44 城，PNG 均为 512×512，文件范围为 15,043–36,569 字节，三端目录和全部 PNG 与源目录逐字节一致。这只证明工作区素材一致，不能证明线上服务或商店安装包已同步。

仓库测试还覆盖国家匹配、行政区域、设备优先、IP 回退、未知城市、缓存、取消和发送目标变化。本轮未运行这些测试，真实卫星定位、系统 Geocoder 可用性、跨网络发送与商店包仍须按[测试](https://document.thestarline.cn/app/testing.md)和[发布](https://document.thestarline.cn/app/releases.md)验收。


原始地址：https://document.thestarline.cn/app/permissions-accessibility/
Markdown：https://document.thestarline.cn/app/permissions-accessibility.md

# 权限、系统能力与可访问性

星线按扫码、通话、城市识别、实时位置和文件操作分别接入系统能力。本文列明源码声明及触发路径，并说明现有可访问性实现与验收范围。

## iOS 权限与能力

| 能力 | 触发与用途 |
| --- | --- |
| 相机 | 扫码、拍摄和视频通话，在对应路径请求视频访问 |
| 麦克风 | 发起或接入音视频通话时请求音频访问 |
| 使用期间定位 | 城市贴纸、位置选择、附近地点及用户确认后的实时共享 |
| 文件与照片选择 | 使用系统选择器读取用户明确选中的项目 |

`Info.plist` 和 `project.yml` 提供相机、麦克风、使用期间定位说明；后台模式声明 location、audio、voip。城市识别只发起一次前台请求，实时共享在用户开启后才允许后台定位，结束时关闭后台更新。声明后台模式本身不会让共享自动开始。

扫码检查 `DataScannerViewController.isSupported` 和 `isAvailable`。相机不可用或未授权时保留照片选择、粘贴内容和系统设置入口；相册使用 `PhotosPicker`，文件使用 `fileImporter`，不要求扫描整个照片库。通话分别处理麦克风与摄像头授权，视频开关会检查摄像头访问。

系统来电桥接使用 CallKit/PushKit，APNs entitlement 根据 Debug/Release 注入 development/production 环境。推送凭据、服务和描述文件是否可用，需要独立验收，不能由 entitlement 存在推断后台来电已交付。

## Android 清单与运行时请求

清单声明 INTERNET、CAMERA、RECORD_AUDIO、MODIFY_AUDIO_SETTINGS、ACCESS_NETWORK_STATE、FINE/COARSE_LOCATION、FOREGROUND_SERVICE、FOREGROUND_SERVICE_LOCATION 和 POST_NOTIFICATIONS。其中敏感权限还需运行时获得用户授权。

扫码相机进入页面后请求 CAMERA，CameraX 随生命周期绑定与释放；拒绝后仍可选择图片或粘贴。通话依据接听、入会、开麦或开摄像头动作请求所需权限，支持视频通话的仅音频加入路径。

城市贴纸优先使用已获得的 COARSE_LOCATION，界面提供主动授权按钮；即使没有定位权限也可用 IP 粗略城市或手选。实时共享同时处理精确／粗略位置，以及 Android 13 及以上的通知权限，再启动带持续通知的定位前台服务。清单没有申请 ACCESS_BACKGROUND_LOCATION；前台服务的系统限制和厂商后台策略仍需真机检查。

应用关闭系统自动备份，Release 禁止明文网络，Debug 单独允许本地联调。FileProvider 不对外导出组件，只向选中的接收应用授予临时 URI 权限。文件选择通过系统文档选择器读取指定内容，没有请求广泛存储访问。相关数据边界见[安全与隐私](https://document.thestarline.cn/app/security-and-privacy.md)。

## 拒绝、撤权与替代路径

| 场景 | iOS 当前行为 | Android 当前行为 |
| --- | --- | --- |
| 扫码相机拒绝 | 保留照片／粘贴，显示系统设置入口 | 相机区域可再次申请，照片／粘贴仍可用；永久拒绝后不能假设重按必有弹窗 |
| 扫描硬件不支持 | VisionKit 能力检查后显示替代入口 | CameraX 初始化失败显示错误，不把取景框存在算识别可用 |
| 通话麦克风拒绝 | 准备媒体阶段报错，不能正常发布音频 | 动作提示所需权限，可重新授权 |
| 视频摄像头拒绝 | 摄像头状态保持关闭，不能声称发送视频 | 视频发起要求相机；来电／加入可选择仅音频路径 |
| 城市粗略位置未授权 | 单次请求可能触发授权；失败保留 IP 与手选 | 不强制先授予精确定位，用户可主动申请粗略位置 |
| 实时位置所需通知拒绝 | 不适用 Android 通知前台服务门槛 | Android 13及以上通知未授权时不开始持续共享 |
| 共享中撤销位置 | 停本机位置更新，页面须呈现最后更新时间 | 前台服务停采集并提示处理原有共享；不等于服务器已删除旧坐标 |
| 文件或照片选择取消 | 不添加本次项目 | 不添加本次项目 |

权限“已拒绝”和系统定位／相机服务关闭不同；同一个按钮重新点击也不能替代前往系统设置。普通文件选择、附件预览和 JSON 转出也属于不同授权范围：选择输入文件不表示允许读取整个目录，授予 FileProvider 读权限不表示接收应用不能复制内容，选择转出目标可能涉及用户所选云盘。详细明文和清理边界见[记忆转出](https://document.thestarline.cn/app/memory-export.md)。

回归按以下顺序记录：在明确的初始权限下进入功能；拒绝并确认替代入口；到系统设置改变权限后回前台；重新触发；进行中再次撤权；最后退出页面和进程，检查资源释放及服务器状态。不得为了截图统一清除已有 App 数据，测试夹具和权限状态应使用专用设备或明确授权的范围。

## 已有可访问性实现

iOS 为扫码、记忆操作、任务完成、名片和消息等提供语义标签或提示；部分纯装饰插画隐藏于辅助技术。任务筛选在辅助功能大字号下由横排改为纵排；新事及个人页读取 Reduce Motion，减少过渡动画。测试使用的 `accessibilityIdentifier` 是定位标识，不能替代用户能听到的 `accessibilityLabel`。

Android 底部导航提供 `Role.Tab` 与导航描述，设置开关使用 Switch 语义，任务操作描述包含目标任务。通话状态和错误使用 polite live region；装饰插画移除语义，动作图标提供中文描述。主要工具栏动作采用 48dp 点击区域；插画与页面过渡读取系统动画时长开关，关闭动画时使用静态状态。

## 扩展与验收

新增能力应将用途说明、运行时请求、拒绝后的可用路径和资源释放放在同一功能中检查。新增图标沿用已有矢量体系，统一尺寸、线宽和语义颜色；功能名称由标签表达，装饰图不重复播报。布局需检查窄屏、键盘弹出、较大字体、长文件名和多行内容的实际摆放。

本篇依据源码，不宣称已通过完整 VoiceOver、TalkBack、大字号、对比度或无障碍合规认证。本轮未操作设备。回归需覆盖首次允许、拒绝、永久拒绝、系统设置撤权、前后台切换与进程恢复，并实际检查焦点顺序、朗读、触控区域及动画关闭后的状态，见[测试](https://document.thestarline.cn/app/testing.md)。源码入口为 iOS `ScannerView/ChatCallCoordinator/ChatLiveLocation/TaskListView` 与 Android `ScanCameraPreview/CallScreen/LiveLocationPanel/VisualArtwork`。城市与医疗的专项边界分别见[城市贴纸](https://document.thestarline.cn/app/city-stickers.md)和[医疗健康记录](https://document.thestarline.cn/app/medical-records.md)。


原始地址：https://document.thestarline.cn/app/security-and-privacy/
Markdown：https://document.thestarline.cn/app/security-and-privacy.md

# 安全、加密与隐私边界

本页描述当前源码可确认的防护、数据可见性和已知实现边界。它不是独立安全审计报告，也不表示生产部署、客户端权限、外部依赖或端到端安全已经全部验收。维护者应以实际构建、配置回读和完整双设备路径的结果更新状态。

## 登录与凭据分层

Account 负责账号身份与授权，聊天服务负责业务会话。原生登录有 App→聊天服务的 S256 proof 和聊天服务→Account 的 S256 PKCE；state 与一次性 ticket 绑定，ticket 有效期 60 秒，聊天会话默认 24 小时。App 不需要存储机密 OIDC 客户端 secret。正式回调为 `https://chat.thestarline.cn/auth/callback`，自定义 scheme 只接收受 proof 约束的一次性 ticket。

服务端仅保存 state、ticket 和聊天 token 的 SHA-256 摘要，业务请求按未过期 token 摘要鉴权；原始 token 仍是持有即授权的凭据，客户端和日志系统须保护。原生回调需验证 scheme、host、state、参数唯一性和到期时间。仅仅“浏览器打开了 Account 页面”不算登录完成。

iOS 使用 Keychain 的 `AfterFirstUnlockThisDeviceOnly` 保存会话和原生授权待完成状态。Android 使用 Keystore 支持的本地加密存储。设备安全存储与服务器端会话到期是互补措施，设备已解锁、恶意软件、屏幕录制、系统备份和权限边界仍需单独评估。`/auth/logout` 成功时只撤销当前聊天 session，不等于所有 Account 登录和其他设备都已撤销。两端退出均会清除本机状态并忽略远端退出失败，网络失败时旧 session 可能继续有效直至到期；Account 改密码或撤销其自身会话没有自动联动撤销聊天 session 的实现。

## 服务端权限是核心约束

每个聊天资源都先验证 Bearer 用户，再检查会话双方、群当前成员或内容可见性。单聊发送、发起或接听通话、开始或更新位置、MLS 准备与应用事件等还会检查好友和任一方向屏蔽。群主权限用于邀请、改名、移除和解散，不能仅靠隐藏客户端按钮实现。

媒体下载要求所有者或可见消息授权；新事下载要求所有者或可见帖子授权。不可见资源通常使用 404 避免直接返回内容。普通单聊历史媒体的可见消息授权不重新检查is_friend或block，删好友/屏蔽不保证撤销原来仍可见的媒体；群消息授权分支要求当前成员，但所有者下载分支独立。不要把发送限制当历史读取限制。依据：`chat-service/src/database.mjs:239-254`。星企企业接口按组织成员、管理员与所有者执行独立检查，个人聊天身份不能绕过组织边界。返回 401、403、404、409 的具体语义见[API 参考](https://document.thestarline.cn/app/api-reference.md)。

## 哪些数据是服务端可读的

| 数据 | 当前实现 |
| --- | --- |
| 普通聊天正文、附件与贴纸 | 正文与原始媒体 BLOB 在服务端保存；主聊天链路尚未全量改用 MLS |
| MLS application 内容 | 已建立并激活的 MLS 范围存储应用密文；设备负责解密与发送者验证 |
| 新事文字、图片、视频、评论 | 服务端可读，依赖访问控制和可见范围 |
| 实时位置 | 经度、纬度、精度与时间在服务端可读保存 |
| 个人资料联系电话 | 服务端 AES-256-GCM 加密保存；按可见性解密返回 |
| 手机号查找索引 | HMAC-SHA256 摘要，登录后有效期 24 小时 |
| 来电推送 | 通话、聊天范围、模式、来电人名称及可选群名；不含聊天正文和媒体凭证 |

HTTPS 保护传输，磁盘加密保护本地存储，服务端加密保护特定字段，MLS 保护特定会话内容；它们的信任主体不同。当前不能把普通附件、实时位置、新事、通话媒体统称为端到端加密。代码中的上传接口没有客户端附件密钥、密文封装或附件解密协议。

## MLS 的已实现约束

Rust 核心使用 OpenMLS，固定 MLS 1.0 与 X25519、AES-128-GCM、SHA-256、Ed25519 对应的固定套件。服务端校验密钥包的协议、签名、套件以及账号/设备身份，已注册设备不能静默改签名公钥；密钥包使用一次性领取标记。服务端解析消息类型与群 ID，终端负责 MLS 消息验证、解密和发送者身份核对，服务端格式校验不能代替终端认证。

iOS 独立传输器在首次见到设备时固定签名公钥，已知设备换钥时拒绝继续；解密所得发送者与服务端 user/device 元数据不一致时失败。此为代码中的信任固定机制，不能据此宣称已经提供可供用户线下核对的完整安全号码体验或第三方目录透明性。

设备或成员变化使现有加密范围 blocked，服务端暂停应用密文发送；新 Commit、必要 Welcome 和确认完成后才激活。preparing/active/blocked 范围禁止旧明文发送接口。加密状态丢失时不得静默生成新密钥假装旧设备，也不得跳过失败的消息来推进 sequence。

Rust 状态快照使用 AES-256-GCM、随机 nonce 和固定附加认证数据封装，iOS 还将游标、待发密文、邀请与确认纳入加密 checkpoint；封装密钥存入设备安全存储。原生文件写入使用临时文件、同步与替换流程。恢复校验失败表示状态不可用，不能把它显示成“没有聊天记录”。这些机制仍需结合断电、进程中断、设备迁移和回滚测试验收。

## 个人资料、新事和位置控制

资料手机号可见范围为 private、selected、friends、everyone；everyone 仍是已登录聊天 API 用户。指定用户必须为当前好友，最多 100 位，双方屏蔽后不可通过这些规则获取手机号。可展示联系电话与 Account 已验证手机号查找索引不同，修改资料不等于修改 Account 安全手机号。

新事的 friends、selected、public、private 在每次读取时结合当前好友、屏蔽和个人隐藏判定，public 仍需要登录。点赞、评论和通知会产生参与关系元数据。隐藏新事、删除个人消息、删除个人聊天和解散群的语义不同；个人视图隐藏不承诺数据库、备份或另一端同时擦除。

实时位置必须显式开始，客户端应允许停止并说明系统位置权限。位置表没有自动到期字段，界面要呈现最后更新时间；用户停止本机定位采集与服务器删除共享记录是两个需要协调的动作。IP 城市只返回粗略结果，可信代理只接受 allowlist 中上游覆盖的单个 X-Real-IP，不能把任意 X-Forwarded-For 当可信地址。

## 输入限制、日志和公开资料

JSON 默认最大 16 KiB，不同媒体与加密接口有专用上限；普通上传、贴纸数量、账号空间、新事媒体、查找和识别分别受限。文字长度、规范 base64、文件名和 MIME 校验能减少异常输入，但文件头检查不等于恶意文件扫描，当前文档不承诺存在未实现的病毒扫描或内容安全服务。

公开文档仅发布接口契约与合成示例，不发布真实 token、客户端 secret、APNs/LiveKit 凭据、用户资料、数据库、附件、服务器地址或私有部署位置。机器人可索引文档不代表业务 API 免鉴权，也不授权访问个人数据。排错时使用错误码、请求阶段和已脱敏时间线，避免记录 verifier、票据、访问令牌、授权码和推送 token。

## 当前验收范围

可以确认的是源码中的路由、状态、输入限制、权限与加密实现。当前主聊天尚未全量接入 MLS，Android 未见同等 MLS 发送链路；真实跨网络音视频、后台系统来电和生产 APNs 仍需独立验收。当前权威 Account 主源码没有记忆转出 redeem 路由；App 工作树中的历史副本包含实现，也不能据此认定当前服务支持。安全承诺应以这些边界为准，测试依据见[测试](https://document.thestarline.cn/app/testing.md)，运营配置见[运维](https://document.thestarline.cn/app/operations.md)。


原始地址：https://document.thestarline.cn/app/module-map/
Markdown：https://document.thestarline.cn/app/module-map.md

# 源码模块与修改入口地图

本页将目录、关键文件、跨模块依赖和验证入口对应起来，便于定位变更边界。路径均相对其所属仓库，不代表公开源码下载授权。App 仓库含 iOS、Android、聊天和加密核心；Account 另有当前维护的主仓库，App 工作树附带的 `identity/` 是历史快照。二者不能以目录同名认定版本相同，更不能把旧副本整体覆盖到共享服务。

## 从需求定位负责层

| 需求或故障 | 首要入口 | 继续追踪的依赖 |
| --- | --- | --- |
| 启动页、导航、默认页面 | iOS App／Home，Android MainActivity／StarlineDesign | 本机偏好、页面状态与生命周期 |
| 登录、取消、回跳与重开 | ChatNativeAuth／ChatAuthenticator，Android NativeAuth | ChatAPI／ServiceApi、聊天授权路由、当前 Account OIDC |
| 好友、群、消息、已读与删除 | ChatStore／AppState、聊天 server／database | 关系权限、个人历史边界、事件刷新 |
| 新事、评论、可见性与视频 | MomentsStore／MomentsScreens、moments-repository | 聊天身份、独立媒体与成员关系 |
| 本机任务、收藏与最近访问 | LocalWorkspaceStore／WorkScreens、LocalData | 本机文件／偏好，非企业服务 |
| 记忆、模板与附件 | MemoryStore／MemoryTemplates、MemoryScreens | 设备密钥、格式兼容、本机识别与搜索 |
| 定位、城市与实时共享 | 城市 resolver／ChatLocation／LiveLocationService | 系统权限、目录、IP 城市及显式共享状态 |
| 通话与来电 | ChatCallCoordinator／CallScreen、calls 仓储 | LiveKit、APNs、系统能力、有效 session |
| MLS 独立协议 | ChatEncryptedTransport／chat-crypto／e2ee-delivery | 密钥包、设备身份固定、checkpoint、成员状态机 |

优先沿现有领域入口修改，不直接在视图里另建网络客户端、会话或持久化。页面隐藏只影响展示，服务端授权仍须在资源入口检查；双端使用同一业务服务也不代表本机实现和数据格式一致。

## iOS 文件职责

| 相对路径 | 职责与修改注意事项 |
| --- | --- |
| `ios-app/project.yml`、`StarlineWorkbench.xcodeproj` | XcodeGen 配置与实际工程；新增文件、资源和能力后核对二者 |
| `Sources/App/StarlineWorkbenchApp.swift` | Store 创建、系统来电桥、前后台与 URL 回调分发 |
| `Sources/Features/Home/HomeView.swift` | 根页面组织、本机工作台入口与偏好；不要混入服务端企业权限 |
| `Sources/Features/Chat/ChatAPI.swift`、`ChatModels.swift` | HTTP、解码、错误与 Debug base URL；服务字段改动需同步模型 |
| `ChatNativeAuth.swift`、`ChatAuthenticator.swift`、`ChatKeychain.swift` | PKCE／pending、系统授权会话与安全存储；检查取消、进程恢复和提交顺序 |
| `ChatStore.swift` | 账号、关系、消息、pending、已读、事件与位置业务协调；异步操作核对当前账号和范围 |
| `ChatComposer.swift`、`ChatThreadView.swift`、`GroupThreadView.swift` | 输入、附件、消息展示及目标会话；文件上传与消息引用是两步 |
| `ChatCallCoordinator.swift`、`ChatCallView.swift`、`CallSystemBridge.swift` | 媒体与系统通话桥接；信令 active 不等于轨道可用 |
| `CityStickerSelection.swift`、`CityStickerDeviceLocator.swift` | 设备城市、IP／手选优先级、缓存与迟到响应保护 |
| `ChatCryptoDevice.swift`、`ChatCryptoTrustStore.swift`、`ChatEncryptedTransport.swift` | 独立 MLS 核心包装、设备公钥固定和加密投递；不等于主消息全部接入 |
| `Sources/Features/Moments/` | 新事模型、Store、发布、详情和媒体；与普通聊天媒体契约分开 |
| `Sources/Data/MemoryStore.swift`、`MemoryVaultCrypto.swift` | 加密索引、附件、迁移、写入顺序与损坏保护 |
| `MemoryLocalRecognizer.swift`、`MemoryLocalSearch.swift` | 本机推荐与搜索；系统模型可用性与本机回退 |
| `Sources/Domain/MemoryTemplate.swift`、`MemoryGeneratedSchema.swift` | 固定模板、字段、长度与生成结构兼容 |
| `Sources/Features/Profile/MemoryExportDocument.swift` | 额外授权后的本机明文输出与临时文件清理 |
| `Sources/Data/LocalWorkspaceStore.swift` | 本机任务、收藏、最近访问的原子快照 |
| `Sources/Features/Scanner/`、`Browser/` | 相机／相册识别、网页、账号确认浏览会话 |

除完整路径的表项外，Chat 文件均位于 `ios-app/Sources/Features/Chat/`，Data 文件位于 `ios-app/Sources/Data/`。界面改动检查真实视口、键盘、大字号与辅助技术语义；资源名称存在不代表已放进当前 target。当前主设备族是 iPhone，没有 watchOS target，iPad 审核仍需独立验收。

## Android 文件职责

下表文件位于 `android-app/app/src/main/java/cn/thestarline/workbench/`。

| 文件 | 职责与联动范围 |
| --- | --- |
| `MainActivity.kt`、`StarlineDesign.kt` | Activity、Intent、根 Compose 布局、导航与系统 inset |
| `AppState.kt` | 当前账号、页面、事件循环、业务请求、通话与位置协调；注意协程取消和迟到结果 |
| `AppData.kt` | ServiceApi、错误、SecureFile、LocalData；任务偏好与加密会话／记忆分类不同 |
| `NativeAuth.kt` | verifier、state、目标 URL、回调与 pending；没有 Debug 本地 Account 例外 |
| `MessageSendIdCoordinator.kt` | 未确认发送的 clientId 复用；确认、换账号和换范围要保持隔离 |
| `ChatScreens.kt`、`ChatManagementScreens.kt`、`ChatMediaBubble.kt` | 消息、群、关系菜单、附件读取；引用权限来自服务端 |
| `MomentsScreens.kt` | 新事流、评论、通知、图片／视频发布与播放 |
| `CallScreen.kt`、`CallMediaControls.kt` | 运行时权限、LiveKit 控件与输出轨道；绑定当前通话 generation |
| `LiveLocationService.kt`、`LiveLocationPanel.kt`、`ChatLocation.kt` | 显式共享、前台服务、地图与更新时间；停止采集和删除共享要协调 |
| `CitySticker.kt`、`CityStickerLocation.kt`、`CityStickerSheet.kt` | 城市匹配、短时定位、IP 回退、手选、缓存与发送目标检查 |
| `MemoryTemplates.kt`、`MemoryScreens.kt` | 固定主题、关键词、编辑、搜索和旧字段保留 |
| `MemoryExport.kt`、`MemoryExportDocument.kt` | 一次性授权、生成输出、系统保存位置与取消清理 |
| `WorkScreens.kt`、`ProfileScreens.kt`、`AccountExtras.kt` | 工作台、本机任务／收藏、设置与账号展示 |
| `ScannerScreen.kt`、`ScanCameraPreview.kt` | CameraX、ML Kit、图片与手动输入 |

配置还分布在 `app/build.gradle.kts`、主／Debug `AndroidManifest.xml` 与资源目录。主清单关闭自动备份并禁止明文网络，Debug 另允许本地 API；这一网络例外不改变原生授权 URL 信任。当前 Kotlin、AGP、Gradle 和 JDK 组合应实际验证，不能把工具链声明直接当作可构建保证。

## 聊天与加密服务

| 相对路径 | 职责 |
| --- | --- |
| `chat-service/src/main.mjs` | 环境变量、生产启动条件、监听和信号退出 |
| `src/server.mjs` | HTTP 解析、授权、资源路由、长轮询、模型桥接与定时协调 |
| `src/database.mjs` | SQLite 表、启动迁移、事务、关系、消息、媒体、事件与设备会话 |
| `src/moments-repository.mjs` | 新事可见范围、互动、通知、媒体与孤立资源清理 |
| `src/call-repository.mjs`、`call-media.mjs` | 通话状态与参与者、媒体 token、房间和成员清理 |
| `src/apns-voip.mjs`、`voip-devices.mjs` | APNs 签名发送、设备与 session 关联；提供商接受不等于设备到达 |
| `src/city-location.mjs`、`city-stickers.mjs` | 可信来源与离线城市、白名单素材和媒体去重 |
| `src/memory-recognition.mjs` | 配置模型的结构生成与固定补充；请求文字会离开设备 |
| `src/e2ee-verifier.mjs`、`e2ee-delivery.mjs` | WASM 结构校验与设备密钥包、范围、密文、ack 状态 |
| `src/enterprise-*`、`src/enterprise/` | 共享后台的独立星企领域；不构成星线 App 个人前台功能 |
| `chat-crypto/src/`、`include/`、`scripts/` | Rust OpenMLS、C ABI、平台与 WASM 构建；状态快照与设备私钥由端侧保护 |

表中 `src/` 均相对 `chat-service/`。媒体 BLOB 与消息元数据存于同一 SQLite 数据集；数据库构造会迁移，不能为了检查 schema 随意用新服务打开真实旧库。恢复测试使用副本和配套密钥，见[故障手册](https://document.thestarline.cn/app/incident-runbooks.md)。

## Account 权威源与历史副本

Account 的当前 `server/config.ts`、`store.ts`、`notify.ts`、`captcha.ts`、`oidc.ts`、`admin-policy.ts` 与 `main.ts` 分别定义配置、MySQL／PII、投递、人机验证、协议、管理策略与启动。现行代码还包含资料、扫码／手机授权、小程序、实名与开放接口等模块；这些不能凭 App 历史副本的文件清单推断缺失。

目前可确认的差异有：主迁移为 001–007 并有 PII 加密审批；生产邮件为腾讯 SES、短信为阿里云；管理员通行密钥开关由环境精确值读取；开发注册也有 captcha 门禁。App 副本中的本地聊天客户端登记脚本在当前 Account 主仓库不存在，旧注册 fixture 也没有新的 captcha 请求字段。应先修订隔离夹具并验证，不能称为现成一键联调。记忆转出 redeem 契约在当前主源码缺失，不能用旧副本证明跨服务可用。

修改共享身份时，应在当前 Account 仓库执行其类型与测试检查；修改 App 侧协议时同时核对目标部署的实际契约。两个仓库的版本和授权是独立边界，文档发布不等于身份服务升级，文件拷贝也不是协议迁移方案。

## 修改入口与验证命令

| 修改类型 | 最少关联入口 | 进一步验证 |
| --- | --- | --- |
| 原生授权 | iOS `ChatNativeAuthTests`、Android `NativeAuthTest`、服务端 native-auth | 系统浏览器、取消、冷启动、401／断网与真实目标平台 |
| 发送与关系 | chat、group、management、media 测试；双端发送状态 | 丢响应重试、三账号拒绝、删除历史和双端已读 |
| 新事 | moments 测试与两端发布／媒体界面 | 可见范围、屏蔽、视频 Range、取消与孤立资源 |
| 本机记忆 | MemoryLocal／MemoryStore、MemoryTemplates／MedicalMemory | 损坏库、丢密钥、旧字段、多行、附件与重开 |
| 城市／位置 | city-location、city-stickers、live-location 及原生 resolver | 权限拒绝、缓存、换账号／会话、停止、前后台 |
| 通话 | calls、call-media、apns-voip、voip-devices | 两台真机音画、跨网、后台、锁屏与多设备 |

真实命令入口示例，本次未执行：

```sh
node --test chat-service/tests/native-auth.test.mjs
node --test chat-service/tests/group.test.mjs chat-service/tests/management.test.mjs
node --test chat-service/tests/memory.test.mjs chat-service/tests/moments.test.mjs
zsh ios-app/scripts/test-native-auth.sh
```

```sh
cd android-app
./gradlew :app:testDebugUnitTest --max-workers=1
```

```sh
cd identity
npm run typecheck
npm test
npm --prefix client run typecheck
```

最后一组必须在当前 Account 源码上下文执行。文档统一构建入口位于 `technical-docs/build.mjs`、`technical-docs/check.mjs`；App 的内容与导航继续从 `app-download/docs/` 读取，作为全产品文档站的一个产品目录。构建只处理公开静态资料，不运行产品后台。它们的通过只能说明文档产物，不能成为业务验收。完整模块×故障矩阵见[测试矩阵](https://document.thestarline.cn/app/qa-matrix.md)，配置与发行门禁见[配置参考](https://document.thestarline.cn/app/configuration-reference.md)和[发行清单](https://document.thestarline.cn/app/release-checklist.md)。


原始地址：https://document.thestarline.cn/app/development/
Markdown：https://document.thestarline.cn/app/development.md

# 本地开发与配置

本文说明星线 App 的源码入口、隔离开发环境和配置方法。App 与聊天命令默认从 App 仓库根目录执行；Account 命令必须进入其当前维护仓库，不能使用 App 工作树中同名的历史 `identity/` 副本。示例中的账号、口令和 `example.test` 域名均为合成测试值。配置依据 2026-10-23 当前源码整理，本次文档整理没有启动服务、模拟器或访问生产配置。

## 先理解组成

| 仓库路径 | 职责 | 开发入口 |
| --- | --- | --- |
| `ios-app/` | iPhone 原生界面、本机数据、系统浏览器登录 | Xcode 工程 `StarlineWorkbench.xcodeproj` |
| `android-app/` | Android Compose 界面、Keystore 和本机数据 | Gradle Wrapper |
| Account 当前仓库的 `identity/` | 账号、验证码、通行密钥、OIDC、管理权限、PII 保护 | Node.js / TypeScript / Fastify / MySQL；App 副本不是当前权威源 |
| Account 当前仓库的 `identity/client/` | Account 与管理站前端 | React / Vite |
| `chat-service/` | 聊天、新事、媒体、设备会话、通话信令 | Node.js / SQLite |
| `chat-crypto/` | OpenMLS 加密核心及跨端绑定 | Rust 与平台构建脚本 |
| `app-download/dist/` | 公开下载介绍页 | 静态 HTTP 服务 |

开发前先查看当前工作区差异。需要可丢弃环境时使用新的独立工作区，不把现有 App 私有目录、账号数据库、Keychain 或 Keystore 当作测试夹具。Account、聊天和 App 必须指向同一环境；本地签发的 ticket 不能提交给正式聊天服务。

## 工具与依赖

服务端的 `package.json` 要求 Node.js 24 或更新版本；身份服务使用 MySQL 8.4。Android 当前使用 Java 17、Android SDK 35，最低支持 Android 8.0（API 26）；构建应使用仓库自带 `gradlew`。iOS 工程使用 Swift 6、最低 iOS 17，需安装可用的 Xcode 与 XcodeGen。具体 Xcode、SDK 和签名兼容性以所选工具链实际构建结果为准，不由一次历史构建推断。

```sh
node --version
java -version
xcodebuild -version
```

未安装的目标平台可跳过对应工具检查。依赖使用锁文件安装；前三条在当前 Account 仓库执行，最后一条在 App 仓库执行：

```sh
npm --prefix identity ci
npm --prefix identity/client ci
npm --prefix identity/client run build
npm --prefix chat-service ci
```

## 隔离的账号与聊天联调

身份测试与本地 fixture 固定使用回环地址 `127.0.0.1:3310` 上的新建 `identity_dev` 数据库。可以在专用开发环境创建容器；下面的口令公开且只用于可丢弃的本地数据库，禁止用于公网：

```sh
docker run --name starline-identity-dev \
  -p 127.0.0.1:3310:3306 \
  -e MYSQL_DATABASE=identity_dev \
  -e MYSQL_USER=identity \
  -e MYSQL_PASSWORD=local-test-only \
  -e MYSQL_ROOT_PASSWORD=local-root-fixture-only \
  -d mysql:8.4
```

等待数据库就绪后，在当前 Account 的新建隔离工作区运行：

```sh
cd identity
node scripts/start-local-preview.mjs --local-fixtures
```

预览启动器先检查依赖、数据库和端口，已有健康服务会被复用；端口被其他异常服务占用时会退出。它持续运行账号后端与前端，不按展示时长关闭。此命令只证明启动流程，不提供当前注册、客户端登记和原生回跳的完整夹具。

当前注册即使在 development 也需要 captcha。保留的 `preview-fixture.mjs` 没有提交该参数，不能照旧当作可用的一键注册；它需要先按现行协议修订并验证。App 历史副本的 `create-chat-local-client.ts` 在当前 Account 主源码中不存在，也不能复制回共享服务冒充当前工具。隔离测试应使用 `env=test` 专用构造和合成依赖；需要浏览器联调时另行完成受控人机验证与客户端登记，精确登记本地 HTTPS／开发回调、scopes 和 confidential 类型，不使用生产客户端秘密。

聊天本地配置需由上述受控登记产生并保存在被忽略的受保护文件中；它不是本页启动命令自动生成的产物。取得匹配配置后才能继续：

另开终端，从仓库根目录执行：

```sh
cd chat-service
CHAT_DATABASE_PATH=./data/qa-chat.sqlite node --env-file=.env.local src/main.mjs
```

这里显式使用独立 SQLite 文件，避免接触已有预览数据。此服务前台持续运行，正常结束应发送终端中断，让服务关闭连接。账号页为 `http://localhost:9100`，前端开发入口为 `http://localhost:9101`，聊天健康检查为 `http://localhost:4210/health`。WebAuthn 本地 RP 使用 `localhost`，不要把 IP 页面和域名页面混为同一 RP。

## 连接原生 App

iOS 在 Xcode 的 Debug Run 环境中设置 `STARLINE_CHAT_BASE_URL=http://localhost:4210`。该覆盖仅在 Debug 生效，Release 忽略它；HTTP 仅允许本机回环主机。默认地址已经是正式聊天服务，旧资料中“模拟器默认连接 localhost”的表述不再适用。

```sh
cd ios-app
xcodegen generate
open StarlineWorkbench.xcodeproj
```

若缺少 `chat-crypto/dist/StarlineChatCrypto.xcframework`，先按工具链准备 Rust iOS 目标，再从仓库根目录执行 `bash chat-crypto/scripts/build-apple.sh`。该脚本构建原生库，并不证明聊天界面已启用端到端加密。

Android 模拟器对本机聊天 API 做隔离联调时可显式构建：

```sh
cd android-app
./gradlew :app:assembleDebug \
  -PstarlineChatBaseUrl=http://10.0.2.2:4210 \
  --max-workers=1
```

`10.0.2.2` 是 Android 模拟器的宿主机别名，不能直接用于实体手机。上述覆盖和端口反向转发只解决普通 API 的网络可达性，不能直接完成隔离 Account 的原生登录。当前 Android `NativeAuth.kt` 仅信任正式 `https://account.thestarline.cn` 授权目的地，没有 Debug localhost 例外；本地聊天服务返回本地 Account 授权 URL 时，客户端会拒绝打开。完整隔离原生登录需要另行设计并实现受控测试信任配置，再单独验收，目前没有现成的完整流程。不要放宽正式构建的信任范围，或把模拟器地址写入公开发行包。安装到已有预览设备前先确认签名兼容，不卸载、不清空数据。

## 配置变量目录

配置值应由本地受保护文件或部署系统注入，公开文档只说明名字与用途。生产模式包含固定批准域名、HTTPS 和密钥强度约束，`https://account.example.test/oidc` 这样的合成值仅用于测试构造，不能直接作为生产配置运行。

| 分组 | 变量名 | 用途与边界 |
| --- | --- | --- |
| 身份基础 | `NODE_ENV`、`IDENTITY_HOST`、`IDENTITY_PORT`、`IDENTITY_DATABASE_URL`、`IDENTITY_DB_PREFIX` | 模式、监听和数据库命名空间 |
| 身份安全 | `IDENTITY_SECRET`、`IDENTITY_PII_KEY`、`IDENTITY_PII_MIGRATION_APPROVED`、`IDENTITY_ORIGINS`、`IDENTITY_TRUST_PROXY`、`IDENTITY_OIDC_JWKS_FILE` | 稳定加密材料、PII 迁移审批、精确来源与可信代理 |
| 身份站点 | `IDENTITY_ACCOUNT_ORIGIN`、`IDENTITY_OPEN_ORIGIN`、`IDENTITY_WEBAUTHN_RP_ID` | 页面来源与通行密钥 RP |
| 邮件投递 | `IDENTITY_DELIVERY`、`TENCENT_SES_SECRET_ID`、`TENCENT_SES_SECRET_KEY`、`TENCENT_SES_TEMPLATE_ID` | 当前生产仅使用腾讯 SES；生产禁用开发投递 |
| 非生产邮件备用 | `SMTP_HOST`、`SMTP_PORT`、`SMTP_SECURE`、`SMTP_USER`、`SMTP_PASSWORD`、`SMTP_FROM`、`SMTP_LOCAL_SINK` | 当前 SMTP 不作为生产回退，本地 sink 仅允许非生产回环 |
| 短信 | `ALIBABA_CLOUD_ACCESS_KEY_ID`、`ALIBABA_CLOUD_ACCESS_KEY_SECRET`、`ALIYUN_SMS_SIGN_NAME`、`ALIYUN_SMS_TEMPLATE_CODE` | 当前阿里云短信配置；旧腾讯短信变量不再适用 |
| 人机验证 | `TENCENT_CAPTCHA_APP_ID`、`TENCENT_CAPTCHA_APP_SECRET`、`TENCENT_CAPTCHA_SECRET_ID`、`TENCENT_CAPTCHA_SECRET_KEY` | 开发注册也受门禁，缺配置不模拟通过 |
| 聊天 | `CHAT_HOST`、`CHAT_PORT`、`CHAT_DATABASE_PATH`、`CHAT_ISSUER_URL`、`CHAT_PUBLIC_URL`、`CHAT_CLIENT_ID`、`CHAT_CLIENT_SECRET` | 存储与 confidential OIDC 客户端 |
| 可选服务 | `CHAT_PROFILE_ENCRYPTION_KEY`、`CHAT_CRYPTO_NODE_BUNDLE`、`CHAT_TRUST_PROXY_ALLOWLIST`、`CHAT_IP_CITY_DATABASE_DIR`、`CHAT_MEMORY_MODEL_URL`、`CHAT_MEMORY_MODEL` | 资料加密、MLS 校验、城市与自建模型 |
| 媒体与推送 | `LIVEKIT_URL`、`LIVEKIT_API_KEY`、`LIVEKIT_API_SECRET`、`APNS_TEAM_ID`、`APNS_KEY_ID`、`APNS_KEY_PATH`、`APNS_VOIP_TOPIC`、`APNS_ENVIRONMENT` | 通话媒体与 APNs；密钥留在服务端 |

第三方身份变量还有 `WECHAT_APP_ID`、`WECHAT_APP_SECRET`、`QQ_APP_ID`、`QQ_APP_SECRET`、`ALIPAY_APP_ID`、`ALIPAY_PRIVATE_KEY`、`ALIPAY_PUBLIC_KEY`。配置存在只说明适配器具备材料，不能代替平台开通与真实回调验收。当前管理通行密钥策略由 `IDENTITY_ADMIN_PASSKEY_REQUIRED` 精确值控制，不再是旧副本的生产硬编码；小程序、实名与 PII 的附加条件见[完整配置参考](https://document.thestarline.cn/app/configuration-reference.md)。验证方法见[测试与验收](https://document.thestarline.cn/app/testing.md)，生产处理见[运行维护](https://document.thestarline.cn/app/operations.md)。


原始地址：https://document.thestarline.cn/app/configuration/
Markdown：https://document.thestarline.cn/app/configuration.md

# 环境、配置与兼容性

星线 App、聊天服务与 Account 必须使用匹配环境。本页解释配置契约与变更影响；变量明细及本地命令见[开发配置](https://document.thestarline.cn/app/development.md)，生产变更步骤见[运维](https://document.thestarline.cn/app/operations.md)。公开资料不包含任何实际密钥或私有配置文件。

## 环境一致性

| 环节 | 需要匹配的内容 | 配错的表现 |
| --- | --- | --- |
| App → 聊天服务 | API 基地址、HTTPS、回跳 scheme、客户端 state | 登录回到错误 App、换票失败、会话不能恢复 |
| 聊天服务 → Account | issuer、client ID、机密凭据、回调地址和授权范围 | 授权端拒绝、token 交换失败或用户信息不可读 |
| Account 浏览器 | 来源、Cookie、RP ID、可信代理 | 会话丢失、通行密钥失败、Host 或来源被拒绝 |
| 通话 | LiveKit 地址、签发配置与设备网络 | 信令已接收但房间或媒体不可用 |
| 城市、识别、推送 | 城市数据库、模型、APNs 与对应平台配置 | 相关功能受限，而非整个服务必然失败 |

开发环境的 localhost、Android 模拟器宿主别名与真机网络地址各有用途。Release 包应核对真正的服务器地址和回调配置，不能把调试覆盖或本地 fixture 配置带入分发产物。

## 原生端配置

iOS 的 `STARLINE_CHAT_BASE_URL` 仅用于 Debug 覆盖；HTTP 仅允许回环。默认聊天地址为 `https://chat.thestarline.cn`。最低系统为 iOS 17，Swift 语言版本为 6；当前工程以 iPhone 为设备家族，iPad 与 watchOS 不能由此自动推断已交付。

Android 的 `starlineChatBaseUrl` 是构建属性，默认同样指向正式聊天服务。原生授权地址校验只信任正式 Account HTTPS 来源，没有 Debug localhost 例外；仅覆盖聊天基地址不能完成隔离 Account 原生登录。最低 API 26，目标/编译 API 35，Java 17。当前仓库声明 AGP 8.7.3 和 Gradle Wrapper 9.2.1；这一组合需要在所选环境实际验证兼容性，本技术文档没有执行新的原生构建。构建成功还需要继续检查签名、manifest、实际 API 地址和真机行为。

## 服务启动和可选能力

聊天服务要求 Node.js 24 或以上，使用内置 SQLite；Account 使用独立 MySQL。聊天数据库、身份数据库、静态文档内容和设备本地数据不是同一数据集。服务的健康 HTTP 响应不自动覆盖外部身份、模型、媒体或推送依赖。

`CHAT_CRYPTO_NODE_BUNDLE` 指向 MLS 验证器产物；配置该产物不会自动切换所有客户端的主消息路径。`CHAT_MEMORY_MODEL_URL` 与模型名称配置影响服务器识别适配器，而不是启用记忆云同步。APNs 和 LiveKit 的可用性既受配置影响，也受证书、网络、设备和平台状态影响。

`CHAT_PROFILE_ENCRYPTION_KEY` 等持久密钥与既有资料有关。轮换前需分析解密、索引、会话和回滚影响，不能把随意重建配置当作故障修复。客户端只保存必要会话材料，服务端机密凭据不得放入 App 包、下载脚本或公开文档。

## 配置变更的检查顺序

1. 识别变更归属：设备、聊天、Account、媒体、推送或静态站。
2. 核对当前运行基线与目标版本，保留可恢复的配置和数据，不回显实际值。
3. 在隔离环境验证格式与依赖；测试只使用合成账号和合成数据。
4. 对原生包重新构建并核对产物；对服务执行对应配置、迁移和健康检查。
5. 运行真实路径：授权回跳、换票、会话恢复及受到影响的业务步骤。
6. 记录已验证范围、未覆盖设备和待办，不把一个检查结果推广为全部能力通过。

## 文档站的配置

技术文档由 Markdown 生成静态文件，没有服务端账号、数据库或访问令牌。站点基本地址固定为 `https://app.thestarline.cn`，构建时同步生成 canonical、站点地图和索引文件。部署只需要静态产物以及正确的 Markdown MIME；不需开放 Account 或聊天权限。构建说明保存在文档源目录的维护指南，公开抓取规则见[文档访问与引用](https://document.thestarline.cn/app/ai-access.md)。


原始地址：https://document.thestarline.cn/app/configuration-reference/
Markdown：https://document.thestarline.cn/app/configuration-reference.md

# 配置变量与启动校验参考

本页从配置加载器、服务入口、构建文件和适配器提取变量名、默认行为与失败条件，不使用环境文件中的实际值。Account 以其当前维护的主源码为准；App 独立工作树中的 `identity/` 是历史副本，不能作为现行生产配置模板。以下描述是源码契约，不是运行配置或业务可用性的回读结果。环境选择见[开发配置](https://document.thestarline.cn/app/development.md)，维护流程见[故障处理手册](https://document.thestarline.cn/app/incident-runbooks.md)。

## 配置的读取顺序与分类

Account 的 `npm start`、`dev`、`migrate` 会通过 Node 的环境文件参数加载配置；生产构建入口直接读取进程环境，Compose 还会增加容器环境和变量插值。聊天 `npm start` 本身不会自动加载本地配置文件，需由启动器或 Node 参数注入。对同名值应核对最终进程环境的来源，不能只看到某份文件就认定容器已使用它。检查时报告变量是否存在、格式是否合法、来源与版本，避免回显实际值。

| 分类 | 例子 | 处理方式 |
| --- | --- | --- |
| 服务端秘密 | 身份主密钥、PII 密钥、客户端 secret、云服务 secret、签名私钥 | 受保护系统注入；不进入仓库、App 包、日志或文档 |
| 稳定加密依赖 | `IDENTITY_SECRET`、`IDENTITY_PII_KEY`、`CHAT_PROFILE_ENCRYPTION_KEY` | 与数据版本一起备份；轮换前设计迁移，不能随意重建 |
| 标识与策略 | issuer、origin、client ID、topic、模板 ID、开关 | 不一定是秘密，仍需核对环境与变更影响 |
| 本机开发配置 | API 端口、Debug 地址、测试命名空间 | 仅用于隔离环境，不能冒充生产回执 |

本页用“未设置”描述没有默认值；不是建议将变量设置为空字符串。Account 多数变量用 `||` 取默认值，聊天多数使用 `??`，因此聊天的空字符串通常不会回退到默认值。所有布尔开关只有源码指定的精确字符串才启用，`1`、`TRUE` 与 `true` 不能随意互换。

## Account 基础与持久化

| 变量 | 默认或格式 | 必填条件与影响 |
| --- | --- | --- |
| `NODE_ENV` | 仅精确 `production` 进入生产分支，其他为 development | 必须显式核对模式，不能靠目录名称判断 |
| `IDENTITY_HOST` / `IDENTITY_PORT` | 本机 IPv4 回环 / `9100` | 容器通常由运行配置覆盖；端口转为 Number |
| `IDENTITY_DATABASE_URL` | 未设置 | 所有正常服务入口必需；指向 MySQL |
| `IDENTITY_DB_PREFIX` | 空前缀 | 仅字母、数字、下划线；改变它会切换表命名空间 |
| `IDENTITY_SECRET` | 空值，启动校验要求至少 32 字符 | 生产拒绝公开示例标记；保护协议材料与 HMAC |
| `IDENTITY_PII_KEY` | 64 位十六进制，解码后 32 字节 | 生产必需；已加密数据库在任何模式下均需匹配原密钥 |
| `IDENTITY_PII_MIGRATION_APPROVED` | 仅精确 `1` 表示已批准 | 有旧联系方式、flow 或 challenge 数据时，迁移前需验证备份并明确批准 |
| `IDENTITY_AUDIT_RETENTION_DAYS` | `180` | 供清理策略读取；修改前核对保留要求与实际清理任务 |
| `IDENTITY_RATE_LIMIT` | `20`，正安全整数 | 与固定 600 秒窗口配合；不是各业务独立限额的统一替代 |
| `IDENTITY_BOOTSTRAP_EMAIL` | 未设置 | 仅首次管理员初始化脚本读取；不是持续服务的登录凭据 |
| `IDENTITY_DB_PASSWORD` / `IDENTITY_DB_ROOT_PASSWORD` | 当前 Compose 必需的插值变量 | 分别用于应用数据库用户和数据库 root 初始化；属于秘密，不能以示例口令部署 |
| `IDENTITY_BIND_PORT` | 当前 Compose 默认 `9100` | 只改宿主映射，不改变容器内服务端口；不是 `IDENTITY_PORT` 的同义项 |

`PiiProtector.fromHex` 拒绝错误长度或非十六进制密钥。数据库保存密钥检查标记，缺密钥、错误密钥或迁移后残留不一致都会拒绝继续。当前迁移顺序为 `001.sql` 至 `007.sql`，随后执行 PII 与补列处理。迁移审批开关只表示维护流程已满足前置条件，不会替维护者自动备份，也不是修复错误密钥的方法。

## 来源、管理与协议

| 变量 | 默认行为 | 启动或运行约束 |
| --- | --- | --- |
| `IDENTITY_ORIGINS` | 开发允许本机 9100、9101 的两种回环来源；生产无默认列表 | 至少一个精确 origin；不得带路径；生产只允许批准的 Account 与管理站 HTTPS 主机 |
| `IDENTITY_ACCOUNT_ORIGIN` / `IDENTITY_OPEN_ORIGIN` | 开发为 localhost 的 9100 / 9101；生产为各自正式 HTTPS 来源 | 决定页面、协议及来源判断，需与代理和客户端一致 |
| `IDENTITY_WEBAUTHN_RP_ID` | 开发 `localhost`，生产为正式 Account 主机 | RP 与 origin 是不同字段，已有通行密钥不能任意迁移到其他 RP |
| `IDENTITY_TRUST_PROXY` | `false` | 逗号分隔的明确可信代理；拒绝 `*`，不能复制其他网络的配置 |
| `IDENTITY_OIDC_JWKS_FILE` | 开发可生成并加密持久化签名材料 | 生产必需稳定私有 JWKS；RSA、RS256、use=sig、kid，私钥至少 2048 位 |
| `IDENTITY_ADMIN_PASSKEY_REQUIRED` | 仅精确 `true` 启用 | 当前主源码不再硬编码生产必为 true；管理授权仍需按当前策略与服务端角色检查 |
| `IDENTITY_REAL_NAME_ENABLED` | 仅精确 `true` 启用 | 启用时要求可用 PII 保护器；开关不代表外部实名能力已验收 |
| `IDENTITY_DEV_API_PORT` | `9100` | 仅 Vite 开发代理使用，不改变生产服务监听端口 |
| `IDENTITY_PREVIEW_URL` | fixture 脚本默认本机 9100 HTTP | 仅该旧预览脚本读取；限制本机、非生产，不解决当前 captcha 契约差异 |

Account 会话 28800 秒、OTP 300 秒、验证事务 1800 秒、OTP 尝试 5 次、重发间隔 60 秒是当前加载器中的固定配置值，不能凭这些字段名推导存在对应环境变量。公开资料中的角色与通行密钥建议属于运维要求，实际可接受的认证方法需依据现行 `admin-policy.ts` 和目标会话验证。

## 验证码、人机验证与第三方身份

| 变量 | 默认及启用条件 | 缺失时的行为 |
| --- | --- | --- |
| `IDENTITY_DELIVERY` | 精确 `development` 选择开发投递，其余选择真实适配器 | 生产禁止开发适配器；真实配置缺失不模拟投递成功 |
| `TENCENT_SES_SECRET_ID` / `TENCENT_SES_SECRET_KEY` / `TENCENT_SES_TEMPLATE_ID` | 三项齐全，模板 ID 为正安全整数 | 当前生产邮件只接受此 SES 路径；SMTP 不作为生产回退 |
| `ALIBABA_CLOUD_ACCESS_KEY_ID` / `ALIBABA_CLOUD_ACCESS_KEY_SECRET` / `ALIYUN_SMS_SIGN_NAME` / `ALIYUN_SMS_TEMPLATE_CODE` | 四项齐全启用阿里云短信 | 无可用适配器时返回投递不可用；当前发送校验中国大陆手机号与六位验证码 |
| `SMTP_HOST` / `SMTP_FROM` / `SMTP_USER` / `SMTP_PASSWORD` | 常规 SMTP 要求四项；仅供非生产备用 | 即使四项齐全，生产邮件也不会使用 SMTP |
| `SMTP_PORT` / `SMTP_SECURE` | 普通端口默认 465；非精确 `false` 时 secure=true | 保持 TLS 验证；选择其他端口时要同时核对 TLS 模式 |
| `SMTP_LOCAL_SINK` | 精确 `true`；端口默认 9125，无认证和 TLS | 仅非生产回环；生产或外部主机直接拒绝 |
| `TENCENT_CAPTCHA_APP_ID` | 正整数形式、5–16 位十进制且为安全整数 | 公开配置返回 null 或验证不可用 |
| `TENCENT_CAPTCHA_APP_SECRET` / `TENCENT_CAPTCHA_SECRET_ID` / `TENCENT_CAPTCHA_SECRET_KEY` | 与有效 App ID 四项齐全 | 注册等受保护入口返回 CAPTCHA_UNAVAILABLE；不能靠开发投递绕过 |
| `WECHAT_APP_ID` / `WECHAT_APP_SECRET`、`QQ_APP_ID` / `QQ_APP_SECRET` | 各提供商成对配置 | configured 与后台启用、平台开通、真实回调是不同状态 |
| `ALIPAY_APP_ID` / `ALIPAY_PRIVATE_KEY` / `ALIPAY_PUBLIC_KEY` | 应用 ID、RSA2 私钥与平台公钥 | 不完整时不能据此启用支付宝身份验证 |

当前 SES 模板参数为带三位分组显示的验证码，发件地址由适配器代码固定，不由 `SMTP_FROM` 控制。旧副本中的 `TENCENT_SMS_*` 不是现行主源码的短信配置。当前开发注册同样有人机验证门禁；仅 `env=test` 的测试构造允许专用注入或隔离跳过，正常服务没有通用免验证开关。

微信小程序还有 `WECHAT_MINI_APP_ID`、`WECHAT_MINI_APP_SECRET`，以及 `IDENTITY_WECHAT_MINI_ENABLED`、`IDENTITY_WECHAT_MINI_PUBLISHED`、`IDENTITY_WECHAT_MINI_LAUNCH_ENABLED`、`IDENTITY_WECHAT_MINI_VERIFICATION_ENABLED` 四个精确 `true` 开关。配置完成、预览验证、正式 URL Link 与公开入口分别检查；小程序 ID 还不能与网页微信提供商 ID 混用。配置中的 published 不等于官方发布回执，当前暂停要求不因改配置而自动解除。

## 聊天、媒体与可选依赖

| 变量 | 默认与校验 | 所属能力 |
| --- | --- | --- |
| `CHAT_HOST` / `CHAT_PORT` / `CHAT_DATABASE_PATH` | 本机回环 / 4210 / `./data/chat.sqlite` | 路径相对工作目录；确认持久卷映射，避免误建空库 |
| `CHAT_ISSUER_URL` / `CHAT_PUBLIC_URL` | 未设置；生产要求批准的正式 issuer 与 HTTPS public URL | OIDC discovery、授权回调与站点身份 |
| `CHAT_CLIENT_ID` / `CHAT_CLIENT_SECRET` | 未设置；生产要求存在，secret 至少 24 字符 | confidential 客户端；不放入原生 App |
| `CHAT_PROFILE_ENCRYPTION_KEY` | 未设置则使用客户端 secret 作为派生输入 | 资料联系电话加密；轮换可能影响旧数据解密 |
| `CHAT_CRYPTO_NODE_BUNDLE` | 未设置则校验器为 null | 设置时要求导出两个 MLS 校验函数，错误文件会导致启动异常 |
| `CHAT_TRUST_PROXY_ALLOWLIST` | 无可信代理；逗号分隔并去空白 | 仅合法地址或 CIDR；IP 城市不信任任意转发头 |
| `CHAT_IP_CITY_DATABASE_DIR` | 仓库固定城市库目录 | 需匹配版本与摘要；缺库、坏库返回空城市，不制造位置 |
| `CHAT_MEMORY_MODEL_URL` / `CHAT_MEMORY_MODEL` | 非生产默认本机 11434 HTTP 与 `qwen2.5vl:7b`；生产未设置 | 识别接口；请求文字发送给配置模型，不形成云同步 |
| `LIVEKIT_URL` / `LIVEKIT_API_KEY` / `LIVEKIT_API_SECRET` | 未设置 | 通话媒体必需；健康接口不验证这三项是否真实可用 |
| `APNS_TEAM_ID` / `APNS_KEY_ID` / `APNS_KEY_PATH` / `APNS_VOIP_TOPIC` | 未设置；四项齐全才可发送 | 配置路径读取失败或私钥格式错误可在启动时报错 |
| `APNS_ENVIRONMENT` | 精确 `sandbox` 才走测试 APNs，其余走生产 | 与 App 签名环境匹配，不能以默认值推断配置正确 |

`cityStickerDirectory`、媒体房间清理间隔和 APNs 测试 origin 是测试构造参数，并没有同名环境变量入口。聊天设备 session 默认 24 小时也没有公开环境变量或 refresh 路由。完整约束见[限制与错误](https://document.thestarline.cn/app/limits-and-errors.md)。

## 原生构建差异与核对方法

iOS `STARLINE_CHAT_BASE_URL` 仅 Debug 读取，接受 HTTPS 或 HTTP 回环，拒绝用户名密码、查询与 fragment；Release 忽略覆盖。iOS 工程的 `APNS_ENVIRONMENT` 在 Debug 为 development、Release 为 production，服务端测试环境字符串却是 sandbox，二者不得直接照抄。Android `starlineChatBaseUrl` 编译为 `BuildConfig.CHAT_BASE_URL`，Debug 允许本地明文 API，Release 清单禁止；`NativeAuth.kt` 两种构建均只信任正式 Account HTTPS，没有本地授权例外。`ANDROID_HOME`、`JAVA_HOME`、`ANDROID_NDK_HOME`、`CARGO` 是工具链定位配置，不能当作产品服务变量。文档生成器的 `STARLINE_DOCS_NODE_MODULES` 仅增加 Markdown 构建依赖的查找位置，不影响 App、Account 或聊天运行配置。

只查代码中的声明可使用：

```sh
rg -n 'env\.[A-Z_]+|process\.env' identity/server identity/client/vite.config.ts
rg -n 'environment\.[A-Z_]+|production' chat-service/src/main.mjs
rg -n 'STARLINE_CHAT_BASE_URL|#if DEBUG' ios-app/Sources/Features/Chat/ChatAPI.swift
rg -n 'gradleProperty|versionName|versionCode' android-app/app/build.gradle.kts
```

第一条应在 Account 当前源码仓库执行，其余在 App 仓库执行。不要把搜索范围扩展到环境文件、运行目录或秘密材料。变更结果按[测试矩阵](https://document.thestarline.cn/app/qa-matrix.md)验证，再按[发行清单](https://document.thestarline.cn/app/release-checklist.md)记录实际交付阶段。


原始地址：https://document.thestarline.cn/app/testing/
Markdown：https://document.thestarline.cn/app/testing.md

# 测试、隔离与验收边界

本文给出仓库实际存在的测试入口，说明各层测试能够证明什么，以及如何保护本机数据。命令供维护者在具备条件的隔离环境执行；本次文档编写没有重跑产品测试。文中历史数量仅指相应日期的保存记录，不能作为当前版本、线上部署或所有设备均可用的保证。

## 选择最小有效范围

修改账号协议时优先运行协议与原生登录测试；修改记忆模板时运行本机解析、加密存储和相应界面流程；修改下载站时核对真实浏览器视口、键盘操作和下载配置。不要仅因某个聚焦测试通过就扩大结论，也不要为只读文档更新启动整套模拟器。版本和交付边界见[版本与分发状态](https://document.thestarline.cn/app/releases.md)。

| 层级 | 主要覆盖 | 不包含的结论 |
| --- | --- | --- |
| 静态检查与编译 | 类型、语法、依赖、资源打包 | 真实登录、投递和可用界面 |
| 单元与本地集成 | PKCE、状态机、权限、持久化、错误恢复 | 公网平台配置与跨网络表现 |
| 模拟器 UI | 元素位置、流程、键盘、无障碍树 | 实体相机、蜂窝网络、正式推送 |
| 授权真机验收 | 目标设备上的完整真实流程 | 未测系统版本、其他平台和永久稳定性 |
| 商店与生产回执 | 上传、提审、审核、发布各自状态 | 未在回执中确认的后续步骤 |

## 服务端测试

身份服务测试必须在 Account 当前维护仓库执行，App 工作树的 `identity/` 副本存在历史漂移。MySQL 集成测试使用固定的独立开发库：回环端口 `3310`、库名 `identity_dev`，随机生成 `t` 加 12 位十六进制与下划线的表前缀，结束时只删除该命名空间；不要把它改指生产库或现有业务库。非生产 SMTP 适配器测试另需 Mailpit 端口 `9125`、API `9135`。这只验证备用适配器，不代表当前生产 SES 邮件或阿里云短信已经送达。

```sh
cd identity
npm test
npm run typecheck
npm run build
npm --prefix client test
npm --prefix client run typecheck
npm --prefix client run build
```

`npm test` 实际调用单并发的 `tests/*.test.ts`。当前主源码还应覆盖 PII 加密／旧数据审批／错误密钥拒绝、captcha、手机号与邮件投递、管理策略、资料和手机授权等新增模块，不能只运行旧副本的文件集合。`tests/pii.test.ts` 用合成数据验证迁移；`tests/captcha.test.ts` 验证专用依赖注入，正常开发服务不提供同等绕过开关。旧注册 fixture 缺少 captcha，主仓库也没有 App 副本的本地聊天登记脚本，不能作为现成浏览器端到端前置条件。

协议测试包含软件认证器产生的真实密码学证明，但软件认证器是隔离 fixture，不是物理通行密钥验收。前端测试使用 DOM 测试环境，仍需浏览器核对表单、焦点、系统确认框和实际回调。依赖安装与构建可能访问包源，应在受控开发环境执行。详细场景、断网与双端期望见[测试矩阵](https://document.thestarline.cn/app/qa-matrix.md)。

聊天服务测试以 Node 测试运行器执行，测试自行构造合成用户、临时 SQLite 和本机 HTTP 监听。原生登录测试用合成身份响应覆盖进程重建、state、PKCE、单次票据和失败边界，不会完成真实 Account 登录。

```sh
cd chat-service
node --test tests/native-auth.test.mjs
node --test tests/city-location.test.mjs tests/city-stickers.test.mjs
node --test tests/enterprise-onboarding.test.mjs tests/enterprise.test.mjs tests/enterprise-auth.test.mjs
npm test
```

最后一条是完整聊天回归；只在变更影响范围与可用资源需要时执行。服务端状态、权限、APNs 请求格式测试通过，仍不能证明真实通知到达或两端实际接通。

## iOS 原生测试

无需启动 iOS 模拟器的登录聚焦检查入口是：

```sh
zsh ios-app/scripts/test-native-auth.sh
```

该脚本将实际授权、API、Keychain 和模型源文件复制到临时 Swift 包，单并发运行 `ChatNativeAuthTests`，结束删除临时包。测试覆盖随机 verifier、RFC 7636 向量、可信目的地、持久化失败、独立 Keychain 恢复、冷回调、取消、过期、重放、并发、迟到响应和网络重试。它不是完整 iOS 应用构建。

需要界面验证时，先创建专用 QA 模拟器并把 `QA_SIMULATOR_UDID` 设为它的标识，再串行运行指定用例：

```sh
xcodebuild -project ios-app/StarlineWorkbench.xcodeproj \
  -scheme StarlineWorkbench \
  -destination "platform=iOS Simulator,id=$QA_SIMULATOR_UDID" \
  -parallel-testing-enabled NO \
  -only-testing:StarlineWorkbenchUITests/NavigationUITests/testSignedOutProfileOpensAccountWebsiteDirectly \
  test
```

该用例核对系统“继续”提示和正式 Account 登录表单。不得把出现表单写成“真实账号已登录”。完整验收还需用户在真实表单完成身份验证、授权后回到 App、重开恢复、取消保留原会话，并核对 iPhone 与审核所涉 iPad。安装前不卸载已有 App，不清除 Keychain 或记忆。

## Android 测试

以下任务不要求启动设备，适合先验证 JVM 状态机和 APK 打包。资源受限环境可使用单 worker、限制堆与 Kotlin 进程内编译：

```sh
cd android-app
./gradlew :app:testDebugUnitTest :app:assembleDebug :app:assembleDebugAndroidTest \
  --max-workers=1 \
  -Dorg.gradle.jvmargs=-Xmx1g \
  -Pkotlin.compiler.execution.strategy=in-process
```

`NativeAuthTest` 覆盖 PKCE、state、过期、取消、事务替换与退出竞态。必须核对构建使用的 `starlineChatBaseUrl`，因为默认地址是正式聊天服务。需要隔离网络时采用[本地开发](https://document.thestarline.cn/app/development.md)中的显式覆盖。

设备测试只在已选定且允许使用的 QA 设备上运行，避免同时连接多台导致误选：

```sh
./gradlew :app:connectedDebugAndroidTest \
  -Pandroid.testInstrumentationRunnerArguments.class=cn.thestarline.workbench.NativeAuthSessionTest \
  --max-workers=1 \
  -Dorg.gradle.jvmargs=-Xmx1g \
  -Pkotlin.compiler.execution.strategy=in-process
```

该测试类使用独立文件、缓存、设置命名空间和设备回环 HTTP fixture，覆盖加密 pending、会话恢复、401 清理、503 保留与退出后的迟到结果。设备测试重建 AppState 的证明范围与系统真正杀进程后的回跳不同，后者要保留独立的端到端记录。

## 医疗健康、本机数据与视觉验收

保存记录 `docs/qa-memory-medical-health-2026-10-21.md` 描述了双端医疗模板的历史验收：八项可选字段、两段各 2000 字多行内容、搜索、编辑、附件、重开读取和删除合成记录。iOS 当时记录 37 项本机测试以及原生 UI 流程；Android 当时记录 69 项单元测试与两项设备流程。这些数量属于特定快照，本次没有复跑，也未覆盖全部 OS、实体设备、全部字号或跨设备同步。

新测试只创建自己的合成记录，不读取真实用户记忆正文、token 或验证码。对数据保护的比较可以核对密文哈希与文件数量，不把密文或 Keychain 内容复制到公开报告。视觉验收应检查窄屏、长字段、键盘、大字号、保存按钮、底栏与弹窗位置；图标采用统一 SVG 尺寸、线宽和颜色，不用装饰 Emoji 替代。预览持续展示，不设置自动关闭时限。

## 如何记录结果

每次写清提交或工作区基线、命令、目标设备与系统、环境、退出码、失败数、产物位置和未测范围。出现失败保留首个有效错误与日志，修复后重跑相关用例；不要删掉失败记录，只保留成功截图。历史 Android 生产记录已经证明一次真实账号授权自动返回与 force-stop 后冷启动恢复，设备会话为 24 小时；它不代表连续运行 24 小时或永久登录。iOS 完整真实账户闭环、正式分发、推送与跨网通话仍分别待验收。故障分层方法见[故障定位](https://document.thestarline.cn/app/troubleshooting.md)。


原始地址：https://document.thestarline.cn/app/qa-matrix/
Markdown：https://document.thestarline.cn/app/qa-matrix.md

# 分层测试与双端验收矩阵

本页将源码检查、自动测试、界面验证、真实设备与生产验收分开。矩阵中的“期望”是测试断言或必须满足的产品边界，不表示本轮已经运行。历史记录按其日期和目标保留；所有新增执行都应记录当前基线、设备、环境、命令、结果与剩余范围。基础命令见[测试](https://document.thestarline.cn/app/testing.md)，模块入口见[模块地图](https://document.thestarline.cn/app/module-map.md)。

## 环境与证据约定

每个场景至少记录 App 平台、构建、OS、网络、Account／聊天环境、合成账号代号和前置关系。正常、拒绝、断网与重启不能混为同一用例。一次失败若发生在环境准备阶段，应记为“前置条件未满足”，不能删掉或改成测试跳过后再宣称功能通过。

| 证据层 | 能确认 | 不能替代 |
| --- | --- | --- |
| 源码与配置 | 路由、类型、校验、状态机、默认值 | 实际运行配置与业务结果 |
| 单元／本地集成 | 可重复的输入、状态和权限断言 | 真实平台回调与公网服务 |
| 系统 UI 测试 | 指定设备的元素、焦点和操作路径 | 其他屏幕、OS、硬件和商店环境 |
| 授权真机闭环 | 指定账号、设备与网络的实际结果 | 永久登录、所有地区或所有用户 |
| 正式回执 | 上传、提审、审核与发布的各自阶段 | 未记录的后续动作 |

Account 自动测试使用专用 `identity_dev` MySQL 与随机表前缀；聊天测试使用内存库或临时 SQLite；原生设备测试使用自己的文件和设置命名空间。禁止把生产 token、真实记忆、私人聊天或现有设备数据作为通用夹具。测试前后可核对密文数量和摘要，不读取正文证明“没有修改”。

## 登录与设备会话

| 场景 | 正常与拒绝 | 断网／重启及双端期望 | 验证方法 |
| --- | --- | --- | --- |
| 发起原生授权 | 随机 verifier、S256、保存 pending 后才开浏览器；错 URL 或存储失败拒绝打开 | 连点只创建当前事务；退出后的迟到响应不重新登录 | iOS `ChatNativeAuthTests`、Android `NativeAuthTest`、服务端 native-auth 测试 |
| state 与 ticket | 正确 proof 单次换票；缺失、错误、重复、取消、过期均不替换原有效账号 | 回调不能从另一环境或设备拼接；重放不产生第二个 session | 服务端验证与两端隔离状态机断言 |
| 网页到 App | 系统浏览器显示正确 Account、用户完成授权、自动回 App | 真正替换进程后回跳；需保存完整阶段与设备时间线 | 授权真机人工闭环；iOS 系统“继续”提示单独观察 |
| 会话恢复 | `/me` 成功恢复资料；401 清理当前凭据 | 503、超时和临时离线保留凭据；恢复网络后重试 | Android `NativeAuthSessionTest`；iOS 授权与 Keychain 测试，加真机恢复 |
| 退出竞态 | 本机退出并停止轮询、通话和待处理授权 | 服务端退出失败不能显示为已撤销全部会话；旧请求不能回写新账号 | 测试迟到响应、同机账号切换及离线退出 |

iOS 会保存待换票 ticket 与 API 来源，Android pending 没有相同字段，不能把 iOS 的“换票时中断可重试”结论直接套用 Android。Android 当前没有 Debug 本地 Account 信任例外，隔离普通 API 可测，隔离浏览器原生登录仍需受控测试配置。聊天会话 24 小时，无 refresh-token 路由；不得用修改系统时钟或共享真实 token 代替可控时钟测试。

## 联系人、消息与在线状态

| 模块与场景 | 正常期望 | 拒绝／断网／重启／双端期望 | 验证入口 |
| --- | --- | --- | --- |
| 好友申请 | 唯一好友 ID 或当前临时码发申请，对方同意后可私聊 | 自己、未知、过期码、限流与屏蔽拒绝；重开后关系仍一致 | `chat.test.mjs`、`management.test.mjs`，两合成账号与第三观察账号 |
| 群成员 | 群主邀请、改名、移除；成员按权限读取 | 非成员不可读；被移除后不可发送或拿新媒体凭证；新成员历史边界正确 | `group.test.mjs`、通话成员变化测试 |
| 文本去重 | 成功写入一条并产生当前用户事件 | 丢响应后使用原 clientId 重试只保留一条；换内容／换范围复用 ID 拒绝 | `chat.test.mjs`、`MessageSendIdCoordinatorTest`、iOS 聊天测试 |
| 已读与删除 | 已读位置单向前进；本人删除只改变自己的视图 | 旧读位置不倒退；恢复聊天不恢复删除前历史；双方结果分别核对 | 服务端权限断言、双端可见列表与历史分页 |
| 事件同步 | 消费普通事件 ID 并重新读取资源 | 断线保留已处理游标；重建快照不漏消息；不把消息 ID 或 MLS sequence 当普通事件游标 | `chat.test.mjs` 与真实网络中断后列表核对 |
| 媒体 | 上传者可读，发送引用后授权接收者可读 | 未发送、外人、删除可见历史后不能越权；重开不丢引用；大文件拒绝 | `media.test.mjs`、`profile.test.mjs` 与下载字节摘要 |
| 新事 | 好友、指定人、已登录公开、仅本人各自可见 | 解除关系、屏蔽、隐藏、删除立即影响读取；视频 Range 边界正确 | `moments.test.mjs`，至少三合成账号逐项比对 |
| 城市贴纸 | 内置 ID 与三端素材一致，设备城市优先 | 权限拒绝用 IP 或手选；离开会话／换账号丢弃迟到结果；坏素材不伪造成功 | city-location、city-stickers 服务端测试和原生城市测试 |

消息行应同时观察发送者和接收者，不能只凭本机气泡出现判断服务端成功，也不能凭 HTTP 200 判断对方已读。断网测试分别覆盖发送前、服务端提交后丢响应、媒体已上传但消息未发送三个时点；记录相同 clientId 的行为，避免测试本身重复点击产生另一条合法新消息。

## 位置、通话与系统能力

| 场景 | 期望 | 需要独立验证 |
| --- | --- | --- |
| 实时位置 | 用户明确开始；PUT 只更新已开启共享；停止、离群或权限变化处理采集与服务端记录 | 两端前后台、粗略权限、最后更新时间、断网后旧坐标与手动停止 |
| 通话状态 | 成员才能发起／接听；重试不新建通话；响铃超时、忙、拒绝、挂断与群离开终态正确 | calls 与 call-media 测试；至少两设备逐角色检查 |
| 媒体连接 | 只有 active 当前参与者可获得短时房间 token | 麦克风、扬声器、蓝牙、摄像头切换、双向画面与声音、网络切换 |
| 系统来电 | 正确签名环境、topic、session 与设备注册 | APNs 真正到达、锁屏展示、后台、取消来电、多设备竞争接听 |
| 相机与文档 | 只读取用户选择的内容，拒绝后仍有可用替代入口 | 实体相机、无相机、永久拒绝、系统撤权、文件授权失效 |
| MLS 独立协议 | 密钥包、Welcome、Commit、ack、激活、密文重试与发件人校验 | iOS 独立传输与 Rust 测试；不能写成主聊天及全部附件 E2EE 通过 |

LiveKit 本机入房与 APNs 请求格式仅属于部分证据。媒体连接成功还应在双方分别断开与恢复、对方退群、挂断后迟到 token 等场景检查，不能让旧异步操作恢复已结束通话。普通聊天、新事、位置与推送元数据的数据可读性，应与[安全边界](https://document.thestarline.cn/app/security-and-privacy.md)一致。

位置退出必须单独验收：当前 iOS 退出只停止本机采集，不逐范围 DELETE 远端共享；聊天 session 注销或到期也不会自动删除 `live_locations`，其他仍有资格成员可能继续读取最后位置。Android 远端清理采用 bestEffort，失败时同样可能残留。用合成共享分别测试退出、到期、DELETE 成功与失败，记录本机是否采集、远端是否仍有记录、其他成员能否读取，不能把一项成功当作三项全部完成。

## 本机工作台、记忆与转出

| 场景 | 正常与拒绝期望 | 重启／离线／双端区别与验证 |
| --- | --- | --- |
| 任务与收藏 | 新建、编辑、筛选、去重与最近访问按本机规则保存 | 离线可读写；同设备重开保持；另一设备不自动同步；`LocalWorkspaceStoreTests`、任务 UI 与 Android 工作台流程 |
| 记忆与附件 | 合法内容加密保存；空模板不落盘；字段按上限处理 | 重开、编辑、搜索与附件字节一致；iOS/Android 文件格式分别检查，不直接互拷 |
| 损坏或丢密钥 | 显示无法读取并阻止覆盖 | 不把损坏库当空库；不新建密钥覆盖旧密文；`MemoryStoreTests` 与 Android 医疗／转出测试 |
| 医疗与宠物 | 八项医疗字段、两段 2000 字与换行保留；宠物优先规则正确 | 英文缩写与动物词边界、未知旧字段、附件、超长内容分别回归；不用真实医疗记录 |
| 系统推荐 | iOS 系统模型可用时生成待确认结构，不可用则本机回退 | Android 固定关键词路线独立；服务器识别 API 不等于本机识别，也不等于云同步 |
| 授权转出 | 当前用户取得额外许可后才生成明文 JSON；取消不生成完整输出 | 错账号、过期、断网、文件写失败清理部分文件；当前 Account 跨服务契约未闭环，需保持待验收 |

视觉流程另检查 320 级窄屏布局、大字号、键盘、长文件名、长文本、列表空态、底栏、弹窗与保存按钮。无障碍标识只用于测试定位，仍需实际核对朗读标签、焦点与点击区域；关闭动画后页面必须可操作。预览不按展示时长自动关闭。

## 命令与执行记录

以下命令展示真实测试入口，本次未执行。服务端命令在 App 仓库；Account 测试应进入其当前维护仓库另行运行：

```sh
node --test chat-service/tests/native-auth.test.mjs chat-service/tests/chat.test.mjs
node --test chat-service/tests/media.test.mjs chat-service/tests/moments.test.mjs
node --test chat-service/tests/calls.test.mjs chat-service/tests/call-media.test.mjs chat-service/tests/live-location.test.mjs
zsh ios-app/scripts/test-native-auth.sh
```

```sh
cd android-app
./gradlew :app:testDebugUnitTest --max-workers=1 \
  -Dorg.gradle.jvmargs=-Xmx1g -Pkotlin.compiler.execution.strategy=in-process
```

```sh
cd identity
npm run typecheck
npm test
npm --prefix client test
```

设备用例必须先指定允许使用的 QA 目标，串行执行，不卸载现有 App，不 wipe 模拟器或清 Keychain。历史医疗 QA 记录了 iOS 37 项本机测试、Android 69 项单测及专项 UI；原生授权记录包含 iOS 16 项测试与 Android 85 项 JVM、5 项隔离设备测试。Android 另有一次真实授权与 force-stop 冷启动记录；iOS 完整真实账号回跳、审核 iPad、生产推送、跨网音视频、正式包和手表独立版仍需新的证据。

每条验收结果填写：场景 ID、当前基线、期望、实得、退出码、日志摘要、目标设备、是否改变夹具、复验结果与未覆盖项。失败记录保留并关联修复后的结果；统计数量只能帮助追溯，不能替代具体断言或成为生产功能保证。发行门禁见[发行清单](https://document.thestarline.cn/app/release-checklist.md)。


原始地址：https://document.thestarline.cn/app/operations/
Markdown：https://document.thestarline.cn/app/operations.md

# 服务运行、迁移与数据保护

星线 App 的运行涉及静态下载站、Account 身份服务、聊天服务，以及可选的模型、LiveKit 和 APNs。本文介绍源码中可确认的运行机制与维护原则，不提供生产凭据、服务器地址或私有部署目录。本次仅核对代码与历史文档，没有连接生产、读取数据库、执行迁移或演练恢复。

## 运行拓扑与边界

身份服务使用 Node.js 24、MySQL 8.4 和独立 Account／管理站来源；其代码、命令与迁移以当前维护仓库为准，App 工作树的 `identity/` 不能当作现行部署模板。聊天服务使用 Node.js 24 与 SQLite，保存聊天、媒体、新事、设备会话和相关权限。下载介绍与公开技术文档属于静态内容，不需要数据库。App 内的记忆、个人任务和收藏存于设备，不因后端数据库备份而自动备份，也不因账号退出而删除。

| 组件 | 实际入口 | 持久数据或材料 |
| --- | --- | --- |
| 身份服务 | 当前 Account 的 `identity/server/main.ts`；构建后 `dist/server/main.js` | MySQL、稳定身份密钥、PII 密钥、私有 OIDC JWKS |
| 聊天服务 | `chat-service/src/main.mjs` | SQLite、WAL、资料加密密钥、OIDC 客户端配置 |
| 下载与文档 | `app-download/dist/` 的发布产物 | 经过核对的静态文件与下载配置 |
| 通话与推送 | LiveKit、APNs 服务端适配器 | 各自受保护配置与运行状态 |

配置变量用途见[配置参考](https://document.thestarline.cn/app/configuration-reference.md)。生产身份服务会校验批准的 HTTPS 来源、身份主密钥、PII 密钥和 OIDC 签名材料。当前管理员通行密钥要求由环境开关控制，不能沿用旧副本“生产始终强制 true”的断言；应另核对 `admin-policy.ts` 与实际角色及认证方法。聊天生产启动要求固定批准的身份 issuer、HTTPS public URL 与 confidential 客户端。合成域名只适合测试构造，不能通过替换示例值绕过这些检查。

## 构建与持续运行

在当前 Account 仓库的隔离构建环境准备依赖与身份服务产物：

```sh
npm --prefix identity ci
npm --prefix identity/client ci
npm --prefix identity/client run build
npm --prefix identity run typecheck
npm --prefix identity run build
```

身份服务的源码入口 `npm start` 适合本地运行；生产宿主部署由进程管理器运行构建产物，并注入受保护配置。仓库还提供 `identity/Dockerfile`、`identity/compose.yml`、`chat-service/Dockerfile` 与 `chat-service/compose.yml`。聊天镜像从同一 Rust 源码构建 Node WASM 校验器，复制固定城市库与贴纸素材，并用非 root 用户运行。Compose 将数据库映射到持久卷，应用端口默认仅绑定宿主回环；容器代理要按实际网络选择可达地址。

构建命令可以在新环境准备镜像。第一条在当前 Account 仓库执行，第二条在 App 仓库执行，不能因相对路径相同而混用历史副本：

```sh
docker compose -f identity/compose.yml build
docker compose -f chat-service/compose.yml build
```

这一步只构建，不等于启动、发布或健康。镜像准备后先核对现有部署基线、配置链、持久卷、回滚产物和目标服务，再按维护窗口切换。共享 Account 有独立维护来源，不能用 App 工作区的旧副本覆盖其最新代码、Compose 或代理配置。进程应持续运行，不设置用于展示的时间上限；退出时优先使用 `SIGTERM` 或 `SIGINT`，源码会关闭定时任务和连接。

## 健康检查与业务探测

本地检查命令是：

```sh
curl --fail --silent --show-error http://127.0.0.1:9100/api/health
curl --fail --silent --show-error http://127.0.0.1:4210/health
```

身份健康接口执行 `SELECT 1`，因此检查了数据库连接。聊天 `/health` 只返回进程的 `status: ok`，没有逐项探测 OIDC、LiveKit、APNs、模型或数据库后续写入。公开入口还要分别验证 DNS、TLS、反向代理、Host、重定向及正确响应。生产身份接口有可信代理和 Host 约束，不应直接照搬开发 curl 判断生产不可用，也不应为了探测关闭约束。

业务探测使用专用合成账号，依次确认授权、换票、`/me` 恢复、双方收发、媒体权限与重开读取。通话还需两台真实设备跨网络验证，APNs 还需证明通知实际到达。只记录状态和关联请求信息，不保存 token、code、完整回跳 URL、验证码或用户内容。

## 迁移与版本切换

身份服务启动前自动调用迁移，也提供独立入口：

```sh
cd identity
npm run migrate
```

当前 Account `MySqlStore.migrate()` 顺序处理 `001.sql` 至 `007.sql`，随后执行 PII 与补列逻辑，表前缀取自配置；部分幂等迁移会先检查现有结构。生产要求 64 位十六进制 `IDENTITY_PII_KEY`。已有明文联系方式、flow 或 challenge 转换前需要验证备份，并明确设置 `IDENTITY_PII_MIGRATION_APPROVED=1`；数据库密钥标记不匹配时拒绝启动，不能通过审批开关绕过。修改迁移前应审查 SQL、在隔离副本验证，再记录执行结果；不能由命令返回 0 推断所有业务兼容。

聊天没有独立 `npm run migrate`，`ChatDatabase` 与各仓储在构造时创建表、补充列或重建特定表，企业、城市贴纸、原生授权等结构也在启动阶段处理。因此新旧进程不能同时对同一份数据库随意切换。

上线顺序应为：冻结当前基线与构建产物，取得一致性备份，在隔离环境验证迁移与读写，确认客户端兼容，停止旧实例后切换，再做健康与业务验收。仓库未提供通用自动降级脚本；数据库结构已变化时，单独退回旧镜像可能不兼容，回滚需要与已演练的数据快照一起设计。

## 备份与恢复原则

聊天 SQLite 启用 WAL、外键和 5 秒 busy timeout。备份应使用一致性快照机制，或在有序停止写入后保存数据库及其 WAL 所需状态；不能在服务写入时只随手复制主数据库。媒体 BLOB、新事及权限也属于数据集，不能只备份消息表。不要删除 WAL、手工改表或清空数据作为通用修复步骤。

身份 MySQL 与稳定 `IDENTITY_SECRET`、`IDENTITY_PII_KEY`、私有 OIDC 签名材料需要按受控流程配套保护。PII 密钥同时影响联系方式解密与查找摘要，缺失或换错会拒绝启动或无法使用旧数据。聊天的 `CHAT_PROFILE_ENCRYPTION_KEY` 未设置时从客户端密钥派生；更换这些值可能导致已存资料无法解密或手机号查找索引失效。密钥轮换必须先分析受影响数据与会话，实施迁移或撤销，不把“生成新密钥”当作无损恢复。具体隔离演练见[故障处理与恢复](https://document.thestarline.cn/app/incident-runbooks.md)。

备份应加密、限制访问、设置保留期并定期检查可恢复性。恢复先在隔离环境验证结构、读取、权限和合成写入；正式切换前停止旧实例，避免双写。身份恢复后根据风险撤销旧会话与授权。管理员恢复只能由获授权维护者在受保护环境审计处理，不提供公开提权或绕过验证入口。本机记忆密钥绑定设备安全存储，服务端备份不能重建丢失的设备密钥；换机前应由用户按 App 的授权转出流程处理。

## 日志、队列和保留

身份日志保留方法、去除查询参数的路径、请求 ID 与响应状态，脱敏 Cookie、Authorization 和 CSRF 头。当前验证码 worker 每 250 毫秒调用 `processPendingDeliveries()` 处理持久队列，多实例依靠数据库锁分配任务；不能沿用旧方法名当作当前运维接口。生产邮件为腾讯 SES，短信为阿里云，SMTP 仅非生产备用；“请求已受理”“提供商接受”和“用户已收件”是三个不同结果。聊天源码将未处理异常写入标准错误，目前没有完整集中指标面板，应在进程及代理层补充错误率、延迟、重启、磁盘和资源观测，并先过滤敏感信息。

身份维护入口为 `npm run cleanup`，按过期状态与 `IDENTITY_AUDIT_RETENTION_DAYS` 清理，审计默认保留 180 天。新事未发布媒体会在启动及每小时检查中清理过期孤立项。不能把这些清理误认为完整备份或容量治理。生产状态、发布与商店进度见[版本与分发状态](https://document.thestarline.cn/app/releases.md)，按症状排查见[故障定位](https://document.thestarline.cn/app/troubleshooting.md)。


原始地址：https://document.thestarline.cn/app/incident-runbooks/
Markdown：https://document.thestarline.cn/app/incident-runbooks.md

# 故障处理与恢复演练手册

本页按现象给出只读排查、安全修复、验证与恢复边界。命令中的 `qa-fixture`、`qa-backup`、测试数据库和连接别名均为隔离演练示例，不指向真实用户数据。本次编写没有运行这些命令或执行恢复。首先记录时间、平台、版本、网络、操作阶段与脱敏错误；不要收集密码、验证码、verifier、票据、访问 token、记忆正文或完整带参数回跳 URL。

## 处理顺序与共同保护措施

1. 确定影响范围：单设备、单账号、单资源、全部 API、身份上游、媒体或存储。
2. 保留当前基线和原始错误，用只读检查确认实际运行版本、配置来源、资源与请求阶段。
3. 对能重现的最小场景准备合成夹具；涉及写入、权限、密钥和迁移时先制定可验证的恢复点。
4. 修复后重复原触发路径，再测拒绝、断网、重启与另一账号；记录实得，不只记录进程恢复。
5. 关闭事件前确认未产生数据覆盖、重复业务对象或滞留资源，并注明未覆盖设备和依赖。

本地健康探测只说明对应层：Account `/api/health` 执行数据库查询，聊天 `/health` 仅说明 HTTP 进程响应。公开入口还需分别验证 DNS、TLS、代理和业务。正常退出使用进程管理器的有序停止，让服务处理信号；不要把强杀、重装或删除数据库作为默认动作。

## 授权网页成功但未回到 App

| 阶段 | 只读检查 | 安全处理与验证 |
| --- | --- | --- |
| 开始 | App 目标聊天地址、授权 URL 主机、pending 保存结果 | 修复环境或存储错误后重新发起；不要手工拼接他人回调 |
| Account | 用户是否完成身份验证与应用授权、系统浏览器是否仍显示确认 | 区分系统“继续”提示、登录表单和实际授权完成；不因表单出现而结案 |
| HTTPS 回调 | 回调路由阶段、上游交换状态、是否过期或取消 | 对照客户端登记和当前 issuer 修复；一次性票据不反复消费 |
| App scheme | scheme／host 注册、当前构建、返回时进程状态 | 用授权测试账号重新完成流程；实际杀进程后的回跳单独记录 |
| 换票 | proof、state 的校验阶段、HTTP 状态、是否切换账号 | 只比较状态，不输出秘密；失败后保持原有效会话并重新授权 |

Android `NativeAuth.kt` 只允许正式 Account HTTPS；覆盖聊天地址或端口转发不能建立隔离 Account 原生登录。iOS Debug 可接受受限本机环境，但 Release 不读取该覆盖。恢复验证应覆盖正常授权、取消、过期、错 state、重放、临时离线与主动退出后的迟到响应。Android 已有一次真实授权冷启动历史，iOS 完整真实账号及审核 iPad 仍需独立证据。

## 会话突然 401 或临时无法连接

先确认 401 来自聊天 `/me` 或业务接口，而不是网页、媒体服务或反向代理。聊天 session 默认 24 小时，当前没有 refresh-token 接口。核对设备时间、环境、最近退出和升级；不要复制原 token 到其他设备，也不要把 Account token 当聊天 token。

真实 401 应清理对应失效会话并重新登录；网络超时、503 或临时离线应保留凭据。检查错误分类与当前账号 generation，避免旧请求清掉新账号。离线退出只证明本机已退出，远端退出失败时旧 session 可能持续到期限。修复后的验证包括重开恢复、断网恢复、账号切换与另一设备不受无关清理影响，见[客户端生命周期](https://document.thestarline.cn/app/client-lifecycle.md)。

## 消息重复、发送结果不明或事件似乎丢失

先区分两次独立点击和一次提交丢响应。记录合成用例的范围与 clientId，核对服务端是否返回已有消息；不能把相同文字当作同一业务动作。原请求重试沿用原 clientId、正文与 mediaId；换内容或范围后复用旧 ID 会返回 `CLIENT_ID_REUSED`。修复协调器或队列后模拟“提交已成功但响应丢失”，断言服务端与双方列表各只有一条。

事件是刷新信号，不是完整消息正文。比较当前快照、普通事件游标、请求 after 与返回 cursor，确认没有使用消息 ID 或 MLS sequence 代替。长轮询等待者在单进程内，断线或多实例场景要检查后续查询是否取到已提交事件；不能把没有即时唤醒等同于数据已丢失。恢复时重新读取有权限的列表与历史，随后从正确游标继续；不要倒改数据库 ID、删除事件或清空消息“重同步”。

## 媒体下载拒绝、位置不更新与城市为空

媒体 401 先处理会话；403／404 核对所有者、可见引用消息、当前群成员与个人历史可见边界。普通媒体的单聊读取不额外检查好友或屏蔽状态，既有可见引用不会仅因屏蔽／删好友自动失效；不能把发送限制当读取限制。上传成功不自动向其他账号公开，删除自己的可见历史后也可能失去引用授权。新事媒体的权限与 Range 另有契约。恢复时修正错误引用或客户端状态，不扩大为匿名公开下载；以发送者、接收者和外人三账号验证。

城市为空先区分拒绝定位、IP 兜底、目录未收录、系统解析失败和离线库损坏。只查目录版本、摘要与可信代理规则，不记录设备坐标，不信任任意转发头，也不使用附近城市伪造当前位置。坏库允许返回空值；素材恢复后重新载入并验证，检查离开会话时迟到结果被丢弃。

实时位置要分别检查系统采集、服务端更新和界面刷新。记录最后更新时间，确认用户已经显式开始，PUT 不应替用户自动开始。当前服务端记录没有自动过期字段，停止本机采集与删除共享记录必须协调；断网时不能把最后一帧说成实时移动。iOS 退出没有逐范围 DELETE，共享不会随聊天 session 注销或到期自动删除；其他仍有资格成员可能读取最后位置。Android bestEffort 远端清理失败也可能残留。安全处理应在授权账号可用时使用明确停止入口，并复查远端记录与其他成员视图；不能仅以退出界面或通知消失结案。验证停止、离群、权限撤回、前后台和重启，详见[位置共享](https://document.thestarline.cn/app/location-sharing.md)。

## 来电不响、接听后无声或通话未结束

按创建、邀请、系统推送、接听、媒体 token、入房、轨道、输出设备、结束逐段检查。`active` 只表示信令状态；LiveKit 本机入房也不能证明蜂窝网络双向媒体。核对成员资格、媒体服务配置、token 期限与网络路径；若参与者已离开，不应为其签发新媒体凭证。

iOS 另核对签名环境、APNs sandbox／production、VoIP topic、设备注册是否绑定有效 session，以及提供商返回的脱敏状态。提供商接受不能替代锁屏系统来电到达。修复后测双方音画、静音、扬声器、蓝牙、切后台、网络切换、多设备竞争与挂断后的迟到任务。结束状态异常时先复查房间人数与宽限期，不能因一次查询失败就宣告空房。不要将恢复通话状态用于发出虚构 VoIP 来电。

## 记忆损坏、密钥不可用或转出失败

iOS `loadError` 与 Android `memoryLocked` 表示应保护原库，读取失败不能转换成可写空库。先确认设备是否解锁、是否刚升级、文件与密钥是否仍匹配；用文件存在性、大小和密文摘要辅助诊断，不解密真实内容作为报告。禁止清 Keychain／Keystore、卸载、生成新密钥覆盖或删掉“坏文件”后重建。

修复只针对确定的解码、权限或兼容问题，并先在合成副本重现。已有密钥丢失时，服务端聊天备份不能重建本机记忆；没有成功导出的资料不能承诺恢复。转出失败还应区分聊天许可桥接、当前 Account 契约与系统保存位置。现行 Account 主源码缺少对应 redeem 路由，旧副本和本地 fixture 不能证明生产可用。清理仅针对本次生成的部分临时输出，验证取消与失败不损坏原库，见[记忆转出](https://document.thestarline.cn/app/memory-export.md)。

## SQLite 锁、磁盘满与一致性故障

`SQLITE_BUSY` 先检查是否存在重复写实例、长事务或备份／迁移任务；当前数据库使用 WAL、外键与 5 秒 busy timeout。磁盘满先检查所在卷空间、配额和权限，不能先删数据库或 WAL 腾空间。`/health` 200 不保证新事务能写入，必须用合成业务验证。出现损坏信号时停止继续写入，保留数据库与相关 WAL 状态，交由授权维护者处理。

只对已经取得的隔离快照做检查：

```sh
set -eu
test -f qa-backup/chat.sqlite
sqlite3 -readonly qa-backup/chat.sqlite 'PRAGMA quick_check;'
sqlite3 -readonly qa-backup/chat.sqlite 'PRAGMA integrity_check; PRAGMA foreign_key_check;'
```

`integrity_check` 返回 ok 不检查外键关系，需另运行 `foreign_key_check`；空输出表示没有报告外键违例。结构完整也不代表账号映射、加密密钥和权限语义正确。不要对故障原件运行通用 `.recover` 后直接上线，更不能手工禁用外键掩盖不一致。[SQLite PRAGMA 说明](https://sqlite.org/pragma.html)给出了检查范围。

## 仅用合成数据进行备份与恢复演练

1. 在新 QA 环境建立两合成账号、好友、群、消息、媒体与私有新事，记录预期关系和少量摘要。
2. 明确镜像／源码、数据库结构、当前稳定密钥的版本标识，暂停该演练环境的结构变更。在线备份使用 SQLite Backup API，不在写入时随手复制主文件。CLI `.backup` 与快照机制见[官方命令行说明](https://sqlite.org/cli.html)和[备份说明](https://sqlite.org/backup.html)。
3. 源文件必须存在，目的文件必须是新的演练文件；示例只读取合成源并写入新备份：

```sh
set -eu
test -f qa-fixture/chat.sqlite
mkdir -p qa-backup
test ! -e qa-backup/chat.sqlite
sqlite3 -readonly qa-fixture/chat.sqlite ".backup 'qa-backup/chat.sqlite'"
shasum -a 256 qa-backup/chat.sqlite
```

4. 运行前述结构与外键检查，记录工具版本和退出码。复制备份到新的隔离恢复目录，拒绝覆盖已有目的库；在恢复环境使用配套密钥与匹配的 Account 测试映射，不能指向原服务或真实云投递。
5. 启动恢复环境后验证两账号资料、历史、未读、外人拒绝、媒体摘要、群成员边界及合成新写入。API 验证由获授权的测试操作完成，不把源库与恢复库同时当作生产写入口。
6. 对照恢复点记录可接受的数据损失范围和恢复用时。任何结构、权限或解密差异未解决时，不进行正式切换。

Account MySQL 要另行演练，一致性数据备份与 `IDENTITY_SECRET`、PII 密钥、签名材料配套保护。示例连接别名需预先指向独立 QA 实例，凭据通过受保护客户端配置提供：

```sh
set -eu
test -d qa-backup
test ! -e qa-backup/identity.sql
mysqldump --login-path=qa-identity --single-transaction \
  --routines --triggers --events identity_qa > qa-backup/identity.sql
mysql --login-path=qa-identity-restore identity_qa_restored < qa-backup/identity.sql
```

导入对象必须是事先批准的新隔离数据库，不是现有业务库；备份命令失败时应立即停止，不能拿空文件继续导入。备份文件本身是敏感数据，不进入公开站点。PII 旧数据迁移需先验证备份，再明确审批，错误密钥不能用审批开关绕过。正式恢复由维护窗口停旧实例后切换，必要时撤销旧资格；回退数据库可能丢弃恢复点之后的写入，应单独决策并记录。更多门禁见[发行清单](https://document.thestarline.cn/app/release-checklist.md)。


原始地址：https://document.thestarline.cn/app/releases/
Markdown：https://document.thestarline.cn/app/releases.md

# 版本、构建与分发状态

本文区分源码、预览构建、真实验收、商店上传、审核与公开发布。状态依据截至 2026-10-22 的仓库与保存记录整理；本次文档工作没有重新登录商店后台、复跑产品测试或重新核验生产。后续状态必须由新的可核对回执更新，不能用构建数量或聊天中的完成表述代替。

## 当前可以确认的范围

| 项目 | 源码或历史证据 | 尚需完成或重新核对 |
| --- | --- | --- |
| Android App | 当前 `versionName=1.0.6-preview`、`versionCode=7`；保存记录包含一次真实账号授权、自动返回与 force-stop 后冷启动恢复 | 正式 Release 签名、公开 APK、备案签名一致性、商店与跨网络验收 |
| iOS App | 原生系统授权、PKCE、Keychain 与冷回调实现；保存记录包含 16 项授权测试与正式登录表单 UI 验证 | 真实账号完整登录／授权回跳／冷启动，以及 iPhone、iPad 真机闭环 |
| 医疗健康记忆 | 双端历史 QA 覆盖八个可选字段、多行文本、本机加密、附件、搜索和重开 | 其他设备、全部系统版本和字号不在原记录范围 |
| 下载介绍站 | 历史部署记录已确认静态站、HTTPS 和备案页脚发布 | 公开 App Store 地址和可分发正式 APK 仍未提供 |
| 音视频与推送 | 本机媒体入房、状态与 APNs 请求构造测试 | 真实 APNs 到达、双向媒体、跨网络、锁屏与后台真机验收 |
| watchOS | 手表独立登录联网版的产品方向已确定 | 尚无独立版实现交付证据；登录、网络、输入、消息和来电提醒待实施 |

Android 真实生产授权记录仅保存布尔结果与必要范围：真实账号授权成功、一次性票据消费、自动回前台、替换进程后恢复，以及原记忆与会话密文未改变。设备会话期限为 24 小时，没有 refresh token 或永久登录承诺，也没有连续运行 24 小时的验收。Android 结论不能代替 iOS 或 Apple 审核设备的结果。

## Apple 与小米渠道

Apple 渠道仍需完成 iPad 账号授权可访问性及商业模式说明等审核事项的闭环；后续签名 Archive、构建上传及重新提审，需要新的后台记录核对。仅修复源码、打开登录页、通过模拟器用例或完成 Android 登录都不足以宣称审核问题已解决。

小米渠道仍是草稿、未提审。版权证明与聊天安全评估等渠道要求材料仍需按实际情况核对补齐；不能把待备材料写成已提交。正式 Android Release 签名、备案相关签名一致性和联网验收仍待完成，Debug APK 仅用于开发预览。

watchOS 的规划方向是“独立登录联网版”。范围包括独立登录、文字／听写、语音消息、图片、普通与城市贴纸、回应、未读已读、历史和来电提醒。现有通话 SDK 不支持 watchOS，手表直接接听需另行设计与验证；尚不能宣称手表版可下载或接听。

## 星线智联暂停状态

星线智联小程序开发版本 `0.1.0` 有上传成功的历史回执，但回执明确尚未提审、尚未发布。后续发布流程已暂停；文档公开、App 开发和资料整理不会自动恢复小程序验收或提交审核。

真实微信登录曾显示“暂时无法核对”，已有证据不足以确定是 `wx.login`、网络还是后端 inspect 环节失败，不能直接断言密钥或合法域名错误。恢复后先核对当前 Account 运行版本及请求链，再做真实手机闭环。正式 URL Link 需要线上发布版本；开发预览或填写版本号不等于正式往返已通过，公开入口状态也应以恢复后的实际回读为准。

## 可复现构建与正式产物

Android 构建入口存在，但当前配置没有提供可公开使用的正式签名凭据。下面命令生成 Release 构建候选，不能仅凭文件存在就称为正式已签名发行包：

```sh
cd android-app
./gradlew :app:assembleRelease --max-workers=1
```

正式分发前应核对 application ID、版本号／版本码、目标服务、签名证书、权限、最低系统、安装升级兼容与备案材料。用 Android SDK 工具验证签名，并为最终文件计算摘要；以下路径假定维护者已将真正完成签名的候选命名为该文件：

```sh
apksigner verify --verbose candidate-release.apk
shasum -a 256 candidate-release.apk
```

同一待发布 APK 的签名、大小、摘要、下载内容和验收记录必须对应。不能把测试 APK 或另一轮构建的摘要写到下载站。

iOS 使用工程的 `StarlineWorkbench` scheme；生产 Archive 需正确的 Apple 开发团队、证书、描述文件、Bundle ID 与推送能力。示例将归档保存到本工作区的构建目录，实际签名参数通过受保护的 Xcode 配置提供：

```sh
xcodebuild -project ios-app/StarlineWorkbench.xcodeproj \
  -scheme StarlineWorkbench -configuration Release \
  -destination 'generic/platform=iOS' \
  -archivePath build/StarlineWorkbench.xcarchive archive
```

Archive 成功只产生候选。之后仍需签名检查、目标设备安装、隐私与权限复核、上传回执、审核提交、审核结果与公开版本链接。开发推送和发布推送环境不同，不能混用测试签名和正式 APNs 结论。

## 下载站与文档发布

下载配置在 `app-download/dist/downloads.config.js`。空地址显示“准备中”；`ios.url` 应为确认存在的公开 App Store HTTPS 地址，`android.url` 应指向真实可分发 APK。只有正式稳定版验收完成后才把 `android.channel` 切为 `stable`，同时更新真实版本、大小、最低系统与 64 位 SHA-256。浏览器的 URL 结构校验不能证明服务器可下载或安装成功。

静态页面与文档发布也要单独记录：本地预览、上传、公网访问与抓取规则分别核对。发布产物只包含明确允许公开的页面、样式、脚本、图片和文档，不包含仓库 README、部署回执、环境文件、源代码快照、日志或数据库。下载新增后验证公网 GET、字节摘要和安装；文档新增后验证导航、Markdown、站点地图与抓取规则。旧部署脚本带有一次性基线假设，不应直接重复运行。

建议每次发行记录版本与提交基线、构建工具链、最终产物摘要、签名标识、测试环境、真实验收范围、渠道回执及已知限制。状态词使用“本地构建”“已上传”“已提审”“审核通过”“公开发布”等准确阶段；测试数量只作为证据索引。当前 Account 已有 001–007 与 PII 迁移、SES／阿里云投递等变化，不能从 App 历史副本冻结服务版本。具体门禁与签名命令见[发行核对清单](https://document.thestarline.cn/app/release-checklist.md)，测试见[测试与验收](https://document.thestarline.cn/app/testing.md)，服务切换和恢复见[运行维护](https://document.thestarline.cn/app/operations.md)。


原始地址：https://document.thestarline.cn/app/release-checklist/
Markdown：https://document.thestarline.cn/app/release-checklist.md

# 构建、签名与发行核对清单

发行应绑定一个明确基线、一组不可混用的最终产物和分阶段回执。源码版本、测试数量、Archive、APK 文件、上传、提审和公开下载各有独立证据。以下命令供在授权构建环境核对，本次没有运行原生构建、签名、服务测试或渠道操作；当前状态见[版本发布](https://document.thestarline.cn/app/releases.md)。

## 冻结范围与版本资料

先记录仓库提交及未提交差异、目标平台、工具链、依赖锁文件、API 环境和计划版本。未提交改动也属于构建输入，不能只记一个 commit 后忽略工作区。共享 Account 必须以当前维护仓库和实际运行版本为准，不从 App 历史副本整目录部署。任何发布都不自动恢复暂停的小程序或启动手表任务。

```sh
git status --short
git rev-parse HEAD
node --version
xcodebuild -version
java -version
```

仅执行目标平台所需检查。保存输出前去除个人路径、账号、凭据和内部地址；公开发行说明只保留对评估兼容性有用的版本、产物标识及限制。版本表还应记录法律／隐私页版本、数据迁移、已知问题和回滚条件。

| 对象 | 必核对项 | 不能替代的证据 |
| --- | --- | --- |
| iOS | Bundle ID、营销版本、构建号、最低系统、设备族、权限、推送环境 | 源 plist 不等于最终 Archive，iPhone 测试不替代审核 iPad |
| Android | applicationId、versionName、versionCode、min/target SDK、权限、签名 | Debug 版本不等于 Release；文件名不证明签名或升级兼容 |
| 服务端 | 源码／镜像基线、迁移、配置来源、持久卷和稳定密钥版本 | 构建成功不等于已运行或业务可用 |
| 静态站 | 最终清单、正文、下载配置、公共文件范围 | 上传成功不等于公网字节、MIME、TLS 和链接正确 |

## Android 构建候选与签名

当前源码声明 `1.0.6-preview`、versionCode 7、API 26 起、编译与目标 API 35，实际候选必须重新读取。采用仓库 Gradle Wrapper，先核对 JDK 与插件组合，不因历史构建通过跳过当前兼容检查：

```sh
cd android-app
./gradlew --version
./gradlew :app:testDebugUnitTest :app:assembleDebug :app:assembleDebugAndroidTest \
  --max-workers=1 -Dorg.gradle.jvmargs=-Xmx1g \
  -Pkotlin.compiler.execution.strategy=in-process
./gradlew :app:assembleRelease --max-workers=1
```

最后一步只产生构建候选。当前 Gradle 未配置公开可复用的正式 Release 签名流程，不能把 unsigned 包、Debug key 或任意临时签名当作正式升级渠道。正式密钥由受保护签名系统提供，不在命令历史或文档中填写口令。

以下命令假定维护者已将正确签名的最终 APK 放为工作区内 `candidate-release.apk`，并准备好 Android SDK 命令：

```sh
apksigner verify --verbose --print-certs candidate-release.apk
apkanalyzer manifest application-id candidate-release.apk
apkanalyzer manifest version-name candidate-release.apk
apkanalyzer manifest version-code candidate-release.apk
apkanalyzer manifest min-sdk candidate-release.apk
apkanalyzer manifest target-sdk candidate-release.apk
shasum -a 256 candidate-release.apk
```

比对签名证书摘要、备案材料与上一可升级安装包，确认 application ID 不变、versionCode 递增。正式包不得包含模拟器地址、fixture 登录或本地 HTTP 依赖。Release 清单禁止明文流量，编译属性接受 URL 不代表网络策略允许。安装验收至少包括干净安装与从上一版原地升级；现有用户预览设备不得为测试方便而卸载或清数据。

升级后确认记忆、附件、任务、收藏和已登录恢复策略；对旧字段、加密格式和失败保护做专项回归。包签名变化可能阻止升级，应在独立 QA 设备发现，不能先要求用户删除原 App。验证完成后计算最终 SHA-256 与大小，后续重新签名、重打包或修改资源都要求重算并重验，不能沿用上一份摘要。

## iOS Archive 与发布签名

从 `project.yml` 与已提交 Xcode 工程核对源配置；当前最低 iOS 17、设备族 iPhone，Info.plist 仍含历史 1.0／构建 1。不得据此声称商店已有新构建。生成工程或修改版本后，检查实际构建设置：

```sh
xcodebuild -project ios-app/StarlineWorkbench.xcodeproj \
  -scheme StarlineWorkbench -configuration Release -showBuildSettings \
  | rg 'PRODUCT_BUNDLE_IDENTIFIER|MARKETING_VERSION|CURRENT_PROJECT_VERSION|IPHONEOS_DEPLOYMENT_TARGET|TARGETED_DEVICE_FAMILY'
```

没有出现某字段时继续核对 Info.plist 与最终产物，不能把空输出解释为默认正确。签名团队、证书、描述文件和 Push Notifications 能力需匹配；Debug 使用 development entitlement，Release 使用 production，并与服务端 APNs 环境及 VoIP topic 对齐。

```sh
xcodebuild -project ios-app/StarlineWorkbench.xcodeproj \
  -scheme StarlineWorkbench -configuration Release \
  -destination 'generic/platform=iOS' \
  -archivePath build/StarlineWorkbench.xcarchive archive
```

生成后在实际 App 目录检查签名和打包后的版本。这里的路径是仓库内候选产物，不是用户安装目录：

```sh
codesign --verify --deep --strict build/StarlineWorkbench.xcarchive/Products/Applications/StarlineWorkbench.app
codesign -dv --verbose=4 build/StarlineWorkbench.xcarchive/Products/Applications/StarlineWorkbench.app
plutil -p build/StarlineWorkbench.xcarchive/Products/Applications/StarlineWorkbench.app/Info.plist
```

Xcode Archive、导出、上传回执、处理完成、选择构建、审核提交、审核通过与正式可下载应逐项记录。iOS 的真实账号授权、自动返回、冷启动、取消与记忆保护必须在目标设备完成；历史系统表单测试不能代替完整授权。Apple iPad 登录驳回与商业模式说明仍需形成新的后台闭环，不能引用 Android 成功作为修复证明。

## 服务端、数据库与兼容门禁

| 检查阶段 | 执行内容 | 通过标准 |
| --- | --- | --- |
| 配置 | 按[配置参考](https://document.thestarline.cn/app/configuration-reference.md)核对变量来源、格式和依赖 | 无 fixture 混入；稳定密钥可匹配当前数据；外部能力明确启用条件 |
| 迁移 | 在隔离副本运行对应版本，验证 schema、读写与权限 | Account 001–007 与 PII 迁移有配套备份；聊天构造迁移不破坏旧记录 |
| 切换 | 停旧写入口、按维护窗口启用新实例 | 无双写、无指错持久卷、无新建空库误报健康 |
| 验证 | HTTP、身份、消息、媒体、事件、通话等分层探测 | 合成业务断言与拒绝路径通过，真实依赖另有证据 |
| 观测 | 错误、延迟、重启、磁盘、队列和外部接受状态 | 发现异常能关联阶段，日志不含秘密与用户内容 |

数据库升级没有通用降级脚本。发布前应验证旧客户端对新增字段的容忍、旧服务是否能读取升级后结构、数据保护密钥是否变化。退镜像与退数据是两种动作：退镜像可能遇到 schema 不兼容，退数据库可能丢失恢复点后写入。不能承诺一键无损回滚；按[恢复演练](https://document.thestarline.cn/app/incident-runbooks.md)预先验证并记录边界。

## 下载、渠道与正式回执

下载地址只指向已核验的最终产物。iOS 使用真实公开 App Store 链接；Android 填写最终版本、最低系统、大小、SHA-256 与渠道状态。只有稳定版验收完成后才切 `stable`，预览包需保留其可用范围说明；空地址继续显示准备中。

可以在发布后的授权核验阶段下载公开候选并比较，以下域名与文件名为合成示例：

```sh
set -eu
curl --fail --location --output qa-download.apk https://downloads.example.test/starline-release.apk
shasum -a 256 qa-download.apk
apksigner verify --verbose qa-download.apk
```

同时核对 HTTPS 信任链、重定向、响应文件类型、真实字节和安装升级，不只发 HEAD 请求或检查 URL 格式。备案标识、包名、签名证书和商店材料应属于同一产品；网站号与 App 号分开，星线与星企不混用。小米仍缺版权证明与聊天安全评估材料，草稿保存不能当作提审；正式 APK 与渠道回执仍需取得。

星线智联 0.1.0 只有开发上传历史，未提审、未发布，且保持暂停。上传版本号、开发者工具预览或设置 published 环境开关均不是官方发布回执。watchOS 独立联网版没有成品交付，手机包不能替它填报已上线。

渠道操作前把版本记录与材料逐项对应：创建草稿只记录草稿；上传成功记录包处理状态；选择构建后确认实际提交；审核结果以后台决定为准；公开发布后核对目标地区、可下载版本与安装结果。被拒后保留具体原因和对应设备，再关联修复提交、复验和新回执。截图、客服说明、审核回复和补件上传分别保存，不能用一项替代整套流程。渠道要求变化时核对当前后台字段，不从旧材料复制过期状态。

## 关闭发行记录

发行记录至少包含：最终源码／工作区基线、工具链、版本与签名标识、产物摘要、数据兼容结论、所选设备与网络、通过和失败用例、外部依赖、上传／审核／发布回执、公开下载核验、可回退版本和已知限制。给每项写准确阶段，不用“已经弄好”概括整条链路。后续紧急修复仍须关联相同清单，避免源码、文档、安装包和商店说明分别指向不同版本。


原始地址：https://document.thestarline.cn/app/troubleshooting/
Markdown：https://document.thestarline.cn/app/troubleshooting.md

# 故障定位与恢复边界

排查星线 App 时，先确定故障发生在本机界面、网络、聊天服务、Account、第三方授权还是商店。本文根据源码中的实际错误与运行机制整理处理顺序。示例仅使用本机地址和合成数据；本次没有访问生产、读取用户内容或实施恢复操作。服务机制见[运行维护](https://document.thestarline.cn/app/operations.md)，验收命令见[测试与验收](https://document.thestarline.cn/app/testing.md)。

## 先收集最少必要信息

记录平台、App 版本、系统、网络、时间、入口、可重复步骤、HTTP 状态或错误代码，以及是否刚更新版本。把“按钮没反应”“网页报错”“网页成功但未回 App”“回 App 后账号为空”分开；它们位于不同边界。日志只截取必要部分，移除 Authorization、Cookie、验证码、state、ticket、完整回跳 URL、手机号和记忆正文。

优先做只读检查，保留原进程和数据。不要一开始卸载 App、清空 Keychain／Keystore、删除 SQLite、清空记忆或重置模拟器。构建成功不能解释真实路径失败，截图出现某一页面也不能证明用户已完成授权。

## 页面打不开或连接被拒绝

本地 `ERR_CONNECTION_REFUSED` 通常先确认目标端口确有服务，而不是反复刷新页面：

```sh
curl --fail --silent --show-error http://127.0.0.1:9100/api/health
curl --fail --silent --show-error http://127.0.0.1:4210/health
```

身份健康检查会访问数据库；聊天健康仅证明 HTTP 进程响应。若前端开发页能打开而 API 不可用，分别检查 `identity/client` 的 Vite 与身份后端，不把一个端口的 200 当成整套服务可用。静态下载页可独立预览：

```sh
python3 -m http.server 8868 --bind 127.0.0.1 --directory app-download/dist
```

该预览持续运行，不自动按时间退出。端口冲突时先识别已有服务，不随意结束用户进程。公开入口还需分层核对 DNS、证书、HTTPS、代理和上游，502 与 DNS 解析失败属于不同阶段；不通过关闭 TLS 验证或修改系统网络来掩盖原因。

## 登录、回跳与冷启动

当前原生流程是 `POST /auth/native/start` 获取授权地址，系统浏览器进入 Account，网页返回聊天服务 `/auth/callback`，再以 `starlineworkbench://chat-auth` 回到 App，最后 `POST /auth/exchange` 换取设备会话。客户端保存 verifier 与 state，服务端票据为单次且有效一分钟；访问 token 不放在回跳 URL。

| 现象 | 优先定位 | 处理边界 |
| --- | --- | --- |
| `LOGIN_UNAVAILABLE` 或启动登录 503 | 聊天 OIDC 配置、discovery、上游可达性 | 不在客户端补写 secret 或伪造成功 |
| 打开了错误环境 | App base URL、issuer、public URL、构建参数 | Account 与聊天必须来自同一联调环境 |
| 网页完成但未回 App | scheme 注册、目标 app、系统授权会话、回调阶段 | 先确认回调到达位置，不重复消费 ticket |
| state 错误、过期或 ticket 401 | 是否原设备发起、是否重放、是否过期、是否取消 | 发起新的完整授权；保留原有有效会话 |
| 冷启动临时离线 | `/me` 网络错误或服务 503 | 客户端应保留凭据并允许恢复 |
| `/me` 返回 401 | 会话到期、退出或无效 | 重新登录，不把 token 复制到其他设备 |

设备会话有效期为 24 小时，没有永久登录或 refresh token。iOS 的 Debug 仅通过 `STARLINE_CHAT_BASE_URL` 显式覆盖，Release 使用正式地址；Android 通过 `-PstarlineChatBaseUrl` 编译，默认也是正式服务。本地 ticket 不能提交正式服务换票。iOS 系统“继续”提示是授权会话的一部分，应检查提示与实际表单，不能把它当作 App 登录失败后直接删掉。

Android 保存过真实授权和 force-stop 冷启动成功的历史证据；iOS 真实账号完整闭环及审核 iPad 仍待验收。定位问题时应针对失败平台重现，不能用另一平台的成功结果代替。对已有账号执行恢复测试须保留记忆与原会话数据，不把重新安装作为默认步骤。

## 验证码未到或第三方暂不可用

匿名邮箱码接口返回 `request_accepted` 表示受理，发送在持久验证码队列中执行；提供商接受与实际收件仍需分别确认。`DELIVERY_UNAVAILABLE` 先检查当前主源码的投递适配器：生产邮件为腾讯 SES，短信为阿里云；SMTP 只用于非生产备用，配置 SMTP 不能恢复生产邮件。旧副本的腾讯短信变量也不能用于当前服务。TLS 验证保持严格，等待重发冷却，避免重复请求导致难以判断当前有效验证码。

若注册先返回 CAPTCHA_REQUIRED／CAPTCHA_UNAVAILABLE，优先检查当前验证码门禁及四项 captcha 配置，不把它归为邮件失败。开发注册同样需要证明；旧 fixture 没有提交 captcha，不能据此认定后端注册损坏。若启动报 PII 密钥缺失、不匹配或旧数据迁移未批准，保留库与稳定密钥，先验证隔离备份和迁移方案，不通过删除标记、重置密钥或盲开审批修复。当前 Account 迁移已为 001–007，排查必须使用其当前维护仓库，见[完整配置参考](https://document.thestarline.cn/app/configuration-reference.md)与[故障处理手册](https://document.thestarline.cn/app/incident-runbooks.md)。

微信、QQ、支付宝配置存在不等于平台已启用或真实回调通过。星线智联 `0.1.0` 只有开发上传历史，尚未提审、发布，并按用户要求暂停。手机“暂时无法核对”可能包含 `wx.login`、网络或 inspect 错误，需恢复后检查分段日志；不能仅凭统一提示断言 AppSecret 或合法域名错误，也不能自动恢复暂停任务。

## 消息、贴纸与模型

401 先处理登录，403／404 核对成员和资源权限；已解除好友、屏蔽、离群或删除记录会改变可见范围。失败消息应通过原重试入口发送，避免新建另一条造成重复。只在已加载聊天摘要中搜索的结果不能代表完整历史不存在。

城市贴纸未知 `cityId` 或额外字段返回 400，缺少／损坏素材返回 503。城市目录来自内置 catalog，客户端不能提交文件路径。IP 城市为空可能是私网地址、代理未在精确 allowlist、离线库缺失或无法识别；先核对输入边界、素材版本与哈希，不扩大为信任所有代理。设备城市优先、IP 只是粗略兜底，空值时保留选择城市，不伪造位置。

实时位置的本机停采集与远端停止必须分别核对。当前 iOS 退出不会逐范围删除共享，session 注销或到期也不清理服务端最后位置；Android bestEffort 删除失败同样可能残留。不能以退出、通知消失或坐标不再变化证明其他成员已不可读；使用明确停止入口并确认远端状态，详见[故障处置](https://document.thestarline.cn/app/incident-runbooks.md)。

未配置 `CHAT_CRYPTO_NODE_BUNDLE` 时加密接口返回 503；加密核心测试或 WASM 构建成功不能证明聊天 UI 已全量采用 MLS，也不能声明旧消息、附件或新事均为端到端加密。记忆模型未就绪可返回 503，但本机自由记录和固定模板仍可使用；不要把模型不可用修成上传用户记忆到未知外部服务。

## 通话与通知

`CALL_MEDIA_UNAVAILABLE` 先核对 LiveKit 地址、密钥、媒体房间与网络连通。HTTP 业务接口响应正常不代表 WebRTC／TURN 端口可达；同房间连接测试也不代表双向声音和画面正常。排查时分别确认发起、振铃、接听、媒体、挂断与多设备竞争，保留双方时间线。

APNs 请求构造成功或提供商接受不等于设备收到来电。核对 Bundle／VoIP topic、开发或生产环境、签名能力、会话期限、锁屏与后台状态；不要记录推送 token 或私钥。watchOS 尚无独立版交付，现有通话 SDK 不支持手表，不能用手机接通结果声称手表可接听。

## 本机记忆、升级与资源异常

记忆索引和附件分别加密，密钥在设备安全存储。升级或迁移失败应保留原文件，不用空数据覆盖；卸载会丢失 App 私有数据，服务端备份不能恢复设备密钥。用户换机或卸载前，应按现有账号多因素授权流程主动转出；公开报告只描述结果，不收集导出正文。医疗健康模板只记录信息，没有自动复诊提醒、系统健康接入或跨设备同步。

模拟器内存异常先观察进程、物理内存、swap、日志和是否存在重复实例，不擅自关闭程序或修改系统配置。Android 预览启动器复用既有 AVD，保护阈值是资源异常条件，不是展示时限。界面截图停在旧帧时先区分绘制与业务状态，不清空数据强行“修复”。问题修复后只重跑相关验证并记录剩余边界；发布与审核状态依据新的正式回执更新，见[版本与分发状态](https://document.thestarline.cn/app/releases.md)。


原始地址：https://document.thestarline.cn/app/glossary/
Markdown：https://document.thestarline.cn/app/glossary.md

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

本页统一文档中的名称、数据单位和状态含义。相似名称不一定代表同一对象；集成时应同时核对所属服务、用户、会话范围和有效期。具体字段以 [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)逐步核对。


原始地址：https://document.thestarline.cn/app/ai-access/
Markdown：https://document.thestarline.cn/app/ai-access.md

# 文档访问与引用

技术文档提供 HTML、Markdown 和索引文件，无需登录或 API key。允许自动化工具访问、抓取、索引、摘要及引用 `https://document.thestarline.cn/app/` 的公开内容。引用时请保留文章标题、原始 URL、资料日期和相关限制。

## 机器可读入口

| 地址 | 内容与使用方式 |
| --- | --- |
| [/llms.txt](https://document.thestarline.cn/llms.txt) | 文档入口、阅读顺序和能力边界 |
| [/llms-full.txt](https://document.thestarline.cn/llms-full.txt) | 按章节汇总的完整公开 Markdown |
| [/docs/catalog.json](https://document.thestarline.cn/app/catalog.json) | 文档标题、摘要、HTML URL、Markdown URL、内容摘要值 |
| [/docs/search-index.json](https://document.thestarline.cn/app/search-index.json) | 本站搜索使用的公开正文索引 |
| [/docs/api-index.json](https://document.thestarline.cn/app/api-index.json) | 从当前服务路由整理的方法、路径、鉴权和范围元数据 |
| [/sitemap.xml](https://document.thestarline.cn/sitemap.xml) | 公开页面的 canonical 地址 |
| [/robots.txt](https://document.thestarline.cn/robots.txt) | 本域名自动抓取规则 |

每篇文章页面提供 Markdown 原文链接。例如首页原文是 [/docs/overview.md](https://document.thestarline.cn/app/overview.md)，API 原文是 [/docs/api-reference.md](https://document.thestarline.cn/app/api-reference.md)。HTML 正文在服务器构建时已经生成，关闭 JavaScript 仍可阅读，不需要执行搜索脚本才能取得文章。

`llms.txt` 是帮助 AI 发现和理解网站内容的提案，不是所有模型都实现的统一索引协议，也不保证任何平台会主动抓取或收录。格式背景见 [llms.txt 提案](https://llmstxt.org/)。

## 抓取策略

本域名的 robots.txt 对普通爬虫开放，并显式允许 `OAI-SearchBot`、`GPTBot` 与 `ChatGPT-User`。根据 [OpenAI 爬虫说明](https://developers.openai.com/api/docs/bots)，前两者分别用于搜索和可能用于模型训练的内容抓取，控制项独立；`ChatGPT-User` 是用户触发访问，robots 规则可能不适用。网站表达允许访问，不代表控制 AI 平台的后续行为或保证内容进入训练、搜索或回答。

抓取者应合理控制并发，复用已取得的静态文件，并在遇到 HTTP 429 或临时服务错误时退避。可通过 `catalog.json` 的 SHA-256 判断内容变化，不必重复下载所有文章。没有对特定账号、国家、设备或 User-Agent 提供不同的文档正文。

robots.txt 的语义依据 [RFC 9309](https://www.rfc-editor.org/rfc/rfc9309.html)。它表达自动抓取规则，不能代替身份验证和访问控制；私有内容应继续受真正的鉴权保护，参见 [Google 关于 robots.txt 的说明](https://developers.google.com/search/docs/crawling-indexing/robots/intro)。

## 公开许可的边界

公开技术文档可被自动获取、摘要和引用。此许可不授予 App 源码、商标、软件包或第三方素材的开源许可，不授予读取用户聊天、媒体、记忆、账号资料或受保护 API 的权限。API 描述中的 Bearer token、成员关系、票据和授权检查继续生效；请勿尝试把抓取许可作为绕过访问控制的依据。

完整文本和索引只包含公开文章。原生客户端中的本机记忆、医疗记录、日志、服务配置和数据库均不属于文档内容。法律文件以相应[隐私说明](https://privacy.thestarline.cn/app-privacy.html)与[法律站](https://legal.thestarline.cn/)为准。

## 如何可靠地引用

引用具体文章的 canonical 地址，而不是本地预览、搜索结果或登录回跳 URL。例如讨论加密时引用[安全和隐私](https://document.thestarline.cn/app/security-and-privacy.md)，并保留“当前默认主消息与附件尚未形成全量 E2EE 闭环”的范围说明；讨论功能时区分实现、历史验收和待办。

资料截至 2026-10-23。机器目录含内容摘要值和资料日期；它们用于辨识文档版本，不是签名验证或产品服务等级承诺。更新文档时会重新生成 HTML、原文、搜索、完整文本和站点地图，避免不同入口互相矛盾。

站点地图帮助发现 URL，但提交或提供 sitemap 本身不保证索引，参见 [Google sitemap 文档](https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap)。本次公开发布验证的是公网 HTTP 可读、文件完整与抓取规则；是否被外部平台实际收录仍需其自身结果确认。


原始地址：https://document.thestarline.cn/account/
Markdown：https://document.thestarline.cn/account/overview.md

# 星线账户技术概览

星线账户（Account）负责账户凭据、网页登录、安全设置、个人资料和应用授权。资料依据 2026 年 10 月 23 日 `identity/` 源码整理。账户站为 `https://account.thestarline.cn`，第三方接入见[开放平台](https://document.thestarline.cn/open-platform/)，微信小程序确认见[星线智联](https://document.thestarline.cn/zhilian/)。

## 服务组成与身份边界

服务端使用 Node.js、TypeScript、Fastify 和 MySQL。`identity/server/main.ts` 组装注册登录、协议、开放 API、静态前端与投递工作器；`identity/server/app.ts` 负责请求上下文、来源校验、CSRF、路由限额及统一错误。前端在 `identity/client/`，账户站与开放平台按配置的站点来源识别，不通过任意请求参数切换管理权限。

账户主键是 32 位十六进制字符串。它与聊天服务的用户 UUID、好友码、企业组织 ID 都是不同标识。业务系统应通过授权响应建立自己的映射，不把邮箱或手机号码当作永不变化的主键，也不解析显示名称推断身份。Account Cookie、OIDC 令牌、开放 API 签名密钥、聊天 Bearer 会话分别有独立用途和生命周期。

| 模块 | 可确认的职责 | 源码入口 |
| --- | --- | --- |
| 注册、验证码与密码 | 邮箱注册、手机号注册、登录、重置与风险追加验证 | `identity/server/auth.ts` |
| 会话 | Cookie 令牌摘要、来源与受众隔离、凭据版本、撤销 | `identity/server/sessions.ts` |
| 通行密钥与外部身份 | WebAuthn，微信、QQ、支付宝及小程序身份关联 | `identity/server/passkeys.ts`、`identity/server/providers.ts` |
| 资料与认证 | 名称、规范化头像、个人及企业实名认证申请 | `identity/server/profile.ts`、`identity/server/real-name.ts` |
| 管理与审计 | 角色、应用管理、安全事件、管理员操作保护 | `identity/server/admin.ts`、`identity/server/audit.ts` |
| 授权协议 | OIDC 授权码、同意记录与服务端签名接口 | `identity/server/oidc.ts`、`identity/server/open-api.ts` |

## 注册与登录状态

邮箱注册从 `/api/register/start` 开始，经历邮箱验证码、手机号验证和密码设置后，才能调用 `/api/register/complete`。中间步骤依赖服务端 `transactionId` 与当前浏览器上下文；收到一次验证码成功响应并不等于整个账户已经注册。手机号注册使用 `/api/register/phone/start`，验证手机号后完成注册，首次完成可以签发账户 Cookie；重复完成不会再创建新会话。手机号注册后的账户可以再添加其他凭据。

密码登录与邮箱、手机验证码登录都进入统一风险判断。邮箱验证码、手机验证码和风险验证码发送接口当前均校验 CAPTCHA。邮箱投递使用持久化任务；`request_accepted` 表示请求已受理，不能用来证明目标存在、邮件已送达或用户已登录。风险追加验证响应需要客户端继续执行相应事务，不能提前显示登录成功。

默认账户会话有效期为 28,800 秒，即 8 小时；验证码有效期 300 秒，通用注册事务 1,800 秒，验证码最多尝试 5 次、重发间隔 60 秒。具体协议还可能使用更短的挑战或授权期限。会话认证同时检查令牌摘要、到期、撤销、来源、受众、账户封禁和凭据版本，不以客户端保存了 Cookie 为有效依据。

## 安全设置与资料数据

安全设置提供当前会话、安全事件、登录验证策略、凭据管理及会话撤销。修改密码、绑定联系方式或撤销会话等操作通常先获取短时、单次的重新验证授权 `grantId`。授权绑定当前上下文；更换浏览器、凭据改变或重复使用都会失效。普通用户的单方式验证具有资格检查和期限，拥有管理权限的账户不能据此绕过管理员要求。

管理角色包含 `platform_admin`、`account_admin`、`auditor`。管理员登录方式是否强制为通行密钥，当前由 `IDENTITY_ADMIN_PASSKEY_REQUIRED` 是否精确等于 `true` 决定，不能把生产环境自动等同于强制启用。管理角色也不等于星企的企业所有者或管理员。

资料名称先做 NFC 规范化与首尾清理，最多 32 个 Unicode 字符，拒绝控制和双向文本控制字符。头像仅接受静态 JPG、PNG，解码前原文件不超过 256 KiB、像素总数不超过 1,048,576；服务端重新编码为 512×512 JPEG，清除原图 EXIF、GPS 等元数据。账户头像读取是当前用户私有接口，不是公开头像托管服务。

实名功能有独立开关和人工审核状态。材料格式、文件大小、身份资料加密与审核权限由服务端校验，上传申请不等于通过认证。授权给第三方的 `verification` 声明只提供状态、类型及获批企业名称等摘要，不向第三方下发个人证件材料。

## 存储、配置与运行条件

当前 MySQL 存储按 `001.sql` 至 `007.sql` 执行基础迁移，再处理 PII 与资料等兼容迁移。`IDENTITY_DATABASE_URL` 必需；生产还要求独立的 `IDENTITY_PII_KEY`。联系方式以 AES-256-GCM 加密，并用带用途区分的 HMAC 建立检索值，不能用普通哈希替代可控的联系方式查询设计。密钥标记不匹配时拒绝启动。旧明文迁移要求已核验备份后显式批准；迁移器本身不创建备份。

`IDENTITY_SECRET`、PII 密钥、OIDC 签名密钥有不同用途，恢复资料必须包含数据库与对应密钥的安全托管记录。只恢复数据库、临时重新生成密钥或删掉版本标记不能构成可用恢复方案。生产 OIDC 需要稳定 JWKS 文件；受信代理需要显式地址列表，不接受通配信任。

邮件生产投递走腾讯云 SES，短信走阿里云短信；SMTP 只供非生产使用。手机号校验和实际短信目标当前限制在中国大陆 `+86` 手机号码，界面的地区选项不能证明已支持全球短信。实际部署配置与真实投递需分别验收。

## 验证与已知边界

仓库提供 `identity/tests/auth.test.ts`、`profile.test.ts`、`pii.test.ts`、`oidc-profile.test.ts` 等测试，可通过 `identity/package.json` 的 `test`、`typecheck`、`build` 脚本检查。真实短信、邮件、第三方回调、管理权限与浏览器保持仍需受控环境验证。历史回执仅对应其记录的版本、时间与范围。

账户密码变化会影响 Account 自身凭据版本和相关授权，但不会自动撤销独立聊天服务已签发的会话。原生产品退出时还要区分本机清理和服务端撤销是否成功。当前 Account 实现未提供记忆转出 redeem 接口。接入步骤与失败处理见[账户接口接入](https://document.thestarline.cn/account/integration.md)。


原始地址：https://document.thestarline.cn/account/integration/
Markdown：https://document.thestarline.cn/account/integration.md

# 星线账户接口接入

账户网页接口使用同站 Cookie、精确来源和 CSRF 校验。它们适用于账户前端；第三方业务登录应使用[开放平台](https://document.thestarline.cn/open-platform/)的 OIDC，不要求用户向第三方提交账户密码。资料依据 2026 年 10 月 23 日 `identity/server/` 源码整理，介绍请求顺序、字段与失败边界。

## 建立请求上下文

首先调用 `GET /api/csrf`，保留服务端下发的 CSRF Cookie，并读取返回的 `csrfToken`。后续浏览器写请求同时携带 Cookie、正确 `Origin` 和 `x-csrf-token`。CSRF Cookie 使用 Strict SameSite，期限 3,600 秒；刷新页面后可以重新取得值。请求被来源检查拒绝时，反复更换验证码不会解决问题。

```js
// 在账户站同源页面执行；captchaProof 来自当前 CAPTCHA 验证。
const { csrfToken } = await fetch('/api/csrf', {
  credentials: 'same-origin'
}).then(r => r.json());
const response = await fetch('/api/auth/email-code', {
  method: 'POST', credentials: 'same-origin',
  headers: { 'content-type': 'application/json', 'x-csrf-token': csrfToken },
  body: JSON.stringify({ identifier: 'reader@example.invalid', captcha: captchaProof })
});
const result = await response.json();
```

示例邮箱是合成数据。CAPTCHA 结构以账户前端及 `identity/server/captcha.ts` 为准，不用占位字符串模拟通过。服务端校验 Host 是否属于配置来源；生产要求 HTTPS。普通写请求的正文必须是 JSON 对象。OIDC 协议和签名开放 API 有专门认证机制，小程序只有 inspect、decide 使用单次证明的例外，不应把这些例外扩散到其他路由。

## 注册顺序

| 方法与路径 | 主要输入 | 后续动作 |
| --- | --- | --- |
| `POST /api/register/start` | `email`、`captcha` | 保存 `transactionId`，等待邮箱验证码 |
| `POST /api/register/email/send` | `transactionId`、`captcha` | 仅用于重发，不延长客户端自己计算的期限 |
| `POST /api/register/email/verify` | `transactionId`、`code` | 继续手机号和密码步骤 |
| `POST /api/register/phone/send` | `transactionId`、`phone`、`captcha` | 向事务中的手机号发码 |
| `POST /api/register/phone/verify` | `transactionId`、`code` | 验证当前注册事务 |
| `POST /api/register/password` | `transactionId`、`password` | 设置符合策略的密码 |
| `POST /api/register/complete` | `transactionId` | 以服务端返回确定注册完成 |
| `POST /api/register/phone/start` | `phone`、`captcha` | 开始独立手机号注册流程 |

邮箱注册需要完成邮箱、手机号、密码三项条件。独立手机号注册使用 phone/start 后的事务进行 phone/verify，再 complete；不要额外调用邮箱流程制造第二个账户。注册事务受浏览器上下文约束，不能从另一设备领取。流程未完成返回 `REGISTRATION_INCOMPLETE`，事务失效返回 `INVALID_TRANSACTION`；应按服务端状态回退或重新开始。

密码按 Unicode 码点计 12–128 个字符，同时 UTF-8 编码不超过 512 字节；服务端使用 Argon2id。邮箱会清理并转为小写，手机号按服务端支持范围规范化。客户端可以提前提示格式，但不能跳过服务端结果或把 HTTP 200 的发送受理视为联系方式验证。

## 登录、风险与会话

`POST /api/auth/login` 接受 `method`。密码方式提交 `method:"password"`、`identifier`、`password`；验证码方式提交 `method:"email_code"` 或 `"phone_code"`，以及 `identifier`、`transactionId`、`code`。对应发送入口为 `/api/auth/email-code`、`/api/auth/phone-code`，均需要 CAPTCHA。手机发码还可带服务端给出的关联 `transactionId`。

服务端可能要求追加风险验证，继续调用 `POST /api/auth/risk/send`（`transactionId`、`captcha`）和 `/api/auth/risk/verify`（`transactionId`、`code`）。客户端应保留原事务，不在追加验证过程中重新创建并行登录。未知账户、冷却及部分不可投递状态使用统一发送响应，以减少账户枚举；实际投递基础设施完全不可用时仍可返回 503。

成功后使用 `GET /api/auth/me` 确认身份。返回包含 `user`、当前 `session` 的 `id`、`method`、`createdAt`、`expiresAt`，以及管理与认证能力标志。Cookie 由服务端设置，响应不会把原始会话令牌作为网页 JSON 字段公开。`POST /api/auth/logout` 退出当前 Account 会话；其他产品独立存储的会话需要各自处理。

会话响应中的时间是服务端记录，客户端应按到期时间显示状态，并在受保护操作返回未认证时重新验证。仅隐藏页面、删除某个前端变量或关闭浏览器标签不等于完成服务端会话撤销；网络异常时应保留明确的未确认结果。

## 安全设置、资料与授权

| 操作 | 路由与关键字段 | 约束 |
| --- | --- | --- |
| 查看安全概况 | `GET /api/security` | 返回本人会话与安全事件等 |
| 重新验证 | `POST /api/security/reauth` | 根据 `method` 提交证明，可能继续短信验证；成功才取得 `grantId` |
| 改密码 | `POST /api/security/password`，`grantId,password` | 短时授权不可重复消费 |
| 联系方式变更 | `POST /api/security/contact/send`，`grantId,kind,target,captcha`；随后 `/verify` 提交 `transactionId,code` | kind 仅邮箱或手机号 |
| 撤销会话 | `POST /api/security/sessions/revoke`，`grantId,sessionId`，或 `grantId,target:"others"` | 两个目标字段不能同时使用 |
| 资料更新 | `POST /api/profile`，`displayName` 及可选 `avatar` | 正文字节上限 400,000；不允许额外字段 |
| 资料头像 | `GET /api/profile/avatar` | 当前账户私有，禁止按他人 ID 构造公开地址 |

`avatar` 为 `{mime,data}`，data 是标准 Base64；`avatar:null` 表示删除。更新资料时 `displayName` 应明确传递名称或 null，不能依靠省略字段模拟部分 PATCH。通行密钥的 options/verify 接口位于 `identity/server/protocols.ts`，使用 WebAuthn 原生响应与一次性挑战；不要自行拼装“认证成功”对象。实名认证申请的开关、材料和审核能力与普通资料更新独立。

## 错误、重试与观测

错误格式为 `{error:{code,message},requestId}`。日志可以记录 requestId、路由、时间和错误码，不能记录验证码、Cookie、密码、外部身份 code 或材料正文。

| 状态与代码 | 典型触发 | 处理方式 |
| --- | --- | --- |
| 400 `INVALID_INPUT` / `INVALID_CODE` | 字段无效，验证码错误、过期或已使用 | 修正输入；不要无限重试同一码 |
| 400 `INVALID_TRANSACTION` | 事务到期、上下文或凭据改变、单次证明已用 | 重新开始相应验证 |
| 401 `UNAUTHENTICATED` / `INVALID_CREDENTIALS` | 会话或登录证明无效 | 清理页面认证状态，重新登录 |
| 403 `CSRF_FAILED` / `FORBIDDEN` | Cookie 与头不匹配、来源或权限不符 | 先修复上下文或权限 |
| 403 `RISK_BLOCKED` / `ACCOUNT_BANNED` | 频率风险或账户限制 | 遵循提示，不切换标识规避 |
| 409 `CONFLICT` | 唯一数据冲突 | 刷新当前状态后处理 |
| 503 `DELIVERY_UNAVAILABLE` / `SERVICE_UNAVAILABLE` | 投递未配置或依赖异常 | 有界退避；明确保留“结果未确认” |

限额有全局、来源、目标与路由不同桶，默认窗口 600 秒、基础额度 20；不能把该值解释为全站所有用户合计每十分钟 20 次。发送冷却与接口限额同样存在。发生写请求超时时，先读取当前事务或安全设置核实，不自动重复提交注销、改密等一次性操作。

联调应分别覆盖完整注册、错误验证码与重放、风险追加验证、CSRF、跨浏览器事务、封禁、会话到期、改密后的授权变化、头像边界和投递失败。源码测试、构建成功只能验证其覆盖范围；生产配置、真实投递和第三方平台回调需要单独回执。服务组成与存储要求见[技术概览](https://document.thestarline.cn/account/overview.md)。


原始地址：https://document.thestarline.cn/open-platform/
Markdown：https://document.thestarline.cn/open-platform/overview.md

# 星线开放平台技术概览

开放平台管理第三方应用、OIDC 登录授权、服务端签名 API 和 Webhook，实现与[星线账户](https://document.thestarline.cn/account/)同在 `identity/`，使用账户身份与 MySQL 存储，通过 `https://open.thestarline.cn` 提供独立平台界面。资料依据 2026 年 10 月 23 日源码整理；外部应用接入资格与生产回调需单独验收。

## 三种接入凭据

| 能力 | 使用的证明 | 适用范围 |
| --- | --- | --- |
| OIDC 授权码 | `clientId`、PKCE，机密客户端另用 `clientSecret` | 用户主动登录并同意声明范围 |
| 签名开放 API | `clientId` 与独立 `apiSecret` 的 HMAC | 受控服务端调用，不使用账户 Cookie |
| Webhook | 独立 `webhookSecret` | 接收账户或应用状态事件 |

三类密钥不能互换。公开客户端不保存机密客户端密钥；API 密钥、Webhook 密钥只配置在接入方服务端。创建应用、启用 API 和配置通知目前属于平台管理员操作，不是任何登录用户均可调用的公开自助注册 API。平台管理权限也不由 OIDC 返回的普通用户身份自动授予。

## 应用模型与注册约束

`identity/server/protocols.ts` 的应用模型包含内部 `id`、对外 `clientId`、名称、类型、精确回调列表、允许声明范围、启用状态，以及 API 与通知的独立开关。应用创建时可返回机密客户端的原始密钥，列表接口不返回密钥。密钥在平台数据库中使用服务端保护机制封装；接入方应在创建响应时安全接收并托管。

应用名称上限 120 个字符串长度单位，类型为 `public` 或 `confidential`，回调 1–10 项，权限必须包含 `openid`。可登记 `email`、`profile`、`phone`、`verification`、`management`。回调校验要求规范化后完全相同的 HTTPS URL，无用户信息、片段或通配符；公开客户端的本地开发才可使用带有效端口的本机回环 HTTP。自定义原生 scheme 不能直接登记为此处 OIDC 回调。

应用停用会撤销关联授权状态，并可能发出状态通知。接入方不应因为缓存了一次 clientId、旧授权或成功截图，就假定后续调用仍被允许。应用启用、API 启用、用户有效授权三者是不同判断。

## OIDC 授权与声明

协议实现位于 `identity/server/oidc.ts`，发行者为 `https://account.thestarline.cn/oidc`。发现文档位于该发行者下的 `/.well-known/openid-configuration`。接入端从发现文档读取授权、令牌、UserInfo 与 JWKS 地址，不把账户站网页路由当作协议端点。

当前只启用 `code` 响应类型，所有客户端均要求 PKCE。客户端认证方式为公开客户端 `none` 或机密客户端 `client_secret_basic`。授权码有效期 60 秒；Access Token 和 ID Token 各 900 秒；Grant、协议 Session 各 3,600 秒，交互 300 秒。账户网页登录的 8 小时 Cookie 会话不等于这些协议对象的期限，也不能据此延长访问令牌。

| scope | 可能提供的声明 | 限制 |
| --- | --- | --- |
| `openid` | `sub` | Account 的稳定用户主键 |
| `profile` | `name` | 优先显示名称，可能回落到邮箱名称部分 |
| `email` | `email,email_verified` | 账户确有邮箱时提供 |
| `phone` | `phone_number,phone_number_verified` | 账户确有手机号时提供 |
| `verification` | 认证摘要 | 不包含个人证件材料；企业名称限获批企业 |
| `management` | 管理状态摘要 | 不替代业务系统自己的角色校验 |

最终声明取决于应用登记、实际请求、用户同意和账户资料，不是 scope 名出现就必有非空字段。凭据版本变化、会话撤销、应用停用和封禁检查会影响授权有效性。接入方应验证签名、issuer、audience、nonce 和时间，并使用 `sub` 关联本地用户。

## 签名 API 的数据边界

当前业务路由只有 `POST /api/open/v1/ping` 与 `GET /api/open/v1/users/:id`，不包含批量用户导出、任意资料写入或第三方直接改密。查询用户要求 `users.read`；邮箱、手机号还分别要求 `users.email`、`users.phone`，同时受该用户对该应用 OIDC 同意范围约束。

用户查询还要求存在当前有效的授权门禁和关联 Account 会话，且其凭据版本与账户一致。没有满足条件的授权返回 404，以统一表达“不存在或无权访问”；不能用平台管理员看得到某用户来替代接入应用的用户授权。响应邮箱、电话字段可能省略，接入方应按可选字段解析。

应用配置、用户同意、协议对象和防重放记录分别持久化。删除接入方本地 Cookie 不会主动删除平台应用；停用应用也不等于删除账户。接入方应把本地登录会话、平台授权状态和通知处理记录分开维护，避免把某一层的状态变化误判为其他层已经完成退出或清除。

签名包含请求方法、原始路径与查询串、秒级时间戳、nonce 和原始正文。允许时间偏差 300 秒，nonce 以应用为范围去重。服务端先做来源限额，再核验签名，最后应用级限额；API 请求体最多 16,384 字节。签名细则与例子见[接入与协议细则](https://document.thestarline.cn/open-platform/integration.md)。

## 通知、密钥轮换与运行要求

Webhook 可以发送 `user.banned`、`application.disabled`、`user.closed`、`ping` 等事件，正文含随机事件 `id`、毫秒 `createdAt`、`appId` 和 `data`。请求用独立密钥签名。当前发送实现记录投递结果并返回成功布尔值，没有可据此宣称的持久化重试队列或保证送达机制；接收方应保持自身业务状态可回读、事件幂等和失败监控。

API 密钥轮换给旧密钥 5 分钟重叠期，禁用会清除当前与旧 API 密钥。Webhook 轮换立即更换，不提供同样的旧密钥宽限。通知 URL 在生产需 HTTPS，禁止私网或保留目标、用户密码、片段与通配符；解析结果被固定到实际连接，不跟随重定向。发送超时 5 秒，响应消费有字节上限。

生产依赖 Account 的数据库、PII 和主保护密钥、稳定 OIDC JWKS、精确站点来源及可信代理配置。不要因切换开放平台域名而重建身份库或签名密钥。`identity/tests/open-api.test.ts`、`oidc-profile.test.ts`、`oidc-redirect.test.ts` 验证部分协议契约；真实第三方回调、轮换交接、通知接收与停用传播需要单独联调。


原始地址：https://document.thestarline.cn/open-platform/integration/
Markdown：https://document.thestarline.cn/open-platform/integration.md

# 开放平台接入与协议细则

接入前由平台管理员登记应用类型、精确回调和最小 scope。先完成 OIDC 用户授权，再按实际需要启用签名 API 或通知。三种凭据的区别与数据边界见[技术概览](https://document.thestarline.cn/open-platform/overview.md)；本文依据 `identity/server/protocols.ts`、`oidc.ts`、`open-api.ts` 说明当前契约。

## OIDC 授权次序

1. 读取发行者 `https://account.thestarline.cn/oidc` 的发现文档，保存并验证 issuer，读取协议端点与 JWKS。
2. 为每次登录生成新的 `state`、`nonce` 和 PKCE verifier，保存到发起浏览器或服务端受保护事务。使用 S256 challenge，授权请求带 `response_type=code`、client_id、已登记 redirect_uri 与 scope。
3. 用户在 Account 完成认证和授权后，接入方回调先匹配本地 state，再用 code、原 redirect_uri 和 verifier 换票。机密客户端按发现配置使用 `client_secret_basic`；公开客户端不发送伪造密钥。
4. 验证 ID Token 的 JWKS 签名、issuer、audience、nonce、过期时间，以 `sub` 建立本地账户关联。消费并清除本次事务，拒绝回调重放。

授权码只有 60 秒，交互为 300 秒。丢失 verifier、回调不一致或代码已使用时应重新开始登录，不能尝试另一回调或省略 PKCE。具体协议错误由 OIDC 实现返回，不套用普通 `/api` 的所有 JSON 错误形状。当前没有文档依据可承诺刷新令牌或无限离线授权。

## 管理接口与权限

下列接口均为受保护的管理操作，需平台管理员身份、允许的管理认证方式以及浏览器 CSRF；不能把示例做成接入方公开接口。

| 方法与路径 | 主要字段 | 返回或行为 |
| --- | --- | --- |
| `POST /api/admin/applications` | `name,type,redirectUris,scopes` | `id,clientId`，机密类型另含一次性返回的 `clientSecret` |
| `POST /api/admin/applications/:id/status` | `enabled` 布尔值 | 更新状态，停用撤销授权门禁 |
| `POST /api/admin/applications/:id/api-credentials` | `apiScopes` | 启用并返回 `apiSecret,apiScopes` |
| `POST /api/admin/applications/:id/api-credentials/rotate` | JSON 对象 | 返回新 `apiSecret,previousExpiresAt` |
| `POST /api/admin/applications/:id/api-credentials/disable` | JSON 对象 | 清除 API 密钥并禁用 |
| `POST /api/admin/applications/:id/webhook` | `enabled`，启用时 `webhookUrl` | 配置通知，启用生成密钥 |
| `POST /api/admin/applications/:id/webhook/rotate` | JSON 对象 | 返回新 `webhookSecret`，立即生效 |
| `POST /api/admin/applications/:id/webhook/test` | JSON 对象 | 返回 `delivered`，不等于后续事件保证送达 |

API 与通知只对已启用的机密客户端开放。API scope 必须含 `users.read`，可加 `users.email`、`users.phone`；这些名称与 OIDC 的 `email`、`phone` 是两层权限。用户也可在 Account 撤销应用授权，管理员不应通过重新开 API 开关绕过用户的撤销。

应用内部 id 用于管理路由，clientId 用于协议和签名请求头，二者不能互换。列表只显示配置摘要，不提供取回原始密钥的通用接口。接入方遗失密钥时应按受控轮换流程更新，并核对所有调用实例是否已切换；不要从浏览器缓存、客户端安装包或普通日志寻找和分发旧密钥。创建、轮换响应只在受保护的服务端配置链路接收，避免将其写入业务审计正文。

## HMAC 请求签名

请求头为 `x-starline-key`（clientId）、`x-starline-timestamp`（十进制 Unix 秒）、`x-starline-nonce`（16–128 个字符）和 `x-starline-signature`（64 位十六进制 HMAC-SHA256）。canonical 字符串按以下五行拼接，行间只有一个换行，正文后不额外补换行：

```text
METHOD
原始路径与查询串
timestamp
nonce
原始正文
```

METHOD 使用大写；GET 正文为空。路径不含 scheme 或 host，但保留查询参数原顺序、百分号编码和原始 URL 表达。JSON 签名前后必须发送完全相同的 UTF-8 字节，空格或换行变化也会改变签名。以下为可移植的合成示例，不包含真实应用凭据：

```js
import { createHmac, randomBytes } from 'node:crypto';
const path = '/api/open/v1/ping';
const timestamp = String(Math.floor(Date.now() / 1000));
const nonce = randomBytes(24).toString('base64url');
const body = '{}';
const canonical = ['POST', path, timestamp, nonce, body].join('\n');
const signature = createHmac('sha256', process.env.OPEN_API_SECRET)
  .update(canonical, 'utf8').digest('hex');
const response = await fetch(`https://account.thestarline.cn${path}`, {
  method: 'POST', body,
  headers: {
    'content-type': 'application/json',
    'x-starline-key': process.env.OPEN_CLIENT_ID,
    'x-starline-timestamp': timestamp,
    'x-starline-nonce': nonce,
    'x-starline-signature': signature
  }
});
```

ping 成功返回 `{status:"ok",appId:clientId}`。读取用户改用 `GET /api/open/v1/users/:id`，签名正文为空；id 是已完成该应用授权的 Account 用户主键。返回 `{user:{id,banned,email?,phone?}}`。不要用聊天用户 UUID 替换 Account ID，也不要把字段缺省当成空字符串覆盖已保存资料。

服务端允许时间偏差正负 300 秒；时间戳必须为安全整数。nonce 在每个应用范围内持久化去重，其保存期限与签名窗口相关。同一请求因网络超时需再次发送时，应生成新 nonce、时间戳和签名；这样只更新防重放证明，不意味着可以重复执行未来的非幂等业务接口。当前公开业务路由只含 ping 与读取用户。

## Webhook 验证的特殊约定

通知正文为 `{event,id,createdAt,appId,data}`，createdAt 为毫秒，签名头 timestamp 为秒。接收端必须保存原始正文后再验签，不能先 JSON parse、重排键后重新序列化。

当前 `deliverSignedWebhook` 调用签名函数时，方法固定 `POST`、canonical 路径固定为字面值 `/`。即使配置的接收 URL 是 `https://receiver.example.invalid/events/account`，验签第二行仍应使用 `/`，不是实际请求路径。这是当前源码的协议行为，升级时需与平台同步确认，不能套用普通开放 API 的路径规则。

验签后检查 appId、事件类型与业务目标，按事件 id 去重，再快速返回 2xx。接收端的时间窗、nonce 保存与幂等策略由自己实现，平台不会替接收端建立防重放存储。API 密钥旧值有 5 分钟轮换宽限；Webhook 没有该宽限，双方需要协调切换，或接收端在约定窗口内自行保留旧验签值。

## 失败定位与验证范围

| 结果 | 当前常见原因 | 首要检查 |
| --- | --- | --- |
| 401 `UNAUTHORIZED` | 头缺失、签名错误、时间过偏、nonce 重复、应用或 API 未启用 | 原始字节、时钟、密钥种类与开关 |
| 403 `FORBIDDEN` | 缺少 `users.read` 等 scope | API scope 与用户 OIDC 同意分别核对 |
| 404 `NOT_FOUND` | 用户不存在或授权门禁、关联会话已无效 | 用户主键、会话和用户撤销状态 |
| 400 `INVALID_INPUT` | 非法回调、通知 URL、应用参数，或开放 API 正文超过 16,384 字节 | 精确 URL、类型、数组范围与正文大小 |
| 限额拒绝 | 当前来源、目标或应用限额桶命中 | 降低频率、有界退避，不并发轰炸 |
| `delivered:false` | 网络、非 2xx、目标被阻止或超时 | 接收日志与审计结果，不能假定已自动重投 |

联调至少包含 PKCE 缺失、state/nonce 不匹配、授权码重放、同意范围缩减、会话撤销、签名正文变化、重复 nonce、时钟边界、API 轮换窗口、Webhook 特殊路径、停用与恢复。`identity/tests/open-api.test.ts` 等测试能支持契约复核；真实接入还需接入方回调、通知与密钥轮换的独立验收记录。


原始地址：https://document.thestarline.cn/zhilian/
Markdown：https://document.thestarline.cn/zhilian/overview.md

# 星线智联技术概览

星线智联是用于确认星线账户网页登录请求的微信小程序。它在手机微信中核对发起站点、浏览器和两位核对码，由用户主动确认或取消，再由原浏览器领取结果。工程位于 `identity/mini-program/`，后端桥接位于 `identity/server/wechat-mobile.ts`。资料依据 2026 年 10 月 23 日源码与实施记录整理；联调与发布工作仍处于暂停状态。

## 当前交付与发布状态

开发版本 `0.1.0` 已有历史上传记录，尚未确认提交审核或正式发布。受控记录已验证真实 `wx.login` 到 code2Session 的身份交换；2026 年 10 月 23 日记录还确认手机主动批准、原浏览器领取待绑定凭据通过。领取后仍是原账户会话，没有形成微信新会话，因此完整绑定、微信复登、会话保持与正式 URL Link 唤起仍待验收。开发上传和局部流程通过不能合并成公众登录已可用。

现有记录保持公众入口关闭；配置中的 published、launch 等标志只是服务端开关，不是微信平台审核或发布回执。后续恢复需确认有效事务与真实平台状态，不能继续使用已过期的扫描或确认凭据。更新说明、编译或页面预览不会自动恢复暂停的联调和发布流程。

## 工程与页面

小程序使用原生 JavaScript、WXML、WXSS，没有把网页嵌入 WebView 完成批准。`app.json` 声明首页、确认页和隐私页，网络封装与状态机分别在 `lib/api.js`、`lib/confirmation.js`。工程与网站扫码微信渠道使用不同的小程序身份，不能混填网站应用的 AppID、密钥或授权配置。

| 页面或模块 | 实际行为 | 边界 |
| --- | --- | --- |
| `pages/index/index` | 品牌与隐私入口 | 不调用 wx.login，不创建登录事务 |
| `pages/confirm/index` | 读取短时扫描参数，核对并主动决定 | 无参数或非法参数直接无效，不模拟成功 |
| `pages/privacy/index` | 展示数据处理与公开政策 | 不读取账户资料或发起登录 |
| `lib/api.js` | 固定 Account HTTPS API，调用微信登录与请求 | 不从参数接收任意后端地址 |
| `lib/confirmation.js` | 单次加载、倒计时、批准/拒绝、后台恢复与销毁 | 凭据保存在模块内存，不写页面数据和本地存储 |

首页不会主动索取手机号、昵称、头像。确认过程调用 `wx.login` 获得微信临时 code，不依赖手机号授权来确认网页登录。页面隐藏分享菜单，不提供传播扫描凭据的分享处理；项目没有广告或统计 SDK。公开政策与页面告知仍需在正式审核时和真实后台配置保持一致。

## 三类证明与数据流

服务端创建三个用途分离的随机证明：原浏览器保存 `receiverToken`，手机启动参数携带 `scanToken`，inspect 成功后手机内存保存 `approvalToken`。服务端当前严格校验 43 位 URL-safe 证明，数据库存摘要与加密事务载荷。它们都不是账户长期访问令牌，也不能互换。

1. 原浏览器在 Account 发起事务，保存领取证明与核对信息。
2. 微信打开确认页，页面用 scanToken 和一次性 wx.login code 调用 inspect。
3. 服务端先消费扫描证明，再交换微信身份，创建等待主动确认的审批证明。
4. 手机显示精确 `https://account.thestarline.cn`、浏览器及两位码。点击确认或取消后，单次提交 decide。
5. 原浏览器检查状态，只有批准状态才可 complete。最终登录仍执行账户身份、风险、绑定及凭据版本检查。

小程序确认成功不会取得网页 Cookie，不把登录结果交给其他浏览器，也不自动打开网页。浏览器领取绑定创建事务时的上下文；复制 receiver 到另一浏览器会被拒绝。微信 `session_key` 在服务端校验后丢弃，不返回小程序；UnionID 当前不用于自动合并账户，`wechat_mini` 与网站 `wechat` 是独立身份命名空间。

## 状态、到期与不确定结果

事务逻辑有效期 300 秒。服务端内部状态依次可能为 pending、exchanging、awaiting_confirmation、approved，再由原浏览器消费；取消、过期、交换失败会结束流程。浏览器 status 对前三种中间态统一返回 pending，不应据此认为手机还没有扫描。

小程序有 idle、loading、ready、submitting 及多个终态。ready 时才启用决定按钮；提交前先取走内存中的 approvalToken，两次点击、确认后再取消等操作不会再发第二次决定。倒计时依据服务端毫秒时间戳与本机当前时间计算，不因进入后台而重置。回到前台立即复核绝对期限，卸载页面清除证明、取消请求并忽略迟到回调。

提交决定后断网，或请求在途时跨过本地期限，页面显示结果暂未确认：服务端可能已接受决定，不能简单显示“未批准”并提供重放按钮。用户应返回原浏览器查看。未提交的请求自然到期则显示已过期。这些状态是处理网络与单次证明的实际规则，不能用重新生成页面状态绕过。

## 后端能力与配置

`IDENTITY_WECHAT_MINI_ENABLED` 控制配置参与，`IDENTITY_WECHAT_MINI_PUBLISHED` 和 `IDENTITY_WECHAT_MINI_LAUNCH_ENABLED` 共同参与公众可用判断；受控预览另需 `IDENTITY_WECHAT_MINI_VERIFICATION_ENABLED` 及 Account 管理员认证。上述布尔量都只在精确字符串 `true` 时启用。独立小程序身份和服务端密钥必须配置在后端，不能进入小程序包。

公众 start 在具备条件时请求微信正式 URL Link，指向 `pages/confirm/index`，只携带扫描证明。返回链接仅接受微信 `wxaurl.cn` HTTPS 形式。受控 preview/start 返回开发工具可用页面路径，仍受管理员身份与来源校验保护，不能当作公开入口或审核可访问方案。

## 验证与后续范围

项目有 `api.test.js`、`confirmation.test.js`、`pages.test.js`，覆盖参数、固定来源、单次决定、凭据不进入页面数据、后台与迟到响应等契约；`scripts/validate.js` 检查工程、语法与上传排除项。账户端另有 `identity/tests/wechat-mobile.test.ts` 和 `wechat-mini-adapter.test.ts`。这些测试与原生编译不代替真实微信身份和原浏览器回程。

恢复后的必要验收包括 iOS、Android 微信真实流程，新旧绑定身份、明确拒绝、过期、扫描与审批重放、断网、后台返回、原浏览器独占领取及登录保持。已通过的手机批准与待绑定领取仍需与完整身份绑定、复登结果分别记录；之后才是审核、正式发布和正式入口复核。具体路由、错误与联调次序见[智联接入流程](https://document.thestarline.cn/zhilian/integration.md)，账户会话边界见[星线账户](https://document.thestarline.cn/account/)。


原始地址：https://document.thestarline.cn/zhilian/integration/
Markdown：https://document.thestarline.cn/zhilian/integration.md

# 星线智联接入流程

智联的接入方是 Account 原浏览器及固定微信小程序，不是任意第三方登录 SDK。所有后端路由使用 `https://account.thestarline.cn`，路径前缀为 `/api/providers/wechat/mobile`。资料依据 2026 年 10 月 23 日 `identity/server/protocols.ts`、`wechat-mobile.ts` 和 `identity/mini-program/lib/` 整理；目前联调暂停、开发上传未审核，完整流程仍待验收。

## 能力发现与发起条件

`GET /api/auth/methods` 当前返回 `wechatMobile.available`。网页应按当前响应显示入口，不根据工程内存在确认页、旧上传记录或单个 enabled 标志判断可用。服务端公众可用判断要求独立小程序配置完整、与网站微信身份不同、enabled、published、launchEnabled 均满足。

发起、状态、取消、领取和绑定是浏览器操作，仍要求 Account 来源、Cookie、CSRF 与上下文绑定。只有小程序 inspect、decide 使用单次证明免除浏览器 Cookie CSRF；若它们携带 Origin，仍只允许账户来源。这不是整个前缀免鉴权。受控预览入口另要求已认证的 Account 管理员及允许的管理登录方式。

| 方法与完整路径 | 输入 | 返回或含义 |
| --- | --- | --- |
| `POST /api/providers/wechat/mobile/start` | `intent:"login"` | `receiverToken,verificationCode,expiresAt,interval,launchUrl` |
| `POST /api/providers/wechat/mobile/preview/start` | `intent:"login"` | 管理员受控路径，返回 `previewPath`，不返回正式 URL Link |
| `POST /api/providers/wechat/mobile/inspect` | `scanToken,code` | `approvalToken,targetOrigin,browser,verificationCode,expiresAt` |
| `POST /api/providers/wechat/mobile/decide` | `approvalToken,decision` | `status:"approved"` 或 `"cancelled"` |
| `POST /api/providers/wechat/mobile/status` | `receiverToken` | 当前 `status,expiresAt` |
| `POST /api/providers/wechat/mobile/complete` | `receiverToken` | 返回 `redirect`，进入账户登录或待绑定处理，可能设置浏览器 Cookie |
| `POST /api/providers/wechat/mobile/cancel` | `receiverToken` | 取消尚可取消的事务 |
| `GET /api/providers/wechat/mobile/pending` | 无正文 | 查询当前浏览器是否有待绑定身份 |
| `POST /api/providers/wechat/mobile/bind` | `grantId`，以及当前浏览器待绑定 Cookie | 将待绑定小程序身份关联到已验证账户 |

expiresAt 为 Unix 毫秒，interval 单位为秒，当前为 5。服务器状态轮询有单独路由额度，但并不取消全局与来源限额；不要把 160 的路由配置理解为允许无限并发请求。

## 浏览器与手机的操作次序

1. 原浏览器取得 CSRF 后 start，内存保留 receiverToken、服务端 expiresAt 和两位 verificationCode。仅把服务端允许的 launchUrl 用于微信唤起，不拼接任意外部网址。
2. 确认页校验 scanToken 后只执行一次 wx.login，将 code 与扫描证明传给 inspect。缺失、非法参数时不执行 wx.login，不调用后端。
3. 服务端先锁定 receiver，再锁扫描证明，消费 scan 后才调用微信交换。交换成功返回短时 approvalToken；扫描证明已用，不能因页面刷新自动重放。
4. 小程序验证 targetOrigin 必须精确等于账户 HTTPS 来源，verificationCode 为两位数字字符串，expiresAt 为正的安全整数毫秒值，展示后才允许用户决定。
5. 用户点击确认或取消，发出一次 decide；decision 只能 `approve` 或 `deny`。响应应与本次决定匹配。小程序结束后提示手动返回原浏览器。
6. 原浏览器按间隔读取 status，approved 后 complete。完成时再次核对微信绑定与账户凭据版本，并原子消费 receiver，重复领取被拒绝。

合成请求体只表达结构，不能作为实际可用凭据：

```json
{"scanToken":"<本次页面收到的单次扫描证明>","code":"<本次wx.login临时code>"}
```

```json
{"approvalToken":"<inspect返回且仅保存在页面内存的证明>","decision":"approve"}
```

这些字符串不应出现在日志、截图、分析事件、`setData`、Storage 或复制分享内容中。小程序不接收 receiverToken；浏览器不凭 approvalToken 直接换会话。两位核对码只用于人工核对，不是决定接口的身份凭据。

## 状态机与绑定

| 服务端状态 | 浏览器 status 可见值 | 客户端动作 |
| --- | --- | --- |
| pending / exchanging / awaiting_confirmation | pending | 继续有限轮询，等待明确决定 |
| approved | approved | 原浏览器调用 complete |
| cancelled | cancelled | 停止，用户可重新开始新事务 |
| failed | failed | 停止并报告失败，旧证明不可再用 |
| 超过期限 | expired | 重新开始，不延长本次事务 |
| 已消费 receiver | 错误响应 | 不再重复领取 |

inspect 成功时保存的预期绑定包含当时关联的用户与凭据版本。等待期间有人解绑、改凭据或改变身份关联，complete 会重新检查，防止旧批准继续生效。未绑定身份进入 Account 的后续登录/绑定处理；批准本身不会自动创建一个已验证的业务账户。通用 `/api/providers/:provider/start` 不是小程序启动入口；移除已绑定身份则走相应 provider/remove，并受重新验证与最后凭据保护约束。

## 网络与错误处理

API 封装 wx.login 超时为 10 秒，请求超时为 15 秒；服务端访问微信也有限时和响应大小校验。小程序只显示本地固定提示，不原样呈现后端错误内容。调用方可按错误码定位，但不得记录携带的证明。

| 状态与代码 | 触发场景 | 处理 |
| --- | --- | --- |
| 400 `INVALID_TRANSACTION` | 证明格式不符、到期、已消费、状态不允许 | 返回原浏览器开始新请求 |
| 403 `CONTEXT_CHANGED` | 换浏览器领取 | 使用原发起浏览器，不转发 receiver |
| 403 `FORBIDDEN` / `CSRF_FAILED` | 非账户来源、管理员门禁或浏览器证明错误 | 核对来源、会话及能力范围 |
| 401 `INVALID_CREDENTIALS` | 等待期间微信绑定已改变 | 重新验证，不套用旧批准 |
| 502 `PROVIDER_FAILED` | 微信交换或 URL Link 获取失败 | 核对微信平台条件与服务端审计，重新发起 |
| 503 `PROVIDER_UNAVAILABLE` | 当前模式未开通 | 保持入口关闭，不虚报 published |

decide 提交后断网或在途跨期为 uncertain，不能自动再次提交批准；服务器可能已接受。检查原浏览器状态后再决定是否开始新事务。页面卸载取消本地请求不代表服务端已经撤销决定；需要原浏览器 cancel 才能按服务端规则改变事务。进入后台也不增加五分钟有效期。

## 检查与发布范围

在 `identity/mini-program/` 可使用 `npm test`、`npm run validate` 检查状态机与工程；账号服务测试在 `identity/tests/wechat-mobile.test.ts`、`wechat-mini-adapter.test.ts`。开发者工具编译、游客预览和合成 UI fixture 分别验证结构与显示，不能证明真实身份、审批或 Cookie 保持。

正式接入还需核对小程序主体、请求合法域名、独立服务端身份、隐私保护指引、体验与审核可执行入口，以及微信正式 URL Link 能力。现有记录已验证手机批准及原浏览器领取待绑定凭据，仍需完成实际绑定、微信复登与会话保持，再按真实审核号与发布回执记录状态。现有 `0.1.0` 开发上传不能替代这些回执，暂停流程需另行恢复。范围说明见[技术概览](https://document.thestarline.cn/zhilian/overview.md)。


原始地址：https://document.thestarline.cn/xingqi/
Markdown：https://document.thestarline.cn/xingqi/overview.md

# 星企技术概览

星企是独立的企业协作客户端，拥有 iOS、Android 工程，与[星线 App](https://document.thestarline.cn/app/)共享聊天服务的账户映射与部分基础设施。企业 API 位于 `chat-service/src/enterprise-routes.mjs`，并不因此成为星线 App 的前台功能。资料依据 2026 年 10 月 23 日源码整理；两端界面仍标记开发预览，正式企业服务及商店发布不能由源码或本机样例推定。

## 工程与服务边界

iOS 工程在 `xingqi-ios-app/`，使用 Swift、SwiftUI、URLSession 与独立安全凭据存储；Android 工程在 `xingqi-android-app/`，使用 Kotlin、Compose。二者 application/bundle 标识为 `cn.thestarline.xingqi`，与个人聊天产品分离。iOS 当前面向 iOS 17 及以后，Android 最低 API 26，编译与目标 API 35；构建元数据仍需随发布重新核对。

共享服务把 Account OIDC 用户映射为聊天用户，再使用聊天 Bearer 会话访问企业路由。Account 用户主键、聊天用户 UUID、组织 UUID 和消息序号各自独立。企业角色存储在企业成员关系中，与 Account 的平台管理员角色不相互授予。

| 模块 | 当前数据与操作 | 服务端实现 |
| --- | --- | --- |
| 企业空间 | 创建、列出、选择组织，读取聚合工作区 | `enterprise/organizations.mjs` |
| 通讯录 | 部门、成员角色、职务、企业名片 | `enterprise/core.mjs`、`organizations.mjs` |
| 邀请与入企 | 有效期邀请码、预览、申请、审批、记录 | `enterprise/admissions.mjs` |
| 企业会话 | 全员群、同事单聊、成员群、文本、未读 | `enterprise/channels.mjs` |
| 工作内容 | 待办、公告与已读、HTTPS 办公服务入口 | `enterprise/content.mjs` |
| 数据约束 | 企业外键、成员关联、消息去重与历史边界 | `enterprise/schema.mjs`、`content-schema.mjs` |

以上路径均相对 `chat-service/src/`。当前未提供企业附件上传、音视频会议、考勤、网盘、企业认证审批或端到端加密主链路；不能把个人 App 的其他接口、占位页面或企业认证“待开放”界面写成已实现企业能力。

## 企业、成员与权限

创建组织时，服务端在同一事务创建组织、owner 成员和唯一 general 全员群。成员角色为 owner、admin、member。owner 可以给非所有者设置 admin/member；admin 不能提升自己、改所有者角色或移除其他管理员；所有者不能通过普通移除接口删除。部门、成员和服务均限定当前组织，不能只凭一个有效对象 ID 跨企业操作。

本人名片 PATCH 只接受 `name`，名称为 1–80 个 Unicode 字符的单行文字，null 恢复为账户名称。企业通讯录同时返回 accountName、cardName 与解析后的 displayName。名片是组织内资料，不修改 Account 全局名称，也不把一个企业的昵称带到另一个企业。管理者修改成员时还可维护部门、职务和受权限限制的角色。

邀请由管理者创建，随机码有效期 3 天，数据库只存摘要；它可以被多位同事使用，但仍需要管理者审批。预览只确认企业、期限和本人状态，不直接加入。申请人不能审批自己的申请，已决定的申请不能改为相反结果。重新申请需要新的有效邀请，不能复活已处理的旧记录。

## 会话与可见历史

会话类型为 general、direct、group。创建同事单聊要求最终恰好两名当前企业成员，同一对成员以稳定键复用会话。群会话也只能选择当前企业成员；企业成员资格并不自动提供某个专用群的访问权限，还要检查频道成员关系。

成员加入频道时保存 `visible_after` 历史边界和 `last_read`。新入企成员进入全员群只能看到加入边界后的消息；移除成员会通过外键清理其频道资格，重新加入时不会据此重新获得早期历史。消息列表最多 100 条，通过 `before` 向前翻页，按时间序号升序返回本页；消息 ID 是 JSON 字符串，客户端不应按字典序比较。

发送仅接受文本 `body` 与 `clientId`。服务端以频道、发送者、clientId 去重；同一内容重试返回原消息，换正文却复用 ID 返回冲突。未读计数排除本人发送的消息，并受个人可见边界与已读位置限制。企业消息没有单独事件游标或 WebSocket 推送接口，两端通过轮询更新工作区和当前会话。

## 待办、公告与办公入口

任意成员可以创建待办，指派对象必须是当前企业成员。管理者和创建者可以修改完整内容或删除；仅作为被指派人的普通成员只能更新完成状态。标题最多 120 字符，备注 4,000 字符，dueAt 是可空的安全整数毫秒时间，isCompleted 是布尔值。

公告由管理者发布、删除，所有企业成员可以标记已读。已读关系去重，重复打开不增加人数。标题最多 120 字符、正文 10,000 字符。服务入口由管理者维护，名称最多 80 字符、URL 最多 2,000 字符，只接受不嵌入账号密码的 HTTPS 地址，并拒绝控制字符等危险表达。

iOS 办公服务在非持久化网站数据容器中打开，Android 使用外部系统浏览器；不会把企业 Bearer 令牌注入外部网站。服务卡片是网址入口，不代表星企代理了该网站的认证、数据、审批或可用性。

## 客户端隔离与验收边界

两端使用会话与企业选择代次隔离异步响应，切换账号或企业时清除工作区、频道、草稿和待处理动作，避免旧请求覆盖新企业。401 需要处理账户会话；403 可能只是成员或管理权限变化，通常重新读取组织与当前角色，不能把它一律等同于 Account 全局退出。

当前星企登录仍从 `GET /auth/start?app=xingqi` 进入浏览器，回到 `xingqiworkbench://auth` 后只以 ticket 换票。聊天服务到 Account 的 OIDC 有 PKCE，但两端没有采用星线 App 已有的 `/auth/native/start` 原生附加 proof；不能宣称二者登录实现完全一致。

仓库有 iOS 契约、消息排序、企业隔离、退出持久化及 UI 测试，Android 有领域与企业流程等测试，服务端另有企业模块测试。本机专用样例入口仅用于隔离预览，生产 `/__preview/enterprise/session` 明确返回 404。历史测试记录不构成真实 Account 登录、跨网络企业业务或商店审核通过。具体接口与联调方法见[星企接入细则](https://document.thestarline.cn/xingqi/integration.md)。


原始地址：https://document.thestarline.cn/xingqi/integration/
Markdown：https://document.thestarline.cn/xingqi/integration.md

# 星企接口与客户端接入

星企业务接口由共享聊天服务提供，正式目标来源配置为 `https://chat.thestarline.cn`。请求使用聊天服务签发的 Bearer 会话，企业范围写入路由路径。不要使用 Account Cookie、OIDC Access Token 或开放平台 HMAC 密钥直接调用企业路由。模块边界见[技术概览](https://document.thestarline.cn/xingqi/overview.md)。

## 登录与本机恢复

当前 iOS、Android 都打开 `GET /auth/start?app=xingqi`。聊天服务保存自己的 OIDC state、verifier，并把用户送到 Account；回调在服务端换取账户资料，再生成短时 ticket，重定向到 `xingqiworkbench://auth?ticket=…`。客户端调用 `POST /auth/exchange`，正文为 `{ticket}`，成功返回 `accessToken,expiresAt,user,eventCursor`。eventCursor 是共享聊天会话返回字段，企业频道本身不使用它分页。

ticket 为单次使用，当前服务端有效期 60 秒；聊天会话有效期 24 小时。星企两端未接入 `/auth/native/start` 的原生 codeChallenge/state/codeVerifier 附加证明，不能把星线 App 的完整原生 PKCE 方案照搬为当前星企事实。回调错误、丢票或过期应重新开始登录，不保存或分享回调 URL。

iOS 把会话保存到独立安全存储，并用退出意图标记阻止旧会话恢复；恢复验证失败会清除当前登录。退出先做本机清理，再请求 `/auth/logout`，网络失败会提示服务端注销尚未确认。Android 也区分本机退出与远程请求结果。退出界面成功不能证明旧服务端会话已撤销；Account 改密码同样不自动撤销独立聊天会话。

## 工作区初始化与基础路由

先 `GET /enterprise/organizations`，选择组织后调用 `GET /enterprise/organizations/:org`。聚合响应包含 organization、members、departments、channels、tasks、announcements、services；管理者还收到 joinRequests、invitations，普通成员对应数组为空。客户端切换企业时应取消旧请求、清除旧状态，再处理新响应。

| 方法与路径 | 主要输入 | 结果与权限 |
| --- | --- | --- |
| `POST /enterprise/organizations` | `name`，1–80 字符 | 201 `{organization}`，创建者为 owner |
| `PATCH /enterprise/organizations/:org/members/me/card` | `name`，字符串或 null | 200 `{member}`，只允许本人名片字段 |
| `POST /enterprise/organizations/:org/departments` | `name` | 201 `{department}`，管理者 |
| `PATCH /enterprise/organizations/:org/departments/:id` | `name` | 修改本企业部门 |
| `DELETE /enterprise/organizations/:org/departments/:id` | 无业务正文 | 删除部门，清空成员部门关联 |
| `PATCH /enterprise/organizations/:org/members/:id` | 可选 `role,departmentId,jobTitle,cardName` | 管理者操作，角色另受 owner 约束 |
| `DELETE /enterprise/organizations/:org/members/:id` | 无业务正文 | 受保护的移除，不能移除所有者 |

没有独立公开的“跳过审批加入组织”接口。邀请创建为 `POST /enterprise/organizations/:org/invitations`，返回 `id,code,expiresAt`；撤销用相同前缀加 `/:id` 的 DELETE。接收者先 POST `/enterprise/invitations/preview` 提交 `{code}`，再 POST `/enterprise/join-requests` 提交同一结构。已有成员返回 joined，有效申请为 pending。

申请列表 `GET /enterprise/join-requests` 最多返回 100 项，状态还可能为 approved、rejected、invalid、removed。管理者以 `POST /enterprise/organizations/:org/join-requests/:id` 提交 `{approve:true}` 或 false。重复相同决定可成功，相反决定返回冲突；申请被同意后才建立成员与全员群资格。

## 企业消息协议

创建频道为 `POST /enterprise/organizations/:org/channels`，输入 `kind:"direct"|"group"`、`memberIds`，群还需要 name。memberIds 输入 1–200 项，不能重复，服务端自动包含发起人；这不是“最终频道人数固定最多 200”的等价表达。单聊最终必须两人，群至少两人，所有成员均须属于当前企业。

```sh
curl 'https://chat.thestarline.cn/enterprise/organizations/<组织ID>/channels/<频道ID>/messages' \
  -H 'Authorization: Bearer <聊天会话令牌>' \
  -H 'Content-Type: application/json' \
  --data '{"body":"请核对合成示例任务","clientId":"example_message_001"}'
```

上例是结构示范，不对应真实组织或令牌。消息正文为清理首尾空白后的非空文本，最多 2,000 个 Unicode 字符；请求 JSON 上限 32,768 字节。clientId 为 1–128 位字母、数字、下划线或连字符，应在本次发送操作生成并持续复用。同一正文重试成功为 200，首次创建为 201；二者均返回 `{message}`。

消息字段包含字符串 `id`、channelId、senderId、senderName、body、clientId、createdAt。读取使用相同路径 GET，可加 `?before=<正整数消息序号>`，每次最多 100 条、本页升序。before 必须能表示为安全整数；不可传 ISO 时间或普通聊天事件 cursor。`POST .../channels/:id/read` 用 JSON 对象标记到服务器当前最新消息，无客户端 lastMessageId 参数。

## 待办、公告和服务

| 操作 | 路由尾部（均在 `/enterprise/organizations/:org` 下） | 输入与规则 |
| --- | --- | --- |
| 创建待办 | `POST /tasks` | `title,notes,dueAt,assigneeId`；创建时未完成 |
| 更新待办 | `PATCH /tasks/:id` | 管理者/创建者可改内容，被指派的普通成员仅可传 `isCompleted` |
| 删除待办 | `DELETE /tasks/:id` | 管理者或创建者 |
| 发布公告 | `POST /announcements` | `title,body`，管理者；请求上限 131,072 字节 |
| 公告已读 | `PUT /announcements/:id/read` | JSON 对象，重复不增加读者 |
| 删除公告 | `DELETE /announcements/:id` | 管理者 |
| 添加服务 | `POST /services` | `name,url`，管理者，仅合规 HTTPS URL |
| 删除服务 | `DELETE /services/:id` | 管理者 |

待办 notes 可为空字符串，dueAt 可以为 null 或非负安全整数毫秒值，assigneeId 必须是有效企业成员；待办请求上限 65,536 字节。不要发送网页日期字符串或把“未设置”写成 undefined 后期待服务器自动填充。服务链接只保存地址，不接收账户令牌，也不让外部页面继承企业会话。

## 失败与客户端一致性

错误形状为 `{error:{code,message}}`，应结合 HTTP 状态判断。401 表示聊天会话无效；403 `FORBIDDEN` 可能是组织资格、频道成员或管理权限变化，需要刷新相关作用域。400 `INVALID_MEMBER`、`INVALID_ASSIGNEE`、`INVALID_DEPARTMENT` 表示对象不属于当前企业；不能以另一企业 ID 重试。

400 `INVALID_CURSOR`、`INVALID_CLIENT_ID` 要修正参数；409 `CLIENT_ID_REUSED` 表示同一发送编号用于不同正文或加入前旧消息，需要核对待发送记录后决定新操作。409 `DUPLICATE_DEPARTMENT`、`DECISION_CONFLICT`、`INVITATION_ALREADY_USED` 应读取最新状态，不自动覆盖。400 `INVALID_INVITATION` 可能为格式错误、到期或撤销，需新的有效邀请。

企业工作区通过轮询更新，iOS 工作区约 8 秒、当前频道约 3 秒；Android 以 3 秒节拍更新频道、约每三个节拍刷新工作区。它不是强实时推送承诺。异步结果需校验当前会话和企业代次；被移除、切换企业和退出后返回的旧响应不能重新填充页面。消息未知结果可使用原 clientId 重试，审批未知结果先查申请状态。

## 验证与发布要求

应覆盖不同企业同名对象、越权 ID、移除后读取、重新加入历史边界、消息重试及换正文冲突、邀请过期和反向审批、待办角色权限、公告重复已读、退出存储失败、切换企业迟到响应及外部网站隔离。测试入口可从 `xingqi-ios-app/Tests/`、`xingqi-ios-app/UITests/`、`xingqi-android-app/app/src/test/` 与 `chat-service/tests/` 查阅，历史报告只按原日期解释。

模拟器样例不能验证正式 Account 回调、真实组织数据、跨网络轮询或商店发布。生产 `/__preview/enterprise/session` 明确不存在，不向接入者提供绕过登录的演示凭据。发布前需分别取得真实身份回调、企业业务与原生设备验收记录。


原始地址：https://document.thestarline.cn/cloud/
Markdown：https://document.thestarline.cn/cloud/overview.md

# 星线云技术概览

星线云包含公开产品页面、资源配置与风险提示、本机演示控制台，以及接入 Account 的服务端登录适配层。登录会话与演示资源是两套独立状态：取得身份不代表已经购买、创建或接管真实云服务器。

## 入口与组件

公开入口为 [星线云](https://cloud.thestarline.cn/)。当前源代码由原生 HTML、CSS、JavaScript 和 Node.js 服务组成。

| 组件 | 实现职责 | 数据来源 |
| --- | --- | --- |
| 产品与配置页 | 选择实例系列、地区、系统、资源与期限 | 静态模型和 URL 参数 |
| 控制台 | 实例列表、详情、订单、操作记录、帮助 | 浏览器本机演示状态 |
| 认证适配层 | 登录跳转、回调、会话、退出、管理能力检查 | Account OIDC |
| 静态服务 | 文件白名单、路径检查、响应头 | 公开站点文件 |

配置模型包含 `family`、`region`、`os`、`vcpus`、`memory`、`storage`、`bandwidth`、`duration`。系列为 `general`、`compute`、`memory`、`performance`；期限为 1、3、6、12 个月。模型允许的资源范围分别为 1–64 vCPU、1–256 GB 内存、20–2048 GB 存储和 1–1000 Mbps 带宽。这些是输入与展示规则，不能据此推断某地区的可售库存或交付承诺。

重复 URL 参数、非正整数和超界资源会进入校验或提示流程。性能等级按照所选资源计算；风险说明要求结合真实工作负载测试。等级与提示不构成跑分、实时监控或服务等级协议。

## 演示控制台的数据流

页面从 `starline-cloud-console-demo-v1` 读取本机状态，恢复失败时使用初始化状态。模型带 `version: 1` 和 `mode: "demo"`，包含实例、订单、事件；演示实例的地址标记为“未分配（演示）”，订单金额可以为 `null` 并处于待确认价格状态。

开机、关机、重启和重命名先检查当前实例状态，再更新本机副本与事件记录。名称限制为 1–40 个字符，并拒绝控制字符。监控曲线来自固定样例序列。切换异常展示不会改变已存状态；浏览器禁止本机存储时，页面仍可操作，但修改仅在当前页面生命周期内保留。

因此刷新后的状态一致性只属于当前浏览器存储，不是跨设备账户同步。页面没有实现真实资源创建、远程终端、计费扣款或支付后自动开通链路；接入真实资源前，需要补齐服务端资源归属、幂等操作、审计和真实监控接口。

## Account 登录契约

认证接口位于 `/cloud/api/auth/`，响应禁止缓存。浏览器只持有不透明会话 Cookie，上游访问令牌留在服务端内存。

| 路径 | 方法 | 行为 |
| --- | --- | --- |
| `session` | GET | 返回配置状态、登录状态；已登录时含展示资料、CSRF 值与 ISO 时间格式的到期时间 |
| `login` | POST | 创建带 state、nonce、校验材料和 10 分钟期限的登录流程，返回授权 URL |
| `callback` | GET | 验证流程绑定、唯一参数、state 与 issuer，交换身份后跳回允许的控制台地址 |
| `logout` | POST | 删除本地会话，并尝试撤销上游令牌 |
| `management` | GET | 重新验证身份与 `cloud.admin.read` 管理能力 |

登录和退出要求精确匹配站点 Origin；已有会话的退出还校验 CSRF。`next` 只允许控制台路径与受限片段，不允许任意外站跳转。HTTPS Cookie 使用 Secure、HttpOnly、SameSite=Lax，并限定认证路径。流程与会话存于进程内 `Map`，进程重启会丢失；多进程部署需要另行设计共享存储或固定会话归属。

上游明确返回身份失效时会清除会话；临时不可用会返回错误，不能解释成用户主动退出。退出在本地立即生效，上游撤销失败不会阻止清除本地状态。管理能力接口的存在不代表资源管理 API 已实现。

## 失败、配置与验证边界

服务端只允许配置好的 Host，拒绝越界路径、隐藏路径、非白名单扩展和不支持的静态写入方法。认证未配置、流程过期、用户取消、上游异常、权限不足和流程容量达到上限分别进入对应错误或回调提示。客户端凭据及会话材料不能放入前端配置。

资料依据 2026-10-23 源码整理。模型和认证相关测试只能覆盖对应实现，实际部署仍需验证认证闭环、进程重启后的会话表现及上游故障处理；真实实例操作需要另行实现和验收。支付产品边界见 [星线 Pay](https://document.thestarline.cn/pay/)，公开支持入口见 [支持中心](https://document.thestarline.cn/support/)。

## 源码依据

主要实现为 `cloud/server.mjs`、`cloud/server/auth.mjs`、`cloud/server/oidc.mjs`、`cloud/server/management.mjs`、`cloud/purchase-model.js`、`cloud/console-model.js`、`cloud/dashboard.js` 与 `cloud/account.js`。页面行为应以这些实现与实际验收结果共同确认。


原始地址：https://document.thestarline.cn/email/
Markdown：https://document.thestarline.cn/email/overview.md

# 星线 Email 技术概览

星线 Email 提供公开邮箱入口、工作空间域名与邮箱管理、网页收发信和管理功能。网页服务负责身份、权限和元数据，邮件协议与邮箱内容由 Mailu、IMAP 和 SMTP 链路承载；网页可打开不等于邮件已能送达外部收件人。

## 入口与架构

公开入口为 [星线 Email](https://stline.cn/)，个人邮箱域名为 `stline.cn`，协议主机默认 `mx.thestarline.cn`。服务端要求 Node.js 24 或以上，使用 TypeScript、Fastify、SQLite、ImapFlow、Nodemailer；客户端使用 React 与 Vite，构建后由同一服务提供静态文件。

| 层 | 主要数据与职责 |
| --- | --- |
| 网页客户端 | 邮箱、文件夹、邮件阅读与编辑、域名和邮箱管理 |
| 平台服务 | 工作空间、成员、会话、域名验证、配额、草稿、审计和发送计数 |
| Mailu 管理接口 | 创建和管理真实域名、邮箱、别名等协议侧资源 |
| IMAP / SMTP | 列表、正文与附件读取，邮件投递请求 |

SQLite 启用 WAL、外键与忙等待，记录工作空间、用户、会话、域名、邮箱、别名、审计、发送用量和注册预留等元数据。邮件正文不能从这些平台表推断为完整备份；正式邮箱内容依赖协议侧存储。本机进程中的工作空间互斥只约束同一服务进程，不是分布式锁。

## 身份、授权与会话

工作空间管理身份与具体邮箱的协议访问凭据分开管理。管理接口按工作空间限制查询和修改，普通邮箱成员不能取得客户管理权限；被暂停的工作空间会被拒绝。邮箱禁用或密码变更会更新认证版本并撤销相关会话，不能继续使用旧的邮箱凭据缓存。

平台会话默认 24 小时，存储令牌摘要；打开邮箱时，服务端将用于协议登录的密码加密后绑定会话与邮箱认证版本，默认 2 小时到期。该机制服务于服务端连接 IMAP/SMTP，不是邮件端到端加密。修改邮箱密码需要当前密码，完成后要求重新登录邮箱。邮箱退出与整个平台会话退出是不同操作。

生产配置拒绝演示模式，要求精确 HTTPS Origin 和合格的凭据加密密钥。默认 IMAP 为 993，SMTP 为 465 并启用 TLS；受信代理范围须显式配置，不能将任意来源都视作可信代理。密钥与 Mailu 管理凭据只属于服务端配置。

## 域名和邮箱的创建流程

1. 客户在工作空间内添加域名，取得 `_starline-verification.<域名>` TXT 验证要求。
2. 服务端查询并核对所有权证明。已被其他工作空间有效占用的域名不能重复认领。
3. 验证通过后调用 Mailu 创建协议侧域名，成功后才进入可用状态。
4. 分别检查 MX、SPF、DKIM、DMARC；所有权验证与投递 DNS 状态是不同结果。
5. 在已启用域名下创建邮箱，检查本地部分、密码与配额；分配总额不能超过工作空间配额。

邮箱本地部分按小写 ASCII 校验，长度 1–64，不接受连续句点。别名目的地址必须是当前工作空间内有效邮箱，最多 50 个；仍被别名引用的邮箱需要先处理引用关系再删除。公开个人邮箱域名受保护，不能由普通客户接管。

## 邮件、草稿与附件

邮件身份由 `folder`、`uidValidity`、`uid` 共同确定，UID 不能当作跨文件夹永久 ID。列表每页读取 50 封；读取、标记和附件请求均重新校验会话、邮箱与文件夹上下文。网页支持回复、全部回复、抄送、密送、转发、星标、归档和草稿。

默认附件总大小配置为 20 MiB，每次最多 10 个文件，仍受上游邮件服务器大小限制。发送时将收件、抄送和密送地址规范化去重，三类合计最多 20 个收件人。草稿按工作空间和邮箱隔离；其字段包括收件人、抄送、密送、主题、文本和附件描述。草稿中的每类地址数组最多 20 项，主题最多 998 字符，文本的字符串长度上限为 1048576，按 JavaScript 字符串长度校验；不能把它直接换算为 UTF-8 字节，也不能把网页限制当作所有外部 SMTP 客户端的限制。

发送计数按收件人数计算，包含网站发送流程中的不确定结果；外部 SMTP 客户端的用量需要协议侧另行限制。SMTP 接受请求只表示上游受理，最终投递、退信和垃圾邮件判定仍可能不同。发送成功后保存“已发送”副本失败时，不能自动重新发送邮件，否则可能造成重复投递。

## PWA、默认值与失败处理

PWA 缓存只覆盖公开页面壳、清单和静态资源，跳过 `/api/`、非 GET 与跨域请求，不缓存邮件、凭据或附件。浏览器本机另存紧凑布局偏好；安装 PWA 不会扩大邮箱权限或启用注册。

个人邮箱默认配额为 1 GiB、网站每日 50 个收件人；生产环境的公开注册默认关闭，是否开放以部署配置与真实验收为准。域名未验证、DNS 查询失败、配额不足、协议认证失效、上游不可用和邮箱禁用必须分别展示，不能用演示数据替代真实结果。健康接口返回进程可用也不能证明对外 SMTP 投递、PTR、DKIM 或第三方中继已验收。

资料依据 2026-10-23 源码整理。部署仍需验证真实 DNS、Mailu 管理、网页及外部客户端收发信、附件和退出重登，不能只凭页面或健康接口判断邮件可用。公开政策见 [隐私中心](https://document.thestarline.cn/privacy/)，使用问题见 [支持中心](https://document.thestarline.cn/support/)。

## 源码依据

实现位于 `mail-platform/server/config.ts`、`app.ts`、`store.ts`、`auth.ts`、`crypto.ts`、`resources.ts`、`domains.ts`、`mail.ts`、`mail-protocol.ts`、`service-health.ts`，以及 `client/src/Pwa.tsx` 和 `client/public/sw.js`。仓库提供单元、协议、容器与端到端验证入口，历史结果应与对应版本和环境一并查看。


原始地址：https://document.thestarline.cn/pay/
Markdown：https://document.thestarline.cn/pay/overview.md

# 星线 Pay 技术概览

星线 Pay 当前包含公开介绍页面与独立的微信支付 Native 后端。后端可以按服务端商品表创建支付订单、核验通知和主动对账；公开页面中的登录、注册地区引导尚未形成用户支付操作闭环。

## 入口与实现范围

公开入口为 [星线 Pay](https://pay.thestarline.cn/)。公开前端是 HTML、CSS、Canvas 与静态地区数据，展示地球、品牌和地区选择；地区选择后的不可用提示不等于用户注册成功、支付资格校验通过或已连接钱包。

支付服务使用 Go，依赖微信支付 API v3 官方 SDK 和 SQLite 驱动。模块声明 Go 1.27.2、微信支付 SDK v0.2.21、`modernc.org/sqlite` v1.60.1。这里的版本来自源码依赖声明，不代表生产进程已按该版本构建或验收。

| 能力 | 当前实现 |
| --- | --- |
| 商品与金额 | 服务端商品记录控制 SKU、说明、分金额和启用状态 |
| 下单 | 内部系统提交业务订单标识，服务端调用 Native 下单 |
| 查询与主动对账 | 查询本地订单，向微信查询并验证成功结果 |
| 支付通知 | 官方 SDK 验签解密后严格核对订单与金额 |
| 履约 | 未提供通用发货、云资源开通或业务交付实现 |

该后端不提供余额钱包、资金托管、汇兑、跨境清结算或金融交易账户。源码也没有退款 HTTP 路由，不能因为上线检查文档提及退款就宣称已具备退款接口。

## 服务间接口与字段

`/internal/` 路由使用 `X-Internal-Key`，通过摘要与常量时间比较校验。该凭据不能交给浏览器或嵌入公开 JavaScript。公开反向代理需要按业务职责限制可达路径，不能把内部下单接口当作匿名客户端 API。

| 接口 | 方法 | 作用 |
| --- | --- | --- |
| `/healthz` | GET | 返回进程状态与创建支付的配置就绪标志 |
| `/internal/orders` | POST | 为已知服务端 SKU 预留或复用订单并取得支付二维码地址 |
| `/internal/orders/{tradeNo}` | GET | 查询订单的受限公开字段 |
| `/internal/orders/{tradeNo}/reconcile` | POST | 主动查询支付结果并尝试更新本地状态 |
| `/wechat/notify` | POST | 接收微信支付成功通知 |

创建请求只接受 `source`、`source_order_id`、`customer_ref`、`sku`。调用方不传金额；服务器按照启用商品的 `amount_fen` 定价。标识只允许字母数字开头，后续为字母数字、下划线、句点、冒号或连字符；长度上限依次为 32、64、128、64。JSON 限制为 2048 字节，拒绝未知字段和额外 JSON 值。

订单响应包含 `trade_no`、`source_order_id`、`sku`、`description`、`amount_fen`、`status`、`code_url`、`expires_at_unix`。金额为整数分，失效时间为 Unix 秒；`code_url` 是支付流程材料，不应作为普通公开内容长期发布。商户配置与内部身份字段不在这组响应中输出。

## 幂等与状态流转

SQLite 对来源与业务订单号的组合、支付订单号和交易号设置唯一约束。首次下单预留 `created` 记录；取得预支付结果后为 `prepay`；核验成功后为 `paid`；模型还包含 `closed`。

重复请求不能仅因业务订单号相同就任意复用：服务会检查 SKU、客户引用和商户/App 上下文是否一致。已支付订单返回原结果；未过期且已有预支付结果的订单复用原二维码；过期或冲突请求返回明确错误。进程内创建锁用于控制并发调用，数据库唯一约束承担持久层约束。

通知最多接收 65536 字节，先由官方 SDK 验签并解密，再要求事件和交易结果符合成功契约。入账必须同时匹配订单号、商户号、App ID、总金额、人民币币种与非空交易号；不能只凭浏览器“支付完成”或一条未验证回调标记成功。主动对账同样复用成功验证，非成功结果不会直接伪造本地支付成功。

## 开启条件、失败与验收

创建支付需要显式启用开关，并具备商户/App 配置、存储、网关和内部调用凭据。未启用返回 `503 PAYMENTS_DISABLED`；商品不可用或订单不存在为 404；订单过期或业务冲突为 409；上游支付服务异常为 502。健康接口中的就绪布尔值只是本地条件判断，不验证微信权限、证书有效性、外网通知可达或实际扣款。

资料依据 2026-10-23 源码整理。历史“关闭支付”记录不能替代当前环境状态检查，代码具备下单能力也不能替代真实商户验收。接入业务必须另外验证通知重复投递、超时主动对账、金额冲突和支付成功后的幂等履约。

## 源码依据

支付模块的 `payment/go.mod`、`http.go`、`domain.go`、`service.go`、`store.go`、`wechat_gateway.go` 与 `cmd/payment/main.go` 定义上述契约。公开产品关系见 [官网](https://document.thestarline.cn/website/)，相关政策见 [法律中心](https://document.thestarline.cn/legal/)。


原始地址：https://document.thestarline.cn/trade/
Markdown：https://document.thestarline.cn/trade/overview.md

# Starline Trade 技术概览

Trade 当前是带模拟 K 线背景的静态产品页面。图形数据在浏览器本地生成，登录和注册入口进入地区选择及暂不可用提示；当前源码没有接入真实行情、交易账户或订单执行服务。

## 入口与结构

公开指定入口为 [Starline Trade](https://trade.thestarline.cn/)。页面由 HTML、CSS、Canvas 2D、独立行情动画模型和地区选择组件组成，无交易服务端依赖。

| 模块 | 职责 |
| --- | --- |
| `market-model.js` | 逐笔模拟、OHLC、随机过程与收盘推进 |
| `market-background.js` | Canvas 尺寸、像素密度、绘制节奏与暂停 |
| `region-gate.js` 及地区数据 | 国家或地区、省份选择、搜索、不可用提示 |
| 风景与署名资料 | 地区图片、地标与图片来源页面 |

页面文案和品牌入口用于产品展示，不能据此推断已开放金融交易或得到任何地区许可。本页只说明代码，不提供交易建议。

## K 线模型与绘制数据流

模型中的每根柱包含开盘、最高、最低和收盘值。最新一根随模拟逐笔价格变化，最高、最低只记录该周期实际生成的价格；默认每 4200 毫秒收盘，新柱开盘承接上一柱收盘，已收盘 OHLC保持不变。

随机模型改变方向偏向、波动强度、逐笔间隔和短暂停顿，避免固定的涨跌阶段循环。模型使用确定的随机状态，并把数据推进与绘制分开：重绘、改变窗口尺寸或降低绘制帧率不会单独改写已经生成的模拟走势。

历史参考文件只用来校准波动比例。运行页面不会持续请求实时 BTC 行情，也不会直接重放该样本。屏幕上的红绿变化、价格范围和走势不能用于资产估值、交易判断或核对外部交易所数据。

绘制按设备像素密度和视口调整，上限为每秒 30 帧；切入后台暂停，系统开启“减少动态效果”时保持静止。该暂停属于页面资源管理，不涉及真实市场停盘或订单处理。

## 地区选择流程

登录和注册复用地区选择界面：可搜索 250 个国家或地区，选中国后再选省份，最后显示对应的暂不可用提示。用户可返回、关闭或按 Escape退出，关闭后焦点回到原入口。

该流程不提交用户名、密码或身份资料，不跳转认证服务，也不保存地区选择。选择地区不是 IP定位、GPS定位、KYC、开户或交易适当性判断。页面没有向用户索取位置权限。

旗帜、照片和地标由同源静态资源加载。地区展示优先使用既定地标映射，其余采用当地风景照片。照片灰度只施加在图像层，文字、旗帜和交互控件保持各自样式。图片来源页保留作者、原始出处和许可链接，更新素材时必须同步维护署名，不能只替换文件。

## 当前不具备的服务

源码未提供行情订阅、订单簿、限价或市价委托、撤单、持仓、钱包、充值、提现、清算或结算接口。页面“登录”“注册”是当前展示流程的入口，不能作为已接入 Account 的证据；与 [Pay](https://document.thestarline.cn/pay/) 共享地区界面也不表示共享支付账户或资金系统。

要扩展成真实业务，需要先定义权威服务端、用户授权、数据供应、幂等订单、持仓记账、故障恢复与地域服务边界。视觉模型适合独立调整动画，不宜作为交易状态模型直接复用。

## 失败与验证边界

静态资源失败会影响地区图像或动画展示，但不会产生待执行交易。减少动态、后台暂停、无搜索结果、横竖屏变化和焦点返回需要单独验收。模型测试可以检查 OHLC一致性和模拟结果稳定性，不能验证真实行情延迟或资金正确性。

资料依据 2026-10-23 源码整理。历史域名与部署记录保留原日期；当前可达性、响应式、动画暂停和地区流程需针对实际发布版本验收。相关政策见 [法律中心](https://document.thestarline.cn/legal/) 与 [隐私中心](https://document.thestarline.cn/privacy/)。

## 源码依据

主要依据为 `trade/index.html`、`market-model.js`、`market-background.js`、`market-model.test.cjs`、`region-gate.js`、地区数据及 `scenery/credits.json`。


原始地址：https://document.thestarline.cn/game/
Markdown：https://document.thestarline.cn/game/overview.md

# 星线游戏技术概览

星线游戏当前源码实现一张带 WebGL 局部动态效果的视觉首页，提供暂停、关于和沉浸预览。它还不是可运行的网络游戏、VR游戏或游戏发行平台；页面图像属于视觉创作，不是黑洞物理模拟或观测视频。

## 入口与架构

代码指定入口为 `https://game.thestarline.cn/`。源码说明当前阶段提供本地预览，正式域名部署仍需独立确认。

站点使用 HTML、CSS、原生 ES modules 和 WebGL 1，无第三方前端运行依赖。构建需要 Node.js，静态预览可使用 Python，但正式页面运行不依赖 Python服务。

| 模块 | 职责 |
| --- | --- |
| `index.html`、`styles.css` | 页面内容、响应布局、操作控件与对话框 |
| `app.mjs` | 横竖屏资源选择、播放状态、沉浸模式与场景替换 |
| `scene.mjs` | WebGL 纹理、着色器、尺寸适配、帧循环与资源释放 |
| 两张主视觉 | 横屏和竖屏静态图像，同时承担动态失败时的展示 |

横屏与竖屏使用各自构图。动态着色器主要作用于吸积盘区域，人物与设备保持稳定，不能由此推断页面已生成三维世界、物理碰撞或玩家视角交互。

## 场景启动与生命周期

页面按视口方向选择图像及相应的构图参数，准备图像后创建场景。切换方向可能引发异步加载，控制器使用请求版本区分新旧结果；过期结果不会覆盖当前场景，弃用场景会释放资源。

渲染循环受播放状态、文档可见性和 WebGL上下文状态共同控制。页面隐藏或用户暂停时不继续正常绘制；恢复可见并满足播放条件后再启动。系统“减少动态效果”在初始状态和偏好变化时影响播放，保留清晰静态画面。

场景使用 ResizeObserver 或窗口尺寸变化后备处理画布变化。销毁时移除可见性、尺寸和 WebGL上下文事件监听，停止动画并释放资源，避免横竖屏反复切换积累后台循环。上下文丢失与恢复有专门分支；无法创建 Canvas/WebGL场景时仍可展示静态主视觉。

## 沉浸、暂停与关于

普通模式用 `cover` 铺满视口；沉浸预览隐藏品牌、文案和页脚，以 `contain` 展示完整图像，同时保留退出控制。背景界面使用不可交互状态并处理焦点，退出后恢复合适的操作位置。Escape可退出沉浸，打开关于对话框时优先处理对话框。

“沉浸”是页面显示模式，没有据此调用 WebXR、接入头显或取得摄像头、陀螺仪权限。关于窗口使用对话框行为，提供关闭与外部点击处理；暂停只控制视觉效果，不会暂停任何已连接的游戏服务器。

页面中的“在所在国家或地区未获得批准”是静态说明。代码不读取地理位置，也没有调用许可核验服务，不能把这句话解释成完成了用户定位或逐地区监管核查。

## 数据、权限与发布文件

当前没有账号、玩家资料、存档、房间、匹配、排行榜、道具购买、广告计费或支付 API；不会因为观看视觉页面而创建游戏账户。主要数据是公开图像、样式、脚本和当页运行状态，不包含服务端玩家数据库。

构建采用 10 个文件的显式白名单：页面、样式、两个运行模块、robots、sitemap、横竖屏主视觉、品牌标识和图标。历史 PNG、设计参考、验收资料与文档不会自动进入发布包。新增资源必须明确加入白名单，并确认用途和公开授权。

后续若增加游戏能力，应分别设计账户、玩法状态、服务端规则和真实设备交互。当前视觉场景可以独立演进，但不能作为网络游戏后端或支付能力的现成实现。

## 失败与验证边界

需要验证的场景包括不支持 WebGL、上下文丢失、图像加载失败、快速横竖屏切换、后台恢复、减少动态、触屏操作、窄屏布局和键盘关闭。语法检查与静态文件构建只能验证部分发布条件，不能替代浏览器效果、设备稳定性和正式上线检查。

资料依据 2026-10-23 源码整理。正式发布仍需完成目标浏览器、设备和域名验收。公开产品信息见 [官网](https://document.thestarline.cn/website/)，政策入口见 [法律中心](https://document.thestarline.cn/legal/) 与 [隐私中心](https://document.thestarline.cn/privacy/)。

## 源码依据

主要依据为 `game/README.md`、`index.html`、`styles.css`、`app.mjs`、`scene.mjs` 与 `build.mjs`。README中的本地预览记录与正式公网验收需分别判断。


原始地址：https://document.thestarline.cn/shop/
Markdown：https://document.thestarline.cn/shop/overview.md

# 星线社技术概览

星线社是面向实物商品的静态展示与咨询入口。当前商品数组为空，页面只保留品牌和联系内容；源码保留的搜索、详情和咨询清单组件，不代表当前已有商品可购买或已经形成电商订单系统。

## 入口与当前状态

公开入口为 [星线社](https://thestarline.shop/)。站点使用 HTML、CSS 和原生 ES modules，无运行时服务端或数据库依赖。产品数据来自 `catalog.mjs`，当前导出 `products = []`，分类为“全部”和“实物商品”。

页面初始化先判断商品数量。为空时隐藏商品区域、分类导航、搜索相关展示和咨询清单入口，并显示适用的品牌联系内容；不会自动生成占位商品、轮播或默认购物卡片。维护人员不能仅因组件存在就将站点描述为可下单商城。

| 层 | 实现 |
| --- | --- |
| 商品目录 | 静态 JavaScript 数组，当前为空 |
| 页面交互 | 筛选、商品详情、咨询清单与联系对话框 |
| 本机存储 | 已选咨询商品 ID数组 |
| 公开发布 | 白名单 HTML、CSS、模块与必要图片 |

## 商品模型与扩展方式

恢复商品展示时，应在目录中添加经过确认的真实商品，而不是只改页面隐藏开关。当前渲染器读取以下字段：

| 字段 | 用途 |
| --- | --- |
| `id` | 稳定唯一标识，用于详情和本机选择引用 |
| `name`、`description` | 商品名称及简要说明 |
| `category`、`keywords` | 分类与搜索匹配 |
| `image`、`imageAlt` | 公开图片与替代文字 |
| `priceLabel` | 展示用价格文案，不是结算金额 |
| `overview`、`includes`、`suitableFor`、`note` | 详情中的介绍、包含内容、适用场景及补充说明 |

搜索将查询去除首尾空白并转为小写，在名称、简介和关键词中执行包含匹配；分类与关键词条件同时生效。无结果显示重置筛选入口。字段进入页面时经过转义，避免将普通目录文本当作 HTML执行；这不能替代图片来源、价格和商品信息的人工确认。

## 咨询清单的数据流

咨询选择使用本机键 `starline.shop.inquiry.v1`，内容是 JSON 字符串数组。恢复时只接受数组、去重并保留当前目录已知的商品 ID；不存在或下架的商品不会继续进入咨询结果。损坏的 JSON、存储读取失败或非数组值回退为空清单。

加入和移除只对已知商品生效。存储写入失败时返回失败结果，不能据此宣称选择已跨页面持久保存。这里没有登录用户、服务端购物车或跨设备同步；同一浏览器的选择也不等于订单。

咨询文本由当前已选商品名称生成，附带来源链接；无有效选择时使用通用商品咨询文字。复制失败时使用可选择文本作为后备。站点不自动发送咨询，不会因此替用户向商家创建订单、锁定库存或扣款，用户仍需通过提供的联系渠道完成沟通。

## 对话框与访问性

详情和咨询对话框处理可见可聚焦控件、背景不可交互状态、关闭与焦点恢复，避免键盘停留在隐藏元素中。商品图片包含替代文字，按钮具备可识别名称。空商品目录下的联系入口使用通用分支，不会先要求用户勾选不存在的商品。

新增商品或更改弹窗结构后，仍需在窄屏、触屏和键盘操作中检查布局、文字换行、滚动与焦点；模型测试不能替代这些浏览器验收。

## 发布与能力边界

构建脚本先确认公开白名单文件存在，再重建输出目录，只复制站点运行文件及品牌、图标和公开联系图片。设计草稿、退役商品图、测试和其他内部资料不会因所在目录相邻而自动公开；新增公开资源需要显式纳入白名单。

当前没有支付、订单、库存、优惠、物流、退款或售后工单后端，也没有与 [星线 Pay](https://document.thestarline.cn/pay/) 的结算闭环。若未来接入交易能力，应另建服务端可信商品价格、订单状态、库存和履约契约，不能把 `priceLabel` 或本机清单用作可信收费依据。

资料依据 2026-10-23 源码整理。发布时仍需验证空目录行为、详情与咨询焦点、存储不可用、复制失败和触屏布局；咨询后续结果由实际联系流程确认。相关公开入口见 [官网](https://document.thestarline.cn/website/)，使用问题见 [支持中心](https://document.thestarline.cn/support/)。

## 源码依据

主要实现为 `shop/catalog.mjs`、`store.mjs`、`app.mjs`、`index.html`、`styles.css` 和 `build.mjs`。模型验证与浏览器实际操作需要分别检查。


原始地址：https://document.thestarline.cn/website/
Markdown：https://document.thestarline.cn/website/overview.md

# 星线官网技术概览

星线官网是公司介绍、云产品和网站/App开发服务的静态入口，并通过页脚连接其他公开产品与政策站点。官网里的产品链接说明入口关系，不代表被链接服务的全部能力已经上线或通过验收。

## 入口与站点职责

公开入口为 [星线官网](https://thestarline.cn/)。当前官网实现位于 `official-site/`，使用原生 HTML、CSS、JavaScript、SVG 和本机维护的公开图片，不需要前端框架或运行时构建服务。

| 内容区域 | 主要职责 |
| --- | --- |
| 公司介绍 | 品牌与公司基本信息 |
| 星线云 | Typo 轻量实例、高性能群组服等介绍，并跳转云站 |
| 开发服务 | 网站与 App开发服务说明和联系入口 |
| 页脚 | 产品、支持、法律、隐私等跨站导航 |

页脚产品目录列出星线建站、星线云、星职和星线 Pay。Email、Trade、Game、星线社等有各自模块与入口，官网目录并非所有源码产品的完整清单。扩展导航时应核对公开名称、HTTPS地址、用途和实际可用性，而不是按本机目录名直接生成产品。

## 锚点与页面状态

页面围绕三个主要面板组织。`#about` 指向公司介绍，`#cloud` 指向云产品，`#development` 与 `#contact` 指向开发服务；代码保留 `#services`、`#typo`、`#group` 等旧锚点的可定位性。

导航不仅改变 URL片段，还根据目标元素找到所属面板并处理标题焦点。滚动时依据视口中心更新当前面板，导航使用 `aria-current="location"` 表示位置。顶部区域高度同步至 CSS变量，用于对齐滚动与布局；高频状态更新通过 requestAnimationFrame合并，避免每次原始滚动事件都重复执行整套计算。

URL片段是页面定位状态，不是登录令牌、订单号或服务端路由。用户直接打开旧锚点时仍应落到适当内容，不能只在点击顶部导航时表现正常。

## 响应式与访问性

布局根据视口和输入方式调整，代码包含减少动态偏好、键盘焦点和移动端触控目标处理。链接和主要控件需要保持可见焦点，移动端点击区域以约 44像素的触控需求设计。

滚动面板、顶部导航、脚注和联系入口是需要一同验收的布局关系。添加内容后应检查窄屏长名称、横屏较低视口、浏览器文字放大、键盘跳转、深链接和系统减少动态。桌面页面可打开不能替代手机与触屏检查，文件构建或语法检查也不能证明元素位置正确。

官网没有提交业务数据的表单后端，也不承担其他产品的认证或订单管理。联系二维码属于公开站点资源，但用户扫码后的第三方联系流程不在官网静态代码控制范围内。

## 星线建站与开发服务的边界

“星线建站”公开链接指向 `https://webside.thestarline.cn/`。官网源码只证明该入口和产品名称；独立建站实现尚未验证，因此不能宣称已经具备模板编辑器、项目托管、自动部署、域名绑定、付费订阅或公开建站 API。

官网的网站/App开发服务介绍属于服务入口。它与自助式建站平台是不同层次的能力；公开介绍不能替代具体项目交付、报价、合同或生产验收。相关产品实现应分别参阅 [Cloud](https://document.thestarline.cn/cloud/)、[Pay](https://document.thestarline.cn/pay/) 与 [星职](https://document.thestarline.cn/careers/)。

## 资源与发布方式

运行文件可由普通静态 Web服务托管。更换图片或 SVG时，应维护尺寸、替代文字、缓存策略和公开使用权；脚本、样式及相对资源路径应在目标站点根路径下共同检查。不得将设计草稿、备份、构建工具或运行配置连同公开素材直接上传。

发布检查应确认目标域名与 HTTPS、canonical、锚点、跨站入口、资源响应和缓存更新；本机预览、文件上传和公网部署是不同状态。跨站产品暂不可用时，应由对应产品提供明确状态，而不是用官网链接存在代替可用性结论。

## 资料与验证边界

资料依据 2026-10-23 源码整理。本文说明静态实现；域名当前可达性、全尺寸浏览器效果、联系渠道和各产品真实业务链路仍需分别验收。历史发布记录保留各自日期，不能作为持续可用承诺。

## 源码依据

主要实现为 `official-site/index.html`、`styles.css`、`site.js` 和 `README.md`。政策页面由独立模块维护，见 [法律中心](https://document.thestarline.cn/legal/) 与 [隐私中心](https://document.thestarline.cn/privacy/)；帮助文章见 [支持中心](https://document.thestarline.cn/support/)。


原始地址：https://document.thestarline.cn/careers/
Markdown：https://document.thestarline.cn/careers/overview.md

# 星职技术概览

星职是职位发布、候选人投递、HR 初筛和管理员复核的招聘系统。当前流程覆盖录用与拒绝状态；面试排期、面试通知日历或自动入职办理不在已实现范围内。

## 入口与技术栈

公开入口为 [星职](https://career.thestarline.cn/)。应用使用 Next.js App Router、React、TypeScript、Drizzle ORM 与 MySQL；私有简历文件存于兼容 S3 的对象存储，邮件通过 SMTP 发送。依赖声明为 Next.js 15.5.24、React 19.1.1、TypeScript 5.9.2、Drizzle 0.45.2。

候选人、HR 和管理员使用本系统的身份与会话能力。源码中独立的邮箱验证、密码重置、角色授权和会话检查，不能解释为已完成 Account 单点登录。候选人个人资料和简历均属于受限数据，不作为公开职位页面资源。

| 数据模型 | 关键关系 |
| --- | --- |
| 用户与候选人资料 | 身份、邮箱验证状态、姓名和联系方式等资料 |
| 员工账号 | HR / ADMIN 角色及启用状态 |
| 职位与职位版本 | 发布指针引用已发布版本，投递关联具体版本 |
| 简历、上传意图、清理意图 | 数据库记录所有权和状态，对象存储保存私有文件 |
| 投递与状态历史 | 候选人、职位、职位版本、简历、当前状态、版本号 |
| 会话、邮件任务、审计事件 | 权限恢复、异步通知与变更追踪 |

## 发布与投递数据流

职位发布不是直接覆盖候选人已经投递时看到的全部数据。系统保留职位版本，投递时记录版本引用，使审核能够对应当时发布内容。同一候选人对同一职位受唯一约束，重复请求不能产生多份独立投递。

候选人提交申请时，服务端重新检查身份和邮箱验证、职位当前发布版本、简历所有权及上传状态，并确认必要的通知接收方。校验通过后，在事务中写入申请、初始版本、状态历史、审计和待发邮件任务。HTTP 成功代表业务写入成功；邮件任务入队不代表收件人已经收到通知。

## 角色与审核状态机

| 操作者 | 当前状态 | 允许的下一状态 |
| --- | --- | --- |
| HR | `APPLIED` | `HR_SCREENING` |
| HR | `HR_SCREENING` | `PENDING_ADMIN_REVIEW` 或 `REJECTED` |
| ADMIN | `PENDING_ADMIN_REVIEW` | `HIRED` 或 `REJECTED` |

`HIRED` 与 `REJECTED` 为当前状态机的终点。管理员可以访问需要员工身份的范围，但不能越过状态机直接替 HR 完成任何阶段；角色能力与转换规则分别检查。未知角色、未知状态或不允许的转换都拒绝执行。

审核更新携带正整数 `expectedVersion` 和目标 `to`，使用乐观并发控制。两名员工打开同一份旧资料时，先完成的修改推进版本；后续旧版本请求返回冲突，须刷新后重新决定，不能悄悄覆盖他人审核。角色授权在服务端执行，隐藏按钮不是权限边界。

## 简历上传与下载

上传接口只允许候选人，在验证 Origin、Cookie 和请求体限制后接收单个 `file`。文件限制为 1 字节至 10 MiB，只接受 PDF 或 DOCX。PDF 检查文件头；DOCX 除 ZIP 结构外，检查条目路径、重复条目、加密、宏、ActiveX、嵌入对象和膨胀风险，并拒绝危险 XML 声明。压缩包最多 256 项、展开总量最多 32 MiB，并设压缩比例约束。

这些检查降低格式和压缩炸弹风险，不能当作完整恶意软件扫描。原始文件不放入公开静态目录。候选人只可下载自己的文件；员工下载需要关联有权访问的申请。下载响应使用附件、禁止缓存、nosniff 和沙箱等头，避免把简历作为可信站点内容执行。

上传和删除采用意图记录处理数据库与对象存储之间的中间状态；后台清理按批次推进，不能把一次数据库删除推断成对象已经物理清除。保留时间应以正式政策和实际配置为准，本页不自行给出统一清除期限。

## 接口、失败与发布边界

API 包括身份注册登录、邮箱验证与重置、申请提交、简历上传下载、职位和员工管理、申请审核，以及审计和邮件任务运维。写入接口检查精确 Origin 和请求大小，错误返回使用业务错误码，不回显数据库驱动详情。审核可能返回无效输入、未登录、无权限、记录不存在、版本冲突或服务不可用。

部署需要可用的 MySQL、私有对象存储、SMTP 和后台任务执行。页面可访问、数据库可连或 SMTP 接受请求均不能单独证明从职位发布到录用通知的完整链路可用。

资料依据 2026-10-23 源码整理。仓库有单元、集成、端到端与部署验收入口，历史结果须与对应环境查看；实际发布仍需验证简历隔离、并发审核、对象清理及通知到达。政策入口见 [隐私中心](https://document.thestarline.cn/privacy/)，公司网站入口见 [官网](https://document.thestarline.cn/website/)。

## 源码依据

实现位于 `careers/src/domain/recruitment.ts`、`src/server/db/schema.ts`、`src/server/auth/authorization.ts`、`src/server/auth/http.ts`、`src/server/recruitment/application-service.ts`、`review-http.ts`、`src/server/storage/resume-validation.ts`、`http.ts` 和清理服务；具体路由位于 `src/app/api/`。


原始地址：https://document.thestarline.cn/support/
Markdown：https://document.thestarline.cn/support/overview.md

# 星线支持中心技术概览

支持中心由静态帮助文章、浏览器搜索、地区选择和回电申请组成。文章阅读不要求登录；回电申请另由独立接收服务校验并持久写入待处理队列。申请已接收不等于电话已拨出，也不承诺自动回电时间。

## 入口与内容模型

公开入口为 [星线支持](https://support.thestarline.cn/)。前端使用 HTML、CSS 和原生 ES modules，构建脚本从 `data.mjs` 与模板生成首页、搜索页、联系页、产品页、文章页和真正的 404 页面。

产品目录当前包含 Account、Cloud、Pay、Email 和 App。文章记录包括 `slug`、`product`、标题、摘要、关键词和分节正文；分节可以包含段落和步骤。新增文章需要同时核对 slug 唯一性、产品归属、链接和内容准确性。支持文章说明如何使用产品，不能作为其他产品能力已经验收的替代证据。

搜索在浏览器执行，将文本 NFKC 规范化、转为小写并按空白及常见中英文标点分词；可先按产品筛选。精确关键词、标题、关键词部分匹配、产品名、摘要和正文分别计分，所有查询词都需要获得正分才进入结果，再按总分排序。当前没有服务端全文搜索、语义向量检索或根据账号资料个性化排序。

## 地区选择与联系行为

地区数据覆盖 250 个国家或地区，中国选项继续提供 34 个省级选项。地区偏好使用 `starline-support-region-v1` 保存到本机。它用于联系流程展示，不能证明用户地理位置、产品授权地域或已取得特定国家经营许可。

更改地区后，申请表需要以当前选择重新校验。地区、联系语言和手机号是不同字段，不能仅根据国家码猜测用户希望使用的语言。当前回电语言只允许 `zh`、`en`。公开企业联系入口由站点提供，技术文档不复制联系人资料或二维码内容。

## 回电申请接口

前端向同源 `POST /api/callback-requests` 提交 JSON，不向第三方表单平台传输。服务端使用 Python 标准库实现接收和队列，不属于静态构建产物。

| 字段 | 类型与约束 |
| --- | --- |
| `requestId` | 标准 UUID；用作重试去重标识 |
| `phone` | 国际格式字符串，`+` 后为 7–15 位数字，首位不能为 0 |
| `region` | 白名单国家或地区 `code`；`CN` 必须含已知 `province`，其他地区不能带该字段 |
| `language` | `zh` 或 `en` |
| `consent` | 必须为布尔值 `true` |
| `website` | 必须为空字符串的诱捕字段 |

服务端拒绝缺失或额外字段、重复 JSON 键、非有限数值、无效地区及未经同意的提交。请求体最多 4096 字节，校验精确 Origin、内容类型、方法与读取时限。前端只有在 HTTP 成功、响应 `status` 为 `received` 且 `requestId` 与本次请求一致时，才显示成功。

## 持久化、幂等和失败

有效申请以 JSONL 写入私有队列，记录申请 ID、联系方式、地区、语言、UTC 创建时间、`pending` 状态和同意标志。目录及文件采用受限权限；日志刻意省略请求路径、请求头、申请内容和异常值。队列文件不进入静态站点，也不提供公开读取或管理接口。

写入过程使用线程锁及文件锁，先读取并验证既有队列，写入后同步文件与必要的目录状态，完成持久化才返回成功。同一 ID 与同一有效载荷重试返回 200；首次写入返回 201；相同 ID 携带不同内容返回 409。网络超时后应复用原 ID确认结果，不能通过不断生成 ID规避重试约束。

默认同一来源 15 分钟最多接受 5 份新申请，重复申请不重复计数；限流状态保存在进程内，重启会重置该窗口。超限返回 429 和 `Retry-After`，格式错误为 400，Origin 不符为 403，请求过大为 413，不支持的内容类型为 415。队列损坏或写入不可用时保留原文件并返回 503，不能先显示成功再丢弃申请。

## 扩展与验证边界

仅部署静态文件不会自动启用回电申请，必须同时连接接收服务与受保护的持久存储。当前服务只承担接收，不包含自动拨号、客服派单后台、公开查询进度或通话录音。增加后续处理时应保留申请 ID和状态更新审计，并按正式隐私规则处理联系方式。

资料依据 2026-10-23 源码整理。部署仍需验证同源接收路由、持久化、重试去重、限流、损坏队列和前端成功判断；后续人工联系需要单独确认。产品技术边界见 [Email](https://document.thestarline.cn/email/)、[Cloud](https://document.thestarline.cn/cloud/) 与 [Pay](https://document.thestarline.cn/pay/)，政策见 [隐私中心](https://document.thestarline.cn/privacy/)。

## 源码依据

主要文件为 `support/data.mjs`、`search.mjs`、`templates.mjs`、`build.mjs`、`app.mjs`、`regions.mjs`、`region-picker.mjs`、`callback-form.mjs` 和 `server/callback_server.py`。公开内容构建与申请接收服务须分别检查。


原始地址：https://document.thestarline.cn/legal/
Markdown：https://document.thestarline.cn/legal/overview.md

# 星线法律中心技术概览

法律中心是独立的静态文档站，提供网站条款、账号条款、知识产权与投诉说明、联系信息和旧地址迁移。它与隐私中心共用内容生成及本地化机制，正式政策内容以公开页面为准；本技术文档不修改条款或代替法律审阅。

## 入口与内容分工

公开入口为 [星线法律中心](https://legal.thestarline.cn/)，隐私正文位于 [星线隐私中心](https://privacy.thestarline.cn/)。两站在构建阶段生成 HTML和 UTF-8文本，读者访问时不依赖 Python运行服务，也不需要登录。

| 内容来源 | 用途 |
| --- | --- |
| `content.py` | 网站使用条款、账号条款、网站/账号隐私与知识产权等基础正文 |
| `app_privacy.py` | 星线 App隐私说明 |
| `xingqi_privacy.py` | 星企隐私说明 |
| 模板、样式与客户端脚本 | 阅读布局、目录定位、语言选择、打印与下载 |
| 本地化目录 | 完整译文和界面文案，不使用运行时在线翻译 |

正文、模板和发布内容分开维护。读者看到的生效日期是具体政策的资料，不能被站点构建日期或技术文档更新日期覆盖。

## 审阅版与正式版

默认 `build.py` 生成审阅预览，带审阅提示和 `noindex, nofollow`，跨站链接用于本机审阅。该产物不能直接作为正式网站上传。审阅包里已有 HTML或能正常打开，不代表正文已获批准或是当前正式政策。

`build_release.py` 生成独立正式中文候选包，应用正式发布内容；`build_multilingual.py` 再以正式中文为本地化基准生成语言版本。发布检查需要同时确认内容事实、生效日期、联系渠道和 HTTPS跨站地址，再检查文件完整性与链接。

`release_preflight.py` 检查审阅标记、noindex、断链、遗漏文件与过期压缩包。它可以阻止部分技术发布错误，不能判断条款是否符合真实运营、是否适用于某司法辖区，或是否已经获得独立法律审查。

## 多语言路由与数据流

当前目录覆盖 50 个语言或地区版本，简体中文 `zh-Hans` 使用根路径，其余使用 `/<locale>/`。客户端支持语言参数和常见短码，并在语言选择、跨法律/隐私站跳转、目录与下载之间保留语言上下文。

每种语言维护完整文案块，而不是访问时向在线翻译服务发送政策文本。缺失翻译会使严格构建失败；模板同时生成 `lang`、方向与 hreflang关系。阿拉伯语、希伯来语、乌尔都语使用 RTL，并对中文登记名称等内容处理方向隔离，避免标点和数字错位。

源文案块数量会随正文修订而变化，不应把历史计数当作永久接口。更新正文时需要同步更新对应译文，再核对名称、日期、数字、目录锚点、下载和跨站回跳。机械数字检查会有语言表达差异，仍须结合语义人工确认。

## 阅读、下载与旧入口

页面提供章节目录、同语种文本下载和打印。下载内容是预先生成的 UTF-8文本，不需要读取用户账户或动态导出用户数据。目录依赖稳定的章节锚点；增加或重命名章节时，需要同时更新正文、目录、链接和译文映射。

旧隐私地址迁移到独立隐私站，旧法律入口也有对应迁移处理；语言上下文需要在迁移后保留。维护重定向或迁移页时应检查 canonical与实际目标，避免形成循环或把所有语言都送回中文首页。

## 安全与能力边界

静态法律站不处理账号注销、争议裁定、投诉结案或自动执行个人信息请求。联系页面仅说明公开渠道；是否正式受理、何时答复和结果应以具体流程与回执为准。隐私副本邮件由独立服务处理，其接口和限制见 [隐私中心技术概览](https://document.thestarline.cn/privacy/)。

本地化资料使用机器辅助和语义校订流程，不能宣称全部译文都经过独立母语法律认证。产品代码发生变化后，应先确认实际功能、启用状态及数据处理，再修订政策；不能把政策一句话反向当作产品已经交付的证据。

资料依据 2026-10-23 源码整理。源目录包含历史构建、测试和发布记录；这些记录保持原日期。当前部署文件、线上链接、下载一致性、RTL与窄屏阅读仍需针对发布候选包验收。

## 源码依据

主要依据为 `legal/content.py`、`app_privacy.py`、`xingqi_privacy.py`、`build.py`、`build_release.py`、`build_multilingual.py`、`localization.py`、`release_preflight.py`、本地化目录和阅读脚本。产品入口见 [官网](https://document.thestarline.cn/website/)，使用问题见 [支持中心](https://document.thestarline.cn/support/)。


原始地址：https://document.thestarline.cn/privacy/
Markdown：https://document.thestarline.cn/privacy/overview.md

# 星线隐私中心技术概览

隐私中心提供网站与账号、星线 App、星企三类隐私说明，以及同语种下载、打印和发送邮件副本。政策正文为静态文件；邮件副本由独立服务读取已发布文本发送，不依赖用户登录 Account，也不导出任何用户账户资料。

## 入口与文档模型

公开入口为 [星线隐私中心](https://privacy.thestarline.cn/)。文档类型使用固定标识：`privacy`、`app-privacy`、`xingqi-privacy`。页面路径为相应 `.html`，下载文本位于同语种 `documents/` 下。

正文与法律站共用构建、本地化和审阅/正式版区分。50个语言或地区版本中，`zh-Hans` 使用根路径，其余使用 `/<locale>/`；导航、下载、语言切换和跨站链接共同保留语言。页面运行时不调用在线翻译。法律站生成机制见 [法律中心技术概览](https://document.thestarline.cn/legal/)。

正式政策描述具体产品当时的数据处理事实。本页解释其技术承载方式，不重写法律权利、保留期限或产品权限说明，也不能把旧政策里的产品描述当作最新源码功能证明。

## 邮件副本流程

页面“发送至邮箱”先取得同源挑战，再提交所选文档、语言和收件地址。服务使用 Node.js HTTP模块及腾讯云 SES SDK，与 Account登录进程独立。

| 接口 | 输入或输出 |
| --- | --- |
| `GET /api/policy-email/challenge` | 返回一次性 `token` 与 `expiresIn: 600` |
| `POST /api/policy-email` | JSON字段为 `email`、`document`、`locale`、`token`、空 `website` |
| 成功响应 | `{"ok":true}`，表示邮件服务商已给出受理标识 |

服务校验精确 Origin、有效来源地址、文档和语言白名单、空诱捕字段及邮箱格式；JSON请求最多 4096字节，不允许额外字段。邮箱检查拒绝换行与控制字符，域名按 IDN规则转为 ASCII并规范化；格式有效不表示收件箱存在。

挑战由时间、随机数和来源绑定材料构成，并使用专用密钥 HMAC签名。创建后至少等待 1秒、最多 10分钟内使用，且只能使用一次。来源发生变化、签名不符、已使用或超时需要重新取得挑战，不应重复发送同一令牌。

## 附件选择与受理结果

服务按白名单文档和语言从正式静态目录读取 TXT，不接受客户端指定任意文件路径、正文或邮件模板。文本长度限制为 16–200000字节，首行标题必须有效且不超过 150字符。附件名由文档标识和语言组成，内容使用所选语言的完整文本，不包含用户账户数据。

发送前先持久记录令牌使用及限流预留，再调用 SES模板并附加 TXT。服务商返回 MessageId后响应成功；这代表服务商受理，仍可能出现后续退信、垃圾邮件过滤或邮箱延迟。缺少受理标识或发送异常返回失败，不能仅因 HTTP请求已到服务器就显示“送达”。

失败尝试也会占用相应发送额度，以防故障时反复调用形成邮件轰炸。客户端不应对不确定结果无限自动重试；用户可以稍后重试，或直接下载同一份公开文本。

## 限流与持久数据

| 维度 | 当前代码限制 |
| --- | --- |
| 获取挑战 | 每来源地址每小时 30次 |
| 同一规范化邮箱 | 5分钟 1次，24小时 3次 |
| 发信来源地址 | 每小时 8次 |
| 全站 | 24小时 100次 |

限流账本保存时间、事件种类及 HMAC摘要键，不将收件邮箱或来源地址明文存入该账本。文件使用受限权限并通过临时文件替换保存，过期事件按 24小时窗口清理。这里的 24小时只对应限流账本，不能推断为邮件服务商日志或产品其他数据的统一保留时间。

收件地址仍会在发送请求中交给邮件服务商用于投递。应用日志只记录受限事件和错误码，避免回显地址与正文；部署方仍需核对反向代理、服务商和错误追踪的实际记录规则。专用签名密钥与邮件服务商凭据只在服务端配置，不属于公开页面资源。

## 失败、部署与验证边界

格式错误返回 400，非法来源或令牌返回 403，超大请求为 413，内容类型不符为 415，限流为 429；模板、文本、服务商或必要配置不可用时为 503。健康接口的 ready只检查本地服务条件，不代表真实邮件已发送或送达。

纯静态站点部署不会自动提供邮件副本 API。部署需要正确的同源路由、正式语言文本、独立服务、受保护账本以及服务商发送配置。正文和 TXT更新需要保持一致，避免页面已更新而邮件仍发送旧政策。

资料依据 2026-10-23 源码整理。历史政策发布与受控收件记录保持原日期；新部署、语言文本变更、邮件附件一致性及真实收件仍需独立验收。使用问题见 [支持中心](https://document.thestarline.cn/support/)。

## 源码依据

主要依据为 `privacy/` 页面与阅读脚本，以及 `legal/build_release.py`、`build_multilingual.py`、`localization.py`、`policy-mail/service.mjs`、`policy-mail/server.mjs` 和允许语言目录。这里只公开接口契约，不包含运行凭据、账本内容或真实收件资料。