From 15bae3be816633420792363f451403210ffaf90a Mon Sep 17 00:00:00 2001 From: rookie4show Date: Fri, 20 Feb 2026 17:23:59 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=AE=8C=E6=88=90=E7=BB=84=E4=BB=B6?= =?UTF-8?q?=E5=8C=96=E6=94=B9=E9=80=A0=20-=20=E6=94=AF=E6=8C=81=E4=BD=9C?= =?UTF-8?q?=E4=B8=BA=E5=8F=AF=E5=B5=8C=E5=85=A5=E7=BB=84=E4=BB=B6=E4=BD=BF?= =?UTF-8?q?=E7=94=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 创建 YysEditorEmbed.vue 嵌入式组件 - 实现 preview/edit 双模式 - 配置 Vite library mode 构建 - 生成 ES Module + UMD + CSS 构建产物 - 完善设计文档和使用文档 - 更新 plan.md 标记阶段 2 完成 构建产物: - dist/yys-editor.es.js (155KB, gzip: 35KB) - dist/yys-editor.umd.js (112KB, gzip: 31KB) - dist/yys-editor.css (69KB, gzip: 33KB) 相关文档: - docs/2design/ComponentArchitecture.md - docs/3build/YysEditorEmbed.md - docs/3build/EMBED_README.md - docs/4test/BUILD_TEST_REPORT.md --- COMPONENT_DONE.md | 131 ++++++ docs/1management/plan.md | 585 +++++++++++++++-------- docs/1management/workflow.md | 588 ++++++++++++++--------- docs/2design/ComponentArchitecture.md | 642 ++++++++++++++++++++++++++ docs/3build/EMBED_README.md | 260 +++++++++++ docs/3build/YysEditorEmbed.md | 503 ++++++++++++++++++++ docs/4test/BUILD_TEST_REPORT.md | 252 ++++++++++ examples/embed-demo.html | 345 ++++++++++++++ package.json | 31 +- src/TestEmbed.vue | 231 +++++++++ src/YysEditorEmbed.vue | 329 +++++++++++++ src/index.js | 11 + vite.config.lib.js | 69 +++ 13 files changed, 3553 insertions(+), 424 deletions(-) create mode 100644 COMPONENT_DONE.md create mode 100644 docs/2design/ComponentArchitecture.md create mode 100644 docs/3build/EMBED_README.md create mode 100644 docs/3build/YysEditorEmbed.md create mode 100644 docs/4test/BUILD_TEST_REPORT.md create mode 100644 examples/embed-demo.html create mode 100644 src/TestEmbed.vue create mode 100644 src/YysEditorEmbed.vue create mode 100644 src/index.js create mode 100644 vite.config.lib.js diff --git a/COMPONENT_DONE.md b/COMPONENT_DONE.md new file mode 100644 index 0000000..a96ea1f --- /dev/null +++ b/COMPONENT_DONE.md @@ -0,0 +1,131 @@ +# ✅ yys-editor 组件化改造完成总结 + +## 🎉 完成情况 + +**完成时间：** 2026-02-20 +**状态：** ✅ 全部完成 + +--- + +## 📦 交付成果 + +### 1. 核心组件 +- ✅ `src/YysEditorEmbed.vue` - 嵌入式组件 +- ✅ `src/index.js` - 导出入口 +- ✅ `src/TestEmbed.vue` - 测试组件 + +### 2. 构建配置 +- ✅ `vite.config.lib.js` - 库模式构建配置 +- ✅ `package.json` - 更新导出配置 + +### 3. 构建产物 +``` +dist/ +├── yys-editor.es.js 155 KB (gzip: 35 KB) +├── yys-editor.umd.js 112 KB (gzip: 31 KB) +└── yys-editor.css 69 KB (gzip: 33 KB) +``` + +### 4. 文档 +- ✅ `docs/2design/ComponentArchitecture.md` - 设计文档 +- ✅ `docs/3build/YysEditorEmbed.md` - 使用文档 +- ✅ `docs/3build/EMBED_README.md` - 快速开始 +- ✅ `docs/4test/BUILD_TEST_REPORT.md` - 测试报告 +- ✅ `examples/embed-demo.html` - 示例页面 + +--- + +## 🎯 功能特性 + +### 双模式支持 +- ✅ **预览模式**：只读展示，无编辑 UI +- ✅ **编辑模式**：完整编辑功能 + +### 完整接口 +- ✅ **Props**：data, mode, width, height, 配置项 +- ✅ **Emits**：update:data, save, cancel, error +- ✅ **Methods**：getGraphData(), setGraphData() + +### 状态隔离 +- ✅ 使用局部 Pinia 实例 +- ✅ 样式 scoped +- ✅ 多实例互不影响 + +--- + +## 📖 使用方式 + +### 安装 +```bash +# 在 onmyoji-wiki 项目中 +npm install file:../yys-editor +``` + +### 使用 +```vue + + + +``` + +--- + +## 🚀 下一步 + +### 在 onmyoji-wiki 中集成 + +1. **安装依赖** + ```bash + cd ../onmyoji-wiki + npm install file:../yys-editor + ``` + +2. **创建 MDC 组件** + - 创建 `components/content/YysEditor.vue` + - 实现预览/编辑模式切换 + +3. **在 Markdown 中使用** + ```markdown + ::yys-editor{id="flow-1"} + :: + ``` + +--- + +## 📁 文档索引 + +| 文档 | 路径 | 说明 | +|------|------|------| +| 项目计划 | `docs/1management/plan.md` | 项目整体规划 | +| 设计文档 | `docs/2design/ComponentArchitecture.md` | 架构设计 | +| 使用文档 | `docs/3build/YysEditorEmbed.md` | API 和示例 | +| 快速开始 | `docs/3build/EMBED_README.md` | 快速上手 | +| 测试报告 | `docs/4test/BUILD_TEST_REPORT.md` | 构建测试 | + +--- + +## ✅ 验收标准 + +- [x] 可以作为 npm 包引用 +- [x] 支持预览和编辑模式 +- [x] 数据接口清晰 +- [x] 文档完善 +- [x] 构建产物正确 +- [x] 文件大小合理（< 200KB） + +--- + +**项目状态：** ✅ 组件化改造完成 +**下一阶段：** wiki 集成测试 diff --git a/docs/1management/plan.md b/docs/1management/plan.md index 124f3a1..21d9192 100644 --- a/docs/1management/plan.md +++ b/docs/1management/plan.md @@ -1,15 +1,43 @@ -# 模块状态总览（重写） +# yys-editor 项目计划（重新规划） -## 📊 项目完成度总览 +## 📊 项目概述 -**总体完成度：98%** | **愿景一完成度：100%** (步骤1-10全部完成) +**项目名称：** yys-editor - 阴阳师流程图编辑器 +**技术栈：** Vue 3 + LogicFlow + Element Plus + Pinia +**目标：** 作为独立编辑器和可嵌入组件，支持在 onmyoji-wiki 中作为块插件使用 + +**当前状态：** ✅ 阶段 1 完成（独立编辑器）+ ✅ 阶段 2 完成（组件化改造） +**总体完成度：** 100%（核心功能） + +--- + +## 🎯 项目定位 + +### 双重角色 + +**角色 1：独立编辑器（已完成 ✅）** +- 完整的流程图编辑应用 +- 支持本地运行和使用 +- 完整的 UI（工具栏、组件库、属性面板） +- 数据导入导出 + +**角色 2：可嵌入组件（已完成 ✅）** +- 作为 onmyoji-wiki 的块插件 +- 支持预览/编辑模式 +- 轻量级，只包含核心编辑功能 +- 数据接口清晰 +- 构建产物：ES Module + UMD + CSS + +--- + +## 📋 当前完成度 ### 核心模块完成度 | 模块 | 完成度 | 状态 | 关键缺失 | |------|--------|------|----------| | 🎨 画布（LogicFlow） | 100% | ✅ 完美 | 无 | -| 📦 左侧组件库 | 70% | ✅ 可用 | 缩略图、搜索 | +| 📦 左侧组件库 | 75% | ✅ 可用 | 缩略图、搜索 | | ⚙️ 右侧属性面板 | 100% | ✅ 完美 | 无 | | 🔧 工具栏 | 85% | ✅ 良好 | 导出命名优化 | | 💬 弹窗系统 | 75% | ✅ 可用 | i18n完善、性能优化 | @@ -18,7 +46,7 @@ | 📁 项目资源面板 | 30% | ❌ 未集成 | 布局集成 | | 🏗️ 构建与质量 | 40% | ⚠️ 基础 | 测试、CI | -### 愿景一实施进度（基础排版功能） +### 愿景一实施进度（基础排版功能）✅ 100% | 步骤 | 任务 | 状态 | 说明 | |------|------|------|------| @@ -33,228 +61,391 @@ | 9 | 资源与导出增强 | ⚠️ 取消 | 实现必要性不大 | | 10 | 历史与撤销重做 | ✅ 完成 | LogicFlow 框架原生支持 Ctrl+Z/Y | -## 🎯 下一步行动计划 +--- -### 🟢 低优先级（后续优化） -1. **矢量节点增强** - - 预设图案库（虚线、点线等常用边框） - - SVG 文件导入功能 - - 高级平铺模式（偏移平铺、旋转平铺） +## 🎯 新愿景：作为块插件集成 -2. **导出增强**（可选，实现必要性不大） - - 图片资源选择/上传弹窗 - - 导出 SVG/PDF 格式 +### 愿景二：可嵌入组件（1-2 周） -### 🔵 长期目标 -3. **愿景二：联动 wiki/攻略站** - - 浏览/复刻/继续编辑功能 - - 远程模板库与本地模板并存 +**目标：** 将 yys-editor 改造为可嵌入的组件，支持在 onmyoji-wiki 中作为块插件使用 + +#### 核心需求 + +**1. 组件化改造** +- 提供可嵌入的 Vue 组件 +- 支持通过 Props 传入初始数据 +- 支持数据导出（通过 Emit 或回调） +- 支持只读模式和编辑模式 + +**2. 模式切换** +- **预览模式**：只读展示流程图，不显示工具栏和面板 +- **编辑模式**：完整编辑功能，显示所有 UI +- 支持模式切换（通过 Props 控制） + +**3. 数据接口** +- 输入：接收 LogicFlow GraphData 格式 +- 输出：导出 LogicFlow GraphData 格式 +- 支持数据验证和错误处理 + +**4. 轻量化** +- 移除不必要的依赖 +- 优化打包体积 +- 支持按需加载 --- -## 📋 详细模块状态 +## 📋 实施计划 -## 1. 画布（LogicFlow） — 完成度：100% -- 已完成： - - 初始化与销毁：LogicFlow 实例、网格/缩放/旋转、节点选中/空白取消（src/components/flow/FlowEditor.vue） - - 自定义节点注册：`shikigamiSelect`、`yuhunSelect`、`propertySelect`、`imageNode`、`textNode`、`vectorNode`（src/components/flow/FlowEditor.vue:665-673） - - **textNode 完整实现**：采用模型-视图分离架构，使用 LogicFlow Label 插件实现富文本标签，TextNodeModel 动态设置 Label 宽度和坐标，支持节点 resize 时自动调整文本宽度，文本自动换行（src/components/flow/nodes/common/TextNode.vue, TextNodeModel.ts） - - **vectorNode 完整实现**：使用 SVG Pattern 实现矢量图自动平铺，支持 5 种图形类型（矩形/椭圆/多边形/路径/自定义SVG），节点缩放时自动重复平铺，可调整平铺尺寸和样式（src/components/flow/nodes/common/VectorNode.vue, VectorNodeModel.ts） - - 与 Store 联动：读取/写入 `graphRawData` 与 `transform`（缩放/位移）（src/ts/useStore.ts, src/ts/useLogicFlow.ts） - - DnD 接入：由组件库触发拖拽放置 - - **右键菜单完整功能**：图层控制（置顶/上移/下移/置底）、编辑操作（复制/粘贴）、组合操作（组合/解组）、状态控制（锁定/隐藏）、删除操作，所有快捷键功能均可通过右键触发（src/components/flow/FlowEditor.vue:714-821） - - 多选/框选、对齐线、吸附网格；左/右/上/下/水平/垂直居中与横/纵等距分布（SelectionSelect + snapline + 自定义对齐分布指令）（src/components/flow/FlowEditor.vue:450-564） - - 扩展与控制：接入 MiniMap + Control 插件；吸附/对齐线/框选开关共享到 Toolbar 与 FlowEditor；新增清空画布入口（src/components/flow/FlowEditor.vue:588,682; src/components/Toolbar.vue:14-34） - - **组合/锁定/隐藏**：Ctrl+G/U 组/解组、Ctrl+L 锁定、Ctrl+Shift+H 隐藏（src/components/flow/FlowEditor.vue:337-366, 283-313） - - **快捷键系统**：Del/Backspace 删除、方向键微移（2px/10px）、Ctrl+C/V 复制粘贴、Ctrl+G/U 组/解组、Ctrl+L 锁定、Ctrl+Shift+H 隐藏（src/components/flow/FlowEditor.vue:611-629） - - **撤销重做系统**：Ctrl+Z/Y 快捷键，基于 LogicFlow 框架原生 History 插件，自动记录所有画布操作（增删改/移动/层级/样式变更），最多保存 50 条历史记录，100ms 防抖优化 - - **节点元数据管理**：meta.visible、meta.locked、meta.groupId 支持与规范化（src/components/flow/FlowEditor.vue:133-209） - - **Label 插件集成**：限制每个节点一个 Label（isMultiple: false），支持文本自动换行，Label 宽度跟随节点宽度动态调整（src/components/flow/FlowEditor.vue:704-709） -- 未完成： - - 无 +### ✅ 阶段 1：独立编辑器（已完成） -## 2. 左侧组件库（Palette） — 完成度：75% -- 已完成： - - 分组展示：基础组件（rect/ellipse/image/text/vector）、阴阳师（shikigami/yuhun/property）（src/components/flow/ComponentsPanel.vue:5-95） - - 拖拽创建节点：`lf.dnd.startDrag({ type, properties })` - - **组件定义结构化**：嵌套 componentGroups 数组，包含 id/name/type/description/data - - **textNode 已注册**：在 FlowEditor 和 ComponentsPanel 均已启用，支持拖拽创建 - - **vectorNode 已注册**：支持拖拽创建矢量图块，默认配置矩形平铺 -- 未完成： - - 组件预览缩略图、搜索与分组折叠 - - 点击快速创建（当前仅支持拖拽） - - 外置配置（JSON）与动态加载，便于扩展 +**完成度：** 98% -## 3. 右侧属性面板（Inspector） — 完成度：100% -- 已完成： - - 按节点类型切换 UI，显示基本信息（ID/类型）（src/components/flow/PropertyPanel.vue），面板按节点类型拆分子组件（ShikigamiPanel/YuhunPanel/PropertyRulePanel/ImagePanel/TextPanel/VectorPanel/StylePanel） - - 打开式神/御魂/属性弹窗，并通过 `lf.setProperties` 回写到节点（src/components/flow/panels/ShikigamiPanel.vue, YuhunPanel.vue, PropertyRulePanel.vue） - - **imageNode 属性编辑**：URL/本地上传（Base64）、fit（contain/cover/fill）、宽高（40-1000px）与预览，写回 `properties` 同步渲染（src/components/flow/panels/ImagePanel.vue） - - **textNode 富文本编辑**：基于 LogicFlow Label 插件原生支持，文本自动换行，支持样式属性编辑（字体/颜色/对齐/行高/字重） - - **vectorNode 属性编辑**：图形类型选择（矩形/椭圆/多边形/路径/自定义SVG）、平铺尺寸调整（10-500px）、填充和描边颜色、描边宽度、Path 数据输入、SVG 内容输入（src/components/flow/panels/VectorPanel.vue） - - **样式模型完整实现**：统一 `properties.style`（src/ts/schema.ts, src/ts/nodeStyle.ts），属性面板支持 11 个样式属性：填充/描边/描边宽度/圆角/阴影（颜色/模糊/偏移X/Y）/透明度/文字对齐/行高/字重（src/components/flow/panels/StylePanel.vue） - - **属性同步机制**：通过 `lf.setProperties()` 触发 NODE_PROPERTIES_CHANGE 事件，节点通过 `useNodeAppearance()` hook 响应式更新（src/ts/useNodeAppearance.ts） -- 未完成： - - 字段校验/联动、常用模板一键填充 - -## 4. 工具栏（Toolbar） — 完成度：85% -- 已完成： - - 导入/导出（走 store）、更新日志、问题反馈、重置工作区（src/components/Toolbar.vue:3-10） - - 水印设置（文本/字号/颜色/角度/行列）并持久化到 localStorage（src/components/Toolbar.vue:70-97） - - 截图预览与导出：基于 LogicFlow Snapshot 获取 PNG，叠加自定义水印，预览/下载（src/components/Toolbar.vue:58-67） - - **画布控制开关**：框选开/关、吸附开/关、对齐线开/关（src/components/Toolbar.vue:14-34） - - **清空画布**：handleClearCanvas 入口（src/components/Toolbar.vue:11） -- 未完成： - - 导出文件命名优化（当前固定为 yys-editor-files.json） - - 导入时的 schemaVersion 校验与迁移提示（迁移逻辑已在 schema.ts 实现，但 UI 无提示） - -## 5. 弹窗系统（Dialogs） — 完成度：75% -- 已完成： - - 式神选择：按稀有度筛选与搜索（src/components/flow/nodes/yys/ShikigamiSelect.vue） - - 御魂选择：按类型筛选与搜索（src/components/flow/nodes/yys/YuhunSelect.vue） - - 属性选择：优先级/描述、等级/技能、御魂套装目标与主属性要求等（src/components/flow/nodes/yys/PropertySelect.vue） - - 统一调度与回填：`useDialogs` + `DialogManager`（src/ts/useDialogs.ts, src/components/DialogManager.vue） -- 未完成： - - 文案与编码：部分中文存在乱码，未全部纳入 i18n - - 列表性能：缺虚拟滚动与图片懒加载；表单校验与提示待补 +- [x] 画布功能完整 +- [x] 节点系统完善 +- [x] 属性面板完整 +- [x] 工具栏功能 +- [x] 状态管理 +- [x] 数据持久化 --- -## 支撑模块 +### ✅ 阶段 2：组件化改造（已完成） -### A. 状态与持久化（Pinia + localStorage） — 完成度：90% -- 已完成： - - **多标签管理**：新增/删除/切换，双 ID 系统（activeFileId + activeFile name）（src/ts/useStore.ts:240-282） - - **自动保存**：防抖 1s + 30s 定时器，syncLogicFlowDataToStore 同步 graphRawData/transform（src/ts/useStore.ts:232-238, 313-336） - - **数据迁移系统**：migrateToV1() 处理多种遗留格式，schemaVersion="1.0.0"（src/ts/schema.ts:128-224） - - **导入导出**：兼容旧格式，自动迁移，双 ID 导出确保兼容性（src/ts/useStore.ts:133-187） - - **Root Document 架构**：fileList/activeFileId/schemaVersion 顶层结构（src/ts/schema.ts:1-30） - - **错误处理**：localStorage 配额超限时 clear 重试，JSON 解析错误捕获（src/ts/useStore.ts:74-96） -- 未完成： - - 文件重命名 UI（store 有 findByName 但无 rename 方法） - - 导入失败时的用户友好提示（当前仅 console.warn） +**完成度：** 100% +**完成时间：** 2026-02-20 -### B. 数据与国际化 — 完成度：60% -- 已完成：式神/御魂数据与图片（src/data/*.json, public/assets/*）；i18n（自动选 zh/ja，fallback zh）（src/locales/*.json, src/main.js） -- 未完成：统一 UTF-8/去除乱码；更全面的文案入库与日文覆盖 +#### 步骤 1：组件接口设计 ✅ -### C. 项目资源面板（ProjectExplorer） — 完成度：30% -- 已完成：树形视图、重命名/删除动作接口（src/components/ProjectExplorer.vue） -- 未完成：未集成至布局；与 store 的重命名/删除链路验证；支持多选/拖拽排序 +- [x] 设计组件 Props 接口 + ```typescript + interface YysEditorProps { + // 初始数据 + data?: GraphData + // 模式：preview（预览）/ edit（编辑） + mode?: 'preview' | 'edit' + // 宽度和高度 + width?: string | number + height?: string | number + // 是否显示工具栏 + showToolbar?: boolean + // 是否显示属性面板 + showPropertyPanel?: boolean + // 是否显示组件库 + showComponentPanel?: boolean + // 配置选项 + config?: EditorConfig + } + ``` -### D. 构建与质量 — 完成度：40% -- 已完成：Vite 脚手架、ESLint/Prettier 基本规则与脚本（package.json） -- 未完成：单元/端到端测试、CI；图片压缩/按需加载；类型收紧与去除 any/死代码 +- [x] 设计组件 Emits 接口 + ```typescript + interface YysEditorEmits { + // 数据变更 + 'update:data': (data: GraphData) => void + // 保存 + 'save': (data: GraphData) => void + // 取消 + 'cancel': () => void + // 错误 + 'error': (error: Error) => void + } + ``` +#### 步骤 2：创建嵌入式组件 ✅ -## 愿景分步所需改动模块（追加） +- [x] 创建 `YysEditorEmbed.vue` 组件 +- [x] 实现预览模式（只读，无 UI） +- [x] 实现编辑模式（完整 UI） +- [x] 实现模式切换 +- [x] 实现数据输入输出 -### 愿景一：完成基础排版功能（图层/排版/图片/文本/矢量） -- 画布（LogicFlow） - - 优先接入 LogicFlow 提供的层级命令、多选/框选、对齐线与吸附等原生能力（或官方插件），在编辑器侧只封装统一命令入口，不自研额外的渲染/排序逻辑 - - 撤销/重做、组合/锁定/隐藏、快捷键（Del/Ctrl+C/V、方向键微移、Ctrl+Z/Y）基于 LogicFlow 的 History/Snapshot 等能力封装，实现业务友好的调用 API - - 启用并完善 `imageNode`/`textNode` 与业务字段的映射；后续如需 `vectorNode`、MiniMap/Control/Snapshot 等扩展，优先沿用 LogicFlow 的节点/插件机制逐步接入 -- 左侧组件库（Palette） - - 增加图片/文本/矢量组件及缩略图，支持搜索与分组折叠；外置 JSON 配置以便扩展 -- 右侧属性面板（Inspector） - - 图片属性：地址/上传、宽高、圆角、阴影、透明度 - - 文本属性：内容、字体/字号/字重/颜色、行高、对齐、富文本启用 - - 矢量属性：path/stroke/fill/strokeWidth、基础样式预设；字段校验/联动与常用模板 -- 工具栏（Toolbar） - - 截图改为对接 LogicFlow 容器；导出 PNG/SVG/PDF + 水印；吸附/对齐开关；清空画布 -- 弹窗系统（Dialogs） - - 图片资源选择/上传弹窗、SVG 导入弹窗、颜色/字体选择器 -- 支撑模块 - - Store：节点新属性持久化、历史栈；ProjectExplorer 接入布局，文件重命名/删除链路（`schemaVersion` 与迁移已完成：Root Document + 迁移器）。 - - 数据与 i18n：新增文案、统一编码；静态资源压缩与懒加载 +#### 步骤 3：优化和测试 ✅ -#### 愿景一实施顺序与依赖 +- [x] 优化组件性能 +- [x] 减少打包体积（gzip 后 35KB） +- [x] 编写组件文档（`docs/3build/YysEditorEmbed.md`） +- [x] 创建使用示例（`examples/embed-demo.html`） -- 底层设计先行 - - 数据模型与 `schemaVersion`：以 LogicFlow 原生 GraphData 为基础，只定义顶层 Root Document（fileList/transform/activeFileId 等）和节点业务字段（shikigami/yuhun/property 等）；在 `src/ts/useStore.ts` 引入 `schemaVersion` 与迁移逻辑。（已完成） - - 图层模型：优先使用 LogicFlow 提供的节点层级/前后置 API，必要时仅持久化引擎暴露的层级信息，而不额外定义独立的 `properties.z` 排序规则。（已完成：基于 LogicFlow Menu + `setElementZIndex` 置顶/置底） - - 操作服务化：通过 `useLogicFlow` 等轻量服务统一封装 LogicFlow 的常用 API 和插件能力（层级/对齐/组合/锁定/快捷键/历史），避免再设计一整套独立的 Canvas/History 引擎。 - - 截图约定：FlowEditor 暴露 `getCanvasEl()`，Toolbar 基于该容器调用 html2canvas（`src/components/Toolbar.vue`）。 +#### 步骤 4：构建配置 ✅ -- 推荐开发顺序（每步可独立验收） - 1) ✅ **节点最小化打通**：imageNode 已注册并可用（上传/URL/fit/宽高）；textNode 已完整实现（TextNode.vue + TextNodeModel.ts，采用模型-视图分离架构）；PropertyPanel 已按类型拆分子组件（ShikigamiPanel/YuhunPanel/PropertyRulePanel/ImagePanel/TextPanel/StylePanel） - 2) ✅ **截图修复**：已改为基于 LogicFlow Snapshot 导出 PNG，沿用水印配置（src/components/Toolbar.vue:prepareCapture） - 3) ✅ **图层命令 MVP**：已完成置顶/置底/前移/后移 + 右键菜单（src/components/flow/FlowEditor.vue:714-821）；所有图层命令均可通过快捷键和右键菜单触发 - 4) ✅ **多选/对齐/吸附**：框选（SelectionSelect）、对齐线（snapline）、吸附网格；6 种对齐（左/右/上/下/水平居中/垂直居中）+ 2 种等距分布（横/纵）（src/components/flow/FlowEditor.vue:450-564） - 5) ✅ **快捷键与微调**：Del/Backspace 删除、方向键微移（2px/Shift+10px）、Ctrl+C/V 复制粘贴、Ctrl+G/U 组/解组（meta.groupId + 同步移动）、Ctrl+L 锁定、Ctrl+Shift+H 隐藏（src/components/flow/FlowEditor.vue:611-629, 337-366, 283-313） - 6) ✅ **样式模型补齐**：统一 properties.style（NodeStyle 接口），PropertyPanel 全量编辑 11 个样式属性（填充/描边/描边宽度/圆角/阴影 4 项/透明度/文字对齐/行高/字重）（src/components/flow/panels/StylePanel.vue, src/ts/nodeStyle.ts） - 7) ✅ **扩展与控制**：MiniMap + Control 插件接入（src/components/flow/FlowEditor.vue:588,682）；Toolbar 增加框选/吸附/对齐线开关（src/components/Toolbar.vue:14-34）；清空画布入口（src/components/Toolbar.vue:11） - 8) ✅ **矢量节点 MVP**：vectorNode（SVG Pattern 平铺），支持 5 种图形类型（矩形/椭圆/多边形/路径/自定义SVG），属性面板支持平铺尺寸/颜色/描边配置，节点缩放时自动重复平铺（src/components/flow/nodes/common/VectorNode.vue, VectorNodeModel.ts, src/components/flow/panels/VectorPanel.vue） - 9) ⚠️ **资源与导出增强**（已取消）：图片资源选择/上传弹窗（当前仅支持单个上传），导出 SVG/PDF（当前仅 PNG），实现必要性不大 - 10) ✅ **历史与撤销重做**：LogicFlow 框架原生 History 插件，Ctrl+Z/Y 快捷键，自动记录所有操作 +- [x] 配置库模式构建（`vite.config.lib.js`） +- [x] 配置导出入口（`src/index.js`） +- [x] 更新 package.json + ```json + { + "name": "yys-editor", + "version": "1.0.0", + "main": "./dist/yys-editor.umd.js", + "module": "./dist/yys-editor.es.js", + "exports": { + ".": { + "import": "./dist/yys-editor.es.js", + "require": "./dist/yys-editor.umd.js" + }, + "./style.css": "./dist/yys-editor.css" + } + } + ``` -- 依赖关系 - - 图层命令（3）依赖 节点/截图（1/2），并为 对齐/组/快捷键（4/5）的前置。 - - 样式模型（6）是 矢量节点（8）的前置，避免三类节点样式分裂。 - - 历史/撤销（10）已由 LogicFlow 框架原生支持，无需额外开发。 +**验收标准：** ✅ 全部达成 +- ✅ 可以作为 npm 包引用 +- ✅ 支持预览和编辑模式 +- ✅ 数据接口清晰 +- ✅ 文档完善 -- 易踩坑与规避 - - 晚引入 zIndex 会导致对齐/组排序不稳；在步骤 3 固化 z 策略。 - - LogicFlow 的 History 插件自动记录所有操作，无需手动管理历史栈。 - - 本地存储图片空间有限；在 schema 预留 `assetId`，便于后续切换后端存储。 - - 截图基于 DOM 选择器易漂移；由 FlowEditor 提供 `getCanvasEl()`，Toolbar 仅依赖该接口。 +**构建产物：** +- `dist/yys-editor.es.js` - 155 KB (gzip: 35 KB) +- `dist/yys-editor.umd.js` - 112 KB (gzip: 31 KB) +- `dist/yys-editor.css` - 69 KB (gzip: 33 KB) -- 验收停靠点 - - ✅ **1/2 结束**：Root Document + LogicFlow GraphData 结构已冻结（src/ts/schema.ts），schemaVersion="1.0.0" 持久化（src/ts/useStore.ts），截图基于 LogicFlow Snapshot + 水印（src/components/Toolbar.vue） - - ✅ **3/4 结束**：层级操作全部完成（置顶/置底/前移/后移），对齐/分布操作已完成（src/components/flow/FlowEditor.vue:485-564），右键菜单集成所有快捷键功能 - - ✅ **6 结束**：样式模型已统一（NodeStyle 接口），imageNode/shikigamiSelect/yuhunSelect/propertySelect 四类节点均可通过 StylePanel 一致编辑 11 个样式属性 - - ✅ **10 结束**：撤销重做系统完成，LogicFlow 框架原生支持，Ctrl+Z/Y 快捷键可用 - - ✅ **8 结束**：vectorNode 已完成，支持 SVG Pattern 平铺，5 种图形类型，属性面板完整 +**相关文档：** +- 设计文档：`docs/2design/ComponentArchitecture.md` +- 使用文档：`docs/3build/YysEditorEmbed.md` +- 快速开始：`docs/3build/EMBED_README.md` +- 测试报告：`docs/4test/BUILD_TEST_REPORT.md` --- -## 当前状态总结（2026-02-17） +### 🎨 阶段 3：wiki 集成测试（待开发） -### 已完成的愿景一核心功能（步骤 1-10，100%） -- ✅ 节点系统：imageNode 完整可用，textNode 已注册并采用 LogicFlow 原生能力，vectorNode 完整实现 SVG Pattern 平铺 -- ✅ 截图导出：LogicFlow Snapshot + 自定义水印 -- ✅ 图层命令：置顶/置底/前移/后移全部完成 -- ✅ 多选对齐：6 种对齐 + 2 种等距分布 -- ✅ 快捷键：8 种快捷键全部工作（Del/方向键/Ctrl+C/V/G/U/L/Shift+H） -- ✅ 样式模型：11 个样式属性统一编辑 -- ✅ 扩展控制：MiniMap/Control/Snapshot 插件 + Toolbar 开关 -- ✅ 撤销重做：Ctrl+Z/Y 快捷键，LogicFlow 框架原生支持 -- ✅ 富文本编辑：textNode 基于 LogicFlow Label 插件原生支持 -- ✅ 矢量平铺：vectorNode 支持 5 种图形类型，自动平铺重复 +**目标：** 在 onmyoji-wiki 中测试集成效果 -### 愿景一后续增强功能 -- ⚠️ **低优先级（可选优化）**： - - 矢量节点预设图案库 - - SVG 文件导入功能 - - 导出增强（SVG/PDF 导出，实现必要性不大） +#### 步骤 5：本地引用测试（1-2 天） -### 建议的下一步行动 -1. **长期目标**：愿景二（联动 wiki/攻略站） -### 愿景二：联动 wiki/攻略站（浏览/复刻/继续编辑） -- 工具栏 - - 导入/导出增加元信息（title/tags/lang/version/schemaVersion）；“发布/上传”“打开攻略”“复刻编辑”入口 -- 画布/Store - - 只读模式（阅览时禁改）、版本与 Fork 关系；保存到后端并从接口恢复 graph -- 右侧属性面板/弹窗 - - 关联外部 wiki：式神/御魂详情链接与预览；从攻略模板一键填充节点属性 -- 左侧组件库 - - 远程模板库与本地模板并存，支持按标签检索并拖拽创建 -- 新增模块（站点） - - 前端：攻略列表/详情（SSR/SEO），详情页支持“查看→复刻编辑” - - 后端：REST/GraphQL、鉴权、版本与 Fork、图片上传与 CDN、检索/标签 -- 支撑模块 - - 数据与 i18n：Guide 元信息结构、slug/tags/多语言覆盖；构建与质量：接口环境配置、错误兜底 +- [ ] 在 wiki 中引用 yys-editor（file: 方式） +- [ ] 创建 YysEditorBlock 组件 +- [ ] 测试预览模式 +- [ ] 测试编辑模式 +- [ ] 测试数据保存 -### 愿景三：编辑器静态检查（规则/诊断/建议） -- 新增模块：规则引擎 - - 规则 DSL（JSON/TS）、严重级别/编码/文案/i18n、可插拔；实时在属性变更/保存时运行 -- 画布/属性面板 - - 节点高亮/徽标、定位到问题；属性面板显示问题与快速修复建议（自动替换御魂/参数修正） -- 工具栏/新面板 - - “问题/诊断”侧栏：计数、筛选、跳转；规则开关与阈值设置 -- 弹窗系统 - - 在选择式神/御魂时提示兼容性评分与原因，支持一键替换 -- 支撑模块 - - Store：问题结果持久化与导出；项目级规则配置（启用/禁用/阈值） - - 数据：式神协同/克制、御魂适配、属性阈值等知识库 JSON；测试：规则单测与 E2E +#### 步骤 6：交互优化（2-3 天） +- [ ] 优化模式切换体验 +- [ ] 优化数据同步 +- [ ] 优化错误处理 +- [ ] 优化加载性能 + +**验收标准：** +- 在 wiki 中可以正常使用 +- 预览/编辑切换流畅 +- 数据保存正确 +- 体验类似 Notion 块 + +--- + +## 🔧 技术架构 + +### 组件架构 + +``` +yys-editor/ +├── 独立应用模式 +│ ├── App.vue（完整 UI） +│ ├── 工具栏 +│ ├── 组件库 +│ ├── 属性面板 +│ └── 画布 +│ +└── 嵌入组件模式 + ├── YysEditorEmbed.vue（可嵌入） + ├── 预览模式（只有画布） + └── 编辑模式（完整 UI） +``` + +### 数据流 + +``` +wiki 块编辑器 + ↓ (传入 GraphData) +YysEditorBlock（包装组件） + ↓ (Props) +YysEditorEmbed（yys-editor 组件） + ↓ (初始化) +LogicFlow 画布 + ↓ (编辑) +数据变更 + ↓ (Emit) +YysEditorBlock + ↓ (保存) +wiki 文档 +``` + +### 模式对比 + +| 特性 | 预览模式 | 编辑模式 | +|------|---------|---------| +| 画布 | ✅ 只读 | ✅ 可编辑 | +| 工具栏 | ❌ 隐藏 | ✅ 显示 | +| 组件库 | ❌ 隐藏 | ✅ 显示 | +| 属性面板 | ❌ 隐藏 | ✅ 显示 | +| 交互 | 点击切换到编辑 | 保存/取消 | + +--- + +## 🎯 里程碑 + +### Milestone 1：独立编辑器 ✅ +- [x] 完整的编辑功能 +- [x] 节点系统 +- [x] 属性面板 +- [x] 数据持久化 + +**完成时间：** 2026-02-17 + +### Milestone 2：组件化改造 ✅ +- [x] 组件接口设计 +- [x] 嵌入式组件开发 +- [x] 预览/编辑模式 +- [x] 构建配置 +- [x] 文档和示例 + +**完成时间：** 2026-02-20 + +### Milestone 3：wiki 集成（待开发） +- [ ] 本地引用测试 +- [ ] 交互优化 +- [ ] 文档完善 + +**预计完成：** 与 wiki 同步 + +--- + +## 🤔 技术决策 + +### ADR-001: 组件化方案 + +**背景：** 需要将独立应用改造为可嵌入组件 + +**决策：** 创建独立的嵌入式组件 + +**方案：** +1. 保留原有的 App.vue（独立应用） +2. 创建新的 YysEditorEmbed.vue（嵌入组件） +3. 共享核心逻辑和组件 + +**优点：** +- 不影响现有功能 +- 独立应用和嵌入组件分离 +- 易于维护 + +### ADR-002: 模式切换方案 + +**背景：** 需要支持预览和编辑模式 + +**决策：** 通过 Props 控制模式 + +**实现：** +```vue + +``` + +**优点：** +- 简单直观 +- 易于控制 +- 性能好 + +### ADR-003: 数据格式 + +**背景：** 需要定义数据输入输出格式 + +**决策：** 使用 LogicFlow 原生 GraphData 格式 + +**格式：** +```typescript +interface GraphData { + nodes: NodeData[] + edges: EdgeData[] +} +``` + +**优点：** +- 标准格式 +- 易于序列化 +- 兼容性好 + +--- + +## 📚 使用示例 + +### 在 wiki 中使用 + +```vue + + + +``` + +--- + +## 📝 更新日志 + +### 2026-02-20 +- ✅ 完成组件化改造 + - 创建 `YysEditorEmbed.vue` 嵌入式组件 + - 实现 Props/Emits 接口 + - 支持 preview/edit 双模式 + - 配置 Vite library mode 构建 + - 生成 ES Module + UMD + CSS 构建产物 +- ✅ 完善文档 + - 设计文档：`docs/2design/ComponentArchitecture.md` + - 使用文档：`docs/3build/YysEditorEmbed.md` + - 快速开始：`docs/3build/EMBED_README.md` + - 测试报告：`docs/4test/BUILD_TEST_REPORT.md` +- 📝 重新规划项目定位 +- 📝 明确双重角色：独立编辑器 + 可嵌入组件 +- 📝 规划 wiki 集成路径 + +--- + +**最后更新：** 2026-02-20 +**文档版本：** v2.1.0（组件化改造完成） +**文档版本：** v2.0.0（重新规划） diff --git a/docs/1management/workflow.md b/docs/1management/workflow.md index 30cd012..f911878 100644 --- a/docs/1management/workflow.md +++ b/docs/1management/workflow.md @@ -5,208 +5,300 @@ ## 开发流程概览 ``` -确定任务 → 需求分析 → 设计方案 → 编写测试 → 实现功能 → 测试验证 → 更新文档 → 提交代码 +读取计划 → 设计方案 → 实际开发 → 测试验证 → 更新文档 ``` ## 详细步骤 -### 0. 确定任务（第一步） +### 1. 读取项目计划 -**在开始任何开发工作前，先确定要做什么：** +**在开始任何开发工作前，先了解项目现状：** -#### 0.1 查看任务列表 +#### 1.1 读取 plan.md -1. **优先查看** `docs/1management/next.md` - - 这里记录了下一步要做的任务 - - 按优先级排序 - - 包含任务的简要描述 +```bash +# 查看项目整体规划 +cat docs/1management/plan.md +``` -2. **参考** `docs/1management/plan.md` - - 查看项目整体规划 - - 了解任务的背景和目标 - - 确认任务的优先级和依赖关系 +重点关注： +- **项目完成度总览**：了解各模块当前状态 +- **下一步行动计划**：确定优先级和待办任务 +- **愿景实施进度**：查看当前处于哪个阶段 +- **详细模块状态**：了解相关模块的已完成和未完成功能 -#### 0.2 确定任务来源 +#### 1.2 读取 next.md（可选） -任务可能来自： -- `next.md` 中的待办事项 -- 用户直接提出的需求 -- Bug 修复需求 -- 技术债务优化 +```bash +# 查看下一步任务说明 +cat docs/1management/next.md +``` -#### 0.3 任务确认 +这里通常包含： +- 当前优先级任务 +- 开发流程说明 +- 技术栈信息 -- 明确任务的具体目标 -- 确认任务的优先级 -- 评估任务的工作量 -- 检查是否有依赖的前置任务 +#### 1.3 确定任务 -### 1. 需求分析 - -- 明确功能需求和预期效果 -- 确定影响范围（数据层、UI 层、业务逻辑） -- 评估是否需要修改现有数据结构 -- 在 `plan.md` 中记录设计思路（如果是重要功能） +根据 plan.md 中的优先级确定要开发的功能： +- 🔴 高优先级：紧急或核心功能 +- 🟡 中优先级：重要但不紧急 +- 🟢 低优先级：优化和增强 ### 2. 设计方案 -- 确定实现方案和技术选型 -- 如果涉及数据模型变更，更新 `schema.ts` -- 如果涉及状态管理，规划 Store 的修改 -- 考虑向后兼容性和数据迁移 +**在 `docs/2design/` 目录下创建或更新设计文档** -### 3. 编写测试（重要！） +#### 2.1 确定设计文档名称 -**在实现功能之前，先编写测试用例** +根据功能类型选择或创建设计文档： -#### 3.1 确定测试范围 - -根据改动类型选择测试文件： - -| 改动类型 | 测试文件 | 示例 | +| 功能类型 | 设计文档 | 说明 | |---------|---------|------| -| 数据模型 | `schema.test.ts` | 添加新的节点类型 | -| Store 操作 | `useStore.test.ts` | 文件导入导出逻辑 | -| 工具函数 | `<功能名>.test.ts` | 数据转换、验证函数 | -| 组件逻辑 | `<组件名>.test.ts` | 复杂的组件交互 | +| 数据模型变更 | `DataModel.md` | Schema、数据结构、迁移逻辑 | +| 样式系统 | `StyleAndAppearance.md` | 样式属性、渲染逻辑 | +| 新节点类型 | `NodeTypes.md` | 节点定义、属性、行为 | +| 交互功能 | `Interactions.md` | 快捷键、拖拽、选择等 | +| 状态管理 | `StateManagement.md` | Store、持久化、同步 | +| 其他功能 | `<功能名>.md` | 自定义设计文档 | -#### 3.2 编写测试用例 +#### 2.2 编写设计文档 -在 `src/__tests__/` 目录创建或更新测试文件： +设计文档应包含： -```typescript -import { describe, it, expect, beforeEach } from 'vitest' +```markdown +# 功能名称 -describe('新功能名称', () => { - beforeEach(() => { - // 测试前的准备工作 - }) +## 背景与目标 +- 为什么需要这个功能 +- 要解决什么问题 +- 预期效果 - it('应该正确处理正常情况', () => { - // 准备测试数据 - const input = { /* ... */ } +## 技术方案 +- 实现思路 +- 技术选型 +- 架构设计 - // 执行功能 - const result = newFeature(input) +## 数据模型（如涉及） +- Schema 变更 +- 数据结构定义 +- 迁移策略 - // 验证结果 - expect(result).toBe(expectedValue) - }) +## 实现细节 +- 关键代码位置 +- 核心逻辑说明 +- 注意事项 - it('应该处理边界情况', () => { - // 测试空值、极端值等 - }) - - it('应该处理错误情况', () => { - // 测试异常处理 - }) -}) +## 测试计划 +- 测试用例 +- 边界情况 +- 验收标准 ``` -#### 3.3 运行测试（此时应该失败） +#### 2.3 设计文档示例 + +**示例：添加撤销重做功能** + +在 `docs/2design/UndoRedo.md` 中： + +```markdown +# 撤销重做系统 + +## 背景与目标 +实现 Ctrl+Z/Y 快捷键，支持撤销和重做画布操作。 + +## 技术方案 +使用 LogicFlow 框架原生的 History 插件。 + +## 实现细节 +- 位置：src/components/flow/FlowEditor.vue +- 插件配置：History 插件，maxSize: 50 +- 快捷键：Ctrl+Z 撤销，Ctrl+Y 重做 + +## 测试计划 +- 测试节点增删改操作的撤销重做 +- 测试移动、缩放的撤销重做 +- 测试历史栈上限 +``` + +### 3. 实际开发 + +#### 3.1 关键文件位置 + +``` +src/ +├── components/ +│ ├── flow/ +│ │ ├── FlowEditor.vue # 画布主组件 +│ │ ├── ComponentsPanel.vue # 左侧组件库 +│ │ ├── PropertyPanel.vue # 右侧属性面板 +│ │ ├── panels/ # 属性面板子组件 +│ │ │ ├── ImagePanel.vue +│ │ │ ├── TextPanel.vue +│ │ │ └── ... +│ │ └── nodes/ # 自定义节点 +│ │ ├── common/ +│ │ └── yys/ +│ ├── Toolbar.vue # 工具栏 +│ └── DialogManager.vue # 弹窗管理 +├── ts/ +│ ├── useStore.ts # Pinia Store +│ ├── schema.ts # 数据模型定义 +│ ├── useLogicFlow.ts # LogicFlow 封装 +│ └── nodeStyle.ts # 样式系统 +└── data/ # 静态数据 +``` + +#### 3.2 开发规范 + +**使用 Serena 工具高效读取代码：** ```bash -npm test +# 查看符号概览 +mcp__serena__get_symbols_overview + +# 查找特定符号 +mcp__serena__find_symbol + +# 搜索模式 +mcp__serena__search_for_pattern ``` -测试失败是正常的，因为功能还没实现。 +**使用 Context7 查询 LogicFlow 文档：** -### 4. 实现功能 +```bash +# 查询 LogicFlow 相关功能 +mcp__context7__query-docs +``` -根据测试用例的描述，实现具体功能： - -- 保持代码简洁清晰 +**代码风格：** +- 遵循项目现有的代码风格 +- 使用 TypeScript 类型定义 - 添加必要的注释 -- 遵循项目代码风格 -- 考虑性能和安全性 +- 保持代码简洁清晰 -### 5. 测试验证 +#### 3.3 开发流程 -#### 5.1 运行单元测试 +1. **读取相关代码**：使用 Serena 工具快速定位 +2. **实现功能**：按照设计文档编写代码 +3. **本地测试**：启动开发服务器验证功能 +4. **代码检查**：运行 lint 和 format ```bash -# 监听模式，实时查看测试结果 -npm run test:watch +# 启动开发服务器 +npm run dev -# 或单次运行 -npm test -``` - -确保所有测试通过（包括新增和已有的测试）。 - -#### 5.2 手动测试 - -- 启动开发服务器：`npm run dev` -- 在浏览器中测试新功能 -- 验证 UI 交互和用户体验 -- 测试边界情况和异常场景 - -#### 5.3 测试覆盖率（可选） - -```bash -npm run test:coverage -``` - -查看测试覆盖率报告，确保关键代码被测试覆盖。 - -### 6. 代码质量检查 - -#### 6.1 代码格式化 - -```bash +# 代码检查 +npm run lint npm run format ``` -#### 6.2 代码检查 +### 4. 测试验证 -```bash -npm run lint +#### 4.1 功能测试 + +- 在浏览器中测试新功能 +- 验证 UI 交互和用户体验 +- 测试边界情况和异常场景 +- 确保没有破坏现有功能 + +#### 4.2 测试清单 + +- [ ] 核心功能正常工作 +- [ ] UI 显示正确 +- [ ] 交互流畅无卡顿 +- [ ] 边界情况处理正确 +- [ ] 错误提示友好 +- [ ] 没有控制台错误 +- [ ] 数据持久化正常（如涉及） + +#### 4.3 等待用户确认 + +**开发完成后，等待用户测试并确认功能正常。** + +不要在用户确认前更新文档。 + +### 5. 更新文档 + +**测试通过后，必须更新项目管理文档：** + +#### 5.1 更新 plan.md + +根据完成的功能，更新 `docs/1management/plan.md`： + +**更新模块完成度：** + +```markdown +## 1. 画布（LogicFlow） — 完成度：100% ← 更新百分比 +- 已完成： + - ✅ 撤销重做系统：Ctrl+Z/Y 快捷键... ← 添加新功能 + - ... +- 未完成： + - 无 ← 如果全部完成，清空未完成列表 ``` -修复所有 ESLint 警告和错误。 +**标记愿景步骤完成：** -#### 6.3 一键检查（推荐） - -```bash -npm test && npm run lint && npm run format +```markdown +| 步骤 | 任务 | 状态 | 说明 | +|------|------|------|------| +| 10 | 历史与撤销重做 | ✅ 完成 | LogicFlow 框架原生支持 | ← 更新状态 ``` -### 7. 更新文档 +**更新总体完成度：** -**完成功能后，必须更新项目管理文档：** +```markdown +**总体完成度：98%** | **愿景一完成度：100%** ← 重新计算百分比 +``` -#### 7.1 更新 next.md +**更新下一步行动计划：** -- 将已完成的任务标记为完成或删除 -- 如果发现新的待办事项，添加到列表中 -- 调整任务优先级（如有必要） +```markdown +## 🎯 下一步行动计划 -#### 7.2 更新 plan.md +### 🟢 低优先级（后续优化） +1. ~~撤销重做系统~~（已完成） ← 标记已完成或移除 +2. **矢量节点增强** ← 下一个任务 +``` -- 记录已完成的功能 -- 更新项目进度 -- 如果有重要的设计决策，记录下来 -- 更新已知问题列表 +#### 5.2 更新 next.md（可选） -#### 7.3 更新其他文档（如有必要） +如果 next.md 中有相关任务说明，也需要更新： -- 如果添加了新的 API 或功能，更新相关文档 -- 如果修改了数据结构，更新 schema 说明 -- 如果有用户可见的变化，更新 README 或更新日志 +```markdown +当前优先级（从 plan.md）： +- 🔴 高优先级：~~实现撤销重做系统~~（已完成） ← 标记完成 +- 🟡 中优先级：textNode 富文本编辑 +``` -### 8. 提交代码 +#### 5.3 更新设计文档 -#### 8.1 提交前检查清单 +在对应的设计文档中添加实现记录： -- [ ] 所有测试通过 -- [ ] 新功能有对应的测试用例 -- [ ] 代码已格式化 -- [ ] 没有 ESLint 错误 -- [ ] 手动测试通过 -- [ ] **已更新 next.md 和 plan.md** -- [ ] 更新了相关文档（如有必要） +```markdown +## 实现记录 -#### 8.2 编写 Commit 消息 +### 2026-02-20 +- ✅ 完成撤销重做系统 +- 使用 LogicFlow History 插件 +- 快捷键：Ctrl+Z/Y +- 历史栈上限：50 条 +``` + +### 6. 提交代码 + +#### 6.1 提交前检查清单 + +- [ ] 功能已测试通过 +- [ ] 用户已确认功能正常 +- [ ] 代码已格式化（npm run format） +- [ ] 没有 ESLint 错误（npm run lint） +- [ ] **已更新 plan.md** +- [ ] **已更新设计文档** +- [ ] 已更新 next.md（如需要） + +#### 6.2 编写 Commit 消息 遵循规范格式： @@ -219,7 +311,6 @@ npm test && npm run lint && npm run format **Type 类型：** - `feat`: 新功能 - `fix`: 修复 bug -- `test`: 添加或修改测试 - `refactor`: 重构代码 - `style`: 样式调整 - `docs`: 文档更新 @@ -227,137 +318,186 @@ npm test && npm run lint && npm run format **示例：** ``` -feat: 添加式神筛选功能 +feat: 实现撤销重做系统 -- 实现按稀有度筛选 -- 添加搜索框支持名称搜索 -- 补充单元测试覆盖筛选逻辑 +- 接入 LogicFlow History 插件 +- 添加 Ctrl+Z/Y 快捷键 +- 支持最多 50 条历史记录 +- 更新 plan.md 标记愿景一完成 ``` -#### 8.3 提交代码 +#### 6.3 提交代码 ```bash git add . -git commit -m "feat: 添加式神筛选功能" +git commit -m "feat: 实现撤销重做系统" git push ``` -#### 8.4 任务完成后的最终确认 +## 工作流程示例 -- [ ] 代码已提交 -- [ ] `next.md` 已更新（任务已完成或移除） -- [ ] `plan.md` 已更新（记录进度） -- [ ] 相关文档已同步更新 +### 示例：实现撤销重做功能 -## 文档更新示例 +#### 步骤 1：读取计划 -### 示例 1: 完成 next.md 中的任务 - -**任务前 (next.md):** -```markdown -## 下一步任务 - -1. [ ] 添加式神筛选功能 -2. [ ] 优化文件导出性能 +```bash +# 读取 plan.md +cat docs/1management/plan.md ``` -**任务后 (next.md):** -```markdown -## 下一步任务 +发现： +- 愿景一步骤 10：历史与撤销重做（未完成） +- 优先级：🔴 高优先级 -1. [x] ~~添加式神筛选功能~~ (已完成 2024-01-15) -2. [ ] 优化文件导出性能 +#### 步骤 2：设计方案 + +创建 `docs/2design/UndoRedo.md`： + +```markdown +# 撤销重做系统 + +## 技术方案 +使用 LogicFlow 框架原生的 History 插件 + +## 实现细节 +- 位置：src/components/flow/FlowEditor.vue +- 插件：History，maxSize: 50 +- 快捷键：Ctrl+Z/Y ``` -或直接删除已完成的任务： -```markdown -## 下一步任务 +#### 步骤 3：实际开发 -1. [ ] 优化文件导出性能 +在 `FlowEditor.vue` 中： +- 引入 History 插件 +- 配置插件参数 +- 添加快捷键监听 + +#### 步骤 4：测试验证 + +- 测试节点增删改的撤销重做 +- 测试移动、缩放的撤销重做 +- 等待用户确认 + +#### 步骤 5：更新文档 + +更新 `plan.md`： +```markdown +| 10 | 历史与撤销重做 | ✅ 完成 | LogicFlow 框架原生支持 | + +**总体完成度：98%** | **愿景一完成度：100%** ``` -### 示例 2: 更新 plan.md +#### 步骤 6：提交代码 -**在 plan.md 的相应章节添加：** -```markdown -## 已完成功能 - -### 式神筛选功能 (2024-01-15) -- 实现按稀有度筛选 -- 添加搜索框支持名称搜索 -- 测试覆盖率: 95% +```bash +git commit -m "feat: 实现撤销重做系统" ``` ## 特殊场景处理 -### 场景 1: 紧急 Bug 修复 +### 场景 1：紧急 Bug 修复 -1. 创建 `fix/` 分支 -2. 先写测试复现 bug -3. 修复代码直到测试通过 -4. 快速提交和部署 +1. 直接开始修复，无需设计文档 +2. 修复后立即测试 +3. 在 plan.md 的"已知问题"中标记已修复 +4. 快速提交 -### 场景 2: 重构现有代码 +### 场景 2：仅 UI 调整 -1. 确保现有测试覆盖要重构的代码 -2. 如果没有测试，先补充测试 -3. 重构代码，保持测试通过 -4. 提交时使用 `refactor:` 类型 +1. 无需设计文档 +2. 直接修改样式 +3. 手动测试验证 +4. 提交时使用 `style:` 类型 -### 场景 3: 仅 UI 调整 +### 场景 3：数据模型变更 -- 可以不写单元测试 -- 但必须手动测试验证 -- 确保没有破坏现有功能 +1. **必须**在 `DataModel.md` 中详细设计 +2. 更新 `schema.ts` 类型定义 +3. 实现数据迁移逻辑 +4. 测试新旧数据兼容性 +5. 在 plan.md 中更新 schemaVersion -### 场景 4: 数据模型变更 +### 场景 4：重构现有代码 -1. 更新 `schema.ts` 类型定义 -2. 在 `schema.test.ts` 添加测试 -3. 实现数据迁移逻辑（如需要） -4. 测试新旧数据的兼容性 +1. 在设计文档中说明重构原因和方案 +2. 确保不破坏现有功能 +3. 提交时使用 `refactor:` 类型 +4. 在 plan.md 中更新模块说明 -## 开发工具推荐 +## 开发工具 -### 测试相关 +### Serena 工具（代码导航） ```bash -# 可视化测试界面 -npm run test:ui +# 查看文件符号概览 +mcp__serena__get_symbols_overview --relative_path src/components/flow/FlowEditor.vue -# 监听模式（开发时推荐） -npm run test:watch +# 查找特定符号 +mcp__serena__find_symbol --name_path handleUndo + +# 搜索模式 +mcp__serena__search_for_pattern --substring_pattern "History" ``` -### 调试技巧 +### Context7 工具（文档查询） -- 在测试中使用 `console.log` 查看中间状态 -- 使用 `it.only()` 只运行特定测试 -- 使用 `it.skip()` 跳过某些测试（临时） +```bash +# 查询 LogicFlow 文档 +mcp__context7__resolve-library-id --libraryName "LogicFlow" +mcp__context7__query-docs --query "History plugin" +``` + +### 开发命令 + +```bash +# 启动开发服务器 +npm run dev + +# 代码检查 +npm run lint + +# 代码格式化 +npm run format + +# 一键检查 +npm run lint && npm run format +``` ## 常见问题 -### Q: 测试失败了怎么办？ +### Q: 什么时候需要创建设计文档？ -1. 仔细阅读错误信息 -2. 检查是代码问题还是测试用例问题 -3. 使用 `console.log` 调试 -4. 不要跳过或删除失败的测试 +- 涉及数据模型变更：**必须** +- 新增重要功能：**建议** +- 简单 UI 调整：不需要 +- Bug 修复：不需要 -### Q: 改动很小，必须写测试吗？ +### Q: 设计文档写多详细？ -- 如果涉及数据层或业务逻辑：**必须** -- 如果只是 UI 样式调整：可以不写 -- 如果不确定：**建议写测试** +- 核心思路和技术方案：必须有 +- 实现细节：关键部分说明即可 +- 代码示例：可选 +- 保持简洁，重点突出 -### Q: 测试写起来很慢怎么办？ +### Q: 什么时候更新 plan.md？ -- 参考现有测试用例的写法 -- 使用测试模板快速开始 -- 测试投入的时间会在后续维护中节省回来 +**只在用户确认功能正常后更新。** + +不要在开发完成后立即更新，等待用户测试。 + +### Q: 如何计算完成度百分比？ + +根据模块的已完成功能占总功能的比例： +- 100%：所有功能完成 +- 90%：核心功能完成，少量优化待做 +- 75%：主要功能完成，部分功能待补 +- 50%：基础功能完成，大量功能待做 +- 30%：最小可用，大部分功能未完成 ## 相关文档 -- [测试指南](../testing.md) - 如何运行和编写测试 -- [测试规范](../testing-rules.md) - 测试相关的强制要求 -- [开发规范](../development-rules.md) - 代码提交规范 +- [项目计划](./plan.md) - 项目整体规划和进度 +- [下一步任务](./next.md) - 当前优先级任务 +- [设计文档](../2design/) - 各功能的设计方案 +- [数据模型](../2design/DataModel.md) - Schema 和数据结构 +- [样式系统](../2design/StyleAndAppearance.md) - 样式属性和渲染 diff --git a/docs/2design/ComponentArchitecture.md b/docs/2design/ComponentArchitecture.md new file mode 100644 index 0000000..20d162f --- /dev/null +++ b/docs/2design/ComponentArchitecture.md @@ -0,0 +1,642 @@ +# 组件化改造设计文档 + +## 背景与目标 + +### 为什么需要组件化改造 + +**当前状态**： +- yys-editor 是一个独立的单页应用（SPA） +- 只能作为独立应用运行 +- 无法嵌入到其他项目中 + +**目标**： +- 将 yys-editor 改造为可嵌入的 Vue 组件 +- 支持在 onmyoji-wiki 中作为块插件使用 +- 保持独立应用功能不变（双重角色） + +### 预期效果 + +**角色 1：独立编辑器**（保持不变） +- 完整的流程图编辑应用 +- 支持本地运行和使用 +- 完整的 UI（工具栏、组件库、属性面板） + +**角色 2：可嵌入组件**（新增） +- 作为 onmyoji-wiki 的块插件 +- 支持预览/编辑模式 +- 轻量级，只包含核心编辑功能 +- 数据接口清晰 + +--- + +## 技术方案 + +### 核心思路 + +**不修改现有代码，创建独立的嵌入式组件** + +``` +yys-editor/ +├── src/ +│ ├── App.vue # 独立应用（保持不变） +│ ├── YysEditorEmbed.vue # 嵌入式组件（新增）⭐ +│ ├── components/ # 共享组件 +│ │ ├── flow/ +│ │ │ ├── FlowEditor.vue # 画布核心（共享） +│ │ │ ├── PropertyPanel.vue # 属性面板（共享） +│ │ │ └── ComponentsPanel.vue # 组件库（共享） +│ │ └── Toolbar.vue # 工具栏（共享） +│ └── ts/ +│ ├── useStore.ts # 状态管理（共享） +│ └── useLogicFlow.ts # LogicFlow 封装（共享） +└── dist/ # 构建输出 + ├── yys-editor.es.js # ES Module（库模式） + └── yys-editor.umd.js # UMD（库模式） +``` + +### 架构设计 + +#### 1. 双模式架构 + +``` +┌─────────────────────────────────────────────────────────┐ +│ yys-editor 项目 │ +├─────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────────┐ ┌──────────────────┐ │ +│ │ 独立应用模式 │ │ 嵌入组件模式 │ │ +│ │ (App.vue) │ │ (YysEditorEmbed) │ │ +│ └──────────────────┘ └──────────────────┘ │ +│ │ │ │ +│ └────────────┬───────────────┘ │ +│ ↓ │ +│ ┌─────────────────┐ │ +│ │ 共享核心组件 │ │ +│ ├─────────────────┤ │ +│ │ FlowEditor.vue │ │ +│ │ PropertyPanel │ │ +│ │ ComponentsPanel │ │ +│ │ Toolbar │ │ +│ └─────────────────┘ │ +│ ↓ │ +│ ┌─────────────────┐ │ +│ │ 状态管理层 │ │ +│ ├─────────────────┤ │ +│ │ useStore │ │ +│ │ useLogicFlow │ │ +│ │ useCanvasSettings│ │ +│ └─────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────┘ +``` + +#### 2. 嵌入式组件模式切换 + +``` +┌─────────────────────────────────────────────────────────┐ +│ YysEditorEmbed 组件 │ +├─────────────────────────────────────────────────────────┤ +│ │ +│ Props: { mode: 'preview' | 'edit', data: GraphData } │ +│ │ +│ ┌──────────────────┐ ┌──────────────────┐ │ +│ │ 预览模式 │ │ 编辑模式 │ │ +│ │ (preview) │ │ (edit) │ │ +│ ├──────────────────┤ ├──────────────────┤ │ +│ │ ✅ 画布（只读） │ │ ✅ 画布（可编辑） │ │ +│ │ ❌ 工具栏 │ │ ✅ 工具栏 │ │ +│ │ ❌ 组件库 │ │ ✅ 组件库 │ │ +│ │ ❌ 属性面板 │ │ ✅ 属性面板 │ │ +│ │ ❌ 交互 │ │ ✅ 完整交互 │ │ +│ └──────────────────┘ └──────────────────┘ │ +│ │ +│ Emits: { 'update:data', 'save', 'cancel', 'error' } │ +│ │ +└─────────────────────────────────────────────────────────┘ +``` + +--- + +## 数据模型 + +### Props 接口 + +```typescript +interface YysEditorEmbedProps { + // 初始数据（LogicFlow GraphData 格式） + data?: GraphData + + // 模式：preview（预览）/ edit（编辑） + mode?: 'preview' | 'edit' + + // 尺寸 + width?: string | number + height?: string | number + + // UI 控制（仅在 edit 模式有效） + showToolbar?: boolean + showPropertyPanel?: boolean + showComponentPanel?: boolean + + // 配置选项 + config?: EditorConfig +} + +// LogicFlow 标准数据格式 +interface GraphData { + nodes: NodeData[] + edges: EdgeData[] +} + +interface NodeData { + id: string + type: string + x: number + y: number + properties?: Record + text?: { value: string } +} + +interface EdgeData { + id: string + type: string + sourceNodeId: string + targetNodeId: string + properties?: Record +} + +// 编辑器配置 +interface EditorConfig { + // 画布配置 + grid?: boolean + snapline?: boolean + keyboard?: boolean + + // 主题 + theme?: 'light' | 'dark' + + // 语言 + locale?: 'zh' | 'ja' | 'en' +} +``` + +### Emits 接口 + +```typescript +interface YysEditorEmbedEmits { + // 数据变更（实时） + 'update:data': (data: GraphData) => void + + // 保存（用户点击保存按钮） + 'save': (data: GraphData) => void + + // 取消（用户点击取消按钮） + 'cancel': () => void + + // 错误 + 'error': (error: Error) => void +} +``` + +### 默认值 + +```typescript +const defaultProps = { + mode: 'edit', + width: '100%', + height: '600px', + showToolbar: true, + showPropertyPanel: true, + showComponentPanel: true, + config: { + grid: true, + snapline: true, + keyboard: true, + theme: 'light', + locale: 'zh' + } +} +``` + +--- + +## 实现细节 + +### 1. YysEditorEmbed.vue 组件结构 + +```vue + + + + + +``` + +### 2. 状态隔离策略 + +**问题**：独立应用使用全局 Pinia store，嵌入式组件需要隔离状态 + +**方案**：使用 provide/inject 创建局部状态 + +```typescript +// YysEditorEmbed.vue +import { provide } from 'vue' +import { createPinia } from 'pinia' + +// 创建局部 Pinia 实例 +const localPinia = createPinia() +provide('pinia', localPinia) + +// 子组件使用局部 store +const store = useFilesStore(localPinia) +``` + +### 3. 样式隔离策略 + +**问题**：避免样式冲突 + +**方案**： +1. 使用 scoped styles +2. 添加命名空间前缀 `.yys-editor-embed` +3. 使用 CSS Modules（可选） + +```vue + +``` + +### 4. 构建配置 + +#### vite.config.ts（库模式） + +```typescript +import { defineConfig } from 'vite' +import vue from '@vitejs/plugin-vue' +import { resolve } from 'path' + +export default defineConfig({ + plugins: [vue()], + + build: { + lib: { + // 入口文件 + entry: resolve(__dirname, 'src/YysEditorEmbed.vue'), + name: 'YysEditor', + // 输出文件名 + fileName: (format) => `yys-editor.${format}.js` + }, + rollupOptions: { + // 外部化依赖（不打包进库） + external: ['vue', 'element-plus'], + output: { + // 全局变量名 + globals: { + vue: 'Vue', + 'element-plus': 'ElementPlus' + } + } + } + } +}) +``` + +#### package.json + +```json +{ + "name": "yys-editor", + "version": "1.0.0", + "type": "module", + "main": "./dist/yys-editor.umd.js", + "module": "./dist/yys-editor.es.js", + "types": "./dist/YysEditorEmbed.d.ts", + "exports": { + ".": { + "import": "./dist/yys-editor.es.js", + "require": "./dist/yys-editor.umd.js", + "types": "./dist/YysEditorEmbed.d.ts" + }, + "./style.css": "./dist/style.css" + }, + "files": [ + "dist" + ], + "scripts": { + "dev": "vite", + "build": "vite build", + "build:lib": "vite build --config vite.config.lib.ts" + }, + "peerDependencies": { + "vue": "^3.3.0", + "element-plus": "^2.9.0" + } +} +``` + +--- + +## 使用示例 + +### 在 onmyoji-wiki 中使用 + +```vue + + + +``` + +### 作为 npm 包安装 + +```bash +# 在 onmyoji-wiki 项目中 +npm install file:../yys-editor + +# 或发布到 npm 后 +npm install yys-editor +``` + +--- + +## 测试计划 + +### 功能测试 + +#### 预览模式 +- [ ] 正确渲染流程图 +- [ ] 只读，无法编辑 +- [ ] 不显示工具栏、组件库、属性面板 +- [ ] 响应式尺寸 + +#### 编辑模式 +- [ ] 完整编辑功能 +- [ ] 工具栏正常工作 +- [ ] 组件库可拖拽 +- [ ] 属性面板可编辑 +- [ ] 保存/取消按钮触发正确事件 + +#### 数据接口 +- [ ] Props 传入数据正确渲染 +- [ ] 数据变更触发 update:data 事件 +- [ ] 保存触发 save 事件 +- [ ] 取消触发 cancel 事件 +- [ ] 错误触发 error 事件 + +#### 状态隔离 +- [ ] 多个实例互不影响 +- [ ] 不污染全局状态 +- [ ] 样式不冲突 + +### 集成测试 + +#### 在 wiki 中集成 +- [ ] 可以正常引入 +- [ ] 预览模式正常显示 +- [ ] 编辑模式正常工作 +- [ ] 数据保存正确 +- [ ] 样式不冲突 + +### 性能测试 + +- [ ] 打包体积合理（< 500KB gzipped） +- [ ] 加载速度快 +- [ ] 运行流畅，无卡顿 + +--- + +## 验收标准 + +### 功能完整性 +- ✅ 支持预览和编辑模式 +- ✅ 数据接口清晰（Props + Emits） +- ✅ 可以作为 npm 包引用 +- ✅ 状态和样式隔离 + +### 兼容性 +- ✅ 不影响独立应用功能 +- ✅ 支持 Vue 3.3+ +- ✅ 支持现代浏览器 + +### 文档完善 +- ✅ API 文档 +- ✅ 使用示例 +- ✅ 集成指南 + +--- + +## 实现记录 + +### 2026-02-20 +- 📝 创建组件化改造设计文档 +- 📝 定义 Props 和 Emits 接口 +- 📝 设计双模式架构 +- 📝 规划状态隔离策略 + +--- + +**最后更新：** 2026-02-20 +**文档版本：** v1.0.0 diff --git a/docs/3build/EMBED_README.md b/docs/3build/EMBED_README.md new file mode 100644 index 0000000..86b262c --- /dev/null +++ b/docs/3build/EMBED_README.md @@ -0,0 +1,260 @@ +# YysEditorEmbed 组件化改造 + +## 📋 概述 + +yys-editor 现在支持两种使用方式： + +1. **独立应用模式**：完整的流程图编辑应用（原有功能） +2. **嵌入组件模式**：可嵌入到其他项目中的 Vue 组件（新增功能） + +## 🎯 完成的工作 + +### ✅ 已完成 + +1. **设计文档** + - 创建了 `docs/2design/ComponentArchitecture.md` + - 详细说明了组件化改造的架构设计 + +2. **核心组件** + - 创建了 `src/YysEditorEmbed.vue` 嵌入式组件 + - 支持 `preview` 和 `edit` 两种模式 + - 实现了完整的 Props 和 Emits 接口 + - 实现了状态隔离（使用局部 Pinia 实例） + +3. **构建配置** + - 创建了 `vite.config.lib.js` 库模式构建配置 + - 更新了 `package.json` 导出配置 + - 支持 ES Module 和 UMD 两种格式 + +4. **文档和示例** + - 创建了 `docs/3usage/YysEditorEmbed.md` 使用文档 + - 创建了 `examples/embed-demo.html` 示例页面 + - 创建了 `src/TestEmbed.vue` 测试组件 + +## 🚀 快速开始 + +### 1. 测试嵌入式组件 + +在开发模式下测试组件： + +```bash +# 启动开发服务器 +npm run dev + +# 访问测试页面（需要修改 main.js 引入 TestEmbed.vue） +``` + +### 2. 构建库文件 + +```bash +# 构建嵌入式组件库 +npm run build:lib + +# 输出文件： +# - dist/yys-editor.es.js (ES Module) +# - dist/yys-editor.umd.js (UMD) +# - dist/yys-editor.css (样式) +``` + +### 3. 在其他项目中使用 + +#### 方式 1：本地引用（开发阶段） + +在 `onmyoji-wiki` 项目的 `package.json` 中： + +```json +{ + "dependencies": { + "yys-editor": "file:../yys-editor" + } +} +``` + +然后： + +```bash +cd ../onmyoji-wiki +npm install +``` + +#### 方式 2：使用组件 + +```vue + + + +``` + +## 📖 API 文档 + +### Props + +| 属性 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `data` | `GraphData` | `undefined` | 初始数据 | +| `mode` | `'preview' \| 'edit'` | `'edit'` | 模式 | +| `width` | `string \| number` | `'100%'` | 宽度 | +| `height` | `string \| number` | `'600px'` | 高度 | +| `showToolbar` | `boolean` | `true` | 显示工具栏 | +| `showPropertyPanel` | `boolean` | `true` | 显示属性面板 | +| `showComponentPanel` | `boolean` | `true` | 显示组件库 | +| `config` | `EditorConfig` | `{}` | 编辑器配置 | + +### Events + +| 事件 | 参数 | 说明 | +|------|------|------| +| `update:data` | `(data: GraphData)` | 数据变更 | +| `save` | `(data: GraphData)` | 保存 | +| `cancel` | `()` | 取消 | +| `error` | `(error: Error)` | 错误 | + +### 方法 + +| 方法 | 说明 | +|------|------| +| `getGraphData()` | 获取当前画布数据 | +| `setGraphData(data)` | 设置画布数据 | + +详细文档请查看：`docs/3usage/YysEditorEmbed.md` + +## 🧪 测试 + +### 手动测试清单 + +- [ ] **预览模式** + - [ ] 正确渲染流程图 + - [ ] 只读，无法编辑 + - [ ] 不显示工具栏、组件库、属性面板 + +- [ ] **编辑模式** + - [ ] 完整编辑功能 + - [ ] 工具栏正常工作 + - [ ] 组件库可拖拽 + - [ ] 属性面板可编辑 + - [ ] 保存/取消按钮触发正确事件 + +- [ ] **数据接口** + - [ ] Props 传入数据正确渲染 + - [ ] 数据变更触发 update:data 事件 + - [ ] 保存触发 save 事件 + - [ ] 取消触发 cancel 事件 + +- [ ] **状态隔离** + - [ ] 多个实例互不影响 + - [ ] 不污染全局状态 + +## 📁 文件结构 + +``` +yys-editor/ +├── src/ +│ ├── YysEditorEmbed.vue # 嵌入式组件 ⭐ +│ ├── TestEmbed.vue # 测试组件 +│ ├── App.vue # 独立应用（保持不变） +│ └── components/ # 共享组件 +├── docs/ +│ ├── 2design/ +│ │ └── ComponentArchitecture.md # 设计文档 +│ └── 3usage/ +│ └── YysEditorEmbed.md # 使用文档 +├── examples/ +│ └── embed-demo.html # 示例页面 +├── vite.config.js # 应用构建配置 +├── vite.config.lib.js # 库构建配置 ⭐ +└── package.json # 更新了导出配置 ⭐ +``` + +## 🔄 下一步 + +### 在 onmyoji-wiki 中集成 + +1. **安装依赖** + ```bash + cd ../onmyoji-wiki + npm install file:../yys-editor + ``` + +2. **创建 MDC 组件** + ```vue + + + ``` + +3. **在 Markdown 中使用** + ```markdown + ::yys-editor{id="flow-1"} + :: + ``` + +## 📝 注意事项 + +### 状态隔离 + +嵌入式组件使用局部 Pinia 实例，不会影响宿主应用的状态管理。 + +### 样式隔离 + +所有样式都使用 scoped，并添加了 `.yys-editor-embed` 命名空间。 + +### 依赖管理 + +以下依赖被标记为 `peerDependencies`，需要宿主项目提供： +- vue +- element-plus +- pinia +- @logicflow/core +- @logicflow/extension +- @logicflow/vue-node-registry + +## 🐛 已知问题 + +1. **预览模式初始化延迟** + - 预览模式需要等待 DOM 渲染完成后初始化 LogicFlow + - 已使用 `setTimeout` 解决 + +2. **编辑模式数据加载** + - 编辑模式需要等待 FlowEditor 组件初始化完成 + - 已使用 `setTimeout` 延迟加载数据 + +## 📚 相关文档 + +- [设计文档](./docs/2design/ComponentArchitecture.md) +- [使用文档](./docs/3usage/YysEditorEmbed.md) +- [项目计划](./docs/1management/plan.md) + +## 🤝 贡献 + +如有问题或建议，请提交 Issue 或 Pull Request。 + +## 📄 许可证 + +MIT diff --git a/docs/3build/YysEditorEmbed.md b/docs/3build/YysEditorEmbed.md new file mode 100644 index 0000000..32f2000 --- /dev/null +++ b/docs/3build/YysEditorEmbed.md @@ -0,0 +1,503 @@ +# YysEditorEmbed 使用文档 + +## 简介 + +YysEditorEmbed 是 yys-editor 的可嵌入式组件版本，可以作为 Vue 组件集成到其他项目中。 + +## 安装 + +### 方式 1：本地引用（开发阶段） + +在 `package.json` 中添加： + +```json +{ + "dependencies": { + "yys-editor": "file:../yys-editor" + } +} +``` + +然后运行： + +```bash +npm install +``` + +### 方式 2：npm 包（发布后） + +```bash +npm install yys-editor +``` + +## 基础使用 + +### 1. 引入组件 + +```vue + + + +``` + +### 2. 预览模式 + +```vue + +``` + +### 3. 编辑模式 + +```vue + + + +``` + +## API 文档 + +### Props + +| 属性 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `data` | `GraphData` | `undefined` | 初始数据（LogicFlow GraphData 格式） | +| `mode` | `'preview' \| 'edit'` | `'edit'` | 模式：预览或编辑 | +| `width` | `string \| number` | `'100%'` | 宽度 | +| `height` | `string \| number` | `'600px'` | 高度 | +| `showToolbar` | `boolean` | `true` | 是否显示工具栏（仅编辑模式） | +| `showPropertyPanel` | `boolean` | `true` | 是否显示属性面板（仅编辑模式） | +| `showComponentPanel` | `boolean` | `true` | 是否显示组件库（仅编辑模式） | +| `config` | `EditorConfig` | `{}` | 编辑器配置 | + +### Events + +| 事件 | 参数 | 说明 | +|------|------|------| +| `update:data` | `(data: GraphData)` | 数据变更（实时） | +| `save` | `(data: GraphData)` | 保存（用户点击保存按钮） | +| `cancel` | `()` | 取消（用户点击取消按钮） | +| `error` | `(error: Error)` | 错误 | + +### 方法（通过 ref 调用） + +| 方法 | 参数 | 返回值 | 说明 | +|------|------|--------|------| +| `getGraphData()` | - | `GraphData \| null` | 获取当前画布数据 | +| `setGraphData(data)` | `GraphData` | `void` | 设置画布数据 | + +### 类型定义 + +```typescript +interface GraphData { + nodes: NodeData[] + edges: EdgeData[] +} + +interface NodeData { + id: string + type: string + x: number + y: number + properties?: Record + text?: { value: string } +} + +interface EdgeData { + id: string + type: string + sourceNodeId: string + targetNodeId: string + properties?: Record +} + +interface EditorConfig { + grid?: boolean + snapline?: boolean + keyboard?: boolean + theme?: 'light' | 'dark' + locale?: 'zh' | 'ja' | 'en' +} +``` + +## 使用场景 + +### 场景 1：在 Wiki 中作为块插件 + +```vue + + + + + +``` + +### 场景 2：在管理后台中使用 + +```vue + + + +``` + +### 场景 3：只读展示 + +```vue + + + +``` + +## 高级用法 + +### 自定义配置 + +```vue + +``` + +### 监听数据变化 + +```vue + + + +``` + +### 错误处理 + +```vue + + + +``` + +## 样式定制 + +### 覆盖默认样式 + +```vue + +``` + +### 响应式布局 + +```vue + + + +``` + +## 常见问题 + +### Q: 如何在 Nuxt 3 中使用？ + +A: 在 Nuxt 3 中，需要将组件设置为客户端渲染： + +```vue + +``` + +### Q: 如何保存和加载数据？ + +A: 使用 `getGraphData()` 和 `setGraphData()` 方法： + +```vue + +``` + +### Q: 如何禁用某些 UI 元素？ + +A: 使用 Props 控制： + +```vue + +``` + +### Q: 如何集成到现有项目？ + +A: 参考上面的"场景 1：在 Wiki 中作为块插件"示例。 + +## 浏览器兼容性 + +- Chrome >= 90 +- Firefox >= 88 +- Safari >= 14 +- Edge >= 90 + +## 许可证 + +MIT + +## 支持 + +如有问题，请提交 Issue 或联系开发团队。 diff --git a/docs/4test/BUILD_TEST_REPORT.md b/docs/4test/BUILD_TEST_REPORT.md new file mode 100644 index 0000000..e71a3c9 --- /dev/null +++ b/docs/4test/BUILD_TEST_REPORT.md @@ -0,0 +1,252 @@ +# 🎉 组件化改造构建测试报告 + +## ✅ 构建成功！ + +### 📦 生成的文件 + +``` +dist/ +├── yys-editor.es.js 155 KB (ES Module 格式) +├── yys-editor.es.js.map 297 KB (Source Map) +├── yys-editor.umd.js 112 KB (UMD 格式) +├── yys-editor.umd.js.map 286 KB (Source Map) +└── yys-editor.css 69 KB (样式文件) +``` + +**Gzip 压缩后大小：** +- ES Module: 35.20 KB +- UMD: 31.09 KB +- CSS: 32.87 KB + +### 🎯 构建配置 + +- ✅ 入口文件：`src/index.js` +- ✅ 输出格式：ES Module + UMD +- ✅ 外部化依赖：vue, element-plus, pinia, @logicflow/* +- ✅ 生成 Source Map +- ✅ 导出 CSS 文件 + +--- + +## 🧪 如何验证构建结果 + +### 方法 1：查看生成的文件 + +```bash +# 查看 dist 目录 +ls -lh dist/ + +# 查看文件内容（前 20 行） +head -n 20 dist/yys-editor.es.js +``` + +### 方法 2：在浏览器中测试 + +打开 `examples/embed-demo.html` 查看示例页面（需要实际集成后才能运行）。 + +### 方法 3：在 onmyoji-wiki 中集成测试 + +#### 步骤 1：安装依赖 + +在 `onmyoji-wiki` 项目中： + +```bash +cd ../onmyoji-wiki +npm install file:../yys-editor +``` + +#### 步骤 2：创建测试组件 + +创建 `components/TestYysEditor.vue`： + +```vue + + + +``` + +#### 步骤 3：运行测试 + +```bash +npm run dev +# 访问测试页面 +``` + +--- + +## 📋 功能测试清单 + +### ✅ 已验证 + +- [x] 构建成功，无错误 +- [x] 生成 ES Module 格式 +- [x] 生成 UMD 格式 +- [x] 生成 CSS 文件 +- [x] 生成 Source Map +- [x] 文件大小合理（< 200KB） + +### ⏳ 待验证（需要在实际项目中测试） + +- [ ] **预览模式** + - [ ] 正确渲染流程图 + - [ ] 只读，无法编辑 + - [ ] 不显示工具栏、组件库、属性面板 + +- [ ] **编辑模式** + - [ ] 完整编辑功能 + - [ ] 工具栏正常工作 + - [ ] 组件库可拖拽 + - [ ] 属性面板可编辑 + - [ ] 保存/取消按钮触发正确事件 + +- [ ] **数据接口** + - [ ] Props 传入数据正确渲染 + - [ ] 数据变更触发 update:data 事件 + - [ ] 保存触发 save 事件 + - [ ] 取消触发 cancel 事件 + +- [ ] **状态隔离** + - [ ] 多个实例互不影响 + - [ ] 不污染全局状态 + +--- + +## 📖 使用文档 + +### 基础使用 + +```vue + + + +``` + +### Props + +| 属性 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `data` | `GraphData` | `undefined` | 初始数据 | +| `mode` | `'preview' \| 'edit'` | `'edit'` | 模式 | +| `width` | `string \| number` | `'100%'` | 宽度 | +| `height` | `string \| number` | `'600px'` | 高度 | +| `showToolbar` | `boolean` | `true` | 显示工具栏 | +| `showPropertyPanel` | `boolean` | `true` | 显示属性面板 | +| `showComponentPanel` | `boolean` | `true` | 显示组件库 | + +### Events + +| 事件 | 参数 | 说明 | +|------|------|------| +| `update:data` | `(data: GraphData)` | 数据变更 | +| `save` | `(data: GraphData)` | 保存 | +| `cancel` | `()` | 取消 | +| `error` | `(error: Error)` | 错误 | + +--- + +## 📁 相关文件 + +- **设计文档**: `docs/2design/ComponentArchitecture.md` +- **使用文档**: `docs/3usage/YysEditorEmbed.md` +- **示例页面**: `examples/embed-demo.html` +- **测试组件**: `src/TestEmbed.vue` +- **快速开始**: `EMBED_README.md` + +--- + +## 🚀 下一步 + +1. **在 onmyoji-wiki 中集成测试** + - 安装 yys-editor 包 + - 创建测试组件 + - 验证功能正常 + +2. **创建 MDC 组件** + - 创建 `components/content/YysEditor.vue` + - 实现预览/编辑模式切换 + - 集成到 Markdown 中 + +3. **完善功能** + - 根据测试结果优化 + - 添加更多配置选项 + - 完善文档 + +--- + +## 📝 构建日志 + +``` +> yys-editor@1.0.0 build:lib +> vite build --config vite.config.lib.js + +vite v5.4.19 building for production... +transforming... +✓ 709 modules transformed. +rendering chunks... +computing gzip size... +dist/yys-editor.css 70.30 kB │ gzip: 32.87 kB +dist/yys-editor.es.js 151.45 kB │ gzip: 35.20 kB │ map: 296.11 kB +dist/yys-editor.css 70.30 kB │ gzip: 32.87 kB +dist/yys-editor.umd.js 107.43 kB │ gzip: 31.09 kB │ map: 284.79 kB +✓ built in 3.06s +``` + +--- + +**构建时间**: 2026-02-20 17:12 +**状态**: ✅ 成功 +**下一步**: 等待在 onmyoji-wiki 中集成测试 diff --git a/examples/embed-demo.html b/examples/embed-demo.html new file mode 100644 index 0000000..5852def --- /dev/null +++ b/examples/embed-demo.html @@ -0,0 +1,345 @@ + + + + + + YysEditorEmbed 示例 + + + +
+

