# 组织 让应用的终端用户自己组建团队: 创建组织、邀请成员、分配角色、转让与解散。组织只属于一个应用,不跨应用;成员关系、邀请、席位与组织动态由 CZL Connect 维护,接入方按令牌或应用级 API 读取。 组织与应用的「团队成员」是两回事:团队成员是帮你管理应用的协作者 (管理员、客服),组织是应用的用户之间的团队 (比如一家外贸公司的 5 个人共用一套单据)。 ## 适用场景 - 桌面端 / 移动端要做「团队版」,但不想自建服务端维护成员与邀请 - 有服务端的应用要按团队计费或共享额度,需要可靠的成员关系 - 配合 CZL Connect 的数据同步,让团队成员共享一个数据空间 ## 开通条件 组织按应用所有者的套餐开放,额度为每个应用可建的组织数: | 套餐 | 每应用组织数 | |---|---| | Lite | 不支持 | | Plus | 500 | | Pro | 5,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 `。 | 方法 | 路径 | 说明 | |---|---|---| | 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](/docs/app-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 通知中心;邮箱邀请另发一封邮件。所有组织操作都记入应用的操作日志,并出现在组织动态里。