@me-framework/me-sku-editor 1.0.1

package/document//345/274/200/345/217/221/346/214/207/345/215/227.md

@@ -0,0 +1,637 @@
+# 开发指南
+
+本指南面向需要对 SkuEditor 进行二次开发或修改的开发者。
+
+## 目录
+
+- [项目结构](#项目结构)
+- [核心模块说明](#核心模块说明)
+- [扩展开发](#扩展开发)
+- [样式定制](#样式定制)
+- [常见修改场景](#常见修改场景)
+
+---
+
+## 项目结构
+
+```
+src/
+├── components/              # 组件目录
+│   └── sku/               # SKU 相关组件
+│       ├── SkuEditor.vue      # 主编辑器组件
+│       ├── SpecSection.vue    # 规格管理区域
+│       ├── SkuGrid.vue        # SKU 表格区域
+│       └── dialogs/          # 对话框组件
+│           ├── SpecDialog.vue
+│           ├── AttrDialog.vue
+│           └── BatchEditDialog.vue
+├── composables/            # 组合式函数
+│   └── sku/               # SKU 相关逻辑
+│       ├── useSkuGenerator.ts  # SKU 生成逻辑
+│       ├── useImportExport.ts  # 导入导出逻辑
+│       ├── useSortable.ts      # 拖拽排序逻辑
+│       ├── useMergeCells.ts    # 单元格合并逻辑
+│       ├── useColumnVisibility.ts # 列可见性管理
+│       └── useValidation.ts    # 数据校验逻辑
+├── types/                  # 类型定义
+│   └── sku/               # SKU 相关类型
+│       ├── index.ts         # 类型导出入口
+│       ├── spec.ts          # 规格相关类型
+│       └── sku-row.ts       # SKU 行相关类型
+├── constants/              # 常量定义
+│   └── sku.ts             # SKU 相关常量
+├── App.vue                 # 示例应用
+└── main.ts                 # 入口文件
+```
+
+---
+
+## 核心模块说明
+
+### 1. SkuEditor.vue - 主组件
+
+**职责：**
+- 协调各子组件
+- 管理数据状态（外部模式为主）
+- 处理规格和属性的增删改
+- 暴露公共方法
+- 处理内部/外部格式转换
+
+**关键数据：**
+```typescript
+// 内部统一 SKU 数据源
+const internalSkuData = ref<SkuRow[]>([])
+
+// 同步数据到父组件
+const syncDataToParent = () => {
+  if (isUpdatingFromInside.value) return
+  isUpdatingFromInside.value = true
+  try {
+    const external = toExternalFormat(internalSkuData.value, specsRef.value)
+    emit('update:skuData', external)
+  } finally {
+    nextTick(() => {
+      isUpdatingFromInside.value = false
+    })
+  }
+}
+```
+
+**关键方法：**
+- `saveSpec()` - 保存规格
+- `deleteSpec()` - 删除规格
+- `saveAttr()` - 保存属性
+- `deleteAttr()` - 删除属性
+- `outputData()` - 输出数据到控制台
+- `validateSkuData()` - 校验 SKU 数据
+
+**暴露的方法：**
+```typescript
+defineExpose({
+  exportExcel,
+  exportJson,
+  confirmImport,
+  confirmImportExcel,
+  validateSkuData
+})
+```
+
+---
+
+### 2. SpecSection.vue - 规格管理区域
+
+**职责：**
+- 展示规格列表
+- 提供规格和属性的操作入口
+- 处理拖拽排序的 DOM 引用
+- 处理文件拖放
+
+**关键 Props：**
+```typescript
+interface Props {
+  specs: Spec[]
+}
+```
+
+**关键 Events：**
+```typescript
+interface Emits {
+  addSpec: []
+  editSpec: [spec: Spec]
+  deleteSpec: [spec: Spec]
+  addAttribute: [specId: string]
+  editAttribute: [spec: Spec, attr: SpecAttribute]
+  deleteAttribute: [spec: Spec, attr: SpecAttribute]
+  // ... 更多事件
+}
+```
+
+---
+
+### 3. SkuGrid.vue - SKU 表格区域
+
+**职责：**
+- 展示和编辑 SKU 数据
+- 处理单元格合并
+- 管理列可见性
+- 提供筛选功能
+- 支持行高亮配置
+
+**关键技术：**
+- 使用 VXE Table 组件
+- 动态生成列配置
+- 虚拟滚动支持
+
+---
+
+### 4. useSkuGenerator.ts - SKU 生成逻辑
+
+**核心函数：**
+
+#### generateSkuData(specs, existingData?)
+
+生成 SKU 组合的核心算法：
+
+1. 过滤掉没有属性的规格
+2. 计算笛卡尔积生成所有组合
+3. 保留已有数据中匹配的组合
+
+**笛卡尔积实现：**
+```typescript
+const cartesianProduct = (lists: any[][]): any[][] => {
+  return lists.reduce((a, b) =>
+    a.flatMap(x => b.map(y => [...x, y])),
+    [[]]
+  )
+}
+```
+
+**数据匹配逻辑：**
+```typescript
+// 使用规格ID和属性ID组合作为key
+const generateSkuKey = (specsMap: { [key: string]: string }): string => {
+  const sortedSpecIds = Object.keys(specsMap).sort()
+  return sortedSpecIds.map(specId => `${specId}:${specsMap[specId]}`).join('|')
+}
+```
+
+#### toInternalFormat(externalSkus, specs)
+
+将外部格式（使用规格名称和属性名称）转换为内部格式（使用 ID）。
+
+#### toExternalFormat(internalSkus, specs)
+
+将内部格式转换为外部格式。
+
+---
+
+### 5. useImportExport.ts - 导入导出逻辑
+
+**Excel 导出格式：**
+- Sheet 1：规格信息（规格序号、规格名称、规格类型、属性序号、属性名称、颜色、图片、内容）
+- Sheet 2：SKU 数据（规格列 + 固定列）
+
+**关键处理：**
+- 保留字段名冲突检查（使用 `RESERVED_NAMES` 常量）
+- 属性内容的 JSON 序列化/反序列化
+- 兼容仅含 SKU 数据的 Excel 导入
+
+---
+
+### 6. useSortable.ts - 拖拽排序逻辑
+
+基于 Sortable.js 实现：
+
+```typescript
+const initSpecSortable = () => {
+  specSortable = new Sortable(el, {
+    animation: 150,
+    handle: '.drag-handle',
+    onEnd: (evt) => { /* 处理排序 */ }
+  })
+}
+```
+
+**注意**：拖拽排序后会自动更新 `sort` 字段。
+
+---
+
+### 7. useValidation.ts - 数据校验逻辑
+
+**校验规则配置：**
+```typescript
+interface ValidationRules {
+  specs?: boolean              // 校验规格
+  skuNoDuplication?: boolean  // 校验 SKU 编号重复
+  requiredFields?: boolean    // 校验必填字段
+  numericValues?: boolean     // 校验数值合理性
+  custom?: (specs: any[], skuData: any[]) => ValidationItem[]
+}
+```
+
+**校验结果：**
+```typescript
+interface ValidationResult {
+  valid: boolean
+  items: ValidationItem[]  // 包含 error 和 warning 类型
+}
+```
+
+---
+
+## 扩展开发
+
+### 添加新的 SKU 字段
+
+#### 1. 修改类型定义
+
+在 `src/types/sku/sku-row.ts` 中添加字段：
+
+```typescript
+interface SkuRow {
+  // ... 现有字段
+  customField?: string  // 添加你的自定义字段
+}
+```
+
+#### 2. 更新 SkuGrid.vue
+
+添加列配置：
+
+```typescript
+const skuColumns = computed(() => {
+  const columns: VxeGridProps['columns'] = []
+
+  // ... 规格列
+
+  // 添加自定义列
+  columns.push({
+    field: 'customField',
+    title: '自定义字段',
+    width: 150,
+    visible: true,  // 或在 defaultColumnVisibility 中配置
+    slots: { default: 'customField' },
+    editRender: { name: 'VxeInput' }  // 可编辑
+  })
+
+  // ... 其他列
+  return columns
+})
+```
+
+添加模板插槽：
+
+```vue
+<template #customField="{ row }">
+  {{ row.customField || '-' }}
+</template>
+```
+
+#### 3. 更新 useImportExport.ts
+
+在导出和导入逻辑中添加对新字段的处理：
+
+```typescript
+// 导出时
+rowData['自定义字段'] = row.customField
+
+// 导入时
+tempSkuData.push({
+  // ... 其他字段
+  customField: row['自定义字段']
+})
+```
+
+#### 4. 更新默认列可见性（可选）
+
+在 `useColumnVisibility.ts` 中：
+
+```typescript
+export const defaultColumnVisibility: ColumnVisibilityState = {
+  specColumns: {},
+  fixedColumns: {
+    // ... 现有字段
+    customField: true  // 添加新字段
+  }
+}
+```
+
+#### 5. 更新批量编辑对话框（可选）
+
+在 `BatchEditDialog.vue` 中添加批量设置选项。
+
+#### 6. 更新数据校验（可选）
+
+在 `useValidation.ts` 中添加对新字段的校验。
+
+---
+
+### 添加新的规格类型
+
+#### 1. 修改类型定义
+
+在 `src/types/sku/spec.ts` 中：
+
+```typescript
+export type SpecType = 'text' | 'color' | 'image' | 'yourType'
+```
+
+#### 2. 更新 SpecSection.vue
+
+在属性展示区域添加新类型的渲染：
+
+```vue
+<div class="attr-tag-wrapper attr-drag-handle">
+  <!-- 已有类型 -->
+  <el-color-picker v-if="spec.type === 'color'" ... />
+  <el-image v-else-if="spec.type === 'image'" ... />
+
+  <!-- 新增类型 -->
+  <your-custom-component v-else-if="spec.type === 'yourType'" ... />
+
+  <el-tag ...>{{ attr.name }}</el-tag>
+</div>
+```
+
+#### 3. 更新类型标签显示
+
+在 `getSpecTypeLabel` 函数中：
+
+```typescript
+const getSpecTypeLabel = (type: SpecType) => {
+  const map: Record<SpecType, string> = {
+    text: '文字',
+    color: '颜色',
+    image: '图片',
+    yourType: '你的类型'  // 添加
+  }
+  return map[type] || type
+}
+```
+
+#### 4. 更新导入导出逻辑
+
+在 `useImportExport.ts` 中处理新类型的导入导出。
+
+---
+
+### 添加新的校验规则
+
+#### 1. 在 useValidation.ts 中添加校验逻辑
+
+```typescript
+// 在 validateSkuData 函数中添加
+if (rules.yourRule !== false) {
+  // 添加你的校验逻辑
+  const errors = validateYourRule(specs, skuData)
+  result.items.push(...errors)
+}
+```
+
+#### 2. 更新 ValidationRules 类型
+
+在 `src/types/sku/index.ts` 中：
+
+```typescript
+interface ValidationRules {
+  // ... 现有规则
+  yourRule?: boolean
+}
+```
+
+---
+
+### 添加新的导出格式
+
+#### 1. 在 useImportExport.ts 中添加函数
+
+```typescript
+const exportCSV = () => {
+  // 实现 CSV 导出逻辑
+}
+```
+
+#### 2. 在 SkuEditor.vue 中暴露方法
+
+```typescript
+defineExpose({
+  exportExcel,
+  exportJson,
+  exportCSV,  // 添加
+  confirmImport,
+  confirmImportExcel,
+  validateSkuData
+})
+```
+
+#### 3. 在 SpecSection.vue 中添加入口
+
+在工具栏的下拉菜单中添加选项。
+
+---
+
+## 样式定制
+
+### 使用 CSS 变量
+
+组件使用 Element Plus 的 CSS 变量，可以通过覆盖变量来定制主题：
+
+```css
+:root {
+  --el-color-primary: #your-color;
+  --el-border-radius-base: 8px;
+}
+```
+
+### 覆盖组件样式
+
+各组件都有独立的 scoped 样式，可以通过深度选择器覆盖：
+
+```css
+.sku-editor :deep(.some-class) {
+  /* 你的样式 */
+}
+```
+
+### 主要样式类名
+
+- `.sku-editor` - 主容器
+- `.spec-section` - 规格区域
+- `.sku-section` - SKU 表格区域
+- `.spec-item` - 单个规格项
+- `.attr-tag-wrapper` - 属性标签包装
+
+---
+
+## 常见修改场景
+
+### 1. 修改默认数据
+
+现在组件不再内置默认数据，需要在父组件中传入：
+
+```typescript
+// 在 App.vue 中
+const specs = ref<Spec[]>([
+  // 你的默认数据
+])
+const skuData = ref<SkuRow[]>(generateSkuData(specs.value))
+```
+
+### 2. 禁用某些功能
+
+注释或移除模板中的对应元素：
+
+```vue
+<!-- 移除批量编辑按钮 -->
+<!-- <template #toolbarTools>
+  <vxe-button ...>统一设置</vxe-button>
+</template> -->
+```
+
+### 3. 修改表格配置
+
+在 `SkuGrid.vue` 中修改 `skuGridOptions`：
+
+```typescript
+const skuGridOptions = reactive<VxeGridProps>({
+  border: true,
+  stripe: false,  // 改斑马线样式
+  resizable: true,
+  height: 700,    // 改高度
+  // ...
+})
+```
+
+### 4. 添加数据验证
+
+在保存前添加验证逻辑，或使用新的校验系统：
+
+```typescript
+// 方式 1：在保存时验证
+const saveSpec = (name: string, type: SpecType) => {
+  if (name.length > 20) {
+    ElMessage.error('规格名称不能超过20个字符')
+    return
+  }
+  // ... 原有逻辑
+}
+
+// 方式 2：使用校验系统
+const result = skuEditorRef.value?.validateSkuData({
+  custom: (specs, skuData) => {
+    // 你的自定义校验
+  }
+})
+```
+
+### 5. 修改 SKU 编号生成规则
+
+在 `generateSkuData` 函数中修改：
+
+```typescript
+// 原逻辑
+skuNo: remembered.skuNo || ''
+
+// 修改为你的规则（在父组件中处理）
+skuData.value.forEach((row, index) => {
+  if (!row.skuNo) {
+    row.skuNo = `PROD-${index + 1}`
+  }
+})
+```
+
+### 6. 修改保留字段名
+
+在 `src/constants/sku.ts` 中修改：
+
+```typescript
+export const RESERVED_NAMES: string[] = [
+  'SKU编号',
+  '销售价',
+  // ... 添加你的保留字段
+]
+```
+
+---
+
+## 调试技巧
+
+### 输出数据到控制台
+
+点击工具栏的"输出到控制台"按钮，或调用 `handlePrintData()` 方法，可以查看当前的规格和 SKU 数据。
+
+### 使用 Vue DevTools
+
+1. 安装 Vue DevTools 浏览器扩展
+2. 在组件树中选择 SkuEditor
+3. 查看和修改组件的状态
+
+### 监听数据变化
+
+在 `SkuEditor.vue` 中添加临时的 watch 调试：
+
+```typescript
+watch(specsRef, (newVal) => {
+  console.log('Specs changed:', newVal)
+}, { deep: true })
+
+watch(internalSkuData, (newVal) => {
+  console.log('SKU data changed:', newVal)
+}, { deep: true })
+```
+
+---
+
+## 性能优化建议
+
+### 1. 大量 SKU 数据时
+
+- 确保 VXE Table 的虚拟滚动开启（`virtualYConfig.enabled: true`）
+- 减少不必要的列显示
+- 避免在 `spanMethod` 中做复杂计算
+
+### 2. 频繁更新时
+
+- 使用 `watch` 的 `flush: 'post'` 选项
+- 防抖处理保存操作
+- 避免在渲染期间修改数据
+
+### 3. 导入大文件时
+
+- 添加加载状态提示
+- 考虑分片处理
+- 使用 Web Worker（需要额外配置）
+
+### 4. 数据校验时
+
+- 对于大数据量，考虑只在保存时校验
+- 可以只执行部分校验规则（如快速校验）
+
+---
+
+## 测试建议
+
+### 单元测试关注点
+
+- `useSkuGenerator.ts` - 测试 SKU 生成逻辑、数据转换
+- `useMergeCells.ts` - 测试单元格合并计算
+- `useValidation.ts` - 测试数据校验逻辑
+- 各种边界情况（空数据、单规格、多规格等）
+
+### 集成测试关注点
+
+- 完整的增删改流程
+- 导入导出功能
+- 数据保留功能
+- 拖拽排序功能
+- 数据校验功能
+
+---
+
+## 相关资源
+
+- [Vue 3 Composition API](https://cn.vuejs.org/guide/extras/composition-api-faq.html)
+- [Element Plus 组件](https://element-plus.org/)
+- [VXE Table 文档](https://vxetable.cn/)
+- [Sortable.js 文档](https://sortablejs.github.io/Sortable/)
+- [SheetJS (xlsx)](https://sheetjs.com/)