docs(plan): add three-column modern workbench and block document engine implementation plan
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
WeiCHEN
@@ -0,0 +1,365 @@
|
||||
# 三栏现代工作台与块状受控文档引擎实施计划
|
||||
# (Three-Column Modern Workbench & Block-Based Document Engine Implementation Plan)
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** 构建水木东方医疗器械 AI 协同三栏现代工作台（左侧项目会话/多角色、中间对话意图/脉冲态/标杆推荐、右侧 36px 极简 Tab 与全景抽屉受控文档栏）与微粒度块状 Markdown 双向转换器和就地编辑引擎。
|
||||
|
||||
**Architecture:** 在 `web/` 下建立现代 React 19 + TypeScript + Vite 架构前端工程。设计双向 Block AST 抽象模型与动态自动重编号算法；以对话驱动为主轨、右侧工具栏就地直操为副轨实现文档编制、修改建议、审核批注与终审批准全闭环；通过 Go HTTP 静态托管与 REST/SSE 接口实现实时双向联动。
|
||||
|
||||
**Tech Stack:** React 19, TypeScript, Vite, Tailwind CSS / FlowMind Design Tokens, Lucide Icons, KaTeX, Go HTTP/SSE.
|
||||
|
||||
## Global Constraints
|
||||
- 前端源码完全集中在工程根目录 `web/` 下，独立可编译打包（`npm run build` 产出 `web/dist`）；
|
||||
- 保持深色与浅色双主题无缝切换，全局滚动条 6px 极简圆角；
|
||||
- 遵循 Conventional Commits 规范，分批原子化提交。
|
||||
|
||||
---
|
||||
|
||||
### Task 1: 前端工程脚手架与设计系统基础 (Scaffold & Design Tokens)
|
||||
|
||||
**Files:**
|
||||
- Create: `web/package.json`
|
||||
- Create: `web/tsconfig.json`
|
||||
- Create: `web/vite.config.ts`
|
||||
- Create: `web/index.html`
|
||||
- Create: `web/src/styles/tokens.css`
|
||||
- Create: `web/src/styles/index.css`
|
||||
- Test: `web/package.json` (build smoke test)
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: 基础构建环境与 CSS 变量设计系统 (`--bg-app`, `--bg-panel`, `--brand-500`, `--text-strong`, `--border`, `--ease`)，支持 `[data-theme="dark"]` 与 `[data-theme="light"]`。
|
||||
|
||||
- [ ] **Step 1: 创建 package.json、tsconfig.json 与 vite.config.ts**
|
||||
|
||||
配置 React 19、TypeScript、Vite 及必要依赖（`lucide-react`，`katex` 等）。
|
||||
|
||||
- [ ] **Step 2: 创建 index.html 与 CSS 变量系统 (tokens.css & index.css)**
|
||||
|
||||
融合 `.refs/flowmind-design` 与现代磨砂质感样式，定义 6px 自定义极简滚动条。
|
||||
|
||||
- [ ] **Step 3: 安装依赖并验证前端构建**
|
||||
|
||||
Run: `cd web && npm install && npm run build`
|
||||
Expected: PASS，成功生成 `web/dist/`。
|
||||
|
||||
- [ ] **Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git add web/package.json web/tsconfig.json web/vite.config.ts web/index.html web/src/styles/
|
||||
git commit -m "feat(web): initialize react vite typescript scaffold and token design system"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: 核心类型契约与状态定义 (Types & State Contracts)
|
||||
|
||||
**Files:**
|
||||
- Create: `web/src/types/block.ts`
|
||||
- Create: `web/src/types/workbench.ts`
|
||||
- Create: `web/src/types/docgov.ts`
|
||||
- Test: `web/src/types/types.test.ts` (TypeScript compile & validation)
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `BlockType`, `DocumentBlock`, `BlockComment`, `DocumentAST`, `ProjectSession`, `UserRole` (`author` | `reviewer` | `approver`), `ChatMessage`, `PhaseEvent`.
|
||||
|
||||
- [ ] **Step 1: 编写测试用例验证类型定义完备性**
|
||||
|
||||
编写 `web/src/types/types.test.ts` 验证 `DocumentBlock` 与 `DocumentAST` 的字段结构。
|
||||
|
||||
- [ ] **Step 2: 编写 block.ts 与 docgov.ts 类型文件**
|
||||
|
||||
完整实现规范中确立的微粒度块定义与审核批注接口。
|
||||
|
||||
- [ ] **Step 3: 编写 workbench.ts 类型文件**
|
||||
|
||||
定义项目会话、流式事件、智能体推荐案例与责任人模型。
|
||||
|
||||
- [ ] **Step 4: 执行类型校验**
|
||||
|
||||
Run: `cd web && npx tsc --noEmit`
|
||||
Expected: PASS (0 errors)。
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add web/src/types/
|
||||
git commit -m "feat(web): define block ast, workbench session, and docgov types"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3: 块状文档 AST 转换器与动态自动重编号引擎 (Block Engine & Converters)
|
||||
|
||||
**Files:**
|
||||
- Create: `web/src/engine/autoNumber.ts`
|
||||
- Create: `web/src/engine/markdownToBlock.ts`
|
||||
- Create: `web/src/engine/blockToMarkdown.ts`
|
||||
- Test: `web/src/engine/converters.test.ts`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `DocumentBlock`, `BlockType`, `DocumentAST`
|
||||
- Produces:
|
||||
- `markdownToBlockAST(md: string, meta?: Partial<DocumentAST>): DocumentAST`
|
||||
- `blockASTToMarkdown(ast: DocumentAST): string`
|
||||
- `recomputeNumbering(root: DocumentBlock): DocumentBlock`
|
||||
|
||||
- [ ] **Step 1: 编写单元测试用例 converters.test.ts**
|
||||
|
||||
测试覆盖：
|
||||
1. H1~H6 标题大纲解析与多级编号计算（`1`, `1.1`, `1.1.1`）；
|
||||
2. GFM 表格矩阵与题注提取（`表 1-1`）；
|
||||
3. Mermaid 与 LaTeX 公式代码围栏；
|
||||
4. 法规标准关键词（如 `GB 9706.1-2020`）自动打标；
|
||||
5. 插入块/调换章节顺序后的动态自动重编号测试；
|
||||
6. `blockASTToMarkdown` 无损往返序列化（Round-trip Markdown 还原）。
|
||||
|
||||
- [ ] **Step 2: 运行测试验证失败**
|
||||
|
||||
Run: `cd web && npx vitest run src/engine/converters.test.ts` 或运行 ts-node/tsx 测试脚本。
|
||||
Expected: FAIL (modules not implemented)。
|
||||
|
||||
- [ ] **Step 3: 实现 autoNumber.ts 动态编号引擎**
|
||||
|
||||
堆栈式多级标题层级追踪算法与图表递增编号。
|
||||
|
||||
- [ ] **Step 4: 实现 markdownToBlock.ts 解析器**
|
||||
|
||||
词法行扫描器、表格状态机、代码块捕获与标准正则注入。
|
||||
|
||||
- [ ] **Step 5: 实现 blockToMarkdown.ts 序列化器**
|
||||
|
||||
规范输出 GFM Markdown 与对齐表格。
|
||||
|
||||
- [ ] **Step 6: 运行测试验证通过**
|
||||
|
||||
Run: 运行转换器测试。
|
||||
Expected: PASS (100% 通过)。
|
||||
|
||||
- [ ] **Step 7: Commit**
|
||||
|
||||
```bash
|
||||
git add web/src/engine/
|
||||
git commit -m "feat(web): implement markdown block ast converters and auto-numbering engine"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 4: 三栏响应式工作台骨架与拖拽缩放 (Three-Column Shell & Rails)
|
||||
|
||||
**Files:**
|
||||
- Create: `web/src/components/layout/AppShell.tsx`
|
||||
- Create: `web/src/components/layout/Topbar.tsx`
|
||||
- Create: `web/src/components/layout/LeftRail.tsx`
|
||||
- Create: `web/src/components/layout/ChatColumn.tsx`
|
||||
- Create: `web/src/components/layout/RightDocRail.tsx`
|
||||
- Create: `web/src/components/layout/ResizeHandle.tsx`
|
||||
- Test: `web/src/components/layout/layout.test.ts`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: 响应式主骨架组件 `AppShell`，支持左栏（240~380px）与右栏（360~800px）鼠标拖拽动态缩放、双向折叠隐藏、顶栏项目面包屑与深浅主题切换。
|
||||
|
||||
- [ ] **Step 1: 编写布局拖拽与折叠逻辑的单元/集成测试**
|
||||
|
||||
测试宽度夹紧函数 `clamp(val, min, max)` 与折叠状态翻转。
|
||||
|
||||
- [ ] **Step 2: 实现 ResizeHandle 与拖拽事件监听**
|
||||
|
||||
利用 Pointer Events 实现高帧率抗抖动拖拽缩放。
|
||||
|
||||
- [ ] **Step 3: 实现 Topbar、LeftRail、RightDocRail 骨架**
|
||||
|
||||
左栏挂载会话列表容器与底部用户角色卡片；右栏搭载弹性容器。
|
||||
|
||||
- [ ] **Step 4: 组装 AppShell 并集成测试**
|
||||
|
||||
验证两端折叠与拖拽拉伸流畅性。
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add web/src/components/layout/
|
||||
git commit -m "feat(web): implement responsive three-column shell with resizable rails and theme switch"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 5: 中间栏智能体对话流与脉冲呼吸态 (Chat Stream & Thinking Pulse)
|
||||
|
||||
**Files:**
|
||||
- Create: `web/src/components/chat/MessageStream.tsx`
|
||||
- Create: `web/src/components/chat/MessageBubble.tsx`
|
||||
- Create: `web/src/components/chat/PhaseEventStrip.tsx`
|
||||
- Create: `web/src/components/chat/RecommendedCaseCard.tsx`
|
||||
- Create: `web/src/components/chat/InputArea.tsx`
|
||||
- Modify: `web/src/components/layout/ChatColumn.tsx`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `ChatMessage`, `PhaseEvent`, `RecommendedCase`
|
||||
- Produces:
|
||||
- 智能体流式回复渲染（Markdown 基础样式、三分支意图标签）；
|
||||
- 轻量化时序事件胶囊条（小队组装 ➔ 法规检索 ➔ 步骤推演）；
|
||||
- 智能推荐标杆案例卡片；
|
||||
- 智能发送按钮三态转换（空闲就绪、**思考推演脉冲呼吸态**、流式生成停止态）；
|
||||
- 文件上传与文档挂载交互。
|
||||
|
||||
- [ ] **Step 1: 编写 InputArea 与 MessageBubble 组件**
|
||||
|
||||
实现多行自动撑高、Enter 快捷键与附件挂载气泡。
|
||||
|
||||
- [ ] **Step 2: 实现 PhaseEventStrip 与 RecommendedCaseCard**
|
||||
|
||||
展示结构化时序进度条与推荐案例的相似度、标准引证和一键定位。
|
||||
|
||||
- [ ] **Step 3: 实现智能发送按钮的脉冲呼吸动效 (Breathing Pulse)**
|
||||
|
||||
通过 CSS 关键帧动画呈现科技蓝光晕呼吸态。
|
||||
|
||||
- [ ] **Step 4: 挂载至 ChatColumn 并验证模拟多轮问答流**
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add web/src/components/chat/ web/src/components/layout/ChatColumn.tsx
|
||||
git commit -m "feat(web): implement agent chat stream with thinking pulse indicator and case cards"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 6: 右侧栏 36px 极简 Tab、全景大盘抽屉与块状文档渲染器 (Slim Tabs, Deck Drawer & Block Renderer)
|
||||
|
||||
**Files:**
|
||||
- Create: `web/src/components/doc/SlimTabBar.tsx`
|
||||
- Create: `web/src/components/doc/DeckDrawer.tsx`
|
||||
- Create: `web/src/components/doc/BlockRenderer.tsx`
|
||||
- Create: `web/src/components/doc/blocks/HeadingBlockView.tsx`
|
||||
- Create: `web/src/components/doc/blocks/ParagraphBlockView.tsx`
|
||||
- Create: `web/src/components/doc/blocks/TableBlockView.tsx`
|
||||
- Create: `web/src/components/doc/blocks/CalloutBlockView.tsx`
|
||||
- Create: `web/src/components/doc/blocks/MermaidBlockView.tsx`
|
||||
- Modify: `web/src/components/layout/RightDocRail.tsx`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `DocumentAST`, `DocumentBlock`
|
||||
- Produces:
|
||||
- **36px 极简多文档 Tab 标签条**（各文档 Tab 仅占单行，带状态红绿灯）；
|
||||
- **全景交付物状态大盘抽屉 (DeckDrawer)**（展示跨阶段所有交付物、责任人与待办卡点）；
|
||||
- **块状渲染组件 (BlockRenderer)**：标题（自动编号）、三线表格、合规高亮、流程图与公式渲染。
|
||||
|
||||
- [ ] **Step 1: 编写 SlimTabBar 与 DeckDrawer 组件**
|
||||
|
||||
常驻高度 36px，点击 Tab 切换文档，点击抽屉入口滑出半透明大盘。
|
||||
|
||||
- [ ] **Step 2: 编写各类型块的独立渲染视图 (Heading, Paragraph, Table, Callout)**
|
||||
|
||||
医疗行业标准三线表排版与合规标准条款高亮。
|
||||
|
||||
- [ ] **Step 3: 集成块悬浮微操作栏 (Block Floating Bar)**
|
||||
|
||||
鼠标悬停展示：`[➕ 插块]` `[⬆️ 上移]` `[⬇️ 下移]` `[🗑️ 删除]` `[💬 批注]`。
|
||||
|
||||
- [ ] **Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git add web/src/components/doc/ web/src/components/layout/RightDocRail.tsx
|
||||
git commit -m "feat(web): implement 36px slim tabs, deck drawer, and block views with medical styling"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 7: 受控文档就地编辑、审核批注流转与双轨闭环 (In-Place Edit, Review Comments & Governance)
|
||||
|
||||
**Files:**
|
||||
- Create: `web/src/components/doc/BlockEditorModal.tsx`
|
||||
- Create: `web/src/components/doc/CommentSidePanel.tsx`
|
||||
- Create: `web/src/components/doc/ProposalConfirmCard.tsx`
|
||||
- Create: `web/src/components/doc/ExportToolbar.tsx`
|
||||
- Modify: `web/src/components/layout/AppShell.tsx`
|
||||
- Modify: `web/src/components/doc/BlockRenderer.tsx`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `UserRole`, `DocumentAST`, `onUpdateBlock`, `onAddComment`, `onPassReview`, `onRejectReview`
|
||||
- Produces:
|
||||
- 编制人双击块就地激活编辑模式，`Ctrl+S` 保存并自动重编号；
|
||||
- 审核人点击添加批注侧栏面板；
|
||||
- 审核人「通过审核」与「驳回编制（必填理由）」操作流转；
|
||||
- 已认领文档的《变更提案确认卡片》对话与面板联动；
|
||||
- 受控 Markdown 与 DOCX 结构导出动作。
|
||||
|
||||
- [ ] **Step 1: 实现 BlockEditorModal 与行内就地编辑**
|
||||
|
||||
双击文本或表格单元格激活，支持即时预览与放弃修改。
|
||||
|
||||
- [ ] **Step 2: 实现 CommentSidePanel 批注侧栏**
|
||||
|
||||
展示审核人批注列表，支持按块联动高亮与回复/采纳。
|
||||
|
||||
- [ ] **Step 3: 联动左栏底部角色切换器 (编制/审核/批准) 测试权限受控锁定**
|
||||
|
||||
编制人可修改、审核人锁定只读并支持批注与驳回。
|
||||
|
||||
- [ ] **Step 4: 实现 ExportToolbar 导出工具**
|
||||
|
||||
一键复制规范 Markdown 与生成 DOCX 结构数据下载。
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add web/src/components/doc/ web/src/components/layout/AppShell.tsx
|
||||
git commit -m "feat(web): complete in-place block editing, reviewer comments, and role governance loop"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 8: 后端静态资源托管与端到端协同联调 (Go Server Hosting & End-to-End Smoke Test)
|
||||
|
||||
**Files:**
|
||||
- Modify: `internal/server/server.go`
|
||||
- Create: `internal/server/web_assets_test.go`
|
||||
- Modify: `cmd/server/main.go`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: Go 后端根路径直接托管 `web/dist` SPA 页面，自动回退 `index.html` 路由；提供与 `/api/v1/chat/...` 及 `/api/v1/docgov/...` 的无缝联调通道。
|
||||
|
||||
- [ ] **Step 1: 在 Go Server 中配置 SPA 静态资源路由与 Fallback**
|
||||
|
||||
修改 `internal/server/server.go`，将 `/` 与 `/assets/` 映射至前端构建目录或嵌入式 FS。
|
||||
|
||||
- [ ] **Step 2: 编写 Go 单元与集成测试 web_assets_test.go**
|
||||
|
||||
验证 HTTP GET `/` 正确返回 SPA HTML，且 API 路由优先级正常。
|
||||
|
||||
- [ ] **Step 3: 构建前端并启动服务器全链路测试**
|
||||
|
||||
Run: `cd web && npm run build && cd .. && go test -v ./internal/server -run TestServer_Web*`
|
||||
Expected: PASS。
|
||||
|
||||
- [ ] **Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git add internal/server/ cmd/server/
|
||||
git commit -m "feat(server): integrate web spa static assets hosting and route fallback"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 9: 归档测试报告与交付总结 (Test Report & Completion)
|
||||
|
||||
**Files:**
|
||||
- Create: `.doc/test-reports/2026-09-08-three-column-workbench-and-block-document-test-report.md`
|
||||
|
||||
- [ ] **Step 1: 按照规范模板编制完整的测试报告**
|
||||
|
||||
记录三栏自适应缩放、块状双向转换、36px 标签页空间节省率、编制编辑与审核批注流转判定。
|
||||
|
||||
- [ ] **Step 2: 全量回归测试**
|
||||
|
||||
Run: `go test -v ./...` 与 `cd web && npm test`
|
||||
Expected: 100% PASS。
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add .doc/test-reports/
|
||||
git commit -m "docs(test): add three-column workbench and block document engine test report"
|
||||
```
|
||||
Reference in New Issue
Block a user