diff --git a/docs/superpowers/plans/2026-09-08-three-column-workbench-and-block-document.md b/docs/superpowers/plans/2026-09-08-three-column-workbench-and-block-document.md new file mode 100644 index 00000000..a49b6d9d --- /dev/null +++ b/docs/superpowers/plans/2026-09-08-three-column-workbench-and-block-document.md @@ -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` + - `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" +```