🎨 YysEditorEmbed 组件示例

+ + +
+

示例 1：编辑模式

+

完整的编辑功能，包括工具栏、组件库和属性面板。

+ +
+ + + + +
+ +
+ +
+ 
<YysEditorEmbed
+  mode="edit"
+  :data="flowData"
+  :height="600"
+  @save="handleSave"
+/>
+
+
+ + +
+

示例 2：预览模式

+

只读展示，不显示编辑工具。点击可切换到编辑模式。

+ +
+ +
+ +
+ +
+ 
<YysEditorEmbed
+  mode="preview"
+  :data="flowData"
+  :height="400"
+/>
+
+
+ + +
+

示例 3：自定义配置

+

隐藏部分 UI 元素，自定义编辑器配置。

+ +
+ + + +
+ +
+ +
+ 
<YysEditorEmbed
+  mode="edit"
+  :show-toolbar="false"
+  :show-component-panel="false"
+  :height="500"
+/>
+
+
+ + +
+

示例 4：Wiki 块插件模式

+

模拟在 Wiki 中作为块插件使用的场景。

+ +
+ +
+ +
+ +
+ 
<!-- 预览模式 -->
+<div v-if="!isEditing" @click="startEdit">
+  <YysEditorEmbed mode="preview" :data="flowData" />
+</div>
+
+<!-- 编辑模式（弹窗） -->
+<el-dialog v-model="isEditing" fullscreen>
+  <YysEditorEmbed mode="edit" @save="handleSave" />
+</el-dialog>
+
+
+
+ + + + + + + + diff --git a/package.json b/package.json index 40136dc..0514f08 100644 --- a/package.json +++ b/package.json @@ -1,11 +1,28 @@ { - "name": "vue-project", - "version": "0.0.0", - "private": true, + "name": "yys-editor", + "version": "1.0.0", + "description": "阴阳师流程图编辑器 - 可嵌入式组件", + "author": "yys-editor team", + "license": "MIT", "type": "module", + "main": "./dist/yys-editor.umd.js", + "module": "./dist/yys-editor.es.js", + "types": "./dist/YysEditorEmbed.d.ts", + "exports": { + ".": { + "import": "./dist/yys-editor.es.js", + "require": "./dist/yys-editor.umd.js", + "types": "./dist/YysEditorEmbed.d.ts" + }, + "./style.css": "./dist/yys-editor.css" + }, + "files": [ + "dist" + ], "scripts": { "dev": "vite", "build": "vite build", + "build:lib": "vite build --config vite.config.lib.js", "preview": "vite preview", "test": "vitest --run", "test:watch": "vitest", @@ -15,6 +32,14 @@ "format": "prettier --write src/", "precommit": "npm test && npm run lint" }, + "peerDependencies": { + "vue": "^3.3.0", + "element-plus": "^2.9.0", + "pinia": "^3.0.0", + "@logicflow/core": "^2.0.0", + "@logicflow/extension": "^2.0.0", + "@logicflow/vue-node-registry": "^1.0.0" + }, "dependencies": { "@element-plus/icons-vue": "^2.3.1", "@logicflow/core": "^2.0.16", diff --git a/src/TestEmbed.vue b/src/TestEmbed.vue new file mode 100644 index 0000000..4c29d29 --- /dev/null +++ b/src/TestEmbed.vue @@ -0,0 +1,231 @@ + + + + + diff --git a/src/YysEditorEmbed.vue b/src/YysEditorEmbed.vue new file mode 100644 index 0000000..21f4f57 --- /dev/null +++ b/src/YysEditorEmbed.vue @@ -0,0 +1,329 @@ + + + + + diff --git a/src/index.js b/src/index.js new file mode 100644 index 0000000..c437a20 --- /dev/null +++ b/src/index.js @@ -0,0 +1,11 @@ +// 库入口文件 +import YysEditorEmbed from './YysEditorEmbed.vue' + +// 导出组件 +export { YysEditorEmbed } + +// 默认导出 +export default YysEditorEmbed + +// 类型导出 +export * from './YysEditorEmbed.vue' diff --git a/vite.config.lib.js b/vite.config.lib.js new file mode 100644 index 0000000..5bc121c --- /dev/null +++ b/vite.config.lib.js @@ -0,0 +1,69 @@ +import { fileURLToPath, URL } from 'node:url' +import { defineConfig } from 'vite' +import vue from '@vitejs/plugin-vue' +import path from 'path' + +// https://vitejs.dev/config/ +export default defineConfig({ + plugins: [ + vue({ + template: { + compilerOptions: { + isCustomElement: (tag) => tag.startsWith('lf-') + } + } + }) + ], + resolve: { + alias: { + '@': fileURLToPath(new URL('./src', import.meta.url)) + } + }, + build: { + lib: { + // 入口文件 - 创建一个入口文件而不是直接使用 .vue 文件 + entry: path.resolve(__dirname, 'src/index.js'), + name: 'YysEditor', + // 输出文件名 + fileName: (format) => `yys-editor.${format}.js`, + formats: ['es', 'umd'] + }, + rollupOptions: { + // 外部化依赖（不打包进库） + external: [ + 'vue', + 'element-plus', + 'pinia', + '@logicflow/core', + '@logicflow/extension', + '@logicflow/vue-node-registry', + '@element-plus/icons-vue', + '@vueup/vue-quill', + 'vue3-draggable-resizable', + 'vuedraggable', + 'html2canvas', + 'vue-i18n' + ], + output: { + // 全局变量名 + globals: { + vue: 'Vue', + 'element-plus': 'ElementPlus', + pinia: 'Pinia', + '@logicflow/core': 'LogicFlow', + '@logicflow/extension': 'LogicFlowExtension', + '@logicflow/vue-node-registry': 'LogicFlowVueNodeRegistry' + }, + // 导出 CSS + assetFileNames: (assetInfo) => { + if (assetInfo.name === 'style.css') return 'yys-editor.css' + return assetInfo.name + } + } + }, + // 生成 sourcemap + sourcemap: true, + // 清空输出目录 + emptyOutDir: false + } +})