组织

应用服务

组织

本页目录

让应用的终端用户自己组建团队: 创建组织、邀请成员、分配角色、转让与解散。组织只属于一个应用,不跨应用;成员关系、邀请、席位与组织动态由 CZL Connect 维护,接入方按令牌或应用级 API 读取。

组织与应用的「团队成员」是两回事:团队成员是帮你管理应用的协作者 (管理员、客服),组织是应用的用户之间的团队 (比如一家外贸公司的 5 个人共用一套单据)。

适用场景

  • 桌面端 / 移动端要做「团队版」,但不想自建服务端维护成员与邀请
  • 有服务端的应用要按团队计费或共享额度,需要可靠的成员关系
  • 配合 CZL Connect 的数据同步,让团队成员共享一个数据空间

开通条件

组织按应用所有者的套餐开放,额度为每个应用可建的组织数:

套餐每应用组织数
Lite不支持
Plus500
Pro5,000
Enterprise不限

达到上限后用户无法新建组织,已有组织照常使用。

应用中开通

进入应用详情 → 组织:

设置说明
开通组织关闭后不能新建组织、不能邀请,已有组织与成员保留
每个组织的席位1 ~ 500,席位 = 成员数 + 未过期的邮箱邀请数
每人可拥有的组织数至少 1。设为 1 即「一人只能是一个组织的所有者」
每人可加入的组织数含自己拥有的,不少于可拥有数。设为 1 即「一人只能属于一个组织」

调低上限不影响已有关系,只约束之后的创建、加入与转让。同一页可以按名称搜索应用下的全部组织。

角色

角色能做的事
owner 所有者全部操作,唯一,可转让给其他成员 (原所有者降为管理员),可解散组织,不能退出
admin 管理员改名、邀请 (邮箱 / 邀请码)、撤回邀请、管理成员与只读成员
member 成员查看成员与动态、退出
viewer 只读成员同成员;接入方据此限制写入 (如数据同步只读)

只能管理比自己级别低的成员,只能授予比自己低的角色。组织所有者被全局封禁时组织转为只读 (status: readonly),不能邀请与加入,解封后恢复。

邀请

两种方式,都需要 admin 以上:

  • 邮箱邀请:不论邮箱是否注册都返回同样结果,对方在 CZL Connect 的通知中心接受,同时收到邮件;7 天有效,拒绝后 7 天内不能再邀请同一邮箱
  • 邀请码:12 位字符,可设可用次数 (默认 1,上限为席位数) 与有效期 (默认 7 天,最长 30 天)。明文只在生成时返回一次,同时返回托管加入页 https://connect.czl.net/orgs/join?code=XXXX;也可以自己包装成 App 的自定义协议链接 (如 myapp://team/join?code=XXXX),在 App 里调用加入接口

接受邀请或凭码加入时会再次校验席位与「每人可加入的组织数」。应用开启了「仅受邀用户」时,加入组织即视同进入受邀名单。

用户令牌接口

客户端用 OAuth2 访问令牌直接调用,只能看到令牌所在应用的组织。基址:https://connect.czl.net/api/oauth2/orgs,请求头 Authorization: Bearer <access_token>。

方法路径说明
GET``我在本应用的组织 → {items: [Org]}
POST``创建组织 {name} → Org,创建人为所有者
POST/join凭邀请码加入 {code} → {org: Org, alreadyMember}
GET/{orgId}组织详情:Org + members;admin 以上另含 invites、inviteCodes
PATCH/{orgId}改名 {name}
DELETE/{orgId}解散 (所有者)
POST/{orgId}/transfer转让 {memberId} (所有者)
POST/{orgId}/leave退出
POST/{orgId}/invites邮箱邀请 {email, role}
DELETE/{orgId}/invites/{inviteId}撤回邮箱邀请
POST/{orgId}/invite-codes生成邀请码 {role, maxUses, ttlDays} → 含 code、joinUrl
DELETE/{orgId}/invite-codes/{codeId}撤回邀请码
PUT/{orgId}/members/{memberId}改角色 {role}
DELETE/{orgId}/members/{memberId}移除成员
GET/{orgId}/activity?before=&limit=组织动态,新的在前;before 传上一页最后一条的 createdAt

Org 结构:

JSON
{
  "id": "0193b6a0-…",
  "name": "华东外贸部",
  "status": "active",
  "role": "owner",
  "memberCount": 3,
  "seats": 5,
  "createdAt": "2026-11-20T08:00:00Z"
}

成员条目:{id, name, avatar, email, role, joinedAt, isSelf},email 为打码形式。组织动态条目:{action, actor, actorAvatar, target, params, description, createdAt},action 取值 create / update / invite_member / revoke_invite / accept_invite / decline_invite / update_member / remove_member / leave_org / transfer_owner / delete,params.via 为 email 或 code。

错误统一为 {error: "..."}:不是成员或组织不存在 404,角色不够或应用未开通 403,其余校验失败 400。

托管页面

没有自建界面的接入方可以直接在系统浏览器里打开 CZL Connect 的页面,用户用 CZL Connect 账号登录后管理:

  • https://connect.czl.net/orgs:我加入的全部组织
  • https://connect.czl.net/orgs/{orgId}:成员、邀请、邀请码、动态
  • https://connect.czl.net/orgs/join?code=XXXX:凭邀请码加入

应用级 API

有服务端的接入方用 API key (czlc_live_…,勾选 org:read) 读取,详见 应用级 API:

方法路径说明
GET/api/v1/app/orgs?page=&pageSize=&keyword=应用下的组织 → {items: [{id, name, status, memberCount, owner, createdAt}], total},owner 为用户标识
GET/api/v1/app/orgs/{orgId}/members成员 → {items: [{userId, role, joinedAt}]}
GET/api/v1/app/users/{userId}/orgs用户所属组织 → {items: [{id, name, role}]}

userId 与 OIDC sub 同一个值。

通知

被邀请、被移出、角色变更、成为所有者、组织解散都会写入当事人的 CZL Connect 通知中心;邮箱邀请另发一封邮件。所有组织操作都记入应用的操作日志,并出现在组织动态里。