boardx / boardx/workspacex

feat(canvas): UC-7.3 协作编辑画布 —— 契约已签、缺后端实现(本域最大的一块)

Open
#1,493 6 comments 0 reactions 0 assignees View on GitHub
backlog
Dominant language
TypeScript
Stars
0
Forks
0
Avg merge
1h 7m
Merged PRs (30d)
969

Description

## 背景

同 #1464/#1465/#1468 的调查模式:`renderCanvas` / `getSource` / `updateSource` /
`exportSource` / `saveLayoutSnapshot` / `classifyChange` / `applyStickyChange` /
`applyStructuralChange` / `resolveConflict` / `listGroupCanvases` /
`listProjectCanvases` / `computeCompleteness` 在 `packages/contracts/src/canvas.ts`
里**已全部签核**(`design-signoff.md` confirmed 2026-07-31)。这是 UC-7.3「组内协作
编辑画布」的核心操作集——**canvas 域里规模最大的一块未实现契约面**。

domain 层已有相当完整的支撑逻辑:`change-classification.ts`(结构性 vs 便签级改动
判定)、`conflict-resolution.ts`(三出口冲突裁决)、`group-canvas-status.ts`、
`instance-version-freeze.ts`、`sticky-lww.ts`(便签级 LWW)。**但
`canvas-template.controller.ts` 里这些操作一条路由都没有**,`apps/web`
的 `/canvas?screen=editor`(`CanvasMain` 组件)因此仍是 100% 前端原型:写死的示例
markdown、无真实持久化、无协作。

需求文档 `phases/phase-01-run-a-project/requirements/07-canvas/
uc-7-3-组内协作编辑画布.md` 已经相当完整(工具条/缩放平移/连线锚点重算/`[源码]`视图/
Markdown⇄mermaid⇄画布三段互转/便签级 LWW/结构性冲突条,均有 [原型] 依据),**不缺
需求,缺实现**。

## UI 参考(人类 2026-08-17 指出,务必参考)

本机 `~/Documents/projects/fabric-markdown`(vendor 上游,`packages/fabric-markdown`
的来源)自带一个**可运行的完整 demo**(`demo/index.html` + `demo/main.ts`,未随
vendor 并入本仓,见 `packages/fabric-markdown/VENDOR.md`),实现了:

- 三栏布局:左侧模板分类侧栏 + 中间画布区(工具栏/画布/minimap/状态栏)+ 右侧可折叠
Markdown 源码面板(「应用到画布 ▶」/「◀ 从画布更新」双向同步按钮)
- 顶部工具栏:撤销/重做、缩放(-/100%/+)、自动布局、适配视图、更多菜单
(+节点/+便利贴/连线模式/删除选中)、导出(复制/下载 .md)
- 交互细节:双击对象内联编辑(便利贴/节点/连线/字段四种样式)、mindmap 模式节点
右缘 ⊕ 快捷加子按钮、选中节点悬浮工具条、便利贴颜色选择器、Alt+拖拽平移
- 覆盖全部 13 种 mermaid 图 + 19 个内置模板的可运行样例

这份 demo **不是本仓契约的权威**(UC-7.3 的需求文档才是),但作为「一个真实可用的
fabric-markdown 编辑器长什么样」的参照物,比空想界面细节可靠得多——实现时应先跑起来
体验一遍(`cd ~/Documents/projects/fabric-markdown && npm run dev` 之类,具体命令看
该目录 `package.json`),再对照 `uc-7-3` 需求文档定本仓实现的取舍。

## ⚠️ 实现前必须先确认的点

- **D-08/D-09 已拍板**(见 `uc-7-3` 文件头):数据链
`Markdown ⇄ mermaid 文本 ⇄ DiagramModel ⇄ Fabric 画布对象` 复用 `fabric-markdown`;
并发分粒度便签级 LWW、结构性冲突走人工裁决三出口——这两条不需要再裁决,直接按此实现。
- 规模判断:这是本域最大的一块,建议先拆子任务(如:① `getSource`/`updateSource` 只读
写源码 → ② `renderCanvas` 渲染 → ③ `applyStickyChange` 便签级写 → ④
`applyStructuralChange`/`resolveConflict` 结构写与冲突 → ⑤ `listGroupCanvases` 等
列表面),不要求一次性整块实现,每个子任务可独立验收合并。

## 验收

- `/canvas?screen=editor`(或其真实项目路由落点,需先确认是 `/canvas` hub 还是
`/projects/[id]/canvas`,见 `canvas.ts` 文件头「已建成的 `/projects/[id]/canvas`
是 mock 壳」的既有提示)真实接入至少一条写路径(建议从 `applyStickyChange` 便签级
写开始,风险最低)。
- 真栈 e2e 覆盖 D-09 的并发语义:两个便签级写 LWW 生效,一个结构性写触发冲突条。

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with packages/contracts/src/canvas.ts, the canvas-template.controller.ts entry point, and the UC-7.3 requirements document. Run the vendor demo from ~/Documents/projects/fabric-markdown using its package.json to understand the editor reference, then choose one independently verifiable operation such as applyStickyChange. Done means a real editor route reaches a persisted write path and the relevant D-09 concurrency behavior is covered by end-to-end testing.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
backend-api-design, frontend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.