@me-framework/me-sku-editor 1.0.1

package/document//344/275/277/347/224/250/346/226/207/346/241/243.md

@@ -0,0 +1,1028 @@
+# SkuEditor 使用文档
+
+## 目录
+
+- [组件简介](#组件简介)
+- [功能特性](#功能特性)
+- [快速开始](#快速开始)
+- [组件 API](#组件-api)
+- [数据格式](#数据格式)
+- [工具函数](#工具函数)
+- [数据校验](#数据校验)
+- [高级用法](#高级用法)
+- [常见问题](#常见问题)
+
+---
+
+## 组件简介
+
+SkuEditor 是一个功能强大的 Vue 3 商品规格 SKU 编辑器组件，支持多规格管理、智能 SKU 组合生成、数据导入导出等功能。
+
+### 核心特点
+
+- 支持内部数据管理和外部数据控制两种模式
+- 自动生成 SKU 组合并保留已有数据
+- 支持 Excel 和 JSON 格式的导入导出
+- 拖拽排序、批量编辑、列可见性自定义
+- 内置完整的数据校验系统
+
+---
+
+## 功能特性
+
+### 1. 规格管理
+
+- 支持三种规格类型：**文字**、**颜色**、**图片**
+- 规格可拖拽排序
+- 支持规格的增删改操作
+- 每个规格可包含多个属性值
+
+### 2. 属性管理
+
+- 属性支持名称、颜色值、图片值、扩展内容
+- 属性可拖拽排序
+- 颜色类型规格可直接选择颜色
+- 图片类型规格支持图片预览
+
+### 3. SKU 表格
+
+- 自动生成所有规格组合的 SKU
+- 智能单元格合并显示
+- 支持列筛选和自定义列可见性
+- 支持单元格直接编辑
+- 虚拟滚动支持大量数据
+- 行高亮配置支持
+
+### 4. 数据导入导出
+
+- 导出为 Excel 文件（含规格信息和 SKU 数据两个 Sheet）
+- 导出为 JSON 文件（完整数据格式）
+- 从 Excel 导入数据
+- 从 JSON 导入数据
+- 支持拖拽文件导入
+
+### 5. 批量编辑
+
+- 统一设置多个 SKU 的属性
+- 支持设置：销售价、市场价、成本价、重量、体积、状态、步长、起购数、限购数
+
+### 6. 数据校验
+
+- **规格校验**：校验规格数据完整性
+- **SKU 编号重复校验**：编辑时自动校验重复
+- **必填字段校验**：校验关键字段
+- **数值合理性校验**：校验数值范围
+- **自定义校验**：支持自定义校验函数
+- **错误和警告分级**：支持 error 和 warning 两种级别
+
+---
+
+## 快速开始
+
+### 安装依赖
+
+```bash
+npm install
+```
+
+### 基础用法 - 内部管理模式
+
+组件内部自动管理数据，适合简单场景：
+
+```vue
+<template>
+  <SkuEditor />
+</template>
+
+<script setup lang="ts">
+import SkuEditor from './components/sku/SkuEditor.vue'
+</script>
+```
+
+### 进阶用法 - 外部控制模式
+
+父组件控制数据，适合需要自定义数据处理的场景：
+
+```vue
+<template>
+  <div>
+    <div class="demo-info">
+      <p>当前规格数量：{{ specs.length }}</p>
+      <p>当前SKU数量：{{ skuData.length }}</p>
+    </div>
+    <SkuEditor
+      v-model:specs="specs"
+      v-model:sku-data="skuData"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import SkuEditor from './components/sku/SkuEditor.vue'
+import type { Spec, SkuRow } from './types/sku'
+import { generateSkuData, toInternalFormat } from './composables/sku/useSkuGenerator'
+
+// 初始化规格数据
+const specs = ref<Spec[]>([
+  {
+    id: 'spec-1',
+    name: '颜色',
+    type: 'color',
+    sort: 0,
+    attributes: [
+      { id: 'attr-1-1', name: '红色', color: '#ff0000', image: '', sort: 0, content: '' },
+      { id: 'attr-1-2', name: '蓝色', color: '#0000ff', image: '', sort: 1, content: '' }
+    ]
+  },
+  {
+    id: 'spec-2',
+    name: '尺码',
+    type: 'text',
+    sort: 1,
+    attributes: [
+      { id: 'attr-2-1', name: 'S', color: '', image: '', sort: 0, content: '' },
+      { id: 'attr-2-2', name: 'M', color: '', image: '', sort: 1, content: '' },
+      { id: 'attr-2-3', name: 'L', color: '', image: '', sort: 2, content: '' }
+    ]
+  }
+])
+
+// 生成初始 SKU 数据
+const skuData = ref<SkuRow[]>(generateSkuData(specs.value))
+</script>
+```
+
+### 使用外部格式数据
+
+推荐使用 `spec_json` 格式（规格名称和属性名称），组件内部会自动转换：
+
+```vue
+<template>
+  <SkuEditor
+    v-model:specs="specs"
+    v-model:sku-data="skuData"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import SkuEditor from './components/sku/SkuEditor.vue'
+import type { Spec, SkuRow } from './types/sku'
+import { generateSkuData, toInternalFormat } from './composables/sku/useSkuGenerator'
+
+// 规格数据
+const specs = ref<Spec[]>([
+  {
+    id: 'spec-1',
+    name: '颜色',
+    type: 'color',
+    sort: 0,
+    attributes: [
+      { id: 'attr-1-1', name: '冠军金', color: '#FFD700', image: '', sort: 0, content: '' },
+      { id: 'attr-1-2', name: '荣耀红', color: '#DC143C', image: '', sort: 1, content: '' },
+      { id: 'attr-1-3', name: '星空蓝', color: '#1E90FF', image: '', sort: 2, content: '' }
+    ]
+  },
+  {
+    id: 'spec-2',
+    name: '尺码',
+    type: 'text',
+    sort: 1,
+    attributes: [
+      { id: 'attr-2-1', name: 'S', color: '', image: '', sort: 0, content: '' },
+      { id: 'attr-2-2', name: 'M', color: '', image: '', sort: 1, content: '' },
+      { id: 'attr-2-3', name: 'L', color: '', image: '', sort: 2, content: '' }
+    ]
+  },
+  {
+    id: 'spec-3',
+    name: '款式',
+    type: 'text',
+    sort: 2,
+    attributes: [
+      { id: 'attr-3-1', name: '球迷版', color: '', image: '', sort: 0, content: '' },
+      { id: 'attr-3-2', name: '球员版', color: '', image: '', sort: 1, content: '' }
+    ]
+  }
+])
+
+// 使用 spec_json 格式的 SKU 数据（使用名称而非 ID，推荐用于存储）
+const externalSkus: SkuRow[] = [
+  {
+    spec_json: { '颜色': '冠军金', '尺码': 'S', '款式': '球迷版' },
+    skuNo: 'WC2026-JER-GOLD-S-FAN',
+    skuName: '2026世界杯球衣 冠军金 S码 球迷版',
+    salePrice: 599,
+    marketPrice: 799,
+    costPrice: 299,
+    weight: 0.3,
+    status: 1,
+    sort: 1,
+    step: 1,
+    minBuyLimit: 1,
+    maxBuyLimit: 10
+  },
+  {
+    spec_json: { '颜色': '荣耀红', '尺码': 'M', '款式': '球员版' },
+    skuNo: 'WC2026-JER-RED-M-PRO',
+    skuName: '2026世界杯球衣 荣耀红 M码 球员版',
+    salePrice: 899,
+    marketPrice: 1199,
+    costPrice: 499,
+    weight: 0.25,
+    status: 1,
+    sort: 2,
+    step: 1,
+    minBuyLimit: 1,
+    maxBuyLimit: 5
+  }
+]
+
+// 转换为内部格式并生成完整 SKU 数据
+const internalSkus = toInternalFormat(externalSkus, specs.value)
+const skuData = ref<SkuRow[]>(generateSkuData(specs.value, internalSkus))
+</script>
+```
+
+---
+
+## 组件 API
+
+### SkuEditor Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| specs | 规格列表（外部数据模式时使用） | `Spec[]` | - |
+| skuData | SKU 数据列表（外部数据模式时使用，推荐使用 spec_json 格式） | `SkuRow[]` | - |
+| validationRules | 校验规则配置 | `ValidationRules` | - |
+
+### SkuEditor Events
+
+| 事件名 | 说明 | 回调参数 |
+|--------|------|----------|
+| update:specs | 规格数据更新时触发 | `(value: Spec[]) => void` |
+| update:skuData | SKU 数据更新时触发 | `(value: SkuRow[]) => void` |
+
+### SkuEditor Exposed Methods
+
+通过 `ref` 可以调用组件的以下方法：
+
+| 方法名 | 说明 | 参数 |
+|--------|------|------|
+| exportExcel | 导出 Excel 文件 | - |
+| exportJson | 导出 JSON 文件 | - |
+| confirmImport | 确认导入（会弹出文件选择器） | `(type: 'json' \| 'excel') => void` |
+| confirmImportExcel | 确认导入 Excel | - |
+| validateSkuData | 校验所有 SKU 数据 | `(rules?: ValidationRules) => ValidationResult` |
+
+#### 示例 - 导出数据
+
+```vue
+<template>
+  <div>
+    <SkuEditor ref="skuEditorRef" />
+    <button @click="exportData">导出数据</button>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import SkuEditor from './components/sku/SkuEditor.vue'
+
+const skuEditorRef = ref<InstanceType<typeof SkuEditor>>()
+
+const exportData = () => {
+  skuEditorRef.value?.exportExcel()
+}
+</script>
+```
+
+#### 示例 - 数据校验
+
+```vue
+<template>
+  <div>
+    <SkuEditor
+      ref="skuEditorRef"
+      v-model:specs="specs"
+      v-model:sku-data="skuData"
+      :validation-rules="validationRules"
+    />
+    <div class="actions">
+      <button @click="validateAndSave" type="primary">保存</button>
+      <button @click="quickValidate">快速校验</button>
+    </div>
+    <div v-if="validationResults.length > 0" class="validation-results">
+      <h3>校验结果：</h3>
+      <div
+        v-for="(item, index) in validationResults"
+        :key="index"
+        class="validation-item"
+        :class="item.type"
+      >
+        <span>{{ item.message }}</span>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { ElMessage } from 'element-plus'
+import { CircleCheck, CircleClose, Warning } from '@element-plus/icons-vue'
+import SkuEditor from './components/sku/SkuEditor.vue'
+import type { Spec, SkuRow, ValidationItem, ValidationRules } from './types/sku'
+
+const skuEditorRef = ref<InstanceType<typeof SkuEditor>>()
+const specs = ref<Spec[]>([])
+const skuData = ref<SkuRow[]>([])
+const validationResults = ref<ValidationItem[]>([])
+
+// 配置校验规则
+const validationRules: ValidationRules = {
+  specs: true,
+  skuNoDuplication: true,
+  requiredFields: true,
+  numericValues: true,
+  custom: (_specs: Spec[], skuData: SkuRow[]) => {
+    const customItems: ValidationItem[] = []
+    skuData.forEach((row: SkuRow, index: number) => {
+      if (row.salePrice && row.costPrice && row.costPrice > row.salePrice * 0.9) {
+        customItems.push({
+          type: 'warning',
+          message: `第${index + 1}行：成本价接近销售价，利润空间较小`
+        })
+      }
+    })
+    return customItems
+  }
+}
+
+// 完整校验并保存
+const validateAndSave = () => {
+  const result = skuEditorRef.value?.validateSkuData()
+
+  if (!result) {
+    ElMessage.error('无法获取校验结果')
+    return
+  }
+
+  validationResults.value = result.items
+
+  if (!result.valid) {
+    const errorCount = result.items.filter((item: ValidationItem) => item.type === 'error').length
+    const warningCount = result.items.filter((item: ValidationItem) => item.type === 'warning').length
+    ElMessage.error(`校验发现${errorCount}个错误${warningCount > 0 ? `，${warningCount}个警告` : ''}`)
+    return
+  }
+
+  if (result.items.length > 0) {
+    ElMessage.warning(`校验通过，但有${result.items.length}个警告`)
+  } else {
+    ElMessage.success('数据校验通过')
+  }
+
+  // 校验通过，执行保存逻辑
+  saveToBackend()
+}
+
+// 快速校验（不校验数值范围）
+const quickValidate = () => {
+  const result = skuEditorRef.value?.validateSkuData({
+    specs: true,
+    skuNoDuplication: true,
+    requiredFields: true,
+    numericValues: false
+  })
+
+  if (!result) return
+
+  validationResults.value = result.items
+
+  if (result.valid) {
+    ElMessage.success('快速校验通过')
+  } else {
+    ElMessage.error('快速校验发现问题')
+  }
+}
+
+// 保存到后端
+const saveToBackend = () => {
+  // 在这里实现保存逻辑
+  ElMessage.success('保存成功')
+}
+</script>
+
+<style scoped>
+.actions {
+  margin: 16px 0;
+  gap: 12px;
+  display: flex;
+}
+
+.validation-results {
+  margin-top: 16px;
+}
+
+.validation-item {
+  padding: 12px;
+  border-radius: 4px;
+  margin-bottom: 8px;
+}
+
+.validation-item.error {
+  background-color: #fef0f0;
+  border: 1px solid #fde2e2;
+  color: #f56c6c;
+}
+
+.validation-item.warning {
+  background-color: #fdf6ec;
+  border: 1px solid #faecd8;
+  color: #e6a23c;
+}
+</style>
+```
+
+---
+
+## 数据格式
+
+### 类型定义位置
+
+- 类型定义统一在 `src/types/sku/` 目录下
+- 主入口：`src/types/sku/index.ts`
+- 规格类型：`src/types/sku/spec.ts`
+- SKU 行类型：`src/types/sku/sku-row.ts`
+
+### Spec（规格）
+
+```typescript
+interface Spec {
+  id: string              // 规格唯一标识
+  name: string            // 规格名称，如"颜色"、"尺码"
+  type: SpecType          // 规格类型：'text' | 'color' | 'image'
+  sort: number            // 排序序号
+  attributes: SpecAttribute[]  // 属性列表
+}
+```
+
+### SpecAttribute（规格属性）
+
+```typescript
+interface SpecAttribute {
+  id: string              // 属性唯一标识
+  name: string            // 属性名称，如"红色"、"S"
+  color: string           // 颜色值（颜色类型规格使用），如"#ff0000"
+  image: string           // 图片 URL（图片类型规格使用）
+  sort: number            // 排序序号
+  content: AttributeValue | string  // 扩展内容，可以是字符串或对象
+}
+```
+
+### SkuRow（SKU 行数据）
+
+```typescript
+interface SkuRow {
+  id?: string
+  // 内部格式：规格 ID → 属性 ID（组件内部使用）
+  specs?: { [specId: string]: string }
+  // 外部格式：规格名称 → 属性名称（推荐用于存储和展示）
+  spec_json?: { [specName: string]: string }
+  skuNo?: string
+  skuName?: string
+  image?: string
+  salePrice?: number
+  marketPrice?: number
+  costPrice?: number
+  weight?: number
+  volume?: number
+  barcode?: string
+  status?: number
+  sort?: number
+  step?: number
+  minBuyLimit?: number
+  maxBuyLimit?: number
+  _X_ROW_KEY?: string
+}
+```
+
+**数据格式说明**：
+
+- **外部格式（推荐）**：使用 `spec_json` 字段，键是规格名称，值是属性名称，适合存储和后端交互
+- **内部格式**：使用 `specs` 字段，键是规格 ID，值是属性 ID，组件内部使用
+- 组件会自动在两种格式之间转换，传入和传出都使用外部格式
+
+### ValidationRules（校验规则）
+
+```typescript
+interface ValidationRules {
+  /** 是否校验规格数据 */
+  specs?: boolean
+  /** 是否校验SKU编号重复 */
+  skuNoDuplication?: boolean
+  /** 是否校验必填字段 */
+  requiredFields?: boolean
+  /** 是否校验数值合理性 */
+  numericValues?: boolean
+  /** 自定义校验函数 */
+  custom?: (specs: any[], skuData: any[]) => ValidationItem[]
+}
+```
+
+### ValidationResult（校验结果）
+
+```typescript
+interface ValidationResult {
+  valid: boolean
+  items: ValidationItem[]
+}
+
+interface ValidationItem {
+  type: 'error' | 'warning'
+  message: string
+}
+```
+
+---
+
+## 工具函数
+
+### useSkuGenerator 相关函数
+
+位置：`src/composables/sku/useSkuGenerator.ts`
+
+#### generateId()
+
+生成 UUID v4 格式的唯一 ID。
+
+```typescript
+import { generateId } from './composables/sku/useSkuGenerator'
+
+const id = generateId()
+// 输出类似："xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx"
+```
+
+#### generateSkuData(specs, existingData?)
+
+根据规格生成 SKU 组合数据，可保留已有数据。
+
+```typescript
+import { generateSkuData } from './composables/sku/useSkuGenerator'
+
+// 仅传入规格，生成全新的 SKU 数据
+const skuData = generateSkuData(specs)
+
+// 传入已有数据，保留匹配的 SKU 信息
+const skuData = generateSkuData(specs, existingData)
+```
+
+**参数**：
+- `specs: Spec[]` - 规格列表
+- `existingData?: SkuRow[]` - 已有 SKU 数据（可选）
+
+**返回值**：
+- `SkuRow[]` - 生成的完整 SKU 数据
+
+#### toInternalFormat(externalSkus, specs)
+
+将外部格式（名称）转换为内部格式（ID）。
+
+```typescript
+import { toInternalFormat } from './composables/sku/useSkuGenerator'
+
+const internalSkus = toInternalFormat(externalSkus, specs)
+```
+
+**参数**：
+- `externalSkus: SkuRow[]` - 使用 spec_json 格式的 SKU 列表
+- `specs: Spec[]` - 规格列表
+
+**返回值**：
+- `SkuRow[]` - 转换后的内部格式 SKU 列表
+
+#### toExternalFormat(internalSkus, specs)
+
+将内部格式（ID）转换为外部格式（名称）。
+
+```typescript
+import { toExternalFormat } from './composables/sku/useSkuGenerator'
+
+const externalSkus = toExternalFormat(internalSkus, specs)
+```
+
+**参数**：
+- `internalSkus: SkuRow[]` - 内部格式 SKU 列表
+- `specs: Spec[]` - 规格列表
+
+**返回值**：
+- `SkuRow[]` - 转换后的外部格式 SKU 列表（含 spec_json）
+
+**兼容性别名**（仍可用，推荐使用新名称）：
+- `convertCompatibleToInternal` = `toInternalFormat`
+- `convertInternalToCompatible` = `toExternalFormat`
+
+### useImportExport 相关函数
+
+位置：`src/composables/sku/useImportExport.ts`
+
+通过 `useImportExport` 可以获取导入导出功能：
+
+```typescript
+import { useImportExport } from './composables/sku/useImportExport'
+
+const {
+  exportExcel,    // 导出 Excel
+  exportJson,     // 导出 JSON
+  confirmImport,  // 确认导入
+  handleDropFile  // 处理拖拽文件
+} = useImportExport(specs, skuData, skuGridRef, onDataUpdate)
+```
+
+### useColumnVisibility
+
+位置：`src/composables/sku/useColumnVisibility.ts`
+
+管理表格列的可见性状态：
+
+```typescript
+import { useColumnVisibility, defaultColumnVisibility } from './composables/sku/useColumnVisibility'
+
+const { columnVisibility, saveColumnVisibility } = useColumnVisibility(specs, skuGridRef)
+```
+
+### useMergeCells
+
+位置：`src/composables/sku/useMergeCells.ts`
+
+提供 SKU 表格的单元格合并功能：
+
+```typescript
+import { useMergeCells } from './composables/sku/useMergeCells'
+
+const { spanMethod } = useMergeCells(specs)
+```
+
+### useSortable
+
+位置：`src/composables/sku/useSortable.ts`
+
+提供规格和属性的拖拽排序功能：
+
+```typescript
+import { useSortable } from './composables/sku/useSortable'
+
+const { initSpecSortable, initAttrSortable } = useSortable(
+  specs,
+  specListRef,
+  attrListRefs,
+  (newSpecs) => {
+    // 规格变化时的回调
+    console.log('Specs updated:', newSpecs)
+  }
+)
+```
+
+### useValidation
+
+位置：`src/composables/sku/useValidation.ts`
+
+提供数据校验功能：
+
+```typescript
+import { useValidation } from './composables/sku/useValidation'
+
+const { validateSkuData } = useValidation()
+
+const result = validateSkuData(specs, skuData, rules)
+console.log(result.valid)       // 是否通过
+console.log(result.items)       // 校验结果列表
+```
+
+---
+
+## 数据校验
+
+### 内置校验项
+
+1. **规格校验**（`specs`）
+   - 检查规格是否有名称
+   - 检查规格的属性是否有名称
+
+2. **SKU 编号重复校验**（`skuNoDuplication`）
+   - 检查非空的 SKU 编号是否重复
+
+3. **必填字段校验**（`requiredFields`）
+   - 检查 SKU 名称是否为空
+
+4. **数值合理性校验**（`numericValues`）
+   - 检查销售价是否 ≥ 0
+   - 检查市场价是否 ≥ 0
+   - 检查成本价是否 ≥ 0
+   - 检查重量是否 ≥ 0
+   - 检查体积是否 ≥ 0
+   - 检查步长是否 ≥ 1
+   - 检查起购数是否 ≥ 1
+   - 检查限购数是否 ≥ 0
+
+### 自定义校验
+
+通过 `custom` 函数添加自定义校验：
+
+```typescript
+const validationRules: ValidationRules = {
+  custom: (specs: Spec[], skuData: SkuRow[]) => {
+    const items: ValidationItem[] = []
+
+    skuData.forEach((row, index) => {
+      // 检查利润空间
+      if (row.salePrice && row.costPrice) {
+        const profit = row.salePrice - row.costPrice
+        if (profit < 10) {
+          items.push({
+            type: 'warning',
+            message: `第${index + 1}行：利润空间较小（${profit}元）`
+          })
+        }
+      }
+
+      // 检查状态
+      if (row.status !== 1 && row.salePrice > 0) {
+        items.push({
+          type: 'warning',
+          message: `第${index + 1}行：SKU已下架但设置了销售价`
+        })
+      }
+    })
+
+    return items
+  }
+}
+```
+
+---
+
+## 高级用法
+
+### 监听数据变化
+
+```vue
+<script setup lang="ts">
+import { ref, watch } from 'vue'
+import SkuEditor from './components/sku/SkuEditor.vue'
+import type { Spec, SkuRow } from './types/sku'
+
+const specs = ref<Spec[]>([])
+const skuData = ref<SkuRow[]>([])
+
+// 监听规格变化
+watch(specs, (newSpecs) => {
+  console.log('规格数据已更新:', newSpecs)
+  // 可以在这里保存到后端
+}, { deep: true })
+
+// 监听 SKU 数据变化
+watch(skuData, (newSkuData) => {
+  console.log('SKU 数据已更新:', newSkuData)
+  // 可以在这里保存到后端
+}, { deep: true })
+</script>
+
+<template>
+  <SkuEditor
+    v-model:specs="specs"
+    v-model:sku-data="skuData"
+  />
+</template>
+```
+
+### 保存到后端示例
+
+```vue
+<script setup lang="ts">
+import { ref, watch } from 'vue'
+import { ElMessage } from 'element-plus'
+import SkuEditor from './components/sku/SkuEditor.vue'
+import type { Spec, SkuRow } from './types/sku'
+import { generateSkuData, toExternalFormat } from './composables/sku/useSkuGenerator'
+
+const specs = ref<Spec[]>([])
+const skuData = ref<SkuRow[]>([])
+
+// 防抖保存
+let saveTimer: ReturnType<typeof setTimeout> | null = null
+const saveToBackend = async () => {
+  if (saveTimer) clearTimeout(saveTimer)
+
+  saveTimer = setTimeout(async () => {
+    try {
+      // 转换为外部格式保存到后端
+      const externalSkus = toExternalFormat(skuData.value, specs.value)
+
+      // 发送到后端
+      await fetch('/api/save-sku', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          specs: specs.value,
+          skus: externalSkus
+        })
+      })
+
+      ElMessage.success('保存成功')
+    } catch (error) {
+      ElMessage.error('保存失败')
+    }
+  }, 500)
+}
+
+// 监听数据变化自动保存
+watch([specs, skuData], saveToBackend, { deep: true })
+</script>
+
+<template>
+  <SkuEditor
+    v-model:specs="specs"
+    v-model:sku-data="skuData"
+  />
+</template>
+```
+
+### 从后端加载数据并初始化
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+import SkuEditor from './components/sku/SkuEditor.vue'
+import type { Spec, SkuRow } from './types/sku'
+import { generateSkuData, toInternalFormat } from './composables/sku/useSkuGenerator'
+
+const specs = ref<Spec[]>([])
+const skuData = ref<SkuRow[]>([])
+
+// 从后端加载数据
+onMounted(async () => {
+  try {
+    const response = await fetch('/api/get-sku')
+    const data = await response.json()
+
+    specs.value = data.specs
+
+    // 将后端返回的外部格式（spec_json）转换为内部格式
+    const internalSkus = toInternalFormat(data.skus, data.specs)
+    // 生成完整的 SKU 数据（保留已有数据）
+    skuData.value = generateSkuData(data.specs, internalSkus)
+  } catch (error) {
+    console.error('加载数据失败:', error)
+  }
+})
+</script>
+
+<template>
+  <SkuEditor
+    v-model:specs="specs"
+    v-model:sku-data="skuData"
+  />
+</template>
+```
+
+---
+
+## Excel 文件格式
+
+### Sheet 1：规格信息
+
+| 规格序号 | 规格名称 | 规格类型 | 属性序号 | 属性名称 | 颜色 | 图片 | 内容 |
+|---------|---------|---------|---------|---------|------|------|------|
+| 1 | 颜色 | 颜色 | 1 | 红色 | #ff0000 | | |
+| 1 | 颜色 | 颜色 | 2 | 蓝色 | #0000ff | | |
+| 2 | 尺码 | 文字 | 1 | S | | | |
+| 2 | 尺码 | 文字 | 2 | M | | | |
+
+### Sheet 2：SKU 数据
+
+| 颜色 | 尺码 | SKU编号 | 销售价 | 市场价 | 成本价 | 重量 | 体积 | 条形码 | 状态 | 步长 | 起购数 | 限购数 |
+|------|------|---------|--------|--------|--------|------|------|--------|------|------|--------|--------|
+| 红色 | S | SKU001 | 99 | 199 | 50 | 0.1 | | | 1 | 1 | 1 | 0 |
+| 红色 | M | SKU002 | 99 | 199 | 50 | 0.12 | | | 1 | 1 | 1 | 0 |
+| 蓝色 | S | SKU003 | 99 | 199 | 50 | 0.1 | | | 1 | 1 | 1 | 0 |
+
+**注意**：
+- 规格列名会根据实际的规格名称动态生成
+- 系统保留字段名不能用作规格名称：`SKU编号`、`销售价`、`市场价`、`成本价`、`重量`、`体积`、`条形码`、`状态`、`步长`、`起购数`、`限购数`
+
+---
+
+## 常见问题
+
+### 1. 如何修改默认列可见性？
+
+修改 `src/composables/sku/useColumnVisibility.ts` 中的 `defaultColumnVisibility`：
+
+```typescript
+export const defaultColumnVisibility: ColumnVisibilityState = {
+  specColumns: {},
+  fixedColumns: {
+    skuNo: true,
+    salePrice: true,
+    marketPrice: true,
+    costPrice: true,
+    weight: true,  // 修改为 true 默认显示
+    volume: false,
+    barcode: false,
+    status: true,   // 修改为 true 默认显示
+    step: false,
+    minBuyLimit: false,
+    maxBuyLimit: false
+  }
+}
+```
+
+### 2. 添加新的规格时如何自动生成默认属性？
+
+在 `SkuEditor.vue` 的 `saveSpec` 方法中修改，或在添加规格后手动添加属性。
+
+### 3. 如何自定义 SKU 表格的高度？
+
+修改 `SkuGrid.vue` 中的表格配置，或通过 CSS 调整。
+
+### 4. 规格名称与保留字段冲突怎么办？
+
+系统会检查并提示规格名称不能使用保留字段，请使用其他名称。
+
+保留字段列表：`SKU编号`、`销售价`、`市场价`、`成本价`、`重量`、`体积`、`条形码`、`状态`、`步长`、`起购数`、`限购数`
+
+保留字段定义在 `src/constants/sku.ts`：
+
+```typescript
+export const RESERVED_NAMES: string[] = [
+  'SKU编号',
+  '销售价',
+  '市场价',
+  '成本价',
+  '重量',
+  '体积',
+  '条形码',
+  '状态',
+  '步长',
+  '起购数',
+  '限购数'
+]
+```
+
+### 5. 如何在导入时保留自定义的扩展字段？
+
+需要修改 `useImportExport.ts` 中的导入导出逻辑，在解析和生成数据时包含自定义字段。
+
+### 6. 修改规格时如何保留已编辑的 SKU 数据？
+
+组件已内置此功能。`generateSkuData` 函数会自动保留与新规格组合匹配的已有 SKU 数据。
+
+### 7. 支持多少个规格和属性？
+
+理论上没有硬性限制，但建议规格不超过 5 个，每个规格的属性不超过 10 个，否则 SKU 组合数量会呈指数级增长。
+
+例如：3个规格，每个有 5 个属性，会生成 5×5×5 = 125 个 SKU。
+
+### 8. 如何禁用拖拽排序功能？
+
+可以在 `SkuEditor.vue` 中注释掉 `useSortable` 相关的代码，或者移除模板中的拖拽手柄元素。
+
+### 9. specs 和 spec_json 有什么区别？
+
+- **specs**：内部格式，使用规格 ID 和属性 ID，组件内部使用
+- **spec_json**：外部格式，使用规格名称和属性名称，推荐用于存储和后端交互
+
+推荐始终使用 `spec_json` 格式与组件交互，组件会自动处理转换。
+
+### 10. 如何实现行高亮？
+
+`SkuGrid` 组件已支持行配置属性，可以通过自定义逻辑实现高亮。需要修改 `SkuGrid.vue` 中的行样式逻辑。
+
+### 11. 拖拽排序后 sort 字段会自动更新吗？
+
+会的。无论是规格还是属性，拖拽排序后都会自动更新对应的 `sort` 字段值，确保数据与显示顺序一致。
+
+---
+
+## 技术栈
+
+- **Vue 3** - 渐进式 JavaScript 框架
+- **TypeScript** - JavaScript 的超集，提供类型安全
+- **Element Plus** - Vue 3 组件库
+- **VXE Table** - 功能强大的 Vue 表格组件
+- **XLSX** - Excel 文件处理库
+- **Sortable.js** - 拖拽排序库
+- **Vite** - 下一代前端构建工具
+
+---
+
+## 相关链接
+
+- [项目 README](../README.md)
+- [快速开始指南](./快速开始.md)
+- [开发指南](./开发指南.md)
+- [Vue 3 文档](https://cn.vuejs.org/)
+- [Element Plus 文档](https://element-plus.org/)
+- [VXE Table 文档](https://vxetable.cn/)