mirror of https://github.com/Powerful-517/yys-editor.git synced 2026-03-05 15:05:27 +00:00

Files

rookie4show 15bae3be81 feat: 完成组件化改造 - 支持作为可嵌入组件使用

- 创建 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

2026-02-20 17:23:59 +08:00

11 KiB

Raw Blame History

开发工作流程

本文档描述在 yys-editor 项目中开发新功能的标准流程。

开发流程概览

读取计划 → 设计方案 → 实际开发 → 测试验证 → 更新文档

详细步骤

1. 读取项目计划

在开始任何开发工作前，先了解项目现状：

1.1 读取 plan.md

# 查看项目整体规划
cat docs/1management/plan.md

重点关注：

项目完成度总览：了解各模块当前状态
下一步行动计划：确定优先级和待办任务
愿景实施进度：查看当前处于哪个阶段
详细模块状态：了解相关模块的已完成和未完成功能

1.2 读取 next.md（可选）

# 查看下一步任务说明
cat docs/1management/next.md

这里通常包含：

当前优先级任务
开发流程说明
技术栈信息

1.3 确定任务

根据 plan.md 中的优先级确定要开发的功能：

🔴 高优先级：紧急或核心功能
🟡 中优先级：重要但不紧急
🟢 低优先级：优化和增强

2. 设计方案

在 docs/2design/ 目录下创建或更新设计文档

2.1 确定设计文档名称

根据功能类型选择或创建设计文档：

功能类型	设计文档	说明
数据模型变更	`DataModel.md`	Schema、数据结构、迁移逻辑
样式系统	`StyleAndAppearance.md`	样式属性、渲染逻辑
新节点类型	`NodeTypes.md`	节点定义、属性、行为
交互功能	`Interactions.md`	快捷键、拖拽、选择等
状态管理	`StateManagement.md`	Store、持久化、同步
其他功能	`<功能名>.md`	自定义设计文档

2.2 编写设计文档

设计文档应包含：

# 功能名称

## 背景与目标
- 为什么需要这个功能
- 要解决什么问题
- 预期效果

## 技术方案
- 实现思路
- 技术选型
- 架构设计

## 数据模型（如涉及）
- Schema 变更
- 数据结构定义
- 迁移策略

## 实现细节
- 关键代码位置
- 核心逻辑说明
- 注意事项

## 测试计划
- 测试用例
- 边界情况
- 验收标准

2.3 设计文档示例

示例：添加撤销重做功能

在 docs/2design/UndoRedo.md 中：

# 撤销重做系统

## 背景与目标
实现 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 工具高效读取代码：

# 查看符号概览
mcp__serena__get_symbols_overview

# 查找特定符号
mcp__serena__find_symbol

# 搜索模式
mcp__serena__search_for_pattern

使用 Context7 查询 LogicFlow 文档：

# 查询 LogicFlow 相关功能
mcp__context7__query-docs

代码风格：

遵循项目现有的代码风格
使用 TypeScript 类型定义
添加必要的注释
保持代码简洁清晰

3.3 开发流程

读取相关代码：使用 Serena 工具快速定位
实现功能：按照设计文档编写代码
本地测试：启动开发服务器验证功能
代码检查：运行 lint 和 format

# 启动开发服务器
npm run dev

# 代码检查
npm run lint
npm run format

4. 测试验证

4.1 功能测试

在浏览器中测试新功能
验证 UI 交互和用户体验
测试边界情况和异常场景
确保没有破坏现有功能

4.2 测试清单

核心功能正常工作
UI 显示正确
交互流畅无卡顿
边界情况处理正确
错误提示友好
没有控制台错误
数据持久化正常（如涉及）

4.3 等待用户确认

开发完成后，等待用户测试并确认功能正常。

不要在用户确认前更新文档。

5. 更新文档

测试通过后，必须更新项目管理文档：

5.1 更新 plan.md

根据完成的功能，更新 docs/1management/plan.md：

更新模块完成度：

## 1. 画布（LogicFlow） — 完成度：100%  ← 更新百分比
- 已完成：
  - ✅ 撤销重做系统：Ctrl+Z/Y 快捷键...  ← 添加新功能
  - ...
- 未完成：
  - 无  ← 如果全部完成，清空未完成列表

标记愿景步骤完成：

| 步骤 | 任务 | 状态 | 说明 |
|------|------|------|------|
| 10 | 历史与撤销重做 | ✅ 完成 | LogicFlow 框架原生支持 |  ← 更新状态

更新总体完成度：

