P4 Gotham
协同作战：项目、任务、评论把情报团队拧成一股绳
情报分析不只是一张图，更是团队作战：建项目把工作装进一个"作战室"，按角色分权限、任务看板盯进度、在分析对象上评论 @同事、收站内通知、共享视图恢复分析现场。看完这 3 个故事，你就能用协作工作流把玄武集团专项的情报工作组织起来。
情报分析员
团队负责人
项目
任务看板
@提及
共 3 个故事
能 / 不能速览
✅ 这个主题能做
- 项目：创建（Owner 自动成为 owner 成员）/ 我参与的列表 / 更新 / 归档（软删除）
- 成员角色：owner / editor / viewer 三级，读=成员、写=owner/editor、成员管理仅 owner
- 任务看板：todo → in_progress → review → done 状态机，非法流转 409；分配即发通知
- 上下文评论：挂到 entity / relationship / alert / report / task，@用户名 自动解析并发通知
- 活动流 + 通知：七种动作、五类通知，落库 + WebSocket 实时推送双通道，支持标记已读
- 共享视图：保存 graph / map / timeline / cross_filter / report 视图 State，成员可恢复现场
⛔ 这个主题做不了
- 评论不支持编辑（只有增 / 查 / 删）
- 共享视图创建时不自动发 project_share 通知（类型常量已定义，未触发）
- 通知仅站内 + WebSocket，无邮件 / IM；协同编辑（多人同屏改图）属 V2
- collab 无 demo seed，项目 / 任务 / 成员都要手动创建体验
适用角色
本主题面向两类角色：
- 情报分析员：核心使用者，在项目里建任务、评论分析对象、@同事协作、收通知。
- 团队负责人：建项目、管成员角色、看活动流掌握团队进展、归档结项。
项目内角色决定权限：owner 管人管项目，editor 可写任务评论，viewer 只能浏览。
能力速览（能做什么）
项目协作
七张 gotham_ 表支撑项目 / 成员 / 任务 / 评论 / 活动 / 通知 / 共享视图，Owner 创建即自动成为 owner 成员（事务保证）。
任务看板
四列看板 + 状态机流转，负责人（须为成员）、优先级、关联实体、截止时间；非法流转 409 GOTHAM_COLLAB_INVALID_TRANSITION。
上下文评论
评论挂到具体分析对象而非游离聊天；@用户名 反查用户表解析提及，@自己不触发通知。
实时通知
通知先落库再经 ws.Hub 实时推送；重连后可轮询补齐；服务端每 30s 心跳保活。
共享视图
State JSON 保存分析上下文，成员一键加载恢复；创建者可删（不必等 owner）。
调整指南（怎么调整）
- 改成员权限：AddMember 时选 role（owner/editor/viewer）；改角色用 PUT /collab/projects/:id/members/:user_id 原地更新（仅 owner），加成员前确认 user_id 已注册。
- 改任务：建任务时 priority（low/medium/high）、assignee_id（须为项目成员）、related_entity_ids（关联图节点 rid）、due_date 都可填。
- 改通知范围：/collab/notifications?unread_only=1 只看未读；单条 /read 与全部 /read-all 两种已读操作。
- 改评论范围：ListComments 支持 target_type / target_id 过滤；评论 target 只能是 entity/relationship/alert/report/task 五类。
- 改共享视图：view_type 支持 graph/map/timeline/cross_filter/report；State 存跨视图筛选参数。
做得好的场景
协作工作流最省事的几个场景：
- 上下文不丢：评论直接挂在实体 / 关系 / 告警 / 报告 / 任务上，讨论跟分析对象绑死，不散在群里。
- 权限分层清晰：viewer 只能看、editor 能写、owner 管人，权限判定收敛在服务层，误操作被 403 拦住。
- 通知双通道：在线实时推送、离线重连轮询补齐，任务分配 / 提及 / 状态变更一个不漏。
- 现场可恢复：共享视图存 State JSON，同事恢复你的分析上下文，不重头搭。
限制与不足
以下是明确的边界，使用前先知道：
- 评论无编辑：AddComment / ListComments / DeleteComment 三件套，发错了只能删了重发。
- 通知仅站内：task_assigned / mention / task_status / alert / project_share 五类，无邮件 / IM 触达。
- 协作编辑未实现：多人同屏协同编辑图（Yjs / OT / CRDT）属 V2；无审核工作流引擎。
场景故事
故事 1
周警官建"玄武集团资金链路专项"项目，按角色把三人小组分好权限
场景：项目与成员
角色：团队负责人
耗时：约 5 分钟
- 背景
- 2026 年 8 月，周警官牵头玄武集团资金链路专项，组里有李四（能写能改）和小王（只做复核）。他要在 Gotham 里建一个项目当作"作战室"，把三人的角色一次性分好，避免后面权限混乱。
- 传统做法对比
- 以前靠微信群拉群 + Excel 分任务，谁有没有权限全凭自觉，出了纰漏互相扯皮。现在项目内 owner / editor / viewer 三级角色由服务层强制校验，读 / 写 / 管理边界清楚。
- 角色
- 周警官（owner，建项目并管成员）；李四（editor）、小王（viewer）先注册用户再被加入。
- 操作步骤
-
- 进入 /gotham/projects，新建项目"玄武集团资金链路专项"
- 系统自动把周警官加为 owner 成员
- 添加成员：李四 role=editor、小王 role=viewer
- 在成员列表确认三人角色正确
- 系统响应
- 创建项目返回 201：
{ "code": 0, "data": { "id": 1 } }
成员列表返回：{ "code": 0, "data": [
{ "project_id": 1, "user_id": "zhou", "role": "owner" },
{ "project_id": 1, "user_id": "lisi", "role": "editor" },
{ "project_id": 1, "user_id": "xiaowang", "role": "viewer" } ] }
项目 + owner 成员在同一个事务里写入，不会出现无主项目。
- 结果洞察
- 权限分层即刻生效：owner 才能加人 / 移除成员（且不能移除自己），editor 能建任务 / 评论，viewer 只能看。周警官验证了"添加不存在的用户会被 422 拒绝"——权限边界从源头就堵住了。
- 调整建议
- 想改某人角色，直接用 PUT /collab/projects/:id/members/:user_id 原地更新（仅 owner 可改角色）；加成员前先确认对方已注册；重复添加同一用户会 409 DUPLICATE_ENTRY。
- 动手试一试
- 登录：admin / admin1，端口 18083。页面路径：/gotham/projects。预期结果：新建项目后成员列表自动含 owner（admin）；再注册一个用户 bob 并添加为 editor，列表出现第二行。
- 限制提示
- 成员 user_id 必须真实存在（查 platform 用户表），不存在返回 422；角色只能是 owner/editor/viewer；collab 无 demo seed，项目、成员都要手动创建。
故事 2
任务看板流转：把"梳理玄武→天河资金链路"从待办推到审核中，李四同步收到通知
场景：任务看板
角色：情报分析员
耗时：约 6 分钟
- 背景
- 周警官在项目里建了任务"梳理玄武→天河资金链路"，分配给李四（assignee_id=lisi）。第二天李四把初稿做完，在 /gotham/tasks 把任务从 todo 流转到 in_progress、再推到 review，请周警官复核。
- 传统做法对比
- 以前口头派活，任务到哪一步靠打电话问；现在四列看板 + 状态机，谁做了什么、卡在哪一目了然，状态变更还自动通知负责人。
- 角色
- 周警官（owner，建任务）；李四（editor，流转任务并收到分配 / 状态通知）。
- 操作步骤
-
- 周警官建任务：title=梳理玄武→天河资金链路、priority=high、assignee_id=lisi、related_entity_ids 关联玄武集团与天河贸易节点
- 李四把任务拖到 in_progress 列
- 李四完成后拖到 review 列（请复核）
- 周警官在通知中心看到 task_status 通知，进入任务查看详情
- 系统响应
- 建任务返回 201 与任务 id；分配时 assignee 收 task_assigned 通知。流转时李四试图把任务从 todo 直接拖到 done，返回 409：
{ "code": "GOTHAM_COLLAB_INVALID_TRANSITION",
"error": "任务状态流转非法（todo→in_progress→review→done）" }
合法链路 todo→in_progress→review 通过，李四收到 task_status 通知。
- 结果洞察
- 状态机防住了跳步：todo 不能直接到 done，必须按 todo→in_progress→review→done 走。分配和状态变更都自动落库 + 实时推送，李四和周警官各收一条通知，进度不靠人肉同步。
- 调整建议
- 想过滤看板：GET /collab/projects/:id/tasks?status=review&assignee_id=lisi；任务可关联图节点（related_entity_ids 存 JSON 数组），配合"动手试一试"的评论形成闭环。
- 动手试一试
- 登录：admin / admin1。页面路径：/gotham/tasks。输入内容：建任务分配给 admin 自己，再从 todo 流转 in_progress（成功）、尝试 in_progress→done（409 被拒）。预期结果：合法流转通过、非法流转 409，通知中心出现 task_status 通知。
- 限制提示
- assignee 必须是项目成员（否则 422）；done 是终态不能再流转；删除任务无回收站，删除即不可恢复。
故事 3
在玄武集团实体上评论 @周警官，mention 通知实时推送 + 共享视图恢复分析现场
场景：评论与实时通知
角色：情报分析员
耗时：约 7 分钟
- 背景
- 李四在排查玄武集团实体（graph:org:xuanwu）时发现一笔 50 万转账存疑，想在图上直接 @周警官 复核。周警官当时正开着协同动态页，希望实时收到提醒，而不是事后查列表。
- 传统做法对比
- 以前要切到微信 / 邮件另说一遍，分析上下文和讨论两张皮；现在评论直接挂在实体上，@提及即发通知，讨论跟着分析对象走。
- 角色
- 李四（editor，写评论）；周警官（被 @ 的人，通过 WebSocket 实时收通知）；小王（viewer，只能读评论）。
- 操作步骤
-
- 李四在协同动态页选 target_type=entity、target_id=graph:org:xuanwu，写"@zhou 请复核这笔 50 万转账，怀疑与天河贸易有关"
- 周警官的协同动态页 ws-bar 状态栏显示在线，实时收到 notification 推送
- 周警官点开通知跳到实体讨论区回复
- 李四把当前筛选条件存成共享视图，成员可一键恢复
- 系统响应
- 评论创建成功，被 @ 用户收到 mention 通知（内容截断 80 字符）：
{ "code": 0, "data": { "id": 3 } }
GET /api/v1/collab/notifications?unread_only=1
{ "code": 0, "data": [ { "type": "mention", "title": "评论提及",
"content": "lisi 在评论中 @了你：@zhou 请复核这笔 50 万转账…", "is_read": false } ] }
WebSocket 实时推送载荷为 {"type":"notification","data":{...}}；活动流新增 commented 记录。
- 结果洞察
- 讨论和实体绑在一起，复盘时点开实体就能看到全部评论；通知"落库 + 实时推送"双通道，在线秒收、离线可查；共享视图把李四的筛选条件存成 State JSON，周警官一键恢复分析现场，不用重头搭。
- 调整建议
- 评论列表用 target_type / target_id 过滤只看某一对象的讨论；通知中心支持单条 /read 与 /read-all；共享视图 view_type 可选 graph/map/timeline/cross_filter/report。
- 动手试一试
- 登录：admin / admin1。页面路径：/gotham/collab。输入内容：评论内容 "@admin 请复核这条链路"（@自己会被过滤，不产生通知）。预期结果：评论发表、活动时间线出现 commented；换一个真实存在的第二用户 @ 才产生 mention 通知。
- 限制提示
- @自己不构成提及（作者过滤）；通知仅站内，无邮件；共享视图创建当前不自动发 project_share 通知；评论不可编辑，发错只能删了重发。
常见问题
owner / editor / viewer 分别能做什么？
读操作（看项目 / 任务 / 评论 / 活动 / 共享视图）都要求是成员；写操作（建任务 / 评论 / 更新项目）要求 owner 或 editor；成员管理（加人 / 移除成员）仅 owner，且 owner 不能移除自己。viewer 只能读。
任务状态可以随便拖吗？
不行。状态机固定 todo→in_progress→review→done（含回退边 in_progress→todo、review→in_progress），done 是终态。非法流转返回 409 GOTHAM_COLLAB_INVALID_TRANSITION，比如 todo 直接到 done 会被拒。
@某人为什么没收到通知？
三种可能：@ 的用户名不存在（正则提取后按 username 反查用户表，查不到跳过）；@ 的是评论作者自己（作者过滤）；对方不在线且未订阅 WebSocket（但通知已落库，重连或刷新列表可见）。
通知有哪些类型？
五类：task_assigned（任务分配）、mention（评论提及）、task_status（任务状态变更）、alert（告警，经事件总线桥接广播）、project_share（共享视图，常量已定义但创建时暂未自动触发）。
评论能编辑吗？能删吗？
评论不支持编辑，只有添加 / 列表 / 删除三件套；删除评论要求 owner/editor 角色，删除不可恢复。发错了就删了重发。
主题小结
一句话：协同作战就三件事——建项目分角色、任务看板盯流转、评论 @人实时协作，共享视图保现场。记住几个边界：评论不可编辑、角色变更走原地更新（PUT 成员接口仅 owner）、通知仅站内、协同编辑属 V2。项目 + 任务 + 评论这一套，5 分钟就能跑通。