docs(spec): add three-column modern workbench and block document engine specification
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
WeiCHEN
committed by
weichen
weichen
co-authored by
Cursor
Cursor
parent
a779d353b4
commit
fa9eb31d2b
+243
@@ -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. **角色权限响应**：切换编制人可就地编辑块，切换审核人块被强锁定且支持批注，驳回操作正确触发状态流转。
|
||||
Reference in New Issue
Block a user