DyAttributeBuilders 1.0.6.6

DyAttributeBuilders

DyAttributeBuilders 是一个强大的 .NET 库，用于将 1688 商品数据自动转换为符合 MercadoLibre（美客多）官方规范的变体商品数据。该库提供了完整的商品变体构建、属性动态匹配、价格计算和拆分策略功能。

✨ 核心特性

🎯 主要功能

• 🔄 动态属性匹配：智能匹配 1688 商品属性到 MercadoLibre 标准属性
• 📦 变体自动构建：自动识别和构建商品变体（颜色、尺寸等）
• 💰 价格计算：支持多种价格公式和站点级别配置
• 🔀 拆分策略：支持合并、按规格拆分、完全拆分等多种模式
• ✅ 官方规范遵循：严格遵循 MercadoLibre 官方 API 规范
• 🌐 多站点支持：支持多个 MercadoLibre 站点（MLM、MCO、MLC、MLB、MLA 等）
• 📏 尺寸属性处理：自动处理包装尺寸（PACKAGE_LENGTH、PACKAGE_HEIGHT、PACKAGE_WEIGHT 等）并设置 value_struct
• 🌍 翻译支持：内置中文到英文的批量翻译功能

🎨 支持的拆分模式

1. MergeAll（合并所有）：将所有 SKU 合并到一个 listing，创建变体
2. SplitBySpecification（按规格拆分）：按指定规格（如颜色、尺码）拆分
3. SplitAll（完全拆分）：每个 SKU 创建一个独立的 listing

📦 安装

NuGet Package Manager

Install-Package DyAttributeBuilders

.NET CLI

dotnet add package DyAttributeBuilders

PackageReference

<PackageReference Include="DyAttributeBuilders" Version="1.0.3" />

🚀 快速开始

基本使用

using DyAttributeBuilders;
using Microsoft.Extensions.Logging;

// 1. 创建日志记录器
var loggerFactory = LoggerFactory.Create(builder => builder.AddConsole());
var logger = loggerFactory.CreateLogger<DyVariationBuilder>();

// 2. 创建服务实例（需要注入依赖）
var builder = new DyVariationBuilder(
    logger,
    loggerFactory,
    variationIdentifier,
    variationBuilder,
    itemComposer,
    priceCalculator,
    variationValidator,
    attributeMatcher,
    categoryAttributeService);

// 3. 准备 1688 商品数据
var aliProduct = new ProductData
{
    OfferId = 123456789,
    SubjectTrans = "Product Title",
    CategoryId = 1001,
    ProductSkuInfos = new List<SkuData> { /* SKU 数据 */ },
    ProductAttribute = new List<ProductAttribute> { /* 属性数据 */ },
    ProductShippingInfo = new ProductShippingInfo { /* 物流信息 */ }
};

// 4. 创建构建请求
var request = new DyVariationBuilderRequest
{
    AliProduct = aliProduct,
    CategoryId = "MLM1000", // MercadoLibre 类目 ID
    SplitMode = SpecificationSplitMode.MergeAll,
    CategorySupportedVariationIds = new HashSet<string> { "COLOR", "SIZE" },
    SiteIds = new List<string> { "MLM", "MCO", "MLC" }
};

// 5. 执行构建
var response = await builder.BuildAsync(request);

if (response.IsSuccess)
{
    // 获取生成的 MercadoLibre 商品列表
    foreach (var meliItem in response.MeliItems)
    {
        // 使用 meliItem 上传到 MercadoLibre
        Console.WriteLine($"商品标题: {meliItem.Title}");
        Console.WriteLine($"价格: {meliItem.Price}");
        Console.WriteLine($"变体数: {meliItem.Variations?.Count ?? 0}");
    }
}
else
{
    Console.WriteLine($"构建失败: {response.ErrorMessage}");
}

依赖注入配置

using DyAttributeBuilders;
using DyAttributeBuilders.Core;
using DyAttributeBuilders.Core.Services;
using DyAttributeBuilders.Interfaces;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

var services = new ServiceCollection();

// 添加日志（可选）
services.AddLogging(builder => builder.AddConsole());

// 添加 HttpClient（用于类目属性服务）
services.AddHttpClient();

// 【可选】启用库内日志（NuGet包默认完全禁用）
var serviceConfig = new ServiceCollectionBuilderRequest
{
    EnableLogging = true, // 设置为 true 启用调试日志，默认false（完全禁用）
    DeepSeekChatClientRequest = new DeepSeekChatClientRequest
    {
        DeepSeekApiKey = "your-api-key",
        DeepSeekSystemPrompt = "your-system-prompt"
    }
};

// 注册核心服务
services.DyAttributerBuilderService(serviceConfig);

var serviceProvider = services.BuildServiceProvider();
var builder = serviceProvider.GetRequiredService<IDyVariationBuilder>();

📦 NuGet包日志说明

NuGet包默认通过编译时条件完全禁用日志输出，不会产生任何日志污染。如需调试，请设置 EnableLogging = true。

📖 详细使用指南

1. 拆分模式示例

MergeAll（合并所有）

var request = new DyVariationBuilderRequest
{
    AliProduct = aliProduct,
    CategoryId = "MLM1000",
    SplitMode = SpecificationSplitMode.MergeAll
};
// 结果：所有 SKU 合并到一个 listing，创建变体

SplitBySpecification（按规格拆分）

var request = new DyVariationBuilderRequest
{
    AliProduct = aliProduct,
    CategoryId = "MLM1000",
    SplitMode = SpecificationSplitMode.SplitBySpecification,
    SelectedSpecifications = new List<string> { "颜色" } // 按颜色拆分
};
// 结果：相同颜色的不同尺寸合并到一个 listing

