Agent-System-Dev/docs/superpowers/specs/2026-10-16-document-visualization-design.md

项目文档可视化驾驶舱设计规格 r1

状态：待评审；本文件只冻结设计，不授权业务代码、数据库迁移、部署或运行验收。

1. 目标与背景

当前 RDM 已有项目级“笔记树 / 文档树 / 追溯 / 操作记录”读取入口，RdmAuditWorkspace 可以按树节点加载详情和关系。但这些入口仍以逐项查询为主，不能在进入项目后回答“项目文档完成到哪里、哪里缺内容、哪些来源未核实、哪些地方冲突、最近发生了什么”。本次目标是为文档内容建立一个项目级可视化驾驶舱：它是文档工作的聚合读取和审阅界面，不是目录列表，也不是另一个文档编辑器。

设计基线来自已确认的方向：

• 默认进入结构全景；全景和阅读器共享同一项目上下文、筛选条件和选中节点。
• 结构全景用于整体关系、完成度、风险和影响面；文档阅读器用于连续阅读和审阅正文。
• 两种视图消费同一个服务器权威聚合快照，不各自拼接一套状态。
• 个人视图偏好只决定恢复哪种视图，不扩大项目或文档权限。
• 思维导图式关系画布是后续模式，不作为第一期主界面；第一期仍采用可扫描的结构树和局部关系展开。

2. 用户与成功标准

主要用户是项目成员、文档作者、审阅者和项目管理员。用户进入项目后的前 10 秒内应能判断：

1. 项目有哪些受控文档及其完成度。
2. 哪些章节/段落为空、待确认、来源不足或存在冲突。
3. 最近哪些内容被谁修改，以及修改是否已核实。
4. 选中一个节点后，正文、来源、历史和影响对象是否可在同一屏继续阅读。

成功标准不是“显示更多信息”，而是减少用户在多个列表、弹窗和导出报告之间来回拼接上下文的次数。默认层只显示结论和下一步，原始来源、差异和工具记录按需展开。

3. 范围与非目标

3.1 本次范围

• 项目级文档聚合读取模型（Document Cockpit Read Model）。
• 文档→章节→小节→段落的结构树，带状态徽标和更新时间。
• 结构全景与文档阅读器两种视图，以及两者之间的定位跳转。
• 内容来源、核实状态、置信度、冲突、影响关系和历史摘要的统一展示。
• 按来源类型、状态、负责人、风险和最近更新的筛选。
• 个人视图/密度/展开状态的恢复；权限仍由服务器按项目和资源判定。
• 空数据、部分数据、过期快照、无权限和读取失败的诚实展示。

3.2 非目标

• 本阶段不增加文档生成、提交、审签、审批或导出动作。
• 不替换现有 RDM 事件日志、关系存储、文档正文存储或权限系统。
• 不把私人对话、上传原件或个人草稿直接公开到项目驾驶舱。
• 不引入第三种主布局、独立“后台任务页”或全局关系图。
• 不声称真实模型、真实浏览器、部署或运行环境已经验收。

4. 设计原则

1. 结论先行。 顶部统计和节点摘要先给可行动结论；原始命令、内部 ID、隐藏推理和长日志默认不占据阅读层。
2. 一份事实，多种投影。 全景、阅读器、右侧依据面板都来自同一快照和同一 snapshotRevision。
3. 来源可追溯但不越权。 展示来源类型、摘要、验证状态和可见定位；私人原文依权限字段级隐藏。
4. 不把未知显示成成功。 未读取、被截断、冲突未决和权限过滤都必须有明确状态。
5. 渐进式密度。 紧凑总览适合扫描，完整内容适合审阅；展开使用现有 @ui Collapsible 原语。
6. 视觉克制。 遵守 DESIGN.md 和 @ui/tokens.css：灰白层级、单色主操作、清晰留白、语义色只表达语义，不自造颜色或动效。

5. 总体架构

RDM 文档/章节/段落存储
RDM 来源与关系存储
RDM 原子事件与历史
RDM 项目/成员/职责授权
            |
            v
Document Cockpit Read Service
  - scope + authorization
  - node aggregation
  - source normalization
  - completeness/conflict/impact projection
  - snapshot revision + truncation
            |
            +--> cockpit overview snapshot
            +--> tree page / node detail
            +--> source/history/impact panels
            +--> local refresh / event invalidation
            |
            v
Frontend cockpit shell
  - overview header
  - panorama view
  - reader view
  - shared selection/filter state

读取服务只聚合已有领域事实。它可以建立可重建的读模型或查询投影，但不成为新的写入权威。任何写入（正文、来源核实、冲突裁定、职责变更）仍走现有领域命令和权限检查，并通过事件使读模型失效或刷新。

6. 核心对象

6.1 文档节点

节点层级固定为 document -> section -> subsection -> paragraph。若现有数据缺少某一层，读取服务返回实际层级和 structuralGap，前端不虚构空节点。每个节点至少有：

