yith-brand-migrator/品牌迁移指南.md

# YITH WooCommerce Brands Add-On 到 WooCommerce 原生品牌功能迁移指南

## 概述

本指南将帮助您将现有的 YITH WooCommerce Brands Add-On 数据迁移到 WooCommerce 9.4+ 的原生品牌功能。

## 数据结构分析

### YITH WooCommerce Brands Add-On 结构
- **分类法名称**: `yith_product_brand`
- **数据存储**: 使用标准 WordPress 分类法表
  - `wp_terms` - 品牌名称和别名
  - `wp_term_taxonomy` - 分类法类型和描述  
  - `wp_term_relationships` - 产品与品牌关联
  - `wp_termmeta` - 品牌元数据（logo、banner等）

### WooCommerce 原生品牌功能结构
- **分类法名称**: `product_brand`
- **数据存储**: 同样使用标准 WordPress 分类法表
- **兼容性**: 与现有 WooCommerce 架构完全集成

## 迁移方案

### 方案一：使用提供的 PHP 迁移脚本

1. **上传脚本**
   ```bash
   # 将 migrate-yith-brands.php 上传到 WordPress 根目录
   ```

2. **执行迁移**
   ```bash
   # 方法1：浏览器访问
   http://yoursite.com/migrate-yith-brands.php
   
   # 方法2：WP-CLI 执行
   wp eval-file migrate-yith-brands.php
   ```

3. **验证结果**
   - 检查 WooCommerce > 产品 > 品牌 页面
   - 确认品牌数据正确显示
   - 验证产品页面品牌关联

### 方案二：手动 SQL 迁移

```sql
-- 1. 更新分类法名称
UPDATE wp_term_taxonomy 
SET taxonomy = 'product_brand' 
WHERE taxonomy = 'yith_product_brand';

-- 2. 刷新 WordPress 缓存
-- 需要在 WordPress 后台或通过代码执行
```

### 方案三：使用 WP-CLI（推荐）

```bash
# 预览迁移（不执行实际操作）
wp eval-file wp-cli-migrate-brands.php --dry-run=true

# 执行迁移
wp eval-file wp-cli-migrate-brands.php

# 迁移并清理旧数据
wp eval-file wp-cli-migrate-brands.php --cleanup=true
```

## 迁移步骤详解

### 1. 备份数据库
```bash
# 使用 mysqldump 备份
mysqldump -u username -p database_name > backup_before_migration.sql

# 或使用 WP-CLI
wp db export backup_before_migration.sql
```

### 2. 检查当前品牌数据
```sql
-- 查看现有品牌数量
SELECT COUNT(*) FROM wp_term_taxonomy WHERE taxonomy = 'yith_product_brand';

-- 查看品牌名称
SELECT t.name, t.slug, tt.description, tt.count 
FROM wp_terms t 
JOIN wp_term_taxonomy tt ON t.term_id = tt.term_id 
WHERE tt.taxonomy = 'yith_product_brand';
```

### 3. 启用 WooCommerce 原生品牌功能

在 `functions.php` 中添加：
```php
// 启用 WooCommerce 原生品牌功能
add_action('init', function() {
    if (class_exists('WooCommerce')) {
        // 注册品牌分类法
        register_taxonomy('product_brand', 'product', [
            'labels' => [
                'name' => '品牌',
                'singular_name' => '品牌',
                'menu_name' => '品牌',
            ],
            'public' => true,
            'show_ui' => true,
            'show_in_menu' => true,
            'show_admin_column' => true,
            'hierarchical' => true,
            'rewrite' => ['slug' => 'product-brand'],
            'show_in_rest' => true,
        ]);
    }
});
```

### 4. 执行迁移

选择上述任一方案执行迁移。

### 5. 更新主题模板

如果主题中有自定义的品牌显示代码，需要更新：

```php
// 旧代码
$brands = get_the_terms($product_id, 'yith_product_brand');

// 新代码  
$brands = get_the_terms($product_id, 'product_brand');
```

### 6. 测试验证

- [ ] 品牌页面正常显示
- [ ] 产品页面品牌信息正确
- [ ] 品牌筛选功能正常
- [ ] 品牌 logo 和描述正确显示
- [ ] SEO URL 正常工作

## 注意事项

### 兼容性检查
- 确保 WooCommerce 版本 ≥ 9.4
- 检查主题是否支持原生品牌功能
- 验证相关插件兼容性

### 数据完整性
- 迁移前后品牌数量应一致
- 产品关联关系应保持不变
- 品牌元数据（logo、描述等）应完整迁移

### 性能优化
```php
// 迁移后清理缓存
wp_cache_flush();
delete_option('_transient_wc_attribute_taxonomies');
```

## 回滚方案

如果迁移出现问题，可以通过以下方式回滚：

```sql
-- 恢复原分类法名称
UPDATE wp_term_taxonomy 
SET taxonomy = 'yith_product_brand' 
WHERE taxonomy = 'product_brand';
```

或直接恢复数据库备份：
```bash
mysql -u username -p database_name < backup_before_migration.sql
```

## 常见问题

### Q: 迁移后品牌页面显示 404
**A**: 需要刷新固定链接设置
```bash
wp rewrite flush
```

### Q: 品牌 logo 丢失
**A**: 检查 termmeta 表中的元数据是否正确迁移
```sql
SELECT * FROM wp_termmeta WHERE meta_key LIKE '%brand%';
```

### Q: 产品页面不显示品牌
**A**: 检查主题模板是否使用了正确的分类法名称

## 后续维护

### 禁用 YITH 插件
迁移成功后，可以安全禁用 YITH WooCommerce Brands Add-On 插件。

### 清理旧数据
```sql
-- 删除旧的分类法数据（谨慎操作）
DELETE FROM wp_term_taxonomy WHERE taxonomy = 'yith_product_brand';
```

### 更新相关代码
检查并更新所有使用 `yith_product_brand` 的代码为 `product_brand`。

## 技术支持

如果在迁移过程中遇到问题，请：
1. 检查错误日志
2. 验证数据库连接
3. 确认权限设置
4. 联系技术支持团队