tako 文档 GitHub

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 已落地的团队后端补上用户能点的页面。三件事:

  1. 顶栏工作区切换器:登录用户名下拉,列出我加入的所有工作区(个人 + 团队),点击切换 active tenant,底部有「创建工作区」。
  2. 「团队」tab 加成员管理子页:成员列表、邀请列表;owner 能创建邀请(生成链接)、撤销、移除成员、改角色、转移所有者、归档;任何人能离开。
  3. 邀请落地页 /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 浏览器验收):

页面上没有什么(本篇要做的):

3. 名词

4. 页面与链路

4.1 顶栏工作区切换器

现在:顶栏右侧一块死文字(工作区名 + 角色)。改成:可点下拉。

切换动作:点击某行 → 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 现状。顶部加子导航:设置 | 成员。「设置」= 现状不动;「成员」= 本篇新增。

角色操作的错误分支(按 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 取。

页面三种状态:

  1. 预览正常(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-invite body {token, email, password} → 201 {userId, status:"accepted"} → 显示「已加入 {tenantName},请登录」→ 登录表单 → 登录成功(响应 memberships 里已含新团队)→ 回到预览页或自动切过去。
  2. 预览异常:404 code=111405「邀请无效或已过期」→ 页面显示这句话 + 「去登录/注册」链接。status=accepted/revoked/declined 同理按状态显示对应文案。
  3. 已接受过、现在又打开链接且当前账号已是成员: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. 不在本篇

9. 闭环

所以这解决了什么。 doc/28 A6 的团队后端(创建、邀请、成员/角色、切换)在页面上可用了:任何人能建团队、拉人、被拉的人从一条链接走完注册→加入→登录→切换,多团队用户在顶栏一点就换工作区。后端契约一行不改语义(G1 只加字段、G3 只对齐过滤),路由、角色门槛、错误码全沿用 doc/28 已 curl 过的字节。

仍不解决的: 项目目录前端、归档恢复、审计/用量页、邮件送达。这些都在 §8 明说,不靠本篇顺带。