**总体完成度：98%** | **愿景一完成度：100%**  ← 重新计算百分比

更新下一步行动计划：

## 🎯 下一步行动计划

### 🟢 低优先级（后续优化）
1. ~~撤销重做系统~~（已完成）  ← 标记已完成或移除
2. **矢量节点增强**  ← 下一个任务

5.2 更新 next.md（可选）

如果 next.md 中有相关任务说明，也需要更新：

当前优先级（从 plan.md）：
- 🔴 高优先级：~~实现撤销重做系统~~（已完成）  ← 标记完成
- 🟡 中优先级：textNode 富文本编辑

5.3 更新设计文档

在对应的设计文档中添加实现记录：

## 实现记录

### 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 消息

遵循规范格式：

<type>: <subject>

<body>

Type 类型：

feat: 新功能
fix: 修复 bug
refactor: 重构代码
style: 样式调整
docs: 文档更新
chore: 构建或工具变动

示例：

feat: 实现撤销重做系统

- 接入 LogicFlow History 插件
- 添加 Ctrl+Z/Y 快捷键
- 支持最多 50 条历史记录
- 更新 plan.md 标记愿景一完成

6.3 提交代码

git add .
git commit -m "feat: 实现撤销重做系统"
git push

工作流程示例

示例：实现撤销重做功能

步骤 1：读取计划

# 读取 plan.md
cat docs/1management/plan.md

发现：

愿景一步骤 10：历史与撤销重做（未完成）
优先级：🔴 高优先级

步骤 2：设计方案

创建 docs/2design/UndoRedo.md：

# 撤销重做系统

## 技术方案
使用 LogicFlow 框架原生的 History 插件

## 实现细节
- 位置：src/components/flow/FlowEditor.vue
- 插件：History，maxSize: 50
- 快捷键：Ctrl+Z/Y

步骤 3：实际开发

在 FlowEditor.vue 中：

引入 History 插件
配置插件参数
添加快捷键监听

步骤 4：测试验证

测试节点增删改的撤销重做
测试移动、缩放的撤销重做
等待用户确认

步骤 5：更新文档

更新 plan.md：

| 10 | 历史与撤销重做 | ✅ 完成 | LogicFlow 框架原生支持 |

**总体完成度：98%** | **愿景一完成度：100%**

步骤 6：提交代码

git commit -m "feat: 实现撤销重做系统"

特殊场景处理

场景 1：紧急 Bug 修复

直接开始修复，无需设计文档
修复后立即测试
在 plan.md 的"已知问题"中标记已修复
快速提交

场景 2：仅 UI 调整

无需设计文档
直接修改样式
手动测试验证
提交时使用 style: 类型

场景 3：数据模型变更

必须在 DataModel.md 中详细设计
更新 schema.ts 类型定义
实现数据迁移逻辑
测试新旧数据兼容性
在 plan.md 中更新 schemaVersion

场景 4：重构现有代码

在设计文档中说明重构原因和方案
确保不破坏现有功能
提交时使用 refactor: 类型
在 plan.md 中更新模块说明

开发工具

Serena 工具（代码导航）

# 查看文件符号概览
mcp__serena__get_symbols_overview --relative_path src/components/flow/FlowEditor.vue

# 查找特定符号
mcp__serena__find_symbol --name_path handleUndo

# 搜索模式
mcp__serena__search_for_pattern --substring_pattern "History"

Context7 工具（文档查询）

# 查询 LogicFlow 文档
mcp__context7__resolve-library-id --libraryName "LogicFlow"
mcp__context7__query-docs --query "History plugin"

开发命令

# 启动开发服务器
npm run dev

# 代码检查
npm run lint

# 代码格式化
npm run format

# 一键检查
npm run lint && npm run format

常见问题

Q: 什么时候需要创建设计文档？

涉及数据模型变更：必须
新增重要功能：建议
简单 UI 调整：不需要
Bug 修复：不需要

Q: 设计文档写多详细？

核心思路和技术方案：必须有
实现细节：关键部分说明即可
代码示例：可选
保持简洁，重点突出

Q: 什么时候更新 plan.md？

只在用户确认功能正常后更新。

不要在开发完成后立即更新，等待用户测试。

Q: 如何计算完成度百分比？

根据模块的已完成功能占总功能的比例：

100%：所有功能完成
90%：核心功能完成，少量优化待做
75%：主要功能完成，部分功能待补
50%：基础功能完成，大量功能待做
30%：最小可用，大部分功能未完成

11 KiB Raw Blame History Unescape Escape