SplitAll（完全拆分）

var request = new DyVariationBuilderRequest
{
    AliProduct = aliProduct,
    CategoryId = "MLM1000",
    SplitMode = SpecificationSplitMode.SplitAll
};
// 结果：每个 SKU 创建一个独立的 listing

2. 价格配置

var priceConfig = new PriceFormulaConfig
{
    SiteId = "MLM",
    FormulaType = PriceFormulaType.New,
    CurrencyRate = 7.0m,
    MinPrice = 5.0m,
    ShippingThreshold = 10.0m,
    FixedFee = 9m,
    DiscountRate = 0.9m * 0.9m * 0.92m
};

var request = new DyVariationBuilderRequest
{
    AliProduct = aliProduct,
    CategoryId = "MLM1000",
    PriceConfig = priceConfig
};

3. 变体配置

var variationConfig = new VariationConfig
{
    MaxVariationCount = 99,
    MaxStock = 99000,
    MaxTitleLength = 60,
    AllowCustomVariations = true,
    ExcludeAttributeNames = new List<string> { "Brand" }
};

var request = new DyVariationBuilderRequest
{
    AliProduct = aliProduct,
    CategoryId = "MLM1000",
    VariationConfig = variationConfig
};

🏗️ 架构设计

核心模块

DyAttributeBuilders/
├── Interfaces/              # 接口定义
│   ├── IDyVariationBuilder.cs
│   ├── IVariationIdentifier.cs
│   ├── IVariationBuilder.cs
│   ├── IItemComposer.cs
│   ├── IDynamicAttributeMatcher.cs
│   └── IMeliCategoryAttributeService.cs
├── Core/                    # 核心实现
│   ├── DyVariationBuilder.cs
│   ├── VariationIdentifier.cs
│   ├── VariationBuilder.cs
│   ├── ItemComposer.cs
│   ├── DynamicAttributeMatcher.cs
│   └── Services/
│       ├── MeliCategoryAttributeService.cs
│       └── AttributeMappingService.cs
├── Configuration/           # 配置模型
│   ├── SpecificationSplitMode.cs
│   ├── VariationConfig.cs
│   └── PriceFormulaConfig.cs
└── Validation/              # 验证逻辑
    └── VariationValidator.cs

📋 MercadoLibre 规范遵循

✅ 变体规则

• ✅ 所有变体的价格必须相同：自动使用最高价格统一所有变体
• ✅ 每个变体必须有 attribute_combinations：确保每个变体都有有效的属性组合
• ✅ 所有变体的 attribute_combinations 必须包含相同的属性：确保属性结构一致
• ✅ 避免属性冲突：确保属性不在父商品和变体中重复
• ✅ 优先使用标准变体属性：COLOR、SIZE、PATTERN_NAME 等
• ✅ 变体属性设置 value_struct：自动为 PACKAGE_* 等属性设置正确的 value_struct

✅ 属性规则

• ✅ 动态属性匹配：智能匹配 1688 属性到 MercadoLibre 标准属性
• ✅ 必填属性填充：自动填充缺失的必填属性
• ✅ 属性去重：自动去除重复属性
• ✅ 尺寸属性处理：从 1688 物流信息中提取并设置包装尺寸

🔧 配置选项

DyVariationBuilderRequest 参数说明

📚 依赖项

• .NET 9.0 或更高版本
• Microsoft.Extensions.Logging.Abstractions (9.0.0)
• Microsoft.Extensions.DependencyInjection (9.0.0)
• Microsoft.Extensions.Http (9.0.0)
• Newtonsoft.Json (13.0.3)
• RestSharp (113.0.0)

🎯 使用场景

1. 1688 商品导入 MercadoLibre：批量导入 1688 商品到 MercadoLibre
2. 变体商品管理：自动创建和管理变体商品
3. 多站点发布：同时发布到多个 MercadoLibre 站点
4. 价格计算：自动计算符合各站点要求的价格
5. 属性标准化：自动将 1688 属性转换为 MercadoLibre 标准属性

⚠️ 注意事项

1. 类目 ID 必填：必须提供有效的 MercadoLibre 类目 ID
2. 类目属性支持：在使用标准变体属性前，需要检查类目是否支持
3. 变体数量限制：MercadoLibre 有变体数量上限（默认 99）
4. 库存限制：MercadoLibre 有库存上限（默认 99000）
5. 价格精度：USD 货币的价格只能有 2 位小数
6. 属性冲突：确保属性不在父商品和变体中重复
7. 日志控制：NuGet包默认完全禁用日志输出（通过编译时条件），不会污染消费者应用的日志。如需启用调试日志，请在注册服务时设置 EnableLogging = true。

🔄 版本历史

1.0.3 (当前版本)

• ✅ 修复变体属性 value_struct 设置问题
• ✅ 修复属性冲突问题（有变体时不在父商品中添加某些属性）
• ✅ 支持从 1688 物流信息中提取并设置包装尺寸
• ✅ 改进属性匹配逻辑
• ✅ 添加批量翻译功能

1.0.2

• ✅ 实现动态属性匹配
• ✅ 实现变体构建（基于官方文档）
• ✅ 实现价格计算（策略模式）
• ✅ 实现商品组合

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

📞 支持

如有问题或建议，请通过以下方式联系：

• 提交 Issue
• 发送邮件至：support@mercadocommerce.com

Made with ❤️ by MercadoCommerce