• 稳定引用：projectId、nodeRef {kind,id,version}；UI 不显示内部 ID。
• 可读标题、路径、父节点和子节点计数。
• contentState: complete | partial | empty | inaccessible | unavailable。
• verificationState: verified | mixed | unverified | disputed | not_applicable。
• sourceCount、conflictCount、impactCount、missingChildCount。
• lastChangedAt、lastChangedBy、contentRevision。
• visibility: full | redacted | metadata_only。

6.2 来源

来源类型统一为 conversation | file | web | tool | agent | human | derived。来源记录包含来源摘要、采集时间、核实人/时间、置信度、定位信息和可见性；不能展示的私人原文只返回 redactedReason 和可审计的元数据。

6.3 冲突

冲突不是简单的“有两个来源”。只有当两个可见断言对同一节点/字段在同一有效范围内给出不兼容结论时才生成 conflict。记录冲突两侧的来源引用、差异摘要、发现时间、当前状态（open | acknowledged | resolved | superseded）和裁定依据引用。

6.4 影响对象

影响对象可为 requirement | document | section | risk | task | trace_link。关系带方向、类型、强度、状态和来源。默认只显示一跳；继续展开必须明确请求深度和上限，并返回 truncated。

7. 视图职责

7.1 结构全景

默认入口。左侧显示可展开结构树；中央显示当前项目或选中文档的章节概览、完成度和异常分布；右侧显示选中节点的来源、历史、影响和冲突。全景不把长正文铺满画布，而是显示摘要和可定位的内容片段。

7.2 文档阅读器

用于连续阅读。左侧目录保持当前位置；中央按章节渲染正文、段落状态和版本差异；右侧沿用同一个依据与影响面板。选中段落时，全景和阅读器的 selectedNodeRef 同步；切换视图后保留滚动锚点、筛选条件和权限范围。

7.3 个人偏好

只保存 lastView、density、expandedNodeRefs、rightPanelTab 和阅读锚点。偏好按用户和项目隔离，服务端不得把偏好当作授权依据。新用户默认 panorama + compact；进入项目后恢复最近一次视图。

8. 一致性与刷新

• 每次读取返回 snapshotRevision、asOfSeq、generatedAt 和各自的 truncated 标志。
• 页面内异步请求必须绑定 projectId、筛选哈希、snapshotRevision 和请求代次；旧响应不得覆盖新上下文。
• 领域事件到达时只使受影响节点和统计失效，不自动改变用户正在阅读的滚动位置；显示“有更新”提示，由用户刷新或在安全点合并。
• 历史读取只能落在已提交操作批次的结束序号；落在批次中间时服务端拒绝或规范化到批次末尾。
• 聚合失败时保留上一个可识别快照并显示其时间和过期状态，不把缓存当成当前事实。

9. 权限与隐私

服务端以项目为隔离根执行：项目访问、文档可见性、职责/资源 ACL 和字段级披露共同决定返回内容。客户端隐藏入口不构成授权。私人对话、上传原件和个人草稿默认不进入共享摘要；若某个受控文档引用了它们，只返回经授权的来源摘要和稳定定位。管理员能力不自动等同于作者、审阅者或批准者能力。

10. 分期边界

• V1：聚合快照、双视图、来源/历史/影响/冲突只读展示、筛选、权限和刷新一致性。
• V1.1：局部关系展开、版本对照、来源核实入口（复用已有命令，另行授权）。
• 后续：关系画布、批量审阅、文档导出和更多领域插件。

11. 需求与验收 ID

ID	要求	验收判定
DV-R01	首屏显示项目级完成度、缺项、冲突、未核实来源、待确认变更和最近更新	有真实快照时六项均可定位；缺数据时显示原因而非 0 值冒充
DV-R02	结构树覆盖实际文档层级并显示节点状态	展开、选择、分页和空子节点均可用；不泄漏内部 ID
DV-R03	全景和阅读器共享选中节点、筛选和项目	双向切换后定位同一 nodeRef 和章节锚点
DV-R04	来源、历史、影响、冲突可从选中节点继续展开	每个面板显示计数、权限状态、来源时间和截断状态
DV-R05	快照具有可核验一致性	旧响应、乱序事件和历史中间序号不会覆盖当前状态
DV-R06	私有数据和字段级披露受服务端授权保护	未授权读取返回拒绝/脱敏；客户端绕过入口不能得到原文
DV-R07	窄屏、键盘、大字和减少动效可用	320/390/736/1024/1440 宽度无横向溢出，核心操作不依赖隐藏面板
DV-R08	诚实处理过期、部分、冲突和失败	UI 不生成虚假百分比、ETA、来源核实或完成结论

12. 当前状态

本设计基于 Dev 9edb011e63ab9bf104360379e52c30075bd2f344 的源代码和既有规划进行整理。设计文档、实现、业务测试、真实浏览器验收、CI、部署和生产数据验证均不在本文件中宣称完成。