whistle.mockbubu 1.0.0-dev.4 → 2.0.0

package/CHANGELOG_P0_FIXES.md

@@ -0,0 +1,412 @@
+# P0 Bug 修复记录
+
+本文档记录了所有 P0 级别 bug 的修复内容。
+
+## 修复日期
+2025-10-15
+
+## 修复列表
+
+### ✅ P0-1: 修复 updateVersionName 函数 bug
+
+**文件**: `lib/utils.js:196-201`
+
+**问题**:
+- `getVersionContent` 调用时缺少必需参数，会导致函数执行失败
+- `addNewVersion` 调用时参数名错误（`file` 应该是 `content`）
+
+**修复前**:
+```javascript
+const updateVersionName = ({ storage, filename, versionName, newVersion }) => {
+  const file = getVersionContent(versionName)  // ❌ 缺少参数
+  addNewVersion({ storage, filename, versionName: newVersion, file })  // ❌ 错误的参数名
+  deleteVersion({ storage, filename, versionName })
+}
+```
+
+**修复后**:
+```javascript
+const updateVersionName = ({ storage, filename, versionName, newVersion }) => {
+  const content = getVersionContent({ storage, filename, versionName })  // ✅ 传递完整参数
+  addNewVersion({ storage, filename, versionName: newVersion, content })  // ✅ 正确的参数名
+  deleteVersion({ storage, filename, versionName })
+}
+```
+
+---
+
+### ✅ P0-2: 删除调试用 console.log
+
+**文件**: `lib/utils.js`
+
+**问题**: 存在调试用的 console.log 语句，应该清理
+
+**修复内容**:
+1. 删除 line 73 的 `console.log(content)` (writeFile 函数)
+2. 删除 line 113 的 `console.log(resCache)` (readFile 函数)
+3. 增强错误日志，只在开发环境输出:
+
+```javascript
+const withTryCatch = (fn) => {
+  return async (...args) => {
+    try {
+      return await fn(...args)
+    } catch (e) {
+      // 仅在开发环境输出错误日志
+      if (process.env.NODE_ENV === 'development') {
+        console.error('[mockbubu] 全局捕获异常:', e)
+      }
+      throw e
+    }
+  }
+}
+```
+
+4. 批量删除接口的错误处理改进 (`lib/uiServer/router/index.js:182-199`):
+
+```javascript
+// 批量删除
+const errors = []
+filteredList.forEach((item) => {
+  try {
+    removeFile(localStorage, item.name)
+  } catch (error) {
+    errors.push({ name: item.name, error: error.message })
+    // 仅在开发环境输出错误日志
+    if (process.env.NODE_ENV === 'development') {
+      console.error(`[mockbubu] 删除文件 ${item.name} 失败:`, error.message)
+    }
+  }
+})
+
+// 如果有错误，在响应中返回
+if (errors.length > 0) {
+  ctx.body = createSuccessResponse({ errors }, `删除完成，${errors.length} 个文件删除失败`)
+  return
+}
+```
+
+---
+
+### ✅ P0-3: CORS 安全性增强
+
+**文件**: `lib/uiServer/index.js:18-36`
+
+**问题**: CORS 配置过于宽松（`origin: '*'`），存在安全风险
+
+**修复前**:
+```javascript
+app.use(cors({
+  origin: '*',  // ❌ 允许任何域名访问
+  maxAge: 10,
+  credentials: true,
+  allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+}))
+```
+
+**修复后**:
+```javascript
+app.use(
+  cors({
+    origin: (ctx) => {
+      const origin = ctx.get('Origin')
+      // 只允许 localhost 和 127.0.0.1 的请求
+      if (!origin || /^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/i.test(origin)) {
+        return origin || '*'
+      }
+      // Whistle UI 的域名
+      if (/^https?:\/\/local\.whistlejs\.com(:\d+)?$/i.test(origin)) {
+        return origin
+      }
+      return false  // ✅ 其他域名一律拒绝
+    },
+    maxAge: 10,
+    credentials: true,
+    allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+  }),
+)
+```
+
+**安全说明**:
+- 只允许 localhost、127.0.0.1、local.whistlejs.com 访问
+- 阻止其他域名的跨域请求
+- 保护用户的 mock 数据不被恶意网站访问
+
+---
+
+### ✅ P0-4: 输入参数验证
+
+**新增文件**: `lib/uiServer/validator.js`
+
+**问题**: 所有 API 接口缺少输入验证，存在安全风险和稳定性问题
+
+**解决方案**: 创建完整的验证模块，包含以下验证器：
+
+#### 1. validateFilename - 文件名验证
+```javascript
+const validateFilename = (name) => {
+  if (!name || typeof name !== 'string') {
+    return '文件名不能为空'
+  }
+  if (name.length > 2048) {
+    return '文件名长度不能超过 2048 字符'
+  }
+  return null
+}
+```
+
+#### 2. validateVersionName - 版本名验证
+```javascript
+const validateVersionName = (versionName) => {
+  if (!versionName || typeof versionName !== 'string') {
+    return '版本名不能为空'
+  }
+  if (versionName.length > 100) {
+    return '版本名长度不能超过 100 字符'
+  }
+  // 允许: 中文、字母、数字、下划线、连字符、空格
+  // 不允许: / \ : * ? " < > | 等文件系统保留字符
+  if (/[\/\\:*?"<>|]/.test(versionName)) {
+    return '版本名不能包含特殊字符 / \\ : * ? " < > |'
+  }
+  return null
+}
+```
+
+**重要改进**: 支持中文版本名！
+
+#### 3. validateMockData - Mock 数据验证
+```javascript
+const validateMockData = (data) => {
+  // 允许 undefined (使用默认值)，但不允许 null
+  if (data === null) {
+    return 'Mock 数据不能为 null'
+  }
+  // 如果 data 是 undefined，跳过大小检查（会使用默认值）
+  if (data === undefined) {
+    return null
+  }
+  // 限制大小为 5MB
+  const dataStr = typeof data === 'string' ? data : JSON.stringify(data)
+  if (dataStr.length > 5 * 1024 * 1024) {
+    return 'Mock 数据大小不能超过 5MB'
+  }
+  return null
+}
+```
+
+**重要改进**: 允许 `content` 为 undefined，创建版本时可以不传递内容！
+
+#### 4. validateBoolean - 布尔值验证
+```javascript
+const validateBoolean = (value, fieldName) => {
+  if (typeof value !== 'boolean') {
+    return `${fieldName} 必须是布尔值`
+  }
+  return null
+}
+```
+
+#### 5. validateRuleValue - 规则类型验证
+```javascript
+const validateRuleValue = (ruleValue) => {
+  const validValues = ['pathname', 'href', 'pattern']
+  if (!ruleValue || !validValues.includes(ruleValue)) {
+    return `ruleValue 必须是 ${validValues.join(', ')} 之一`
+  }
+  return null
+}
+```
+
+#### 6. validate - 验证中间件
+```javascript
+const validate = (schema) => {
+  return async (ctx, next) => {
+    const body = ctx.request.body || {}
+    const errors = []
+
+    Object.keys(schema).forEach((key) => {
+      const validator = schema[key]
+      const value = body[key]
+      const error = validator(value)
+      if (error) {
+        errors.push({ field: key, message: error })
+      }
+    })
+
+    if (errors.length > 0) {
+      ctx.status = 400
+      ctx.body = {
+        code: 400,
+        msg: '参数验证失败',
+        data: errors,
+      }
+      return
+    }
+
+    await next()
+  }
+}
+```
+
+---
+
+### 应用验证到所有 API 端点
+
+#### lib/uiServer/router/index.js
+
+1. **获取列表数据** - 无需验证（使用 POST 是为了发送过滤参数）
+2. **更新文件详情** (line 59-79):
+   ```javascript
+   router.post('/cgi-bin/mockbubu/update-api-data', validate({
+     name: validateFilename,
+     data: validateMockData,
+   }), (ctx) => { ... })
+   ```
+
+3. **获取文件详情** (line 82-100):
+   ```javascript
+   router.post('/cgi-bin/mockbubu/get-api-data', validate({
+     name: validateFilename,
+   }), (ctx) => { ... })
+   ```
+
+4. **新增 mock 接口** (line 103-123):
+   ```javascript
+   router.post('/cgi-bin/mockbubu/create-api-data', validate({
+     name: validateFilename,
+     content: validateMockData,
+     ruleValue: validateRuleValue,
+   }), (ctx) => { ... })
+   ```
+
+5. **修改接口 mock 开关** (line 126-139):
+   ```javascript
+   router.post('/cgi-bin/mockbubu/update-api-mock', validate({
+     name: validateFilename,
+     mock: (val) => validateBoolean(val, 'mock'),
+   }), (ctx) => { ... })
+   ```
+
+6. **修改接口 lock 开关** (line 142-155):
+   ```javascript
+   router.post('/cgi-bin/mockbubu/update-api-lock', validate({
+     name: validateFilename,
+     locked: (val) => validateBoolean(val, 'locked'),
+   }), (ctx) => { ... })
+   ```
+
+7. **删除接口数据** (line 158-170):
+   ```javascript
+   router.post('/cgi-bin/mockbubu/delete-api', validate({
+     name: validateFilename,
+   }), (ctx) => { ... })
+   ```
+
+8. **批量删除接口** - 无需验证（参数是可选的过滤条件）
+
+#### lib/uiServer/router/version-router.js
+
+1. **新增版本** (line 22-45):
+   ```javascript
+   router.post('/cgi-bin/mockbubu/add-new-version', validate({
+     name: validateFilename,
+     versionName: validateVersionName,
+     content: validateMockData,
+   }), (ctx) => { ... })
+   ```
+
+2. **删除版本** (line 48-73):
+   ```javascript
+   router.post('/cgi-bin/mockbubu/delete-version', validate({
+     name: validateFilename,
+     versionName: validateVersionName,
+   }), (ctx) => { ... })
+   ```
+
+3. **更新版本内容** (line 76-96):
+   ```javascript
+   router.post('/cgi-bin/mockbubu/update-version-content', validate({
+     name: validateFilename,
+     versionName: validateVersionName,
+     content: validateMockData,
+   }), (ctx) => { ... })
+   ```
+
+4. **更新版本名称** (line 99-119):
+   ```javascript
+   router.post('/cgi-bin/mockbubu/update-version-name', validate({
+     name: validateFilename,
+     versionName: validateVersionName,
+     newVersion: validateVersionName,
+   }), (ctx) => { ... })
+   ```
+
+5. **获取版本列表** (line 122-135):
+   ```javascript
+   router.post('/cgi-bin/mockbubu/get-versions', validate({
+     name: validateFilename,
+   }), (ctx) => { ... })
+   ```
+
+6. **设置 mock 的版本** (line 138-156):
+   ```javascript
+   router.post('/cgi-bin/mockbubu/set-mock-version', validate({
+     name: validateFilename,
+     versionName: (val) => {
+       // versionName 可以为空字符串（表示清除版本）
+       if (val === '') return null
+       return validateVersionName(val)
+     },
+   }), (ctx) => { ... })
+   ```
+
+---
+
+## 验证效果
+
+### 错误响应格式
+当参数验证失败时，返回统一的错误格式：
+
+```json
+{
+  "code": 400,
+  "msg": "参数验证失败",
+  "data": [
+    {
+      "field": "versionName",
+      "message": "版本名不能包含特殊字符 / \\ : * ? \" < > |"
+    },
+    {
+      "field": "content",
+      "message": "Mock 数据不能为 null"
+    }
+  ]
+}
+```
+
+### 安全保护
+- ✅ 防止注入攻击（文件名/版本名长度限制）
+- ✅ 防止文件系统攻击（禁止特殊字符）
+- ✅ 防止内存耗尽（Mock 数据大小限制 5MB）
+- ✅ 防止类型错误（严格的类型检查）
+
+---
+
+## 总结
+
+所有 P0 级别的 bug 已修复：
+
+1. ✅ **P0-1**: updateVersionName 函数参数错误 - 已修复
+2. ✅ **P0-2**: 删除调试用 console.log - 已清理
+3. ✅ **P0-3**: CORS 安全性增强 - 已限制为本地域名
+4. ✅ **P0-4**: 输入参数验证 - 已为所有 API 添加验证
+
+**测试建议**:
+1. 测试创建中文版本名（如 "测试版本1"）
+2. 测试创建版本时不传 content 参数
+3. 测试各种非法输入（超长字符串、特殊字符等）
+4. 测试跨域访问是否被正确阻止
+
+**下一步**:
+可以开始处理 P1 级别的优化任务。

