36 · 团队前端(切换器 / 成员与邀请 / 邀请落地页)
性质:已落地。2026-10-20 起草,2026-10-21 随
0fd15c5入库:G1/G3(邀请预览三字段、归档团队过滤)与 F1/F2/F3(工作区切换器、成员页、邀请落地页与待处理邀请)同批完成。收尾(2026-10-21)npm run build(Node 22.23.2)、go test ./internal/runengine、go vet ./internal/runengine全绿。不表示版本号跳了一档。 代码落点:yk-tako-eino/web/src/App.vue(切换器 / 创建工作区 / 邀请路由分发)、MembersView.vue、InviteLanding.vue、PendingInvites.vue、Configure.vue(设置|成员子导航)、auth.ts(switchTenant/tenantState);yk-tako-eino/internal/runengine/product_api.go、product_store.go(G1/G3 两处小改)。 真源关系:团队后端 API 全量在 doc/28 A6(已落地并 curl 过);Agent 页与 Team 设置页已在 doc/34 U1 落地;本篇只做团队管理的前端:工作区切换、成员与邀请、邀请落地。 不在本篇:项目目录前端(doc/35 明确另立)、助手/Agent 页(doc/34 U1 已做)、团队计费 / SSO / API key(doc/28 A7 以后)、归档团队的管理(见 §8)。
0. 本篇做什么
给 doc/28 A6 已落地的团队后端补上用户能点的页面。三件事:
- 顶栏工作区切换器:登录用户名下拉,列出我加入的所有工作区(个人 + 团队),点击切换 active tenant,底部有「创建工作区」。
- 「团队」tab 加成员管理子页:成员列表、邀请列表;owner 能创建邀请(生成链接)、撤销、移除成员、改角色、转移所有者、归档;任何人能离开。
- 邀请落地页
/invite/<token>:打开邀请链接的人看到团队名和自己的角色;已登录点「接受」直接进群,未注册走「通过邀请注册」再登录。
1. 背景与动机:三个失败故事
后端 API 在 2026-10-18 就全部能跑了,但页面上没有入口,团队功能等于不存在。
故事一:owner 邀请 Bob,只能开终端。 Alice 在页面上把自己的团队配得好好的(Team 设置页能配模型 key),想把 Bob 拉进来。页面上没有任何按钮,她只能 curl -X POST /api/tenants/:id/invitations 拿到 inviteToken,再手动拼一条链接发给 Bob。她用浏览器打开自己发的链接——404,前端没有这个路由。
故事二:Bob 收到链接,流程断在半截。 Bob 没注册过。他打开链接,即便前端有路由,预览页只告诉他「某团队邀请你」;他要注册,但注册页在哪、注册完怎么回来接受邀请,都没有指引。后端 register-by-invite 能把注册 + 建个人租户 + 加入团队一次做完,但成功响应只回 {userId, status:"accepted"},不发 token——Bob 注册完还得自己去登录页再登一次,登完也不知道自己已经在团队里了(memberships 里有,但页面上没人告诉他)。
故事三:Alice 有两个工作区,切不过去。 Alice 被拉进了前东家的团队,token 里的 active tenant 还是自己注册时的个人租户。页面上没有切换入口,她要 curl -X POST /api/auth/switch-tenant,拿到新 token 对,手动替换 sessionStorage 里的旧 token,再刷新页面。普通用户做不到。
所以这解决了什么:团队后端(邀请、成员、角色、切换)从「只能 curl」变成页面上可完成的完整流程,且注册 → 加入 → 登录 → 切到新团队的链路中间不断线。
2. 现状盘点
页面上已有什么(doc/34 U1,2026-10-19 浏览器验收):
App.vue顶栏三个 tab:对话 / 助手 / 团队;顶栏右侧显示当前工作区名和角色(tenant.name+roleLabel,App.vue:31-32)。- 「助手」tab = Agent 页(Root/Subagent,默认/覆盖/自定义);「团队」tab = Team 设置页(默认 modelRef、租户 model key、系统 MCP 状态、自定义 MCP 增删改 + 测试连接)。
- 登录态统一在
auth.ts:authFetch带 Bearer、401 自动刷新(并发 401 共用一次刷新);只有服务端明确拒绝续期(HTTP 401 且响应是引擎信封)才回登录表单,5xx 与代理错误是暂时性故障、保留登录态等下一拍(doc/81);对话页和配置页共享 sessionStorage 里的 token 对——一边登录另一边算登录。 - 未登录时对话页渲染登录表单(邮箱 + 密码)。
页面上没有什么(本篇要做的):
- 没有切换 active tenant 的入口(
POST /api/auth/switch-tenant后端在,前端没调过)。 - 没有创建团队的入口(
POST /api/tenants后端在)。 - 「团队」tab 只有运行时设置,没有成员列表、邀请管理、角色操作(成员/邀请 API 后端全在)。
- 没有
/invite/<token>路由(GET /api/invitations/:token是公开端点,前端没有对应页面)。 - 没有「我的邀请」入口(
GET /api/me/invitations后端在)。
3. 名词
- active tenant:access token 里的
tid,决定这次请求落在哪个工作区。切换走POST /api/auth/switch-tenant,成功返回新 token 对,旧 refresh 撤销。 - memberships / 工作区列表:我加入的 tenant 列表。两个来源:登录/切换响应里的
memberships(每项{tenantId, tenantName, role})和GET /api/tenants(每项{id, name, kind, role, status},多kind字段)。切换器用后者(要区分个人/团队)。 - 邀请 token:
POST /api/tenants/:id/invitations成功时一次性回显的inviteToken(base64url 32 字节随机串),库里只存它的 SHA-256。邀请链接 =<origin>/invite/<inviteToken>,7 天过期。 - 邀请 id:
in_前缀的表行 id。接受/拒绝邀请的端点按它寻址(POST /api/me/invitations/:id/accept),不按 token。 - 角色:
owner > admin > member > viewer(members_store.go 的roleRank)。能通过邀请/直接添加指派的只有admin/member/viewer;owner 只能由「转移所有者」产生。
4. 页面与链路
4.1 顶栏工作区切换器
现在:顶栏右侧一块死文字(工作区名 + 角色)。改成:可点下拉。
- 收起态:当前工作区名 + 角色 + 下拉箭头。角色按现有
roleLabel映射(所有者/管理员/成员)。 - 展开态列出
GET /api/tenants的tenants数组,每项一行:名称、kind 标签(个人/团队)、我的角色。当前 active tenant 高亮。已归档(status=archived)的不显示(§6-G0 后端对齐后天然解决)。 - 底部固定一行「+ 创建工作区」。
切换动作:点击某行 → POST /api/auth/switch-tenant,body {"tenantId":"t_...","refreshToken":"<sessionStorage 里的 refreshToken>"}(refreshToken 必填,缺了 400 111001)。成功响应和登录同形(新 token 对 + user + activeTenant + memberships):auth.ts 里新增 switchTenant(tenantId),把新 token 对写回 sessionStorage,然后整页刷新数据——对话列表、当前 tab 内容都重新拉。失败按信封弹 message(403 111201「你不是这个工作区的成员」、401 111105 登录失效回登录表单)。
创建动作:点「创建工作区」→ 弹小窗输名称 → POST /api/tenants body {"name":"…"} → 201 拿到 {tenant, membership} → 紧接着自动对新 tenant 跑一次 switch-tenant 切过去。名字空白回 400 111003「请填写工作区名称」,弹窗内联显示。
没它会怎样:Bob 加入两个团队后永远停在注册时的个人租户里,除非会 curl。
4.2 「团队」tab 加「成员」子页
Team 设置页(model key、MCP)是「团队」tab 现状。顶部加子导航:设置 | 成员。「设置」= 现状不动;「成员」= 本篇新增。
active tenant是kind=personal时:「成员」子页显示一句「个人工作区没有成员」,不发起成员请求(personal tenant 只有 owner 自己)。kind=team时,「成员」子页三块:- 成员列表(
GET /api/tenants/:id/members,viewer 即可):每行 邮箱 + 角色下拉(owner 可改,其余只读文字)。owner 的行额外有「转移所有者」按钮;非 owner 成员在自己行有「离开团队」。 - 邀请(viewer 可看列表,owner 可操作):「邀请成员」表单(邮箱 + 角色下拉 admin/member/viewer)→
POST /api/tenants/:id/invitations→ 成功后把inviteToken拼成<origin>/invite/<token>显示出来并一键复制。下方列表GET /api/tenants/:id/invitations:邮箱、角色、状态(待处理/已接受/已拒绝/已撤销)、过期时间;pending行有「撤销」(DELETE …/invitations/:inv_id,204 无 body)。 - 危险区(仅 owner):「归档这个工作区」→ 确认弹窗 →
DELETE /api/tenants/:id→ 200{status:"archived"}→ 前端自动切回个人工作区。个人 tenant 调这个端点会 403111203,但前端本来就不给个人 tenant 显示这个按钮。
- 成员列表(
角色操作的错误分支(按 code 弹 message):邀请 owner → 400 111407「不能邀请所有者」;邀请已注册成员 → 409 111406「已经是这个工作区的成员」;直接添加时邮箱未注册 → 404 111201(message 是成员文案,语义错位,见 §6-G2);降/删/退最后一个 owner → 409 111403「至少要留一个所有者」。
没它会怎样:Alice 邀请 Bob 要开终端;Bob 被拉进来了没人能把他移除或改角色(除了 curl)。
4.3 邀请落地页 /invite/<token>
公开路由,未登录也能打开(GET /api/invitations/:token 本身就是无 auth 端点)。Vue 项目目前没有 vue-router,做法:App.vue 挂载时看 location.pathname 是否 /invite/,是则渲染本组件、隐藏三 tab 主界面;token 从 path 取。
页面三种状态:
- 预览正常(200,且
status=pending且未过期——过期前端用expiresAt判断,预览响应带expiresAt,见 §6-G1):显示「{tenantName} 邀请你成为{角色},{到期时间}前有效」。下面按登录态分两种:- 已登录且当前账号邮箱匹配邀请邮箱:「接受邀请」按钮 →
POST /api/me/invitations/:id/accept(id 从预览响应拿,见 §6-G1)→ 200{status:"accepted"}→ 弹「已加入」→ 问「切换到 {tenantName}?」→ 是则switch-tenant切过去。 - 已登录但邮箱不匹配:提示「这个邀请不属于当前账号({预览里的邮箱})」,给「退出并换账号」和「用邀请邮箱注册」两个入口。
- 未登录:内联注册表单(邮箱预填邀请邮箱 + 密码 ≥8 位)→
POST /api/auth/register-by-invitebody{token, email, password}→ 201{userId, status:"accepted"}→ 显示「已加入 {tenantName},请登录」→ 登录表单 → 登录成功(响应memberships里已含新团队)→ 回到预览页或自动切过去。
- 已登录且当前账号邮箱匹配邀请邮箱:「接受邀请」按钮 →
- 预览异常:
404 code=111405「邀请无效或已过期」→ 页面显示这句话 + 「去登录/注册」链接。status=accepted/revoked/declined同理按状态显示对应文案。 - 已接受过、现在又打开链接且当前账号已是成员:accept 会回 409
111406,页面显示「你已经是这个工作区的成员」+ 「切换过去」按钮。
register-by-invite 成功不发 token(后端现状):注册完必须再走一次登录。前端把这个断点显示成一句明确的「注册成功,请登录」,不让用户干等。
没它会怎样:邀请链接发出去是 404 页面,整个邀请流程在后端空转。
4.4 我的邀请入口
登录用户可能同时躺在好几封邀请里(被多个团队邀请,但还没接受)。入口放在切换器下拉顶部:「待处理邀请(N)」一行(N>0 时高亮),点击展开内联列表(GET /api/me/invitations,只回 pending 且未过期的):每条显示团队名、角色、过期时间,「接受」「拒绝」两个按钮(POST /api/me/invitations/:id/accept|decline)。接受后同 §4.3:问是否切过去。
没它会怎样:不接受邀请就永远看不到邀请的存在(没有邮件、没有通知),被邀请的人不知道自己被邀请了。
5. 角色显隐矩阵
原则(doc/28 已定):前端只按角色隐藏按钮,后端每个路由仍自己查角色,前端藏按钮不是权限。
| 界面元素 | owner | admin | member | viewer |
|---|---|---|---|---|
| 切换器、创建工作区 | ✓ | ✓ | ✓ | ✓ |
设置子页:保存(PUT runtime-config) |
✓ | ✓ | 只读 | 只读 |
| 成员列表 / 邀请列表(看) | ✓ | ✓ | ✓ | ✓ |
| 邀请成员 / 撤销邀请 | ✓ | |||
| 移除成员 / 改角色 / 转移所有者 | ✓ | |||
| 归档工作区 | ✓ | |||
| 离开团队 | ✓(受最后 owner 限制) | ✓ | ✓ | ✓ |
6. 写方案时挖到的缺口与补齐拍(G0)
前端流程里有三处现状会让页面做不下去或行为怪异。G1/G3 是几行的后端 diff,按 AGENTS.md 的契约纪律各算一个带 curl 验收的小拍,排在 F1/F3 之前;G2 纯前端特判,并入 F3。
| # | 缺口 | 现状 | 建议 | 影响拍 |
|---|---|---|---|---|
| G1 | 预览响应不够落地页用 | GET /api/invitations/:token 只回 {tenantName, role, status};accept 端点按邀请 id 寻址,前端从 token 拿不到 id;预览也不回 email,未登录注册页没法预填,已登录也没法判断「这个邀请是不是给当前账号的」 |
预览响应加 invitationId、email、expiresAt 三个字段(邀请 id 非秘密,accept 仍要登录 + 邮箱匹配,无安全问题) |
F3 前置 |
| G2 | 邀请已注册成员的提示错位 | POST /api/me/invitations/:id/accept 在「已是成员」时回 409 111406(文案对);但 register-by-invite 的「邮箱已注册」回 409 111401「这个邮箱已经注册」——受邀的已注册用户会被引导去注册而不是登录 |
前端在落地页对 111401 特判:显示「该邮箱已注册,请直接登录后再接受邀请」 |
F3(纯前端,不改后端) |
| G3 | GET /api/tenants 不归档过滤 |
该列表只筛 tenant_members.status='active',不筛 tenants.status;而 Login/Me 的 memberships 两边都筛(identity_store.go:180-190)。归档团队会在切换器里诈尸 |
ListTenants 的 SQL 补上 AND tenants.status='active'(对齐 Login/Me),切换器不再显示已归档团队 |
F1 前置 |
G1/G3 各是几行的后端 diff,但按 AGENTS.md 的契约纪律不混进前端拍:各算一个带 curl 验收的小拍,排在 F1/F3 之前。
7. 分拍
每个 F 做完停下浏览器验收,不自动 commit。
| 拍 | 做什么 | 验收 |
|---|---|---|
| G1 | lookupInvitation 加 invitationId/email/expiresAt;curl:合法 token 的预览含三个新字段,无效 token 仍 404 111405 |
curl + 期望字节 |
| G3 | ListTenants SQL 补 tenants.status='active';curl:归档团队从列表消失,login 的 memberships 行为不变 |
curl + 期望字节 |
| F1 | 顶栏切换器(数据源 GET /api/tenants,切 switch-tenant,建 POST /api/tenants + 自动切过去) |
浏览器:注册两个用户、B 邀请 A(curl 建邀请先)、A 登录能看到两个工作区,点一下切过去,对话列表跟着变;Network 里 switch-tenant 200、新 token 已写入 |
| F2 | 「团队」tab「成员」子页(成员列表、角色下拉、移除、离开、转移 owner、归档危险区) | 浏览器:owner 视角看到全部操作;member 视角只读列表且只能看到自己行的「离开」;降最后 owner 弹「至少要留一个所有者」 |
| F3 | 邀请落地页 /invite/<token> + 切换器里「我的邀请」入口 |
浏览器全流程:owner 建邀请复制链接 → 退出登录 → 新邮箱打开链接 → 注册 → 登录 → memberships 里有新团队 → 切过去 → 成员列表里出现新人 |
8. 不在本篇
- 项目目录前端(doc/35 的项目列表、按项目筛选会话、删项目按钮):doc/35 明确「前端页面不在本篇」,属独立 loop。
- 归档团队的管理:归档不可逆(
DELETE /api/tenants/:id只翻 status),本篇只做「归档并切回个人」;解归档没有后端端点。 - 审计日志 / 用量页(
GET /api/tenants/:id/audit-log、/usage,admin):后端在,页面以后有需要再做。 - 直接添加成员(
POST /api/tenants/:id/members,只能拉已注册用户)不做入口:邀请流已覆盖「拉人」场景,直接添加对未注册邮箱报成员文案(111201)语义错位,入口做出来也是误导。owner 真要用,curl 可用。 - 邀请邮件发送:邀请链接生成后靠 owner 自己复制发出去(粘贴到微信/邮件都行)。服务端发信需要邮件设施,以后再说。
9. 闭环
所以这解决了什么。 doc/28 A6 的团队后端(创建、邀请、成员/角色、切换)在页面上可用了:任何人能建团队、拉人、被拉的人从一条链接走完注册→加入→登录→切换,多团队用户在顶栏一点就换工作区。后端契约一行不改语义(G1 只加字段、G3 只对齐过滤),路由、角色门槛、错误码全沿用 doc/28 已 curl 过的字节。
仍不解决的: 项目目录前端、归档恢复、审计/用量页、邮件送达。这些都在 §8 明说,不靠本篇顺带。