Gotham 项目协作

1. 页面概览

1.1 是什么

「项目协作」页面（页面内标题为 Gotham 项目协作，TAD-11）是 LightGotham 的团队分析项目管理页：创建分析项目（如「反洗钱专项」）、管理项目成员角色，以及保存/恢复共享视图（分析上下文 State JSON）。它把「一群人围绕一个分析主题协作」的最小闭环——建项目、拉成员、存视图——集中在一个页面完成。

1.2 核心价值

1.3 一句话总结

2. 访问入口

2.1 路由与菜单

• 路由：/gotham/projects；路由名称：GothamProjects
• 路由 meta：title: Gotham 项目协作，requiresAuth: true，挂在父路由 /gotham（GothamLayout）下
• 菜单位置：Gotham 左侧边栏「协作工作流」分组下的「项目协作」
• 前端源码：action/web/src/views/GothamProjectsPage.vue
• API 客户端：action/web/src/api/gothamClient.js

2.2 认证与权限

• 路由挂 requiresAuth: true，未登录访问被全局守卫重定向到 /login。
• 请求走 gothamClient：请求拦截器自动附带 Authorization: Bearer <aip_token>；响应拦截器遇 401 时用 gotham_refresh_token 换发新 token 并重放原请求。
• 后端 collab 服务按成员角色鉴权：读操作需项目成员，写操作需 owner/editor，成员管理仅 owner。

2.3 端口与 API 前缀

• Gotham 后端端口：18083（Vite 将 /gotham-api 前缀代理到该端口并重写为 /api/v1）。
• API 前缀：/gotham-api/v1（gothamClient 的 baseURL）。

3. 界面布局

页面为「主列表 + 右侧抽屉」布局：

┌──────────────────────────────────────────────────────────────┐
│ Gotham 项目协作 [刷新]                                         │
│ [alert 操作结果提示条（可关闭）]                                │
│ ① 新建项目：项目名称（如 反洗钱专项）/ 项目描述 [创建项目]        │
│ ② 我参与的项目（N）                                            │
│    ID/名称/描述/状态/创建者/操作（详情/成员/共享视图|归档|删除）│
└──────────────────────────────────────────────────────────────┘
  ┌ 抽屉：项目 #id：name [关闭] ─────────────────────┐
  │ 成员管理：用户 ID（注册用户）/ 角色 [添加成员]      │
  │   [搜索已加入成员（渲染层过滤）]                   │
  │   用户 ID/角色/加入时间/移除                      │
  │ 共享视图（恢复分析上下文）：视图名称/类型 [保存视图] │
  │   State JSON（可选）                              │
  │   名称/类型/创建人/State/恢复（跳转）/删除          │
  └───────────────────────────────────────────────────┘

• 新建项目卡片：名称与描述两个输入框 + 「创建项目」按钮。
• 项目列表卡片：展示我参与的项目；active 项目提供「归档」操作，所有项目提供「删除」操作（软删除，语义同归档）；列表下方常驻说明软删除与无级联的范围。
• 详情抽屉：点击「详情 / 成员 / 共享视图」从右侧滑出，包含成员管理与共享视图两节。

4. 交互元素

5. 后端关联

5.1 API 客户端

• 文件：action/web/src/api/gothamClient.js；baseURL /gotham-api/v1，超时 30000ms。
• 本页为纯 CRUD，无轮询；统一响应体 {code: 0, data: ...}，前端取 res.data.data。

5.2 端点表

5.3 响应结构

统一响应体 {code: 0, data: ...}。项目与共享视图示例：

{ "code": 0, "data": [ { "id": 1, "name": "反洗钱专项", "description": "资金链路分析",
  "status": "active", "owner_id": "alice", "created_at": "2026-08-30T..." } ] }
{ "code": 0, "data": { "id": 1, "project_id": 1, "name": "华北情报视图",
  "view_type": "cross_filter", "state": {"filters":[{"field":"region","op":"eq","value":"北京"}]},
  "created_by": "alice" } }

5.4 关键机制

• 成员角色鉴权：读操作要求项目成员（否则 403「非项目成员，无权访问该项目」）；写操作要求 owner/editor（否则「仅 owner/editor 可执行该写操作」）；成员添加/移除仅 owner（「仅项目 owner 可执行该操作」）。
• 项目状态：active / archived / closed；删除与归档都落到 archived（见下条），页面仅对 active 项目展示「归档」入口。
• 删除 = 归档（软删除）：DELETE /collab/projects/:id（handlers_collab.go:79 handleDeleteCollabProject）与 POST /:id/archive（:93 handleArchiveCollabProject）都调用 collabService.ArchiveProject（collab/service.go:458），仅把 status 置为 archived 并写一条活动记录，不级联删除成员/任务/评论/共享视图，也不清理项目记录；ListProjects（collab/service.go:395）不按状态过滤，故删除后项目仍在列表中。页面确认弹窗与列表下方说明均如实标注。
• 共享视图：state 存 cross_filter/视图参数 JSON，前端「恢复」按 view_type 跳转对应分析路由并携带 view_id/view_type 查询参数（未知类型仅展示 State）。
• 实时协作：后端 collab 服务经 ws.Hub（Notifier）在项目成员变更、任务变动时向项目 room 推送 WebSocket 通知；gothamClient 提供 connectWebSocket / wsSubscribeProject 供订阅，本页未直接调用。

6. 权限与安全

• 认证：全部 /collab/* 端点位于 protected 组，JWT 无效一律 401，前端自动刷新/跳登录。
• 项目级数据隔离：项目列表按成员关系过滤（ListProjects(currentUserID)），非成员无法读取/写入他人项目，服务层 requireMember 兜底。
• 写操作防护：归档、移除成员、删除共享视图均经 window.confirm 二次确认；成员管理操作限 owner，避免越权。
• 输入校验：项目名称必填、成员用户 ID 必填、共享视图名称必填，非法 State JSON 前端自动降级为 {raw: 原文} 不阻断保存。

7. 常见问题与排错

8. 已知缺陷与边界