技术文档
星企资料日期 2026-10-23

星企接口与客户端接入

星企业务接口由共享聊天服务提供，正式目标来源配置为 https://chat.thestarline.cn。请求使用聊天服务签发的 Bearer 会话，企业范围写入路由路径。不要使用 Account Cookie、OIDC Access Token 或开放平台 HMAC 密钥直接调用企业路由。模块边界见技术概览。

登录与本机恢复

当前 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”的等价表达。单聊最终必须两人，群至少两人，所有成员均须属于当前企业。

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 明确不存在，不向接入者提供绕过登录的演示凭据。发布前需分别取得真实身份回调、企业业务与原生设备验收记录。

Markdown 原文完整文档文本