From fa9eb31d2b68ddc8ee8514cdf43f7f4906a7124b Mon Sep 17 00:00:00 2001 From: WeiCHEN Date: Tue, 8 Sep 2026 14:34:12 +0800 Subject: [PATCH] docs(spec): add three-column modern workbench and block document engine specification Co-authored-by: Cursor --- ...umn-workbench-and-block-document-design.md | 243 ++++++++++++++++++ 1 file changed, 243 insertions(+) create mode 100644 docs/superpowers/specs/2026-09-08-three-column-workbench-and-block-document-design.md diff --git a/docs/superpowers/specs/2026-09-08-three-column-workbench-and-block-document-design.md b/docs/superpowers/specs/2026-09-08-three-column-workbench-and-block-document-design.md new file mode 100644 index 00000000..a94ce6bb --- /dev/null +++ b/docs/superpowers/specs/2026-09-08-three-column-workbench-and-block-document-design.md @@ -0,0 +1,243 @@ +# 水木东方现代三栏工作台与块状受控文档引擎设计规范 +# (Three-Column Modern Workbench & Block-Based Document Engine Specification) + +- **归档路径**: `docs/superpowers/specs/2026-09-08-three-column-workbench-and-block-document-design.md` +- **编制日期**: 2026-09-08 +- **状态**: 批准实施 (Approved) +- **技术栈**: React 19 + TypeScript + Vite + FlowMind Token 设计系统 + Go HTTP/SSE 后端 + +--- + +## 一、 系统定位与设计哲学 (Vision & Core Philosophy) + +本前端系统是面向医疗器械高端咨询与全流程研发的**现代化智能协同工作台**。核心遵循三大设计原则： + +1. **以智能体协同对话为主核，以界面工具栏直操为精准辅助（Chat-First Dual-Track Synergy）**： + - 绝大部分文档编制、修改扩写、审核批注、驳回与终审批准，均可以通过自然语言对话由智能体代劳执行； + - 界面工具栏提供高透明度、直观可视与毫秒级微调兜底能力（双击就地修改错别字、拖拽调换块顺序、手工点击签署意见）。 +2. **全生命周期受控治理（Controlled Document Lifecycle & Claiming）**： + - 严格落实**编制负责人 (Author)**、**审核负责人 (Reviewer)**、**批准负责人 (Approver)** 三权分立； + - 编制状态文档认领保护机制：未认领状态智能体直接修改；已认领状态生成变更提案需编制人确认；审核与批准阶段文档强锁定。 +3. **微粒度块状抽象与自动编号（Block-Based Document AST & Reactive Numbering）**： + - 将智能体输出的 Markdown 转换为微粒度块状对象树，赋予每个元素独立的编辑、批注与渲染能力； + - 支持图表、公式、时序图、合规引证与多级章节在拖拽增删时的全局自适应重编号。 + +--- + +## 二、 整体架构与布局系统 (Layout Architecture) + +前端构建于根目录 `web/` 下，作为独立构建但与 Go 后端无缝契合的现代 SPA 应用。 + +``` +┌─────────────────────────────────────────────────────────────────────────────────────────────┐ +│ 顶栏 (Topbar, 52px): Logo「水木东方 AI 协同」| 项目面包屑 | 主题切换 (浅色/深色) | 状态连接指示 │ +├─────────────────┬───────────────────────────────────────────┬───────────────────────────────┤ +│ 左侧栏 (Left) │ 中间栏 (Center) │ 右侧栏 (Right) │ +│ 项目会话与责任人 │ 智能体协同对话与意图流 │ 受控文档与块状编辑器 │ +│ (240px ~ 360px) │ (1fr 弹性) │ (380px ~ 760px) │ +│ [可拖拽调宽/折叠]│ │ [可拖拽调宽/折叠] │ +├─────────────────┼───────────────────────────────────────────┼───────────────────────────────┤ +│ • 新建会话按钮 │ • 顶栏：项目定位 + 成熟度进度 + 协同小队 │ • 阶段交付物全景胶囊条 (Tabs) │ +│ • 项目会话列表 │ • 消息流：用户输入 / 智能体消解回复 │ • 受控治理状态条 (编制/审/批) │ +│ (1项目=1会话) │ • 状态指示：轻量化流式事件时序卡片 │ • 块状文档渲染器 (Block AST) │ +│ • 阶段成熟度标签│ • 决策锦囊：往期标杆案例推荐气泡 │ • 块就地编辑 & 审核批注侧栏 │ +│ • 底部用户卡片 │ • 底部：多行输入框 + 文件上传 + 智能发送 │ • 变更提案确认卡片 (认领联动) │ +│ (支持快速切角色│ [带「智能体准备回复中」脉冲呼吸态] │ • 导出受控 Word / Markdown │ +└─────────────────┴───────────────────────────────────────────┴───────────────────────────────┘ +``` + +### 1. 左侧栏 (Left Rail) +- **尺寸控制**：默认 280px，支持鼠标拖拽边缘在 `240px ~ 380px` 间伸缩；可一键完全收起至 0px（保留收拢指示边条）； +- **项目会话管理 (1 项目 = 1 会话)**： + - 顶部 `+ 新建立项会话` 操作； + - 条目信息：项目名称、器械类型（如 `4K超高清荧光硬管腹腔镜`）、成熟度徽章（`V0.1 摸底` / `V0.5 方案` / `V1.0 报价`）、最后活动时间与消息计数； +- **底部用户账号与法定角色切换面板**： + - 展示当前用户头像、姓名与法定角色； + - **角色快速切换器 (Demo/Test Fast Switcher)**： + - `张工 (编制负责人 Author)` + - `李主管 (审核负责人 Reviewer)` + - `王总监 (批准负责人 Approver)` + - 一键切换用于前台直观实操不同权限下的“编制编辑、变更审批、批注评审、终审批准”。 + +### 2. 中间栏 (Center Chat Stream) +- **对话与事件时序流**： + - **用户消息**：支持纯文本与挂载附件卡片展示； + - **智能体意图与回复**：支持三分支意图标注、多轮上下文消解回复； + - **轻量化流式事件时序条**：以精简图标流展示后台进度（`👥 组装小队` ➔ `📚 检索法规` ➔ `⚙️ 执行步骤` ➔ `🛡️ 门禁把关` ➔ `✅ 阶段完成`），杜绝无效技术日志刷屏； + - **标杆案例智能推荐卡片**：直接在对话流中展示往期已批准交付物的章节摘要、参考标准与相似度，点击一键在右侧栏对比查看； +- **智能输入区域**： + - 多行自动扩展文本域（`Enter` 发送，`Shift+Enter` 换行）； + - 文件上传/输入挂载夹（支持拖拽与选择上传）； + - **智能发送按钮状态机**： + - **就绪态 (Idle)**：明亮发送图标； + - **思考与推演态 (Preparing/Thinking)**：呈现微光脉冲呼吸动画与加载转圈，提示“智能体正在调取法规并推演...”； + - **流式输出态 (Streaming)**：转换为停止按钮。 + +### 3. 右侧栏 (Right Document Rail) +- **全景交付物状态胶囊条 (Deliverable Strip)**： + - 彻底抛弃单一隐藏下拉框，顶部整齐平铺当前阶段的全部文档卡片（如 `📄 注册可行性评估`、`📊 竞品调研`、`📐 初步设计建议`）； + - 每张卡片常驻展示状态徽章：`🔵 编制中 (已认领/未认领)`、`🟠 待我审核 (带脉冲提示)`、`🟣 批准中`、`🟢 已批准受控`； + - 点击任意胶囊毫秒级平滑切换文档正文； + - 支持点击 `📂 全部交付物` 切换为跨阶段大盘清单卡片墙。 + +--- + +## 三、 块状文档抽象语法树 (Block AST) 与双向转换协议 + +所有的文档元素统一建模为**树状块结构 (Block AST)**： + +### 1. 数据结构规范 (TypeScript) + +```typescript +export type BlockType = + | 'document' // 根文档块 (Root Container) + | 'heading' // 标题块 (H1 ~ H6，带自动章节编号) + | 'paragraph' // 富文本段落块 + | 'table' // 数据表格块 (包含表头、单元格矩阵) + | 'mermaid' // 流程图/时序图块 (动态 SVG 渲染) + | 'math' // 公式块 (KaTeX / LaTeX 数学模型) + | 'callout' // 合规/风险警示引用块 (标准引证高亮) + | 'list' // 列表块 (有序/无序，包含 listItem 子块) + | 'divider'; // 分隔线 + +export interface BlockComment { + id: string; + authorName: string; + authorRole: 'reviewer' | 'approver'; + createdAt: string; + type: 'suggestion' | 'issue' | 'approval'; + content: string; + resolved: boolean; +} + +export interface DocumentBlock { + id: string; // 块唯一 UUID + type: BlockType; + level?: number; // 标题层级: 1, 2, 3, 4, 5, 6 + numbering?: string; // 自动编号引擎计算值: 如 "2.1.3"、"表 2-1"、"图 1-2" + content: string; // 块原始内容 (Markdown/文本/公式代码) + properties?: { + caption?: string; // 题注 (如 "表 2-1 4K荧光内窥镜核心技术指标") + tableData?: string[][]; // 表格数据二维数组 [行][列] + calloutType?: 'info' | 'warning' | 'danger' | 'regulatory'; + regulations?: string[]; // 识别出的法规标准 (如 ["GB 9706.1-2020 §8.4"]) + }; + children?: DocumentBlock[]; // 包含的子块 + comments?: BlockComment[]; // 挂载在该块上的审核批注 + metadata?: { + lastModifiedBy?: string; // 最后编辑人 + lastModifiedAt?: string; // 时间戳 + isLocked?: boolean; // 受控锁定标识 + }; +} + +export interface DocumentAST { + docId: string; + title: string; + version: string; + lifecycleState: 'drafting' | 'reviewing' | 'approving' | 'approved' | 'rejected'; + isClaimed: boolean; + author: string; + reviewer: string; + approver: string; + rootBlock: DocumentBlock; +} +``` + +### 2. 转换器一：Markdown ➔ 块状 AST 解析器 (`markdownToBlockAST`) +- **词法分词与状态机切分**： + - 自动识别 `# ~ ######` 标题层级，构建大纲树； + - 自动识别 GFM Table 语法，将行与单元格解析为 `tableData` 矩阵； + - 自动识别 ````mermaid` 代码块，封装为流程图专用 Block； + - 自动识别 `$$` 与 `$` LaTeX 数学公式块； + - 正则扫描法规标准关键词（如 `GB/T 16886.1`、`YY 0569`、`ISO 14971`），注入高亮元数据。 +- **动态自动编号初始化**：调用编号遍历器分配各章节与图表初试编号。 + +### 3. 转换器二：块状 AST ➔ Markdown 序列化器 (`blockASTToMarkdown`) +- 保证无损还原为规范整洁的标准 Markdown 文本； +- 表格自动重新对齐为 GFM 格式； +- 题注与公式规范还原为 Markdown 围栏与引用； +- 提交更新时回传至 Go 后端落盘至 CAS 存储与工作区 `output.md`。 + +### 4. 动态自动重编号引擎 (Reactive Auto-Numbering) +- 当用户插入新块、删除废弃章节块或拖拽调整章节位置时，触发单遍扫描： + - 维护各层级计数堆栈 `counters = [0, 0, 0, 0, 0, 0]`； + - 对标题块更新 `block.numbering`（例如 `1` ➔ `1.1` ➔ `1.2` ➔ `2` ➔ `2.1`）； + - 维护独立的图、表题注计数器（`表 1-1`、`表 1-2`）； + - 界面毫秒级响应，无需手动校准目录大纲编号。 + +--- + +## 四、 双轨协同流转机制 (Dialogue + Toolbar Dual-Track Synergy) + +### 1. 对话驱动流 (Dialogue-Driven Path, Primary) +- **编制人说**：“帮我把第 2 节的预期用途调整为供三甲医院使用的 4K 荧光腹腔镜，并补充 GB 9706.1 说明”： + - 智能体定位目标 Block，生成更新内容； + - **认领保护判定**： + - 若文档**未认领**：智能体直接无感更新该 Block，右侧栏对应位置微光动画刷新； + - 若文档**已认领**：智能体在中间栏抛出《变更提案卡片》（列明改动点、合规影响、风险点），编制人在对话中回复“同意采纳”或点击卡片按钮，右侧文档方才生效。 +- **审核人说**：“第 3 章缺少包装密封完整性标准 YY/T 0681，请记录意见”： + - 智能体解析指令，自动在第 3 章对应 Block 右侧生成一条类型为 `issue` 的审核批注。 +- **审核人说**：“审核通过，进入批准阶段” ➔ 智能体调用后端接口推进至 `approving`，右侧胶囊变为紫色。 +- **批准人说**：“准予发布” ➔ 智能体触发终审批准，右侧文档强锁定并变为绿色 `🟢 已批准`，后端 Hook 触发向量切片索引。 + +### 2. 工具栏就地直操流 (Manual Toolbar Path, Precision Support) +- **编制人编辑**：在编制状态下，双击任意段落或表格单元格就地激活编辑模式，`Ctrl+S` 保存；悬浮工具栏支持增删、上下移； +- **审核人直操**：点击块右侧 `[💬 批注]` 按钮，直接输入意见；点击右上角 `[通过]` 或 `[驳回修改]`（驳回必须填写原因）； +- **操作日志与版本回溯**：点击 `[🕒 历史]` 抽屉，查阅每一次由对话或手工触发的 Block Diff 对比。 + +--- + +## 五、 受控 DOCX 模板化导出规范 (Converter 3: Template-Driven DOCX) + +为严肃医疗器械合规申报打造开箱即用的交付物导出能力： +1. **封面规范**：文档受控编号（如 `SMDF-MD-2026-V05-01`）、器械全称、立项编号、水木东方官方 Logo、三级法定签署人（编制/审核/批准）签署栏； +2. **正文排版**： + - 标题体系：遵循医疗器械注册报告规范（宋体/黑体，1.25倍行距，一级标题自动分页）； + - 表格体系：自动套用工业级**标准三线表**（顶部与底部加粗黑线，表头下方单细线，内部无竖线，跨页表头自动复现）； + - 页眉页脚：“水木东方医疗机器人与智能装备工程中心 受控文件” + “第 X 页 共 Y 页”。 +3. **导出形态**：支持一键导出受控 `.docx` 格式与 `.md` 原文。 + +--- + +## 六、 接口契约与前后端通讯 (API & SSE Contracts) + +| 端点路径 | 方法 | 功能描述 | 配合数据体 | +| :--- | :---: | :--- | :--- | +| `/api/v1/chat/sessions` | `GET` | 分页拉取左侧项目会话列表 | Query: `limit`, `offset`, `user_id` | +| `/api/v1/chat/messages` | `GET` | 获取指定会话的历史对话记录 | Query: `session_id`, `limit` | +| `/api/v1/chat/stream` | `POST` | SSE 流式对话与任务进度推送 | Body: `{session_id, message, user_id, role}` | +| `/api/v1/docgov/document` | `GET` | 获取当前受控文档详情与内容 | Query: `doc_id`, `task_key` | +| `/api/v1/docgov/claim` | `POST` | 编制负责人认领文档 | Body: `{doc_id, user_id}` | +| `/api/v1/docgov/submit-review`| `POST` | 编制人提交送审 | Body: `{doc_id, user_id}` | +| `/api/v1/docgov/review/pass` | `POST` | 审核负责人通过审核 | Body: `{doc_id, user_id, comment}` | +| `/api/v1/docgov/review/reject`| `POST` | 审核负责人驳回编制 | Body: `{doc_id, user_id, reject_reason}` | +| `/api/v1/docgov/approve` | `POST` | 批准负责人终审批准 | Body: `{doc_id, user_id, comment}` | +| `/api/v1/context/cases/recommend` | `GET` | 语义检索往期标杆案例 | Query: `query`, `min_score=0.30` | + +--- + +## 七、 第一步 MVP 落地范围与验收标准 (MVP Scope & Acceptance Criteria) + +### 1. 第一步具体交付范围 (MVP Delivery) +- 在工程根目录下创建独立的现代前端工程 `web/`： + - 基于 React 19 + TypeScript + Vite + Tailwind/CSS Token 系统； + - 包含完善的 `package.json`、`vite.config.ts`、`tsconfig.json`； +- 实现高质感的三栏响应式骨架： + - 左侧栏：会话列表、器械状态标签、**三角色快速切换器 (编制/审核/批准)**、宽度拖拽与折叠； + - 中间栏：对话消息流、**智能体脉冲呼吸态发送指示器**、文件上传按钮、阶段进度条、推荐标杆案例卡片展示； + - 右侧栏：**全景交付物状态胶囊条 (常驻可见)**、受控治理状态徽章、**块状文档渲染器 (支持标题、文本、表格、公式、代码、合规引证与动态重编号)**； +- 实现双向转换器协议： + - `markdownToBlockAST` 解析器； + - `blockASTToMarkdown` 序列化器； + - 动态章节重编号引擎； +- 实现交互闭环： + - 编制人状态下双击块就地编辑、增删块、上下调序； + - 审核人状态下添加批注、通过/驳回操作； + - 支持直接导出为受控 Markdown / DOCX 结构。 + +### 2. 验收判定指标 (Verification) +1. **全链路可编译运行**：`web/` 前端通过 `npm run build` 无任何 TypeScript 报错与样式缺失； +2. **三栏流畅布局**：左栏与右栏均可平滑拖拽调整宽度，并支持一键折叠； +3. **块状解析与双向无损**：将典型医疗器械报告 Markdown 导入解析为 Block AST，再导出为 Markdown，核心内容与层级完全一致； +4. **角色权限响应**：切换编制人可就地编辑块，切换审核人块被强锁定且支持批注，驳回操作正确触发状态流转。