whistle.mockbubu 1.0.0-dev.4 → 2.0.0

package/GROUP_FEATURE_DESIGN.md

@@ -0,0 +1,520 @@
+# Mock 数据分组功能 - 技术方案
+
+**版本**: v2.0.0
+**设计日期**: 2025-10-16
+**设计者**: Claude Code
+
+---
+
+## 一、需求分析与功能定义
+
+### 核心需求
+实现 Mock 数据的分组管理，让用户可以在不同场景（如：开发环境、测试环境、演示环境）下快速切换不同的 Mock 数据配置组合。
+
+### 功能特性
+1. **默认组**: 当前使用的面板即为默认组，所有现有功能保持不变
+2. **组管理**: CRUD 操作（创建、读取、更新、删除）
+3. **组切换**: 快速切换当前使用的组
+4. **组复制**: 从现有组复制创建新组
+5. **原始数据源**: 插件抓取的请求作为原始数据，不属于任何组
+6. **独立配置**: 每个组拥有独立的 mock 状态、锁定状态、版本等配置
+
+### 使用场景示例
+- **场景A**: 用户正常流程，需要 mock 登录成功、订单列表有数据
+- **场景B**: 异常测试流程，需要 mock 登录失败、订单列表为空
+- 切换组后，所有 mock 状态、数据内容都自动切换，无需手动逐个修改
+
+---
+
+## 二、架构设计
+
+### 2.1 数据模型
+
+#### 原始数据层（Source Layer）
+```javascript
+// Whistle Storage 结构保持不变
+files/
+  ├── {url-1}           // 原始抓包 session 数据（req + res）
+  ├── {url-2}
+  └── ...
+
+properties
+  ├── {url-1}           // 基础元数据（url, method, status, date 等）
+  ├── {url-2}
+  └── ...
+```
+
+**说明**:
+- 原始数据不属于任何组
+- 插件抓取的请求都存储在这里
+- 作为所有组的数据源，只读不改
+
+#### 分组数据层（Group Layer）
+```javascript
+// 新增 Storage 结构
+properties/
+  ├── __groups__              // 组列表配置
+  │   └── {
+  │         groups: [
+  │           {id, name, description, createTime, updateTime, isDefault},
+  │           ...
+  │         ],
+  │         currentGroupId: 'group-xxx'  // 当前激活的组
+  │       }
+  │
+  ├── group.{groupId}.{filename}  // 组级别的配置
+  │   └── {
+  │         mock: true/false,
+  │         locked: true/false,
+  │         mockVersion: 'v1',
+  │         mockTime: timestamp,
+  │         version.{name}: content,    // 该组的版本数据
+  │         versionMeta.{name}: {...},
+  │         customData: {...}            // 组内自定义编辑的数据
+  │       }
+  └── ...
+```
+
+**核心概念**:
+1. **原始数据（Source）**: files/ 中的 session 数据，所有组共享
+2. **组配置（Group Config）**: 每个组对每个文件的个性化配置（mock状态、版本等）
+3. **组数据（Group Data）**: 每个组内编辑的自定义数据（覆盖原始数据）
+
+### 2.2 数据读取优先级
+
+```
+用户访问 API →
+  检查当前组ID →
+    读取 group.{groupId}.{filename} 配置 →
+      如果 mock=true:
+        如果有 customData: 返回 customData
+        否则如果有 mockVersion: 返回 version.{name}
+        否则: 返回原始 session.res.body
+      否则: 透传请求
+```
+
+### 2.3 组切换流程
+
+```
+用户选择组 →
+  更新 __groups__.currentGroupId →
+    前端刷新列表 (带 groupId 参数) →
+      后端根据 groupId 读取该组配置 →
+        返回该组视图的数据列表
+```
+
+---
+
+## 三、实现方案
+
+### 3.1 后端实现
+
+#### 新增文件: `lib/group-manager.js`
+```javascript
+// 组管理核心逻辑
+class GroupManager {
+  constructor(storage) {
+    this.storage = storage
+    this.GROUPS_KEY = '__groups__'
+  }
+
+  // 获取所有组
+  getGroups() { ... }
+
+  // 获取当前组ID
+  getCurrentGroupId() { ... }
+
+  // 设置当前组
+  setCurrentGroup(groupId) { ... }
+
+  // 创建组
+  createGroup({name, description, copyFromGroupId}) { ... }
+
+  // 更新组
+  updateGroup(groupId, {name, description}) { ... }
+
+  // 删除组
+  deleteGroup(groupId) { ... }
+
+  // 复制组
+  copyGroup(sourceGroupId, {name, description}) { ... }
+
+  // 获取组的文件配置
+  getGroupFileConfig(groupId, filename) { ... }
+
+  // 设置组的文件配置
+  setGroupFileConfig(groupId, filename, config) { ... }
+}
+```
+
+#### 新增文件: `lib/uiServer/router/group-router.js`
+```javascript
+// 组管理 API 路由
+router.post('/cgi-bin/mockbubu/groups/list', ...)       // 获取组列表
+router.post('/cgi-bin/mockbubu/groups/create', ...)     // 创建组
+router.post('/cgi-bin/mockbubu/groups/update', ...)     // 更新组
+router.post('/cgi-bin/mockbubu/groups/delete', ...)     // 删除组
+router.post('/cgi-bin/mockbubu/groups/copy', ...)       // 复制组
+router.post('/cgi-bin/mockbubu/groups/switch', ...)     // 切换当前组
+router.post('/cgi-bin/mockbubu/groups/current', ...)    // 获取当前组
+```
+
+#### 修改文件: `lib/uiServer/router/index.js`
+```javascript
+// 所有 API 增加 groupId 参数支持
+// 修改点:
+1. /api-list: 增加 groupId 参数，返回该组视图的数据
+2. /update-api-mock: 更新指定组的 mock 状态
+3. /update-api-data: 更新指定组的数据
+4. /create-api-data: 在指定组创建数据
+5. /delete-api: 删除指定组的配置
+... 所有现有 API 都需要支持 groupId
+```
+
+#### 修改文件: `lib/server.js`
+```javascript
+// 请求拦截时读取当前组配置
+module.exports = (server, { storage }) => {
+  const groupManager = new GroupManager(storage)
+
+  server.on('request', (req, res) => {
+    const currentGroupId = groupManager.getCurrentGroupId()
+    const groupConfig = groupManager.getGroupFileConfig(currentGroupId, filename)
+
+    // 根据组配置决定 mock 行为
+    if (groupConfig.mock) {
+      // 优先使用组的自定义数据
+      if (groupConfig.customData) {
+        res.end(JSON.stringify(groupConfig.customData))
+      } else if (groupConfig.mockVersion) {
+        // 使用组的版本数据
+        res.end(JSON.stringify(groupConfig.version[versionName]))
+      } else {
+        // 使用原始数据
+        res.end(sessionCache.res.body)
+      }
+    } else {
+      req.passThrough()
+    }
+  })
+}
+```
+
+### 3.2 前端实现
+
+#### 新增组件: `app/src/components/group/GroupManager.vue`
+```vue
+<template>
+  <el-dialog title="分组管理" :visible.sync="visible" width="800px">
+    <!-- 组列表 -->
+    <el-table :data="groups">
+      <el-table-column label="组名" prop="name" />
+      <el-table-column label="描述" prop="description" />
+      <el-table-column label="创建时间" prop="createTime" />
+      <el-table-column label="操作" width="300">
+        <template slot-scope="scope">
+          <el-button @click="handleSwitch(scope.row)">切换</el-button>
+          <el-button @click="handleEdit(scope.row)">编辑</el-button>
+          <el-button @click="handleCopy(scope.row)">复制</el-button>
+          <el-button @click="handleDelete(scope.row)">删除</el-button>
+        </template>
+      </el-table-column>
+    </el-table>
+
+    <!-- 创建/编辑对话框 -->
+    <el-button @click="showCreateDialog">新建分组</el-button>
+  </el-dialog>
+</template>
+```
+
+#### 新增组件: `app/src/components/group/GroupSelector.vue`
+```vue
+<template>
+  <div class="group-selector">
+    <el-select v-model="currentGroupId" @change="handleSwitch">
+      <el-option
+        v-for="group in groups"
+        :key="group.id"
+        :label="group.name"
+        :value="group.id"
+      />
+    </el-select>
+    <el-button @click="openManager">管理分组</el-button>
+  </div>
+</template>
+```
+
+#### 修改组件: `app/src/components/header/ActionPanel.vue`
+```vue
+<template>
+  <div class="action-panel">
+    <!-- 新增：组选择器 -->
+    <GroupSelector />
+
+    <!-- 原有搜索区域 -->
+    <div class="action-panel__search">...</div>
+
+    <!-- 原有操作区域 -->
+    <div class="action-panel__actions">...</div>
+  </div>
+</template>
+```
+
+#### 修改文件: `app/src/service/index.js`
+```javascript
+// 新增组管理相关 API
+export function getGroups() { ... }
+export function createGroup(params) { ... }
+export function updateGroup(groupId, params) { ... }
+export function deleteGroup(groupId) { ... }
+export function copyGroup(sourceGroupId, params) { ... }
+export function switchGroup(groupId) { ... }
+export function getCurrentGroup() { ... }
+
+// 修改现有 API，增加 groupId 参数
+export function search(params) {
+  const groupId = getCurrentGroupIdFromStore()
+  return fetch('/cgi-bin/mockbubu/api-list', {
+    method: 'post',
+    body: JSON.stringify({ ...params, groupId }),
+    ...
+  })
+}
+// ... 其他 API 同样修改
+```
+
+#### 新增文件: `app/src/store/group.js`
+```javascript
+// Vuex/Pinia store 或 localStorage 管理当前组
+export const groupStore = {
+  currentGroupId: null,
+  groups: [],
+
+  async init() {
+    const res = await getCurrentGroup()
+    this.currentGroupId = res.data.currentGroupId
+    this.groups = res.data.groups
+  },
+
+  async switchGroup(groupId) {
+    await switchGroup(groupId)
+    this.currentGroupId = groupId
+    // 刷新页面数据
+    window.location.reload()
+  }
+}
+```
+
+---
+
+## 四、实施步骤
+
+### Phase 1: 基础架构 ✅ 完成
+1. ✅ 实现 GroupManager 类
+2. ✅ 创建默认组（迁移现有数据）
+3. ✅ 修改 server.js 支持组配置读取
+4. ✅ 测试数据读取优先级
+5. ✅ 添加组级别版本管理方法
+
+### Phase 2: 后端 API ✅ 完成
+1. ✅ 实现 group-router.js 所有 API
+2. ✅ 修改现有 API 支持 groupId 参数
+3. ✅ API 测试
+4. ✅ 修复 version-router.js 使用组级别版本操作
+
+### Phase 3: 前端 UI ✅ 完成
+1. ✅ 实现 GroupSelector 组件
+2. ✅ 实现 GroupManager 对话框
+3. ✅ 集成到 ActionPanel
+4. ✅ 修改所有 API 调用增加 groupId
+5. ✅ 添加表单验证和用户体验优化
+6. ✅ 添加列表刷新过渡动画
+
+### Phase 4: 数据迁移 ✅ 完成
+1. ✅ 编写迁移脚本，将现有数据移到默认组
+2. ✅ 兼容性测试
+3. ✅ 向后兼容旧数据
+
+### Phase 5: Bug 修复 ✅ 完成
+1. ✅ 修复 Element UI Form 组件注册问题
+2. ✅ 修复表单验证回调模式
+3. ✅ 修复 Mock 不生效问题（缓存缺失处理）
+4. ✅ 修复版本数据独立性问题（核心修复）
+5. ✅ 优化组切换用户体验
+6. ✅ 完整功能测试
+
+**总计**: 已完成所有开发和测试
+
+---
+
+## 五、关键技术点
+
+### 5.1 数据隔离
+- 每个组的配置独立存储
+- 组之间互不影响
+- 删除组只删除配置，不删除原始数据
+
+### 5.2 向后兼容
+- 首次启动自动创建默认组
+- 将现有数据迁移到默认组
+- 旧版本插件数据可无缝升级
+
+### 5.3 性能优化
+- 组列表缓存
+- 当前组配置缓存
+- 批量读取组配置
+
+### 5.4 错误处理
+- 组不存在时降级到默认组
+- 删除当前组时自动切换到默认组
+- 组配置损坏时使用原始数据
+
+---
+
+## 六、用户体验设计
+
+### 组选择器位置
+放在 ActionPanel 左上角，搜索框之前：
+```
+[分组: 默认组 ▼] [管理分组] | [搜索框] [筛选器] ...
+```
+
+### 管理分组对话框
+- 表格展示所有组
+- 当前组高亮显示
+- 提供快捷操作（切换、编辑、复制、删除）
+- 创建组时可选择从哪个组复制
+
+### 组切换提示
+- 切换组后显示提示："已切换到【测试组】"
+- 页面自动刷新数据
+- 保持当前选中的文件（如果存在）
+
+---
+
+## 七、风险与应对
+
+### 风险1: 数据迁移失败
+**应对**:
+- 迁移前自动备份
+- 提供回滚脚本
+- 灰度发布，小范围测试
+
+### 风险2: 性能下降
+**应对**:
+- 组配置缓存机制
+- 懒加载组数据
+- 限制组数量上限（如10个）
+
+### 风险3: 用户困惑
+**应对**:
+- 提供详细文档和视频教程
+- 新手引导提示
+- 默认组自动创建，用户无感知
+
+---
+
+## 八、后续扩展
+
+### 可能的增强功能
+1. **组导入导出**: 导出组配置为 JSON，分享给团队
+2. **组权限**: 只读组、编辑组、管理员组
+3. **组模板**: 预设常用场景组（成功场景、失败场景等）
+4. **组对比**: 对比两个组的配置差异
+5. **组历史**: 记录组的修改历史，支持回滚
+
+---
+
+## 九、API 接口定义
+
+### 组管理 API
+
+#### 1. 获取组列表
+```http
+POST /cgi-bin/mockbubu/groups/list
+Response: {
+  code: 200,
+  data: {
+    groups: [
+      {id, name, description, createTime, updateTime, isDefault}
+    ],
+    currentGroupId: 'xxx'
+  }
+}
+```
+
+#### 2. 创建组
+```http
+POST /cgi-bin/mockbubu/groups/create
+Body: {name, description, copyFromGroupId?}
+Response: {code: 200, data: {newGroup}}
+```
+
+#### 3. 更新组
+```http
+POST /cgi-bin/mockbubu/groups/update
+Body: {groupId, name?, description?}
+Response: {code: 200, data: {updatedGroup}}
+```
+
+#### 4. 删除组
+```http
+POST /cgi-bin/mockbubu/groups/delete
+Body: {groupId}
+Response: {code: 200, msg: '删除成功'}
+```
+
+#### 5. 切换当前组
+```http
+POST /cgi-bin/mockbubu/groups/switch
+Body: {groupId}
+Response: {code: 200, data: {currentGroup}}
+```
+
+#### 6. 获取当前组
+```http
+POST /cgi-bin/mockbubu/groups/current
+Response: {code: 200, data: {currentGroup}}
+```
+
+---
+
+## 十、数据库 Schema
+
+### properties.__groups__
+```json
+{
+  "groups": [
+    {
+      "id": "default",
+      "name": "默认组",
+      "description": "系统默认分组",
+      "createTime": 1697472000000,
+      "updateTime": 1697472000000,
+      "isDefault": true
+    }
+  ],
+  "currentGroupId": "default"
+}
+```
+
+### properties.group.{groupId}.{filename}
+```json
+{
+  "mock": true,
+  "locked": false,
+  "mockVersion": "v1",
+  "mockTime": 1697472000000,
+  "version.v1": "{...json...}",
+  "versionMeta.v1": {
+    "description": "版本1",
+    "createTime": 1697472000000,
+    "updateTime": 1697472000000
+  }
+}
+```
+
+---
+
+**文档版本**: v1.0
+**最后更新**: 2025-10-16

