成员与角色
- Asset
- ADP-PLN-FEAT-DOC-0054
- Feature
- workspace-members-and-roles
- 领域
- plane-core
- 作用域
- application-level
- 文档状态
- draft
- 产品生命周期
- active
- 文档 Owner
- DOC
- 事实源
- canonical-docs
- 工程 Owner
- PLN
- Development Ready
- not-ready
- 更新
- 2026/10/14
FEATURE DEVELOPMENT PACKAGE
工程就绪状态
工程 Owner：PLN · 仓库：PLN
- 原子需求与验收
- 设计与工程合同
- 代码与仓库定位
- 里程碑与工作包
- 验证计划
- 无阻断决策
- Development Ready 已通过
- 验收标准已覆盖
- 正式测试已登记
- Fixture 与环境已定义
- 测试规格已物化到正式测试
- Verification Ready 已通过
- 实现修订可定位
- 发布证据已登记
- 兼容与迁移已定义
- Runbook 与回滚已定义
查看阻断项（5）
- Development Ready 缺少：原子需求与验收
- Development Ready 缺少：设计与工程合同
- Development Ready 缺少：代码与仓库定位
- Development Ready 缺少：里程碑与工作包
- Development Ready 缺少：验证计划
功能目标
在一个 Workspace 内管理成员邀请、active membership 与 Workspace Role，并在离开、移除和角色变化时保护最低管理员覆盖和 Project 访问一致性。
功能结论
| 主题 | 当前结论 |
|---|---|
| 用户 | Workspace Admin 管理邀请、角色和移除；Admin/Member 使用当前成员设置页；成员可显式离开。 |
| 入口 | /{workspaceSlug}/settings/members，支持搜索、角色筛选、部门筛选、成员活动和邀请入口。 |
| 可见结果 | 成员列表显示人员、Workspace Role、部门、active 状态等当前字段；Admin 可邀请并执行管理操作。 |
| 当前系统保证 | Workspace Role 为 Admin(20)、Member(15)、Guest(5)；membership 与 Workspace 绑定；退出/移除采用 inactive，而非把历史成员事实静默抹除。 |
| 明确不做 | Workspace Role 不等于 Project Role、部门角色、Producer approval 或 AI Agent identity。 |
| 权威 owner | 本页拥有 Workspace membership 与基础角色；主部门由部门成员页拥有，Project access 由项目成员页拥有。 |
当前落地状态、已批准合同与差距
- 当前落地状态：成员设置页允许 Workspace Admin/Member 查看，Guest 当前看到未授权页；只有 Admin 显示邀请按钮。API 支持列出/读取成员、Admin 修改角色与部门、Admin 移除以及成员自行离开。
- 已批准合同：Workspace Role、Project Role 与部门角色是分离的授权轴；部门不能替代 Workspace Role。
- 当前差距：UI 可见范围、API list/retrieve 对 Guest 的允许范围并不一致；Guest 能看到哪些成员字段需要明确批准。
- 当前差距：邀请过期、重复邀请、重新激活、批量失败、审计可见性和最后管理员规则还没有统一成为长期合同。
- 后续交付：以服务端角色矩阵为基线整理 invite/accept/update/remove/leave 全流程，再补真实 TEST 的正负向权限 evidence。
角色与权限
| Workspace Role | 当前可核验行为 | 不自动获得 |
|---|---|---|
| Admin | 邀请；修改其他成员角色/部门；移除成员；查看管理信息 | 任意 Project 的业务权限、Producer approval。 |
| Member | 当前 Web 可进入成员设置并查看/筛选；可自行离开 | 邀请、修改角色、移除他人、Workspace 基础设置的稳定写权。 |
| Guest | API 层存在受限成员读取；当前 Web 成员设置页拒绝 | Member/Admin 写能力，未加入 Project 的访问。 |
角色值是当前实现枚举，不意味着数值本身应成为外部 API 的永久业务语义。稳定合同应使用命名角色并由 server 映射。
邀请、加入、变更与离开
- Admin 打开邀请入口，提交 email、role，并可在当前实现中预设 department。
- 服务端创建邀请；接受后产生 active WorkspaceMember。邀请与身份账号是不同对象。
- Admin 可修改目标成员角色；当前 API 禁止用户修改自己的角色。
- 将成员降为 Guest 时，当前后端会把该成员的 Project membership role 同步降为 Guest；该跨层副作用需要单独审核，不能默认为最终合同。
- Admin 移除成员时，Workspace membership 和其 active Project memberships 被置为 inactive；历史活动与 creator/actor 不应改写。
- 成员可自行离开；如果其是 Workspace 唯一 Admin，或在某些 Project 中是唯一 Admin，当前后端拒绝离开。
移除他人和自行离开是两个显式动作。不得把角色改为 Guest 当作离开，也不得以删除账号替代 membership 失效。
稳定状态、数据与 API
当前核心对象包括 WorkspaceMember、WorkspaceMemberInvitation 及 member/workspace/role/is_active/department/preferences/created_at 等字段。管理 API 当前提供 member collection/item、邀请、leave、当前用户 membership、批量部门调整和 Project membership 查询。
目标公共合同至少需要：
- role、active status 和 Workspace identity 服务端校验；
- invite 重复、已接受、过期与撤销可区分；
- update/remove/leave 对同一成员并发时有确定结果；
- 最后 Workspace Admin 和最后 Project Admin 保护不依赖 UI；
- 成员失效后的 Project membership、部门关系和历史 actor 处理可解释；
- 列表按调用者角色裁剪字段，不能仅靠前端隐藏敏感信息。
跨层依赖与单一 owner
- 部门成员与角色拥有主部门、调岗历史和部门角色；本页只引用当前 department 摘要。
- 成员与访问拥有 direct Project membership 与 Project Role。
- 账号停用、登录与个人资料由账号与身份 Feature 持有，不由 Workspace membership 替代。
异常与停止条件
- 跨 Workspace member id、inactive actor、权限不足或目标成员不存在时 fail closed。
- 用户修改自己角色、移除高于 actor 的角色、最后 Workspace Admin/Project Admin 离开时拒绝。
- 邀请部分失败必须返回逐项结果，不得把部分成功报告为全部成功。
- 角色变化会影响 Project membership 时，若影响无法预览或 owner 无法解释，应停止高影响写入。
验证与权威来源
- Web 路由：
apps/web/app/(all)/[workspaceSlug]/(settings)/settings/(workspace)/members/page.tsx - Web 列表：
apps/web/core/components/workspace/settings/members-list*.tsx - API：
apps/api/plane/app/views/workspace/member.py - 权限：
apps/api/plane/app/permissions/workspace.py、apps/api/plane/app/permissions/base.py - 模型与类型：
apps/api/plane/db/models/member.py、packages/types/src/workspace.ts
源码核验不证明当前生产已部署，也不替代邀请邮件、权限负向或历史保留的 TEST evidence。
待决策问题
- Guest 是否可以看到 Workspace 成员列表；若可以，字段裁剪到什么范围？
- Workspace 角色降低是否应自动降低 Project role，还是进入影响预览与显式确认？
- 邀请重发、过期、撤销、批量部分成功和成员重新激活的稳定状态机是什么？