Powerful-517/yys-editor
3
0
Fork 0
mirror of https://github.com/Powerful-517/yys-editor.git synced 2026-03-05 06:55:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
- 创建 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
This commit is contained in:
rookie4show
2026-02-20 17:23:59 +08:00
parent 92557d553b
commit 15bae3be81
13 changed files with 3553 additions and 424 deletions
Download Patch File Download Diff File Expand all files Collapse all files

588
docs/1management/workflow.md
View File

@@ -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) - 样式属性和渲染