whistle.mockbubu 1.0.0-dev.4 → 2.0.0-beta.0

package/lib/storage-v3.js

@@ -0,0 +1,1368 @@
+/**
+ * FileSystemStorage V3 - 基于文件系统的存储层
+ *
+ * 架构设计：
+ * - 每个组一个独立目录
+ * - 索引文件（index.json）用于快速列表查询
+ * - 文件数据按需加载，避免内存溢出
+ * - 支持流式导出/导入
+ *
+ * 目录结构：
+ * groups/
+ *   ├── {groupId}/
+ *   │   ├── group.json          # 组元数据
+ *   │   ├── index.json          # 文件索引（轻量级）
+ *   │   └── files/
+ *   │       └── {fileId}/
+ *   │           ├── file.json   # 文件完整数据
+ *   │           └── versions/   # 版本目录
+ *   │               ├── v1.json
+ *   │               └── v2.json
+ */
+
+const fs = require('fs').promises
+const path = require('path')
+
+class FileSystemStorage {
+  constructor(baseDir) {
+    this.baseDir = baseDir
+    this.groupsDir = path.join(baseDir, 'groups')
+    this.currentGroupFile = path.join(baseDir, 'current-group.txt')
+    this.propertiesFile = path.join(baseDir, 'properties.json')
+    this.indexCache = new Map() // 索引缓存
+    this.maxCacheAge = 3000 // 缓存3秒（降低延迟，提高实时性）
+    this.propertiesCache = null // 通用属性缓存
+    this.indexLocks = new Map() // 索引写入锁（内存锁，同进程有效）
+  }
+
+  /**
+   * 初始化存储目录
+   */
+  async init() {
+    await fs.mkdir(this.groupsDir, { recursive: true })
+
+    // 确保默认组存在
+    const defaultGroupDir = path.join(this.groupsDir, 'default')
+    try {
+      await fs.access(defaultGroupDir)
+    } catch {
+      await this.createGroup({
+        id: 'default',
+        name: '默认组',
+        description: '系统默认分组',
+        isDefault: true,
+      })
+    }
+  }
+
+  /**
+   * 生成文件ID（随机生成，确保唯一性）
+   * ⚠️ 重要设计原则：
+   * - fileId 是文件系统的唯一标识符，用于删除/编辑/查找文件
+   * - 每次创建新文件时生成新的 fileId（即使URL相同）
+   * - 重复检测通过文件名（URL）而不是 fileId
+   * - 删除后重新捕获同一URL会生成新的 fileId
+   *
+   * @returns {string} 12位随机ID
+   */
+  generateFileId() {
+    // 使用时间戳 + 随机数确保唯一性
+    const timestamp = Date.now().toString(36)
+    const random = Math.random().toString(36).substring(2, 10)
+    return `${timestamp}${random}`.substring(0, 12)
+  }
+
+  // ========================================
+  // 组管理
+  // ========================================
+
+  /**
+   * 列出所有组
+   */
+  async listGroups() {
+    const entries = await fs.readdir(this.groupsDir, { withFileTypes: true })
+    const groups = []
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        try {
+          const groupData = await this.getGroup(entry.name)
+          groups.push(groupData)
+        } catch (err) {
+          console.error(`[storage-v3] 读取组失败: ${entry.name}`, err.message)
+        }
+      }
+    }
+
+    // 排序：默认组在前,其他组按创建时间升序(旧组在前,新组在后)
+    return groups.sort((a, b) => {
+      // 默认组始终排在第一位
+      if (a.isDefault) return -1
+      if (b.isDefault) return 1
+      // 其他组按创建时间升序排序
+      return (a.createTime || 0) - (b.createTime || 0)
+    })
+  }
+
+  /**
+   * 获取组信息
+   * 如果组文件不存在，自动创建默认组元数据
+   */
+  async getGroup(groupId) {
+    const groupFile = path.join(this.groupsDir, groupId, 'group.json')
+
+    try {
+      const content = await fs.readFile(groupFile, 'utf8')
+      return JSON.parse(content)
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        // 文件不存在，自动创建默认组元数据
+        console.log(`[storage-v3] 组元数据不存在，自动创建: ${groupId}`)
+
+        const defaultMeta = {
+          id: groupId,
+          name: groupId === 'default' ? '默认组' : groupId,
+          description: '',
+          isDefault: groupId === 'default',
+          fileCount: 0,
+          totalSize: 0,
+          createTime: Date.now(),
+          updateTime: Date.now(),
+        }
+
+        // 确保目录存在
+        const groupDir = path.join(this.groupsDir, groupId)
+        await fs.mkdir(groupDir, { recursive: true })
+
+        // 写入组元数据
+        await this._writeJSON(groupFile, defaultMeta)
+
+        return defaultMeta
+      }
+
+      // 其他错误继续抛出
+      console.error(`[storage-v3] 读取组元数据失败: ${groupId}`, err)
+      throw err
+    }
+  }
+
+  /**
+   * 创建组
+   */
+  async createGroup(groupData) {
+    const { id, name, description = '', isDefault = false } = groupData
+
+    const groupDir = path.join(this.groupsDir, id)
+    const filesDir = path.join(groupDir, 'files')
+
+    // 创建目录结构
+    await fs.mkdir(filesDir, { recursive: true })
+
+    // 写入组元数据
+    const group = {
+      id,
+      name,
+      description,
+      isDefault,
+      fileCount: 0,
+      totalSize: 0,
+      createTime: Date.now(),
+      updateTime: Date.now(),
+    }
+
+    await this._writeJSON(path.join(groupDir, 'group.json'), group)
+
+    // 初始化索引文件
+    const index = {
+      version: '3.0.0',
+      updateTime: Date.now(),
+      files: [],
+    }
+
+    await this._writeJSON(path.join(groupDir, 'index.json'), index)
+
+    // 更新组元数据文件（_meta.json）
+    try {
+      const meta = await this.getGroupsMeta()
+      if (!meta.groups.find(g => g.id === id)) {
+        meta.groups.push(group)
+        await this.setGroupsMeta(meta)
+      }
+    } catch (err) {
+      console.error(`[storage-v3 ${new Date().toLocaleString('zh-CN', { hour12: false })}] 更新 _meta.json 失败:`, err.message)
+    }
+
+    return group
+  }
+
+  /**
+   * 更新组信息
+   */
+  async updateGroup(groupId, updates) {
+    const group = await this.getGroup(groupId)
+    const updated = {
+      ...group,
+      ...updates,
+      updateTime: Date.now(),
+    }
+
+    const groupFile = path.join(this.groupsDir, groupId, 'group.json')
+    await this._writeJSON(groupFile, updated)
+
+    return updated
+  }
+
+  /**
+   * 删除组（删除整个目录）
+   */
+  async deleteGroup(groupId) {
+    if (groupId === 'default') {
+      throw new Error('不能删除默认组')
+    }
+
+    const groupDir = path.join(this.groupsDir, groupId)
+    await fs.rm(groupDir, { recursive: true, force: true })
+
+    // 清除缓存
+    this.indexCache.delete(groupId)
+
+    // 同时更新组元数据，移除已删除的组
+    const meta = await this.getGroupsMeta()
+    meta.groups = meta.groups.filter(g => g.id !== groupId)
+    await this.setGroupsMeta(meta)
+  }
+
+  /**
+   * 获取组元数据（所有组列表 + 当前组ID）
+   * Phase 2: 从独立的 _meta.json 读取，兼容旧 properties 文件
+   */
+  async getGroupsMeta() {
+    const metaFile = path.join(this.groupsDir, '_meta.json')
+
+    try {
+      // 尝试从新位置读取
+      const content = await fs.readFile(metaFile, 'utf-8')
+      return JSON.parse(content)
+    } catch (err) {
+      // 如果文件不存在，尝试从 properties 迁移
+      if (err.code === 'ENOENT') {
+        console.log(`[storage-v3 ${new Date().toLocaleString('zh-CN', { hour12: false })}] _meta.json 不存在，尝试从 properties 迁移`)
+        return await this._migrateGroupsMetaFromProperties()
+      }
+      throw err
+    }
+  }
+
+  /**
+   * 设置组元数据
+   * Phase 2: 写入独立的 _meta.json
+   */
+  async setGroupsMeta(meta) {
+    const metaFile = path.join(this.groupsDir, '_meta.json')
+    await this._writeJSON(metaFile, {
+      ...meta,
+      version: '3.0', // 架构版本号
+      updateTime: Date.now(),
+    })
+  }
+
+  /**
+   * 从 properties 文件迁移组元数据（内部方法）
+   * @private
+   */
+  async _migrateGroupsMetaFromProperties() {
+    // 从 storage-adapter 读取旧的 properties
+    const StorageAdapter = require('./storage-adapter')
+    const adapter = new StorageAdapter({ basePath: this.baseDir })
+
+    try {
+      const data = await adapter.getProperty('__groups__')
+      if (data && data.groups) {
+        console.log(`[storage-v3 ${new Date().toLocaleString('zh-CN', { hour12: false })}] 从 properties 迁移 ${data.groups.length} 个组`)
+
+        // 写入新位置
+        await this.setGroupsMeta({
+          groups: data.groups,
+          currentGroupId: data.currentGroupId || 'default',
+        })
+
+        return {
+          groups: data.groups,
+          currentGroupId: data.currentGroupId || 'default',
+        }
+      }
+    } catch (err) {
+      console.error(`[storage-v3 ${new Date().toLocaleString('zh-CN', { hour12: false })}] 从 properties 迁移失败:`, err.message)
+    }
+
+    // 如果迁移失败，返回默认值
+    const defaultMeta = {
+      groups: [{
+        id: 'default',
+        name: '默认组',
+        description: '系统默认分组',
+        createTime: Date.now(),
+        updateTime: Date.now(),
+        isDefault: true,
+      }],
+      currentGroupId: 'default',
+    }
+
+    await this.setGroupsMeta(defaultMeta)
+    return defaultMeta
+  }
+
+  /**
+   * 复制组的所有文件（V3架构专用）
+   * @param {string} sourceGroupId - 源组ID
+   * @param {string} targetGroupId - 目标组ID
+   */
+  async copyGroup(sourceGroupId, targetGroupId) {
+    console.log(`[storage-v3 2025/11/19 14:10:00] 开始复制组: ${sourceGroupId} -> ${targetGroupId}`)
+
+    // 1. 读取源组的索引
+    const sourceIndex = await this.getIndex(sourceGroupId)
+    console.log(`[storage-v3 2025/11/19 14:10:00] 源组文件数: ${sourceIndex.files.length}`)
+
+    // 2. 确保目标组目录存在
+    const targetGroupDir = path.join(this.groupsDir, targetGroupId)
+    const targetFilesDir = path.join(targetGroupDir, 'files')
+    await fs.mkdir(targetFilesDir, { recursive: true })
+
+    // 3. 复制所有文件
+    const copiedFiles = []
+    for (const fileEntry of sourceIndex.files) {
+      try {
+        const sourceFileDir = path.join(this.groupsDir, sourceGroupId, 'files', fileEntry.id)
+        const targetFileDir = path.join(targetFilesDir, fileEntry.id)
+
+        // 递归复制文件目录（包括file.json和versions/）
+        await this._copyDirectory(sourceFileDir, targetFileDir)
+
+        // 将文件条目添加到目标索引
+        copiedFiles.push({
+          ...fileEntry,
+          // 保持原有时间戳
+        })
+
+        console.log(`[storage-v3 2025/11/19 14:10:00] 已复制文件: ${fileEntry.url} (${fileEntry.id})`)
+      } catch (err) {
+        console.error(`[storage-v3 2025/11/19 14:10:00] 复制文件失败: ${fileEntry.id}`, err.message)
+      }
+    }
+
+    // 4. 创建目标组索引
+    const targetIndex = {
+      version: '3.0.0',
+      files: copiedFiles,
+      updateTime: Date.now(),
+    }
+
+    await this.updateIndex(targetGroupId, targetIndex)
+    console.log(`[storage-v3 2025/11/19 14:10:00] 复制完成，共 ${copiedFiles.length} 个文件`)
+
+    return copiedFiles.length
+  }
+
+  /**
+   * 递归复制目录
+   * @private
+   */
+  async _copyDirectory(source, target) {
+    await fs.mkdir(target, { recursive: true })
+
+    const entries = await fs.readdir(source, { withFileTypes: true })
+
+    for (const entry of entries) {
+      const sourcePath = path.join(source, entry.name)
+      const targetPath = path.join(target, entry.name)
+
+      if (entry.isDirectory()) {
+        await this._copyDirectory(sourcePath, targetPath)
+      } else {
+        await fs.copyFile(sourcePath, targetPath)
+      }
+    }
+  }
+
+  // ========================================
+  // 索引管理
+  // ========================================
+
+  /**
+   * 获取索引（带缓存）
+   * 如果索引文件不存在，自动创建空索引
+   */
+  async getIndex(groupId) {
+    // 检查缓存
+    const cached = this.indexCache.get(groupId)
+    if (cached && Date.now() - cached.time < this.maxCacheAge) {
+      return cached.data
+    }
+
+    // 读取索引文件
+    const indexFile = path.join(this.groupsDir, groupId, 'index.json')
+
+    try {
+      const content = await fs.readFile(indexFile, 'utf8')
+      const index = JSON.parse(content)
+
+      // 更新缓存
+      this.indexCache.set(groupId, { data: index, time: Date.now() })
+
+      return index
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        // 文件不存在，自动创建空索引
+        console.log(`[storage-v3] 索引文件不存在，自动创建空索引: ${groupId}`)
+
+        const emptyIndex = {
+          version: '3.0.0',
+          files: [],
+          updateTime: Date.now(),
+        }
+
+        // 确保目录存在
+        const groupDir = path.join(this.groupsDir, groupId)
+        await fs.mkdir(groupDir, { recursive: true })
+
+        // 写入空索引
+        await this._writeJSON(indexFile, emptyIndex)
+
+        // 更新缓存
+        this.indexCache.set(groupId, { data: emptyIndex, time: Date.now() })
+
+        return emptyIndex
+      }
+
+      // 其他错误继续抛出
+      console.error(`[storage-v3] 读取索引失败: ${groupId}`, err)
+      throw err
+    }
+  }
+
+  /**
+   * 更新索引
+   */
+  async updateIndex(groupId, indexData) {
+    const indexFile = path.join(this.groupsDir, groupId, 'index.json')
+    const updated = {
+      ...indexData,
+      updateTime: Date.now(),
+    }
+
+    await this._writeJSON(indexFile, updated)
+
+    // 清除缓存
+    this.indexCache.delete(groupId)
+  }
+
+  /**
+   * 使索引失效（强制下次重新读取）
+   */
+  invalidateIndex(groupId) {
+    this.indexCache.delete(groupId)
+  }
+
+  /**
+   * 重建索引（扫描 files 目录）
+   */
+  async rebuildIndex(groupId) {
+    console.log(`[storage-v3] 开始重建组 ${groupId} 的索引...`)
+
+    const filesDir = path.join(this.groupsDir, groupId, 'files')
+
+    try {
+      const fileDirs = await fs.readdir(filesDir)
+      const index = {
+        version: '3.0.0',
+        files: [],
+        updateTime: Date.now(),
+      }
+
+      for (const fileId of fileDirs) {
+        if (fileId.includes('.backup')) continue // 跳过备份文件
+
+        const fileJsonPath = path.join(filesDir, fileId, 'file.json')
+
+        try {
+          const fileData = await fs.readFile(fileJsonPath, 'utf8')
+          const file = JSON.parse(fileData)
+
+          // 添加到索引
+          index.files.push({
+            id: file.id,
+            url: file.url,
+            method: file.method || 'GET',
+            status: file.status || 200,
+            size: this._calculateSize(file),
+            mock: file.config?.mock || false,
+            locked: file.config?.locked || false,
+            mockVersion: file.config?.mockVersion || 'source',
+            versionCount: 0, // TODO: 扫描 versions 目录
+            createTime: file.createTime,
+            updateTime: file.updateTime,
+          })
+
+          console.log(`[storage-v3] ✓ 添加文件: ${file.url}`)
+        } catch (err) {
+          console.warn(`[storage-v3] ✗ 跳过损坏的文件: ${fileId}`, err.message)
+        }
+      }
+
+      // 写入索引
+      await this.updateIndex(groupId, index)
+      console.log(`[storage-v3] 索引重建完成，共 ${index.files.length} 个文件`)
+
+      return index
+    } catch (err) {
+      console.error('[storage-v3] 重建索引失败:', err.message)
+      throw err
+    }
+  }
+
+  // ========================================
+  // 文件操作
+  // ========================================
+
+  /**
+   * 列出文件（从索引）
+   * @param {string} groupId - 组ID
+   * @param {object} options - 选项
+   * @param {number} options.offset - 偏移量
+   * @param {number} options.limit - 限制数量
+   * @param {object} options.filter - 过滤条件
+   */
+  async listFiles(groupId, options = {}) {
+    const { offset = 0, limit, filter = {} } = options
+
+    const index = await this.getIndex(groupId)
+    let files = index.files
+
+    // 应用过滤器
+    if (Object.keys(filter).length > 0) {
+      files = files.filter(file => {
+        return Object.entries(filter).every(([key, value]) => file[key] === value)
+      })
+    }
+
+    // 应用分页
+    if (limit) {
+      files = files.slice(offset, offset + limit)
+    } else if (offset > 0) {
+      files = files.slice(offset)
+    }
+
+    return files
+  }
+
+  /**
+   * 获取文件完整数据
+   * 如果文件损坏，返回 null 而不是抛出错误
+   */
+  async getFile(groupId, fileId) {
+    const fileJsonPath = path.join(this.groupsDir, groupId, 'files', fileId, 'file.json')
+
+    try {
+      const content = await fs.readFile(fileJsonPath, 'utf8')
+      return JSON.parse(content)
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        // 文件不存在
+        return null
+      }
+
+      // JSON 解析错误 - 文件损坏
+      if (err instanceof SyntaxError) {
+        console.error(`[storage-v3] 文件JSON损坏，跳过: ${groupId}/${fileId}`, err.message)
+        return null
+      }
+
+      // 其他错误继续抛出
+      throw err
+    }
+  }
+
+  /**
+   * 创建文件
+   */
+  async createFile(groupId, fileId, fileData) {
+    // 验证数据
+    const validation = this._validateJSON(fileData)
+    if (!validation.valid) {
+      const error = new Error(`Cannot store invalid JSON data: ${validation.error}`)
+      console.error(`[storage-v3] 创建文件失败: ${groupId}/${fileId}`, error.message)
+      throw error
+    }
+
+    const fileDir = path.join(this.groupsDir, groupId, 'files', fileId)
+    const versionsDir = path.join(fileDir, 'versions')
+
+    // 创建目录
+    await fs.mkdir(versionsDir, { recursive: true })
+
+    // 确保 config 字段存在
+    const config = fileData.config || {
+      mock: false,
+      locked: false,
+      mockVersion: 'source',
+      mockTime: null,
+    }
+
+    // 写入文件数据（只保留 config 字段，不保留根级别的配置字段）
+    const file = {
+      id: fileId,
+      url: fileData.url,
+      method: fileData.method || 'GET',
+      status: fileData.status || 200,
+      date: fileData.date || Date.now(),
+      rule: fileData.rule || '',
+      ruleValue: fileData.ruleValue || '',
+      pattern: fileData.pattern || '',
+      config,
+      createTime: Date.now(),
+      updateTime: Date.now(),
+    }
+
+    await this._writeJSON(path.join(fileDir, 'file.json'), file)
+
+    // 解析 URL 增强字段
+    const urlFields = this._parseUrlFields(fileData.url)
+
+    // 更新索引（包含增强字段）
+    await this._addToIndex(groupId, {
+      id: fileId,
+      url: fileData.url,
+      method: fileData.method || 'GET',
+      status: fileData.status || 200,
+      size: this._calculateSize(file),
+      mock: config.mock,
+      locked: config.locked,
+      mockVersion: config.mockVersion,
+      versionCount: 0,
+      createTime: file.createTime,
+      updateTime: file.updateTime,
+      // ✨ Phase 3.1: 索引增强字段
+      domain: urlFields.domain,
+      pathname: urlFields.pathname,
+      urlHash: urlFields.urlHash,
+    })
+
+    // 更新组统计
+    await this._updateGroupStats(groupId)
+
+    return file
+  }
+
+  /**
+   * 更新文件
+   * 如果原文件损坏或不存在，将 updates 作为新文件创建
+   */
+  async updateFile(groupId, fileId, updates) {
+    const file = await this.getFile(groupId, fileId)
+
+    // 🔧 FIX: 过滤掉 updates 中值为 undefined 的字段
+    // 这样可以支持删除字段的操作
+    const filteredUpdates = {}
+    Object.keys(updates).forEach(key => {
+      if (updates[key] !== undefined) {
+        filteredUpdates[key] = updates[key]
+      }
+    })
+
+    let updated
+    if (!file) {
+      // 原文件不存在或损坏，使用 updates 作为新文件
+      console.log(`[storage-v3] 原文件不存在或损坏，创建新文件: ${groupId}/${fileId}`)
+
+      // 确保 config 字段存在
+      const config = filteredUpdates.config || {
+        mock: false,
+        locked: false,
+        mockVersion: 'source',
+        mockTime: null,
+      }
+
+      updated = {
+        id: fileId,
+        ...filteredUpdates,
+        config,
+        createTime: Date.now(),
+        updateTime: Date.now(),
+      }
+    } else {
+      // 正常更新：深度合并 config 字段
+      const mergedConfig = {
+        ...file.config,
+        ...filteredUpdates.config,
+      }
+
+      updated = {
+        ...file,
+        ...filteredUpdates,
+        config: mergedConfig,
+        updateTime: Date.now(),
+      }
+
+      // 🔧 FIX: 从合并结果中删除 updates 里标记为 undefined 的字段
+      Object.keys(updates).forEach(key => {
+        if (updates[key] === undefined) {
+          delete updated[key]
+        }
+      })
+
+      // 清理根级别的重复配置字段（如果存在）
+      delete updated.mock
+      delete updated.locked
+      delete updated.mockVersion
+      delete updated.mockTime
+    }
+
+    // 验证更新后的数据
+    const validation = this._validateJSON(updated)
+    if (!validation.valid) {
+      const error = new Error(`Cannot store invalid JSON data: ${validation.error}`)
+      console.error(`[storage-v3] 更新文件失败: ${groupId}/${fileId}`, error.message)
+      throw error
+    }
+
+    const fileJsonPath = path.join(this.groupsDir, groupId, 'files', fileId, 'file.json')
+    await this._writeJSON(fileJsonPath, updated)
+
+    // 解析 URL 增强字段（如果 URL 发生变化）
+    const urlFields = updated.url ? this._parseUrlFields(updated.url) : {}
+
+    // 更新索引（包含增强字段）
+    await this._updateInIndex(groupId, fileId, {
+      url: updated.url,
+      method: updated.method,
+      status: updated.status,
+      size: this._calculateSize(updated),
+      mock: updated.config?.mock,
+      locked: updated.config?.locked,
+      mockVersion: updated.config?.mockVersion,
+      updateTime: updated.updateTime,
+      // ✨ Phase 3.1: 索引增强字段
+      ...(updated.url && {
+        domain: urlFields.domain,
+        pathname: urlFields.pathname,
+        urlHash: urlFields.urlHash,
+      }),
+    })
+
+    return updated
+  }
+
+  /**
+   * 删除文件
+   */
+  async deleteFile(groupId, fileId) {
+    const logFile = '/tmp/mockbubu-delete.log'
+    const log = (msg) => {
+      const fs = require('fs')
+      fs.appendFileSync(logFile, `${new Date().toISOString()} ${msg}\n`)
+    }
+
+    log('[storage-v3] deleteFile 开始')
+    log(`[storage-v3] groupId: ${groupId}`)
+    log(`[storage-v3] fileId: ${fileId}`)
+
+    const fileDir = path.join(this.groupsDir, groupId, 'files', fileId)
+    log(`[storage-v3] 要删除的目录: ${fileDir}`)
+
+    try {
+      await fs.rm(fileDir, { recursive: true, force: true })
+      log('[storage-v3] 物理文件删除成功')
+    } catch (err) {
+      log(`[storage-v3] 物理文件删除失败: ${err.message}`)
+      throw err
+    }
+
+    // 从索引中移除
+    try {
+      await this._removeFromIndex(groupId, fileId)
+      log('[storage-v3] 已从索引中移除')
+    } catch (err) {
+      log(`[storage-v3] 从索引移除失败: ${err.message}`)
+      throw err
+    }
+
+    // 更新组统计
+    try {
+      await this._updateGroupStats(groupId)
+      log('[storage-v3] 组统计已更新')
+    } catch (err) {
+      log(`[storage-v3] 更新组统计失败: ${err.message}`)
+      throw err
+    }
+  }
+
+  // ========================================
+  // Phase 3.2: 批量操作支持
+  // ========================================
+
+  /**
+   * 批量删除文件
+   * @param {string} groupId - 组ID
+   * @param {Array<string>} fileIds - 文件ID数组
+   * @returns {Promise<{success: number, failed: Array}>} 删除结果统计
+   */
+  async batchDeleteFiles(groupId, fileIds) {
+    console.log(`[storage-v3] 🗑️  批量删除开始: ${fileIds.length} 个文件`)
+
+    const results = {
+      success: 0,
+      failed: [],
+    }
+
+    // 并发删除文件（但保持索引操作的串行性）
+    await Promise.all(
+      fileIds.map(async fileId => {
+        try {
+          const fileDir = path.join(this.groupsDir, groupId, 'files', fileId)
+          await fs.rm(fileDir, { recursive: true, force: true })
+          results.success++
+        } catch (err) {
+          console.error(`[storage-v3] 删除文件失败: ${groupId}/${fileId}`, err.message)
+          results.failed.push({ fileId, error: err.message })
+        }
+      }),
+    )
+
+    // 批量从索引中移除（一次性更新索引）
+    try {
+      const release = await this._acquireIndexLock(groupId)
+      try {
+        this.invalidateIndex(groupId)
+        const index = await this.getIndex(groupId)
+
+        // 过滤掉已删除的文件
+        const initialCount = index.files.length
+        index.files = index.files.filter(f => !fileIds.includes(f.id))
+        const removedCount = initialCount - index.files.length
+
+        await this.updateIndex(groupId, index)
+        console.log(`[storage-v3] ✅ 从索引中移除 ${removedCount} 个文件`)
+      } finally {
+        this._releaseIndexLock(groupId, release)
+      }
+    } catch (err) {
+      console.error('[storage-v3] 批量更新索引失败:', err.message)
+    }
+
+    // 更新组统计
+    await this._updateGroupStats(groupId)
+
+    console.log(`[storage-v3] ✅ 批量删除完成: 成功 ${results.success}, 失败 ${results.failed.length}`)
+    return results
+  }
+
+  /**
+   * 批量更新文件（用于批量修改 config 等字段）
+   * @param {string} groupId - 组ID
+   * @param {Array<{fileId: string, updates: Object}>} updates - 更新数组
+   * @returns {Promise<{success: number, failed: Array}>} 更新结果统计
+   */
+  async batchUpdateFiles(groupId, updates) {
+    console.log(`[storage-v3] 📝 批量更新开始: ${updates.length} 个文件`)
+
+    const results = {
+      success: 0,
+      failed: [],
+    }
+
+    // 并发更新文件内容
+    await Promise.all(
+      updates.map(async ({ fileId, updates: fileUpdates }) => {
+        try {
+          // 读取现有文件
+          const file = await this.getFile(groupId, fileId)
+          if (!file) {
+            throw new Error('文件不存在')
+          }
+
+          // 合并更新
+          const updated = {
+            ...file,
+            ...fileUpdates,
+            config: {
+              ...file.config,
+              ...fileUpdates.config,
+            },
+            updateTime: Date.now(),
+          }
+
+          // 写入文件
+          const fileJsonPath = path.join(this.groupsDir, groupId, 'files', fileId, 'file.json')
+          await this._writeJSON(fileJsonPath, updated)
+
+          results.success++
+        } catch (err) {
+          console.error(`[storage-v3] 更新文件失败: ${groupId}/${fileId}`, err.message)
+          results.failed.push({ fileId, error: err.message })
+        }
+      }),
+    )
+
+    // 批量更新索引（一次性）
+    try {
+      const release = await this._acquireIndexLock(groupId)
+      try {
+        this.invalidateIndex(groupId)
+        const index = await this.getIndex(groupId)
+
+        // 更新索引中的相关字段
+        updates.forEach(({ fileId, updates: fileUpdates }) => {
+          const fileIndex = index.files.findIndex(f => f.id === fileId)
+          if (fileIndex !== -1) {
+            index.files[fileIndex] = {
+              ...index.files[fileIndex],
+              ...fileUpdates,
+              updateTime: Date.now(),
+            }
+          }
+        })
+
+        await this.updateIndex(groupId, index)
+        console.log('[storage-v3] ✅ 批量更新索引完成')
+      } finally {
+        this._releaseIndexLock(groupId, release)
+      }
+    } catch (err) {
+      console.error('[storage-v3] 批量更新索引失败:', err.message)
+    }
+
+    console.log(`[storage-v3] ✅ 批量更新完成: 成功 ${results.success}, 失败 ${results.failed.length}`)
+    return results
+  }
+
+  /**
+   * 文件是否存在
+   */
+  async fileExists(groupId, fileId) {
+    const fileJsonPath = path.join(this.groupsDir, groupId, 'files', fileId, 'file.json')
+    try {
+      await fs.access(fileJsonPath)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  // ========================================
+  // 版本管理
+  // ========================================
+
+  /**
+   * 列出版本
+   */
+  async listVersions(groupId, fileId) {
+    const versionsDir = path.join(this.groupsDir, groupId, 'files', fileId, 'versions')
+
+    try {
+      const entries = await fs.readdir(versionsDir)
+      const versions = []
+
+      for (const entry of entries) {
+        if (entry.endsWith('.json')) {
+          const versionId = entry.replace('.json', '')
+          const versionData = await this.getVersionById(groupId, fileId, versionId)
+          if (versionData) {
+            versions.push(versionData)
+          }
+        }
+      }
+
+      // 按创建时间降序排序(新版本在前)
+      return versions.sort((a, b) => (b.createTime || 0) - (a.createTime || 0))
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        return []
+      }
+      throw err
+    }
+  }
+
+  /**
+   * 通过版本ID获取版本
+   */
+  async getVersionById(groupId, fileId, versionId) {
+    const versionFile = path.join(this.groupsDir, groupId, 'files', fileId, 'versions', `${versionId}.json`)
+    try {
+      const content = await fs.readFile(versionFile, 'utf8')
+      return JSON.parse(content)
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        return null
+      }
+      throw err
+    }
+  }
+
+  /**
+   * 通过版本名称获取版本
+   */
+  async getVersionByName(groupId, fileId, versionName) {
+    const versions = await this.listVersions(groupId, fileId)
+    return versions.find(v => v.name === versionName)
+  }
+
+  /**
+   * 创建版本
+   * @param {string} versionName - 用户可见的版本名称
+   */
+  async createVersion(groupId, fileId, versionName, versionData) {
+    // 验证版本数据
+    const validation = this._validateJSON(versionData)
+    if (!validation.valid) {
+      const error = new Error(`Cannot store invalid JSON data: ${validation.error}`)
+      console.error(`[storage-v3] 创建版本失败: ${groupId}/${fileId}/${versionName}`, error.message)
+      throw error
+    }
+
+    // 检查版本名是否重复
+    const existingVersion = await this.getVersionByName(groupId, fileId, versionName)
+    if (existingVersion) {
+      throw new Error(`版本名称已存在: ${versionName}`)
+    }
+
+    const versionsDir = path.join(this.groupsDir, groupId, 'files', fileId, 'versions')
+    await fs.mkdir(versionsDir, { recursive: true })
+
+    // 生成唯一的版本ID
+    const versionId = this.generateFileId()
+
+    const version = {
+      id: versionId,
+      name: versionName,
+      ...versionData,
+      createTime: Date.now(),
+      updateTime: Date.now(),
+    }
+
+    const versionFile = path.join(versionsDir, `${versionId}.json`)
+    await this._writeJSON(versionFile, version)
+
+    // 更新索引中的版本计数
+    const versions = await this.listVersions(groupId, fileId)
+    await this._updateInIndex(groupId, fileId, {
+      versionCount: versions.length,
+    })
+
+    return version
+  }
+
+  /**
+   * 更新版本(通过版本ID)
+   */
+  async updateVersion(groupId, fileId, versionId, updates) {
+    const version = await this.getVersionById(groupId, fileId, versionId)
+    if (!version) {
+      throw new Error(`版本不存在: ${versionId}`)
+    }
+
+    // 如果要更新name,检查是否重复
+    if (updates.name && updates.name !== version.name) {
+      const existingVersion = await this.getVersionByName(groupId, fileId, updates.name)
+      if (existingVersion && existingVersion.id !== versionId) {
+        throw new Error(`版本名称已存在: ${updates.name}`)
+      }
+    }
+
+    const updatedVersion = {
+      ...version,
+      ...updates,
+      id: versionId, // 确保ID不被修改
+      updateTime: Date.now(),
+    }
+
+    const versionFile = path.join(this.groupsDir, groupId, 'files', fileId, 'versions', `${versionId}.json`)
+    await this._writeJSON(versionFile, updatedVersion)
+
+    return updatedVersion
+  }
+
+  /**
+   * 删除版本(通过版本ID)
+   */
+  async deleteVersion(groupId, fileId, versionId) {
+    const versionFile = path.join(this.groupsDir, groupId, 'files', fileId, 'versions', `${versionId}.json`)
+    await fs.unlink(versionFile)
+
+    // 更新索引中的版本计数
+    const versions = await this.listVersions(groupId, fileId)
+    await this._updateInIndex(groupId, fileId, {
+      versionCount: versions.length,
+    })
+  }
+
+  // ========================================
+  // 内部辅助方法
+  // ========================================
+
+  /**
+   * 获取当前组ID
+   */
+  async getCurrentGroupId() {
+    try {
+      const content = await fs.readFile(this.currentGroupFile, 'utf8')
+      return content.trim() || 'default'
+    } catch (err) {
+      // 文件不存在，返回默认值
+      return 'default'
+    }
+  }
+
+  /**
+   * 设置当前组ID
+   */
+  async setCurrentGroupId(groupId) {
+    await fs.writeFile(this.currentGroupFile, groupId, 'utf8')
+  }
+
+  /**
+   * 验证数据是否可以安全序列化为 JSON
+   * @param {*} data - 要验证的数据
+   * @returns {Object} { valid: boolean, error?: string }
+   */
+  _validateJSON(data) {
+    try {
+      const json = JSON.stringify(data)
+      JSON.parse(json)
+      return { valid: true }
+    } catch (err) {
+      return {
+        valid: false,
+        error: `Invalid JSON: ${err.message}`,
+      }
+    }
+  }
+
+  /**
+   * 写入JSON文件（原子操作）
+   * 使用临时文件+原子重命名模式，确保并发安全
+   */
+  async _writeJSON(filePath, data) {
+    // 确保目标目录存在
+    const dir = path.dirname(filePath)
+    await fs.mkdir(dir, { recursive: true })
+
+    // 生成唯一的临时文件名（时间戳 + 随机数）
+    const tmpPath = `${filePath}.tmp.${Date.now()}.${Math.random().toString(36).slice(2)}`
+
+    try {
+      // 写入临时文件
+      const content = JSON.stringify(data, null, 2)
+      await fs.writeFile(tmpPath, content, 'utf8')
+
+      // 原子重命名
+      await fs.rename(tmpPath, filePath)
+    } catch (err) {
+      // 清理临时文件
+      try {
+        await fs.unlink(tmpPath)
+      } catch (unlinkErr) {
+        // 忽略清理错误
+      }
+      throw err
+    }
+  }
+
+  /**
+   * 获取索引锁（基于 Promise 的互斥锁）
+   */
+  async _acquireIndexLock(groupId) {
+    while (this.indexLocks.has(groupId)) {
+      await this.indexLocks.get(groupId)
+    }
+    let resolve
+    const promise = new Promise(_resolve => { resolve = _resolve })
+    this.indexLocks.set(groupId, promise)
+    return resolve
+  }
+
+  /**
+   * 释放索引锁
+   */
+  _releaseIndexLock(groupId, resolve) {
+    this.indexLocks.delete(groupId)
+    resolve()
+  }
+
+  /**
+   * 添加到索引（带去重检查和并发保护）
+   */
+  async _addToIndex(groupId, fileEntry) {
+    const release = await this._acquireIndexLock(groupId)
+    try {
+      // ⚠️ 强制清除缓存，确保读取最新数据
+      this.invalidateIndex(groupId)
+      const index = await this.getIndex(groupId)
+
+      // 检查文件是否已存在索引中（防止并发重复添加）
+      const exists = index.files.some(f => f.id === fileEntry.id)
+      if (exists) {
+        console.log(`[storage-v3] 文件已在索引中，跳过添加: ${groupId}/${fileEntry.id}`)
+        return
+      }
+
+      index.files.push(fileEntry)
+      await this.updateIndex(groupId, index)
+    } finally {
+      this._releaseIndexLock(groupId, release)
+    }
+  }
+
+  /**
+   * 更新索引中的文件（带并发保护）
+   * 如果文件不在索引中，自动添加到索引
+   */
+  async _updateInIndex(groupId, fileId, updates) {
+    const release = await this._acquireIndexLock(groupId)
+    try {
+      // 强制清除缓存，确保读取最新数据
+      this.invalidateIndex(groupId)
+      const index = await this.getIndex(groupId)
+      const fileIndex = index.files.findIndex(f => f.id === fileId)
+
+      if (fileIndex !== -1) {
+        // 文件存在于索引，更新
+        index.files[fileIndex] = {
+          ...index.files[fileIndex],
+          ...updates,
+          updateTime: Date.now(),
+        }
+        await this.updateIndex(groupId, index)
+      } else {
+        // 文件不在索引中，添加到索引
+        console.log(`[storage-v3] 文件不在索引中，自动添加: ${groupId}/${fileId}`)
+        // 注意：这里已经持有锁，直接操作索引而不是递归调用 _addToIndex
+        const exists = index.files.some(f => f.id === fileId)
+        if (!exists) {
+          index.files.push({
+            id: fileId,
+            ...updates,
+            createTime: updates.createTime || Date.now(),
+            updateTime: updates.updateTime || Date.now(),
+          })
+          await this.updateIndex(groupId, index)
+        }
+      }
+    } finally {
+      this._releaseIndexLock(groupId, release)
+    }
+  }
+
+  /**
+   * 从索引中移除（带并发保护）
+   */
+  async _removeFromIndex(groupId, fileId) {
+    const release = await this._acquireIndexLock(groupId)
+    try {
+      this.invalidateIndex(groupId)
+      const index = await this.getIndex(groupId)
+      index.files = index.files.filter(f => f.id !== fileId)
+      await this.updateIndex(groupId, index)
+    } finally {
+      this._releaseIndexLock(groupId, release)
+    }
+  }
+
+  /**
+   * 更新组统计信息
+   */
+  async _updateGroupStats(groupId) {
+    const index = await this.getIndex(groupId)
+    const fileCount = index.files.length
+    const totalSize = index.files.reduce((sum, file) => sum + (file.size || 0), 0)
+
+    await this.updateGroup(groupId, { fileCount, totalSize })
+  }
+
+  /**
+   * 计算文件大小
+   */
+  _calculateSize(fileData) {
+    return Buffer.byteLength(JSON.stringify(fileData), 'utf8')
+  }
+
+  /**
+   * 解析 URL 并提取增强字段（domain、pathname、urlHash）
+   * @param {string} url - 完整的 URL
+   * @returns {Object} { domain, pathname, urlHash }
+   */
+  _parseUrlFields(url) {
+    try {
+      const urlObj = new URL(url)
+      const domain = urlObj.hostname || ''
+      const pathname = urlObj.pathname || '/'
+
+      // 生成 URL 哈希（用于快速查找）
+      const crypto = require('crypto')
+      const urlHash = crypto.createHash('md5').update(url).digest('hex').substring(0, 8)
+
+      return { domain, pathname, urlHash }
+    } catch (err) {
+      // URL 解析失败，返回默认值
+      console.warn(`[storage-v3] URL 解析失败: ${url}`, err.message)
+      return {
+        domain: '',
+        pathname: '',
+        urlHash: '',
+      }
+    }
+  }
+
+  // ========================================
+  // 通用属性操作（用于 api-list-updated 等全局标志）
+  // ========================================
+
+  /**
+   * 读取通用属性
+   */
+  async getGenericProperty(key) {
+    try {
+      // 每次都从文件读取,避免多进程/多实例缓存不一致
+      try {
+        const content = await fs.readFile(this.propertiesFile, 'utf8')
+        const properties = JSON.parse(content)
+        return properties[key]
+      } catch (err) {
+        // 文件不存在,返回 undefined
+        return undefined
+      }
+    } catch (err) {
+      return null
+    }
+  }
+
+  /**
+   * 设置通用属性
+   */
+  async setGenericProperty(key, value) {
+    try {
+      // 每次都从文件读取最新数据
+      let properties = {}
+      try {
+        const content = await fs.readFile(this.propertiesFile, 'utf8')
+        properties = JSON.parse(content)
+      } catch (err) {
+        // 文件不存在,使用空对象
+      }
+
+      // 更新属性
+      properties[key] = value
+
+      // 写回文件
+      await fs.writeFile(
+        this.propertiesFile,
+        JSON.stringify(properties, null, 2),
+        'utf8',
+      )
+    } catch (err) {
+      console.error('[storage-v3] setGenericProperty failed:', key, err.message)
+    }
+  }
+}
+
+module.exports = FileSystemStorage