package/lib/const.js

@@ -26,3 +26,22 @@ exports.LockedFilterMap = {
   'locked': { key: 'locked', value: true, method: 'equal' },
   'unlocked': { key: 'locked', value: false, method: 'equal' },
 }
+
+// HTTP Method 筛选映射
+exports.MethodFilterMap = {
+  'GET': { key: 'method', value: 'GET', method: 'equal' },
+  'POST': { key: 'method', value: 'POST', method: 'equal' },
+  'PUT': { key: 'method', value: 'PUT', method: 'equal' },
+  'DELETE': { key: 'method', value: 'DELETE', method: 'equal' },
+  'PATCH': { key: 'method', value: 'PATCH', method: 'equal' },
+  'HEAD': { key: 'method', value: 'HEAD', method: 'equal' },
+  'OPTIONS': { key: 'method', value: 'OPTIONS', method: 'equal' },
+}
+
+// 状态码筛选映射（使用自定义 method: 'statusRange'）
+exports.StatusFilterMap = {
+  '2xx': { key: 'status', value: [200, 299], method: 'range' },
+  '3xx': { key: 'status', value: [300, 399], method: 'range' },
+  '4xx': { key: 'status', value: [400, 499], method: 'range' },
+  '5xx': { key: 'status', value: [500, 599], method: 'range' },
+}