package/CHANGELOG_P1_OPTIMIZATIONS.md

@@ -0,0 +1,292 @@
+# P1 优化任务文档
+
+本文档记录所有 P1 级别的优化任务。
+
+## 优化日期
+2025-10-15
+
+## P1 优化列表
+
+### 🎯 P1-1: 批量操作功能缺失
+
+**优先级**: P1
+**类型**: 功能增强
+**影响**: 用户体验
+
+**问题描述**:
+- 当有大量 mock 数据时，用户需要逐个删除/修改，效率低
+- 缺少批量选择、批量删除、批量开关 mock 的功能
+
+**期望功能**:
+1. 添加全选/反选复选框
+2. 支持批量删除选中的 mock
+3. 支持批量开启/关闭选中的 mock
+4. 显示已选数量
+
+**优化方案**:
+- 在表格中添加复选框列
+- 在操作区域添加批量操作按钮组
+- 实现批量 API 调用
+- 添加操作确认对话框
+
+**文件涉及**:
+- `app/src/components/MockContainer.vue` - 添加选择逻辑
+- `app/src/components/header/ActionPanel.vue` - 添加批量操作按钮
+- `lib/uiServer/router/index.js` - 添加批量操作接口（如 `/batch-update-mock`）
+
+**测试点**:
+- 全选/反选功能
+- 批量删除锁定和未锁定的混合数据
+- 批量操作的错误处理
+
+---
+
+### 🎯 P1-2: 搜索功能不够强大
+
+**优先级**: P1
+**类型**: 功能增强
+**影响**: 用户体验
+
+**问题描述**:
+- 当前只能按文件名搜索
+- 无法按 URL、请求方法、状态码等字段搜索
+- 无法组合多个条件搜索
+
+**期望功能**:
+1. 支持多字段搜索（URL、方法、状态码）
+2. 支持高级筛选器
+3. 支持保存常用搜索条件
+4. 支持搜索历史
+
+**优化方案**:
+- 增强 `ActionPanel` 组件的搜索功能
+- 添加高级搜索弹窗
+- 后端 `handleFilterList` 函数增加更多过滤条件
+
+**文件涉及**:
+- `app/src/components/header/ActionPanel.vue` - 搜索 UI
+- `lib/uiServer/util.js` - `handleFilterList` 函数增强
+- `app/src/hooks/useHeader.js` - 搜索逻辑
+
+**测试点**:
+- 单条件搜索
+- 组合条件搜索
+- 搜索性能（大量数据）
+
+---
+
+### 🎯 P1-3: 版本管理 UI 需要优化
+
+**优先级**: P1
+**类型**: UI/UX 优化
+**影响**: 用户体验
+
+**问题描述**:
+- 版本 tab 横向排列，数量多时不易查看
+- 缺少版本的创建时间、修改时间信息
+- 无法对版本进行备注说明
+- 缺少版本对比功能
+
+**期望功能**:
+1. 优化版本 tab 布局（考虑下拉选择或侧边栏）
+2. 显示版本元信息（创建时间、修改时间）
+3. 支持版本备注
+4. 支持版本对比（diff）
+
+**优化方案 Phase 1** (本次实现):
+- 添加版本创建时间显示
+- 限制版本数量（最多保留 10 个）
+- 添加版本描述字段
+
+**优化方案 Phase 2** (未来):
+- 版本对比（JSON diff）
+- 版本恢复历史
+
+**文件涉及**:
+- `app/src/components/content/ResponsePanel.vue` - 版本 UI
+- `lib/utils.js` - 版本管理函数增加时间戳
+- `lib/uiServer/router/version-router.js` - API 增加描述字段
+
+**测试点**:
+- 版本元信息显示
+- 版本数量限制
+- 版本描述保存和显示
+
+---
+
+### 🎯 P1-4: Mock 数据编辑体验优化
+
+**优先级**: P1
+**类型**: UX 优化
+**影响**: 用户体验
+
+**问题描述**:
+- JSON 编辑器缺少代码格式化
+- 缺少语法错误提示
+- 缺少快捷键说明
+- 保存按钮位置不明显
+
+**期望功能**:
+1. 添加格式化按钮（美化 JSON）
+2. 添加语法错误实时提示
+3. 显示快捷键提示
+4. 优化保存按钮样式和位置
+
+**优化方案**:
+- 在编辑器上方添加工具栏（格式化、验证、快捷键提示）
+- 增强 JsonEditor 组件
+- 优化保存按钮的视觉反馈
+
+**文件涉及**:
+- `app/src/components/common/JsonEditor.vue` - 编辑器组件
+- `app/src/components/content/ResponsePanel.vue` - 添加工具栏
+
+**测试点**:
+- JSON 格式化功能
+- 语法错误提示
+- 快捷键功能
+- 保存状态反馈
+
+---
+
+### 🎯 P1-5: 缺少数据导入导出功能
+
+**优先级**: P1
+**类型**: 功能增强
+**影响**: 用户体验
+
+**问题描述**:
+- 无法导出所有 mock 数据进行备份
+- 无法从其他环境导入 mock 数据
+- 无法分享 mock 配置给团队成员
+
+**期望功能**:
+1. 导出所有 mock 数据为 JSON 文件
+2. 导入 JSON 文件恢复 mock 数据
+3. 导出/导入单个 mock 配置
+4. 支持导出为 Postman Collection 格式
+
+**优化方案 Phase 1** (本次实现):
+- 添加全局导出按钮
+- 添加全局导入按钮
+- 实现 JSON 格式的导出/导入
+
+**优化方案 Phase 2** (未来):
+- Postman Collection 格式支持
+- 增量导入（合并而非覆盖）
+
+**文件涉及**:
+- `app/src/components/header/ActionPanel.vue` - 添加导入/导出按钮
+- `lib/uiServer/router/index.js` - 添加导出/导入接口
+- `app/src/utils/export.js` - 新增导出工具函数
+
+**测试点**:
+- 导出所有 mock 数据
+- 导入 JSON 文件
+- 数据格式兼容性
+- 错误处理
+
+---
+
+### 🎯 P1-6: 缺少操作日志/历史记录
+
+**优先级**: P1
+**类型**: 功能增强
+**影响**: 可追溯性
+
+**问题描述**:
+- 无法查看谁修改了 mock 数据
+- 无法回溯历史操作
+- 调试时难以定位问题
+
+**期望功能**:
+1. 记录所有操作（创建、修改、删除）
+2. 显示操作时间和类型
+3. 支持按时间筛选日志
+4. 支持撤销最近的操作
+
+**优化方案**:
+- 添加操作日志记录中间件
+- 创建日志查看面板
+- 使用 Whistle Storage API 持久化日志
+
+**文件涉及**:
+- `lib/uiServer/middleware/logger.js` - 新增日志中间件
+- `app/src/components/LogPanel.vue` - 新增日志面板组件
+- `lib/utils.js` - 添加日志工具函数
+
+**测试点**:
+- 操作日志记录
+- 日志查看和筛选
+- 日志性能（大量操作）
+
+---
+
+### 🎯 P1-7: Request/Response 详情展示不够完整
+
+**优先级**: P1
+**类型**: 功能增强
+**影响**: 调试体验
+
+**问题描述**:
+- 只显示 Response，Request 信息不完整
+- 缺少 Headers、Query 参数的展示
+- 无法查看原始请求/响应
+
+**期望功能**:
+1. 显示完整的 Request 信息（Headers、Body、Query）
+2. 显示完整的 Response 信息（Headers、Body、Status）
+3. 支持切换查看原始数据和格式化数据
+4. 支持复制请求/响应内容
+
+**优化方案**:
+- 增强 RequestDetail 组件
+- 添加 Tab 切换（Headers、Body、Query）
+- 添加复制按钮
+
+**文件涉及**:
+- `app/src/components/content/RequestDetail.vue` - 增强展示
+- `lib/server.js` - 确保存储完整的请求信息
+
+**测试点**:
+- 完整信息展示
+- Tab 切换
+- 复制功能
+
+---
+
+## 优先级排序
+
+根据用户影响和实现难度，建议实现顺序：
+
+1. **P1-4: Mock 数据编辑体验优化** - 最高频使用，影响最大
+2. **P1-3: 版本管理 UI 优化 (Phase 1)** - 当前功能已有，只需优化
+3. **P1-1: 批量操作功能** - 大量数据时的刚需
+4. **P1-7: Request/Response 详情展示** - 调试必备
+5. **P1-5: 数据导入导出 (Phase 1)** - 备份和分享需求
+6. **P1-2: 搜索功能增强** - 数据多时提升效率
+7. **P1-6: 操作日志** - 长期价值，但不紧急
+
+## 实施计划
+
+### 第一阶段（本次迭代）✅
+- ✅ P1-4: Mock 数据编辑体验优化
+- ✅ P1-3: 版本管理 UI 优化 (Phase 1)
+  - ✅ 版本数量限制（最多10个）
+  - ✅ 版本描述字段
+  - ✅ 版本创建时间和修改时间
+  - ✅ 版本信息tooltip显示
+
+### 第二阶段（下次迭代）
+- P1-1: 批量操作功能
+- P1-7: Request/Response 详情展示
+
+### 第三阶段（未来）
+- P1-5: 数据导入导出
+- P1-2: 搜索功能增强
+
+## 备注
+
+- 所有优化都需要保持向后兼容
+- 优化过程中注意性能影响
+- 每个优化完成后需要更新用户文档