MeliBuilder.Knowledge.Mongo 1.1.13

MeliBuilder

把 1688 商品 JSON 转成 美客多（Mercado Libre）CBT 刊登报文。

设计主张一句话：以平台要求为准，反过来清洗我们的数据——先从类目属性接口编译出「这个类目要什么」，再拿着它回源数据里找材料。找不到就报缺口，绝不编造。

装

dotnet add package MeliBuilder
# 类目缓存放 Mongo 的才需要：
dotnet add package MeliBuilder.Knowledge.Mongo

主包零外部依赖。

用

using MeliBuilder;
using MeliBuilder.Contracts;

var builder = MeliListingBuilder.Create();          // 默认全带:公开类目接口 + 落盘缓存

var receipt = await builder.BuildAsync(new BuildTask
{
    CategoryId = "CBT416005",                        // 必须是**叶子**类目
    RawJson    = rawJsonFrom1688,
    Options    = new BuildOptions
    {
        Sites = { new SiteSell { SiteId = "MLM", LogisticType = "remote", NetProceeds = 21.40m } },
    },
}, ct);

类目知识默认是三层，不需要任何外部依赖：

CachingCategoryKnowledgeProvider   进程内字典 —— 省解析(78 个属性的 JSON)
        └ MeliCategoryApiProvider  公开接口 + 落盘缓存 —— 省外部调用，跨进程有效

批量刊登时同一类目会被问几百次，字典缓存让第 2 次起是 0 成本。Mongo 是可选的，只在你要读已有的 cbt_attribute_cache 时才装。

想换件只覆盖在意的那个，其余走默认：

var builder = MeliListingBuilder.Create(o =>
{
    o.CategoryCacheDir      = "meli-category-cache";  // 公开接口响应的落盘缓存
    o.CategoryDefaultsPath  = "category-defaults.json";  // 人工维护的类目默认值表
    o.Llm                   = new MyDeepSeekGateway(); // 不给 = Stub(低置信→走人工,不猜)
    o.SizeCharts            = new MySizeChartProvider(); // 不给 = 走两趟(回执给建表工单)
    o.Sources.Add(new JdAdapter());                   // 1688 已默认注册

    o.CacheCategoryKnowledge = true;                  // 默认就是 true
    o.CategoryCacheTtl = TimeSpan.FromHours(6);       // 长跑服务建议给,否则类目改版要重启
});

⚠ 长期运行的服务记得设 CategoryCacheTtl —— 不设就不过期（和落盘缓存同一套语义），平台类目改版之后要重启进程才生效。也可以自己拿 CachingCategoryKnowledgeProvider.Invalidate() 手工失效。

DI 宿主（主包不引 DI 抽象，保持零依赖，自己注册一行）：

services.AddSingleton<IMeliListingBuilder>(_ => MeliListingBuilder.Create(o => { /* … */ }));

回执怎么读

receipt.Success      // 报文产出来了(源数据缺字段不影响这个)
receipt.Publishable  // 能否直接发布 —— 没有 Blocking 缺口
receipt.Payloads     // 报文,直接序列化发给平台
receipt.Gaps         // 缺口:Blocking(必补) / Degraded(记账) / Informational
receipt.Decisions    // 每个字段的 原值 → 结果 → 依据 → 置信度
receipt.NeedsManual  // 人工选择题(带候选)
receipt.SizeChartDemand  // 强制尺码表的类目:建表工单(域 / 尺码行 / 性别)

Success 和 Publishable 是两件事：

1688 的数据经常对不上美客多，这时候什么都不给才是真没用——报文出来 + 缺口清单当待补清单，才有得改。

扩展点

包里现成的类目知识实现（MeliBuilder.Knowledge）：

全部通过 MeliListingBuilder.Create(o => …) 传入。工序、清洗器、中间模型都是 internal —— 它们是实现细节，不是 API。

尺码表：搜表/建表要卖家 token，不在引擎里做。不注入 ISizeChartProvider 时走两趟——回执给出 SizeChartDemand（要哪些尺码行、哪个域、什么性别），业务侧建完表把 BuildOptions.SizeChart 喂回来。

铁律

• 零授权调用——引擎只打公开接口（/categories/{id}、/categories/{id}/attributes、domain_discovery），不需要 access_token
• 不编造——编不出就报缺口。唯一例外是官方 hint 背书的那几个（无品牌 → Generic）
• 不硬猜——标题里同时命中两个枚举值就报人工，不取其一
• 全程记账——每个字段怎么来的都在 Decisions 里

打包与验包

pwsh scripts/pack.ps1                    # 先跑测试,再打两个包到 ./artifacts
pwsh scripts/verify-package.ps1          # 建临时消费方装本地包真跑一遍

pack.ps1 会打印每个包的 lib/ 内容和声明的依赖 —— 主包必须是「依赖: (无)」，出现别的就说明有外部依赖漏进来了。

verify-package.ps1 验三件事：

改版本号：pwsh scripts/pack.ps1 -Version 1.0.1 然后 pwsh scripts/verify-package.ps1 -Version 1.0.1。

发到私有源：

dotnet nuget push artifacts\*.nupkg --source <你的源> --api-key <key>

⚠ MeliBuilder.Knowledge.Mongo 依赖主包，先推主包再推它。

两个坑（脚本里已绕开）

• .ps1 里有中文必须存成 UTF-8 with BOM —— Windows PowerShell 5.1 否则按 ANSI 读，语法直接崩
• dotnet run / dotnet new 不认 --nologo，run 还会把它当程序参数传进去

文档

• docs/MeliBuilder-Template-Design.md — 设计定案（模板 + 清洗）
• docs/MeliBuilder-Responsibilities.md — 责任划分与扩展规则