@seeed-studio/solution-cli 0.4.5 → 0.4.7

package/lib/knowledge.js

@@ -125,7 +125,7 @@ export function loadClientConfig() {
 
 const SUPPORTED_LOCALES = new Set(['en', 'zh', 'ja']);
 const HUB_TYPES = new Set(['scenario', 'tech', 'reference_design']);
-const HUB_SECTIONS = new Set(['overview', 'links', 'description', 'architecture', 'products', 'deployment', 'playbook', 'integration']);
+const HUB_SECTIONS = new Set(['overview', 'links', 'description', 'architecture', 'products', 'deployment', 'playbook', 'integration', 'cases']);
 
 function levenshteinDistance(s1, s2) {
   const m = s1.length;
@@ -262,6 +262,12 @@ export function computeSectionCapabilities(record, rowType, core = null) {
     section_status.integration = isCustomContract ? 'documented' : 'inferred';
   }
 
+  const hasCases = rowType === 'scenario' || rowType === 'tech' || Boolean(record?.cases?.length || record?.cases_count);
+  if (hasCases) {
+    available_sections.push('cases');
+    section_status.cases = 'documented';
+  }
+
   return { available_sections, section_status };
 }
 
@@ -645,6 +651,14 @@ function populateSectionData(row, section, record, rowType, loc, selected, conte
       guideText: guideDoc?.body || '',
     });
     row.integration = contract;
+  } else if (section === 'cases') {
+    row.cases = {
+      items: [],
+      availability: 'unavailable',
+      source: 'bundled_manifest',
+      content_locale: null,
+      fallback: false,
+    };
   } else if (section === 'overview') {
     row.links = { landing: row.landing_urls, wiki: record.wiki_url || null, repo: record.repo_url || null };
     row.description = { content_locale: summary.locale, fallback: summary.locale !== null && summary.locale !== loc, source_role: 'summary', summary: summary.value || '' };
@@ -671,7 +685,11 @@ export function getHubRecord(id, { type = null, locale = 'zh', section = null, s
   } else {
     requestedSections = ['overview'];
   }
-  requestedSections = requestedSections.map((s) => s.trim().toLowerCase()).filter(Boolean);
+  requestedSections = requestedSections
+    .map((s) => s.trim().toLowerCase())
+    .map((s) => s === 'stories' ? 'cases' : s)
+    .filter(Boolean);
+  requestedSections = Array.from(new Set(requestedSections));
   if (requestedSections.length === 0) requestedSections = ['overview'];
 
   for (const sec of requestedSections) {
@@ -711,6 +729,339 @@ export function getHubRecord(id, { type = null, locale = 'zh', section = null, s
   return row;
 }
 
+/**
+ * Asynchronously fetches success cases / customer stories for a scenario from Typesense.
+ *
+ * @param {string} scenarioId
+ * @param {Object} options
+ * @param {'zh' | 'en' | 'ja'} [options.locale='zh']
+ * @param {number} [options.limit=10]
+ * @returns {Promise<Object>}
+ */
+export async function fetchCasesForScenario(scenarioId, { locale = 'zh', limit = 10 } = {}) {
+  const loc = normalizeLocale(locale);
+  const locKey = loc === 'zh' ? 'zh_hans' : loc;
+
+  if (process.env.SENSECRAFT_OFFLINE_ONLY) {
+    return {
+      items: [],
+      availability: 'unavailable',
+      source: 'bundled_manifest',
+      content_locale: null,
+      fallback: false,
+    };
+  }
+
+  const clientConfig = loadClientConfig();
+  const host = process.env.TYPESENSE_HOST || clientConfig?.typesense?.host || 'https://rel-search.seeedstudio.com';
+  const keyCases = process.env.TYPESENSE_SEARCH_KEY_CC_SUCCESS_CASES || process.env.TYPESENSE_SEARCH_KEY_SUCCESS_CASE || clientConfig?.typesense?.search_key_cc_success_cases;
+  const keySolution = process.env.TYPESENSE_SEARCH_KEY_SOLUTION || process.env.TYPESENSE_SEARCH_KEY || clientConfig?.typesense?.search_key_solution;
+
+  const items = [];
+  const seenSlugs = new Set();
+  const fetchErrors = [];
+
+  try {
+    const promises = [];
+
+    // 1. Fetch from cc_success_cases collection by solution_ids
+    if (keyCases) {
+      const casesFilter = `solution_ids:[=${scenarioId}] && published:true`;
+      const casesUrl = `${host}/collections/cc_success_cases/documents/search?q=*&filter_by=${encodeURIComponent(casesFilter)}&per_page=${limit}`;
+      promises.push(
+        fetchJson(casesUrl, { 'X-TYPESENSE-API-KEY': keyCases }, 2500)
+          .then((res) => ({ type: 'cc_cases', hits: res?.hits || [] }))
+          .catch((err) => {
+            fetchErrors.push(`cc_success_cases: ${err.message}`);
+            return { type: 'cc_cases', hits: [] };
+          })
+      );
+    }
+
+    // 2. Fetch from Solution collection to parse related_posts
+    if (keySolution) {
+      const solUrl = `${host}/collections/Solution/documents/search?q=*&filter_by=id:=${encodeURIComponent(scenarioId)}&per_page=1`;
+      promises.push(
+        fetchJson(solUrl, { 'X-TYPESENSE-API-KEY': keySolution }, 2500)
+          .then((res) => ({ type: 'solution_doc', hits: res?.hits || [] }))
+          .catch((err) => {
+            fetchErrors.push(`Solution related_posts: ${err.message}`);
+            return { type: 'solution_doc', hits: [] };
+          })
+      );
+    }
+
+    const results = await Promise.all(promises);
+
+    for (const res of results) {
+      if (res.type === 'cc_cases') {
+        for (const hit of res.hits) {
+          const doc = hit.document || {};
+          const slug = doc.slug_zh_hans || doc.slug_en || doc.id || doc.pid;
+          if (!slug || seenSlugs.has(slug)) continue;
+          seenSlugs.add(slug);
+
+          const titleText = onlineLocalizedText(doc, loc, {
+            en: ['title_en'], zh: ['title_zh_hans'], ja: ['title_ja'],
+          });
+          const excerptText = onlineLocalizedText(doc, loc, {
+            en: ['excerpt_en'], zh: ['excerpt_zh_hans'], ja: ['excerpt_ja'],
+          });
+
+          // URL safety check: verify absolute http(s) URL without speculative guessing
+          let url = null;
+          const candidateUrl = doc[`url_${locKey}`] || doc.url_en || doc.url_zh_hans;
+          if (candidateUrl && typeof candidateUrl === 'string' && /^https?:\/\//i.test(candidateUrl)) {
+            url = appendUtm(candidateUrl, {
+              source: 'sensecraft_agent',
+              medium: 'solution_consult',
+              campaign: scenarioId,
+              content: 'success_case',
+            });
+          }
+
+          items.push({
+            id: doc.id || doc.pid,
+            title: titleText.value || doc.title_zh_hans || doc.title_en || slug,
+            description: excerptText.value || doc.excerpt_zh_hans || doc.excerpt_en || '',
+            hardware: doc.hardware || [],
+            family_ids: doc.family_ids || [],
+            industry: doc.industry || [],
+            region: doc.region || [],
+            image: doc.cover_image || null,
+            case_slug: slug,
+            url,
+            content_locale: titleText.locale || loc,
+            fallback: Boolean(titleText.locale && titleText.locale !== loc),
+          });
+        }
+      } else if (res.type === 'solution_doc') {
+        const doc = res.hits?.[0]?.document || {};
+        try {
+          const pData = JSON.parse(doc[`page_data_${locKey}`] || doc.page_data_zh_hans || doc.page_data_en || '{}');
+          const posts = pData.related_posts?.list || [];
+          if (Array.isArray(posts)) {
+            for (const p of posts) {
+              const slug = p.case || String(p.id);
+              if (!slug || seenSlugs.has(slug)) continue;
+              seenSlugs.add(slug);
+
+              let url = null;
+              if (p.url && typeof p.url === 'string' && /^https?:\/\//i.test(p.url)) {
+                url = appendUtm(p.url, {
+                  source: 'sensecraft_agent',
+                  medium: 'solution_consult',
+                  campaign: scenarioId,
+                  content: 'success_case',
+                });
+              }
+
+              items.push({
+                id: String(p.id || slug),
+                title: p.title || slug,
+                description: p.description || '',
+                hardware: [],
+                family_ids: [],
+                industry: [],
+                region: [],
+                image: p.image || null,
+                case_slug: slug,
+                url,
+                content_locale: loc,
+                fallback: false,
+              });
+            }
+          }
+        } catch (_) {}
+      }
+    }
+
+    const hasErrors = fetchErrors.length > 0;
+    const isUnavailable = items.length === 0 && hasErrors;
+
+    return {
+      items,
+      availability: items.length > 0 ? 'available' : (isUnavailable ? 'unavailable' : 'empty'),
+      source: items.length > 0 ? 'typesense' : 'bundled_manifest',
+      content_locale: items.length > 0 ? loc : null,
+      fallback: false,
+      warning: isUnavailable ? `Failed to query online success cases: ${fetchErrors.join('; ')}` : null,
+    };
+  } catch (err) {
+    return {
+      items: [],
+      availability: 'unavailable',
+      source: 'bundled_manifest',
+      content_locale: null,
+      fallback: false,
+      warning: `Failed to fetch online cases for ${scenarioId}: ${err.message}`,
+    };
+  }
+}
+
+/**
+ * Asynchronous orchestrator for getHubRecord that enriches dynamic online sections (e.g. cases).
+ *
+ * @param {string} id
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+export async function getHubRecordAsync(id, options = {}) {
+  const row = getHubRecord(id, options);
+  if (!row) return null;
+
+  const loc = normalizeLocale(options.locale || 'zh');
+  let requestedSections = [];
+  if (options.sections) {
+    if (Array.isArray(options.sections)) requestedSections = options.sections.flatMap((s) => String(s).split(','));
+    else if (typeof options.sections === 'string') requestedSections = options.sections.split(',');
+  } else if (options.section) {
+    requestedSections = String(options.section).split(',');
+  } else {
+    requestedSections = ['overview'];
+  }
+  requestedSections = requestedSections.map((s) => s.trim().toLowerCase()).map((s) => s === 'stories' ? 'cases' : s);
+
+  if (requestedSections.includes('cases')) {
+    const casesRes = await fetchCasesForScenario(id, { locale: loc, limit: 10 });
+    row.cases = casesRes;
+    if (casesRes.warning) {
+      row.warnings = row.warnings || [];
+      row.warnings.push(casesRes.warning);
+    }
+    if (casesRes.items && casesRes.items.length > 0) {
+      row.section_status = row.section_status || {};
+      row.section_status.cases = 'documented';
+      if (!row.available_sections?.includes('cases')) {
+        row.available_sections = [...(row.available_sections || []), 'cases'];
+      }
+    }
+  }
+
+  return row;
+}
+
+/**
+ * Asynchronously retrieves a single success case / customer story in detail, including full body_md.
+ *
+ * @param {string} caseIdOrSlug - Case ID, numeric PID, or localized slug
+ * @param {Object} [options]
+ * @param {'zh' | 'en' | 'ja'} [options.locale='zh']
+ * @returns {Promise<Object>} Catalog DTO with case record
+ */
+export async function getCaseRecord(caseIdOrSlug, { locale = 'zh' } = {}) {
+  const loc = normalizeLocale(locale);
+  const locKey = loc === 'zh' ? 'zh_hans' : loc;
+
+  if (!caseIdOrSlug || typeof caseIdOrSlug !== 'string' || !caseIdOrSlug.trim()) {
+    throw new Error('Case ID or slug must be a non-empty string.');
+  }
+  const cleanTarget = caseIdOrSlug.trim();
+
+  if (process.env.SENSECRAFT_OFFLINE_ONLY) {
+    return createCatalogDto({
+      source: 'bundled_manifest',
+      freshness: 'UNKNOWN',
+      records: [],
+      warnings: [`Offline mode enabled (SENSECRAFT_OFFLINE_ONLY=1). Success case details require online query.`],
+    });
+  }
+
+  const clientConfig = loadClientConfig();
+  const host = process.env.TYPESENSE_HOST || clientConfig?.typesense?.host || 'https://rel-search.seeedstudio.com';
+  const keyCases = process.env.TYPESENSE_SEARCH_KEY_CC_SUCCESS_CASES || process.env.TYPESENSE_SEARCH_KEY_SUCCESS_CASE || clientConfig?.typesense?.search_key_cc_success_cases;
+
+  if (!keyCases) {
+    return createCatalogDto({
+      source: 'bundled_manifest',
+      freshness: 'UNKNOWN',
+      records: [],
+      warnings: ['Missing Typesense API key for success cases.'],
+    });
+  }
+
+  try {
+    const safeTarget = cleanTarget.replace(/["'\[\]\(\)\{\}\\]/g, '');
+    const isNum = /^\d+$/.test(safeTarget);
+    const filterParts = [
+      `id:=[${safeTarget}]`,
+      `slug_zh_hans:=[${safeTarget}]`,
+      `slug_en:=[${safeTarget}]`,
+      `slug_ja:=[${safeTarget}]`,
+    ];
+    if (isNum) {
+      filterParts.push(`pid:=[${safeTarget}]`);
+    }
+    const filterBy = `(${filterParts.join(' || ')}) && published:true`;
+    const searchUrl = `${host}/collections/cc_success_cases/documents/search?q=*&filter_by=${encodeURIComponent(filterBy)}&per_page=1`;
+
+    const data = await fetchJson(searchUrl, { 'X-TYPESENSE-API-KEY': keyCases }, 3500);
+    const hit = data?.hits?.[0]?.document;
+
+    if (!hit) {
+      return createCatalogDto({
+        source: 'typesense',
+        freshness: 'FRESH',
+        records: [],
+        warnings: [`Success case "${cleanTarget}" not found.`],
+      });
+    }
+
+    const titleText = onlineLocalizedText(hit, loc, {
+      en: ['title_en'], zh: ['title_zh_hans'], ja: ['title_ja'],
+    });
+    const excerptText = onlineLocalizedText(hit, loc, {
+      en: ['excerpt_en'], zh: ['excerpt_zh_hans'], ja: ['excerpt_ja'],
+    });
+    const bodyText = onlineLocalizedText(hit, loc, {
+      en: ['body_md_en', 'body_md'], zh: ['body_md_zh_hans', 'body_md'], ja: ['body_md_ja', 'body_md'],
+    });
+
+    let url = null;
+    const candidateUrl = hit[`url_${locKey}`] || hit.url_en || hit.url_zh_hans;
+    if (candidateUrl && typeof candidateUrl === 'string' && /^https?:\/\//i.test(candidateUrl)) {
+      url = appendUtm(candidateUrl, {
+        source: 'sensecraft_agent',
+        medium: 'case_detail',
+        campaign: hit.id || cleanTarget,
+        content: 'success_case_full',
+      });
+    }
+
+    const record = {
+      id: hit.id || String(hit.pid),
+      pid: hit.pid || null,
+      title: titleText.value || hit.title_zh_hans || hit.title_en || cleanTarget,
+      slug: hit.slug_zh_hans || hit.slug_en || cleanTarget,
+      excerpt: excerptText.value || hit.excerpt_zh_hans || hit.excerpt_en || '',
+      body_md: bodyText.value || hit.body_md_zh_hans || hit.body_md_en || hit.body_md || '',
+      hardware: hit.hardware || [],
+      family_ids: hit.family_ids || [],
+      solution_ids: hit.solution_ids || [],
+      industry: hit.industry || [],
+      region: hit.region || [],
+      cover_image: hit.cover_image || null,
+      url,
+      published_at: hit.published_at || null,
+      content_locale: bodyText.locale || titleText.locale || loc,
+      fallback: Boolean((bodyText.locale || titleText.locale) && (bodyText.locale || titleText.locale) !== loc),
+    };
+
+    return createCatalogDto({
+      source: 'typesense',
+      freshness: 'FRESH',
+      records: [record],
+    });
+  } catch (err) {
+    return createCatalogDto({
+      source: 'typesense',
+      freshness: 'UNKNOWN',
+      records: [],
+      warnings: [`Failed to fetch case "${cleanTarget}": ${err.message}`],
+    });
+  }
+}
+
 /**
  * Detects if a search query matches known hardware product families, models, or SKUs.
  *
@@ -820,6 +1171,17 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
             const rawLanding = doc.external_url || doc.landing_url || localizedLanding(bundledScenario, locale) || null;
             const archPreview = extractArchitecturePreview(doc, bundledScenario, locale, 'scenario');
 
+            let casesCount = 0;
+            let casesPreview = [];
+            try {
+              const pData = JSON.parse(doc[`page_data_${locKey}`] || doc.page_data_zh_hans || doc.page_data_en || '{}');
+              const posts = pData.related_posts?.list || [];
+              if (Array.isArray(posts) && posts.length > 0) {
+                casesCount = posts.length;
+                casesPreview = posts.slice(0, 2).map((p) => p.title).filter(Boolean);
+              }
+            } catch (_) {}
+
             onlineScenarios.push({
               type: resolvedType,
               id: docId,
@@ -845,6 +1207,8 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
               }),
               repo_url: doc.repo_url || '',
               diagnostic_playbook: pb,
+              cases_count: casesCount,
+              ...(casesPreview.length > 0 ? { cases_preview: casesPreview } : {}),
               source: 'typesense',
             });
           }
@@ -1096,15 +1460,273 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
   });
 }
 
+/**
+ * Supported product sections for progressive disclosure.
+ */
+export const PRODUCT_SECTIONS = new Set(['overview', 'power', 'interfaces', 'specs', 'all']);
+
+/**
+ * Normalizes an individual SKU specification with calculated package profile and power readiness.
+ *
+ * @param {Object} s - Raw SKU object
+ * @param {Object} family - Parent product family object
+ * @returns {Object} Normalized SKU record
+ */
+export function normalizeSkuRecord(s, family = {}) {
+  const specs = s.specs || {};
+  const pwr = specs.power || {};
+  const pkg = specs.package_contents || [];
+  const pkgText = pkg.join(' ').toLowerCase();
+
+  // Require positive evidence of an included operational battery (not just battery_powered capability or RTC battery)
+  const hasIncludedBattery = pkg.some((item) => {
+    if (!/\bbattery\b/i.test(item)) return false;
+    if (/(?:not\s+included|sold\s+separately|cr1220|rtc|coin)/i.test(item)) return false;
+    if (/(?:without|w\/o|no|exclude[ds]?)\s+[^()]*\bbattery/i.test(item)) return false;
+    return true;
+  });
+
+  let adapterIncluded = pwr.adapter_included;
+  if (adapterIncluded === undefined || adapterIncluded === null) {
+    if (s.attrs?.power_adapter === 'not_included' || /w\/?o\s+power/i.test(s.name)) {
+      adapterIncluded = false;
+    } else if (s.attrs?.power_adapter === 'included' || /power\s+adapter/i.test(pkgText)) {
+      adapterIncluded = true;
+    } else {
+      adapterIncluded = hasIncludedBattery ? false : null;
+    }
+  }
+
+  const cordExplicitlyExcluded =
+    s.attrs?.power_adapter === 'included_no_cord' ||
+    s.attrs?.power_cord === 'not_included' ||
+    /without\s+power\s+cord/i.test(pkgText) ||
+    /no\s+power\s+cord/i.test(pkgText) ||
+    /w\/?o\s+power\s+cord/i.test(pkgText) ||
+    /power\s+cord\s+(?:sold\s+separately|not\s+included|optional|excluded)/i.test(pkgText) ||
+    /without\s+power\s+cord/i.test(pwr.adapter_spec || '') ||
+    /without\s+power\s+cord/i.test(s.name || '');
+
+  let powerCordIncluded = null;
+  if (cordExplicitlyExcluded) {
+    powerCordIncluded = false;
+  } else if (s.attrs?.power_cord === 'included') {
+    powerCordIncluded = true;
+  } else if (pkg.length > 0) {
+    const hasExplicitCord = pkg.some((item) => {
+      const itemLower = item.toLowerCase();
+      return /power\s+cord/i.test(itemLower) &&
+        !/(?:without|sold\s+separately|not\s+included|optional|no\s+|w\/o|separately)/i.test(itemLower);
+    });
+    if (hasExplicitCord) {
+      powerCordIncluded = true;
+    } else if (adapterIncluded === true) {
+      const isIntegratedPlug =
+        /universal|wall\s*mount|plug/i.test(pwr.adapter_spec || '') ||
+        /universal\s+power\s+supply/i.test(pkgText) ||
+        /(?:with\s+[^()]*|\b(?:interchangeable|multi-country|global)\s+)plugs?\b/i.test(pkgText);
+      if (isIntegratedPlug) {
+        powerCordIncluded = true;
+      } else {
+        powerCordIncluded = null;
+      }
+    }
+  }
+
+  let outOfTheBoxReady = false;
+  let readinessSummary = '';
+
+  const isDevBoard = /xiao|seeeduino|arduino/i.test(family?.id || '') || /board|development\s+kit/i.test(s.name) || (pwr.input_voltage && /3\.7|5v/i.test(pwr.input_voltage));
+
+  if (hasIncludedBattery) {
+    outOfTheBoxReady = true;
+    readinessSummary = `随附配套电池供电（${pwr.input_connector ? '支持 ' + pwr.input_connector : '支持太阳能/USB充电'}），开箱即可直接上电运行。`;
+  } else if (adapterIncluded === false) {
+    outOfTheBoxReady = false;
+    if (isDevBoard) {
+      readinessSummary = `开发板/套件（仅含主板与配件），需通过 ${pwr.input_connector || 'USB-C'} 供电或自备外接电源/电池。`;
+    } else {
+      readinessSummary = `仅含主机，不随附电源适配器。用户买回去无法直接开机，必须加配 ${pwr.adapter_spec || '合适规格电源适配器'}。`;
+    }
+  } else if (adapterIncluded === true) {
+    if (powerCordIncluded === false) {
+      outOfTheBoxReady = false;
+      readinessSummary = `随附电源适配器（${pwr.adapter_spec || '标配'}），但不随附 AC 电源线，开箱前需自备或加配电源线。`;
+    } else if (powerCordIncluded === true) {
+      outOfTheBoxReady = true;
+      readinessSummary = `随附电源适配器与电源线（或一体式插头），开箱即用。`;
+    } else {
+      outOfTheBoxReady = false;
+      readinessSummary = `随附电源适配器（${pwr.adapter_spec || '标配'}），包装清单未明确电源线随附情况，请核对是否需自备电源线。`;
+    }
+  } else {
+    outOfTheBoxReady = false;
+    readinessSummary = pwr.input_voltage ? `供电规格: ${pwr.input_voltage} ${pwr.input_connector || ''}，请核对是否自备电源。` : '电源随附情况未声明。';
+  }
+
+  // Get matching required accessories
+  const requiredAccessories = (family?.required_accessories || []).filter((acc) => {
+    if (!acc.applies_when) return true;
+    const attrVal = s.attrs?.[acc.applies_when.attr];
+    const target = acc.applies_when.value;
+    if (Array.isArray(target)) return target.includes(attrVal);
+    return attrVal === target;
+  }).map((acc) => ({
+    id: acc.id,
+    name: acc.name,
+    sku: acc.sku,
+    reason: acc.reason,
+    url: acc.url,
+  }));
+
+  return {
+    sku: s.sku,
+    model: s.model || null,
+    name: s.name,
+    url: appendUtm(s.url, {
+      source: 'sensecraft_agent',
+      medium: 'bom_recommendation',
+      campaign: family?.id || '',
+      content: `sku_${s.sku}`,
+    }),
+    package_profile: {
+      power_adapter_included: adapterIncluded,
+      power_cord_included: powerCordIncluded,
+      out_of_the_box_ready: outOfTheBoxReady,
+      readiness_summary: readinessSummary,
+    },
+    required_accessories: requiredAccessories,
+    power: {
+      adapter_included: adapterIncluded,
+      adapter_spec: pwr.adapter_spec || null,
+      input_voltage: pwr.input_voltage || null,
+      input_connector: pwr.input_connector || null,
+    },
+    package_contents: pkg,
+    interfaces: specs.connectivity?.interfaces || family?.interfaces || [],
+    io_ports: specs.io_ports || [],
+    expansion_slots: specs.expansion_slots || [],
+    ai_performance: specs.ai_performance || null,
+  };
+}
+
+/**
+ * Prunes a product family and member SKU record based on requested section.
+ *
+ * @param {Object} fam - Product family record
+ * @param {string} [section='all'] - Section name ('overview', 'power', 'interfaces', 'specs', 'all')
+ * @returns {Object} Pruned product family record
+ */
+export function pruneProductRecord(fam, section = 'all') {
+  if (!fam || !section || section === 'all') return fam;
+  const s = String(section).toLowerCase().trim();
+  if (!PRODUCT_SECTIONS.has(s)) {
+    throw new Error(`Unsupported product section "${section}". Supported: ${Array.from(PRODUCT_SECTIONS).join(', ')}.`);
+  }
+  if (s === 'all') return fam;
+
+  const rawSkus = fam.matched_skus || fam.skus || [];
+
+  const base = {
+    family_id: fam.family_id,
+    title: fam.title,
+    summary: fam.summary,
+    default_sku: fam.default_sku,
+    regions: fam.regions || [],
+    physical_spec: fam.physical_spec || null,
+    required_accessories_count: fam.required_accessories_count ?? (fam.required_accessories || []).length,
+    optional_accessories_count: fam.optional_accessories_count ?? (fam.optional_accessories || []).length,
+  };
+
+  if (s === 'overview') {
+    const prunedSkus = rawSkus.map((sku) => ({
+      sku: sku.sku,
+      model: sku.model || null,
+      name: sku.name,
+      readiness_summary: sku.package_profile?.readiness_summary || null,
+      out_of_the_box_ready: sku.package_profile?.out_of_the_box_ready ?? null,
+      url: sku.url,
+    }));
+    return {
+      ...base,
+      skus_count: rawSkus.length || fam.skus_count || 0,
+      matched_skus: prunedSkus,
+      skus: prunedSkus,
+    };
+  }
+
+  if (s === 'power') {
+    const prunedSkus = rawSkus.map((sku) => ({
+      sku: sku.sku,
+      model: sku.model || null,
+      name: sku.name,
+      package_profile: sku.package_profile,
+      power: sku.power,
+      required_accessories: sku.required_accessories || [],
+      package_contents: sku.package_contents || [],
+      url: sku.url,
+    }));
+    return {
+      ...base,
+      matched_skus: prunedSkus,
+      skus: prunedSkus,
+    };
+  }
+
+  if (s === 'interfaces') {
+    const prunedSkus = rawSkus.map((sku) => ({
+      sku: sku.sku,
+      model: sku.model || null,
+      name: sku.name,
+      interfaces: sku.interfaces || [],
+      io_ports: sku.io_ports || [],
+      expansion_slots: sku.expansion_slots || [],
+      url: sku.url,
+    }));
+    return {
+      ...base,
+      interfaces: fam.interfaces || [],
+      protocols: fam.protocols || [],
+      matched_skus: prunedSkus,
+      skus: prunedSkus,
+    };
+  }
+
+  if (s === 'specs') {
+    const prunedSkus = rawSkus.map((sku) => ({
+      sku: sku.sku,
+      model: sku.model || null,
+      name: sku.name,
+      ai_performance: sku.ai_performance || null,
+      power: sku.power,
+      interfaces: sku.interfaces || [],
+      io_ports: sku.io_ports || [],
+      expansion_slots: sku.expansion_slots || [],
+      package_contents: sku.package_contents || [],
+      url: sku.url,
+    }));
+    return {
+      ...base,
+      interfaces: fam.interfaces || [],
+      protocols: fam.protocols || [],
+      matched_skus: prunedSkus,
+      skus: prunedSkus,
+    };
+  }
+
+  return fam;
+}
+
 /**
  * Queries product family information, SKUs, and official purchase links.
  *
  * @param {string} familyId
  * @param {Object} [options]
  * @param {string} [options.locale='zh']
+ * @param {string} [options.section='all']
  * @returns {Object} Catalog DTO with product details
  */
-export function queryProductFamily(familyId, { locale = 'zh' } = {}) {
+export function queryProductFamily(familyId, { locale = 'zh', section = 'all' } = {}) {
   const core = loadKnowledgeCore();
   const family = core.product_families?.[familyId];
 
@@ -1117,35 +1739,56 @@ export function queryProductFamily(familyId, { locale = 'zh' } = {}) {
     });
   }
 
+  const normalizedSkus = (family.skus || []).slice(0, 10).map((s) => normalizeSkuRecord(s, family));
+
+  const rawRecord = {
+    family_id: family.id,
+    title: family.title?.[locale] || family.title?.zh || family.title?.en || family.id,
+    summary: family.summary || null,
+    default_sku: family.default_sku,
+    regions: family.regions || [],
+    interfaces: family.interfaces || [],
+    protocols: family.protocols || [],
+    supported_scenarios: family.supported_scenarios || [],
+    skus_count: (family.skus || []).length,
+    skus: normalizedSkus,
+    matched_skus: normalizedSkus,
+    physical_spec: family.physical_spec || null,
+    required_accessories_count: (family.required_accessories || []).length,
+    optional_accessories_count: (family.optional_accessories || []).length,
+  };
+
   return createCatalogDto({
     source: 'bundled_manifest',
     freshness: 'FRESH',
-    records: [{
-      family_id: family.id,
-      title: family.title?.[locale] || family.title?.zh || family.title?.en || family.id,
-      summary: family.summary || null,
-      default_sku: family.default_sku,
-      regions: family.regions || [],
-      interfaces: family.interfaces || [],
-      protocols: family.protocols || [],
-      supported_scenarios: family.supported_scenarios || [],
-      skus_count: (family.skus || []).length,
-      skus: (family.skus || []).slice(0, 10).map((s) => ({
-        ...s,
-        url: appendUtm(s.url, {
-          source: 'sensecraft_agent',
-          medium: 'bom_recommendation',
-          campaign: family.id,
-          content: `sku_${s.sku}`,
-        }),
-      })),
-      physical_spec: family.physical_spec || null,
-      required_accessories_count: (family.required_accessories || []).length,
-      optional_accessories_count: (family.optional_accessories || []).length,
-    }],
+    records: [pruneProductRecord(rawRecord, section)],
   });
 }
 
+const PRODUCT_SYNONYMS = {
+  '树莓派': ['raspberry', 'cm4', 'rpi', 'r1000', 'r12', 'r20', 'r21', 'reterminal'],
+  '工控机': ['industrial', 'ipc', 'recomputer', 'reserver'],
+  '边缘计算': ['recomputer', 'edge', 'orin'],
+  '边缘盒子': ['recomputer', 'edge', 'orin'],
+  '激光雷达': ['lidar', 'rplidar'],
+  '相机': ['recamera', 'camera', 'grove vision', 'vision'],
+  '继电器': ['relay'],
+  '土壤': ['soil', 'mtec'],
+  '气象': ['weather', 's200', 's700', 's2120'],
+  '追踪器': ['tracker', 't1000', 't2000'],
+  '网关': ['gateway', 'lorawan', 'm2', 'r1225'],
+};
+
+function matchesTokenOrSynonym(haystack, token) {
+  if (haystack.includes(token)) return true;
+  for (const [k, syns] of Object.entries(PRODUCT_SYNONYMS)) {
+    if (token.includes(k) || k.includes(token)) {
+      if (syns.some((s) => haystack.includes(s))) return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Searches product families and member SKUs by keywords, model name, interface, or SKU number.
  *
@@ -1153,9 +1796,10 @@ export function queryProductFamily(familyId, { locale = 'zh' } = {}) {
  * @param {string} options.query - Free text query (e.g. "J4012 Super", "RS485", "114110314")
  * @param {'zh' | 'en' | 'ja'} [options.locale='zh']
  * @param {number} [options.limit=5]
+ * @param {string} [options.section='all'] - Section name ('overview', 'power', 'interfaces', 'specs', 'all')
  * @returns {Object} Catalog DTO
  */
-export function searchProducts({ query = '', locale = 'zh', limit = 5 } = {}) {
+export function searchProducts({ query = '', locale = 'zh', limit = 5, section = 'all' } = {}) {
   const core = loadKnowledgeCore();
   const families = Object.values(core.product_families || {});
   const qLower = (query || '').toLowerCase().trim();
@@ -1176,8 +1820,12 @@ export function searchProducts({ query = '', locale = 'zh', limit = 5 } = {}) {
     let score = 0;
     const titleZh = (fam.title?.zh || '').toLowerCase();
     const titleEn = (fam.title?.en || '').toLowerCase();
+    const summaryZh = typeof fam.summary === 'object' ? (fam.summary?.zh || '') : (fam.summary || '');
+    const summaryEn = typeof fam.summary === 'object' ? (fam.summary?.en || '') : '';
+    const series = (fam.series || '').toLowerCase();
+    const pf = (fam.product_family || '').toLowerCase();
     const fid = (fam.id || '').toLowerCase();
-    const famHaystack = [fid, titleZh, titleEn].join(' ');
+    const famHaystack = [fid, titleZh, titleEn, summaryZh, summaryEn, series, pf].join(' ').toLowerCase();
 
     // Check SKU matching
     const matchedSkus = [];
@@ -1195,17 +1843,17 @@ export function searchProducts({ query = '', locale = 'zh', limit = 5 } = {}) {
       const skuProtos = (sku.specs?.connectivity?.protocols || sku.protocols || []).map((p) => String(p).toLowerCase());
       const skuIoPorts = (sku.specs?.io_ports || []).map((p) => String(p.type || '').toLowerCase());
 
-      const skuHaystack = [sNum, sModel, sNameClean, ...sAttrs, ...skuIfaces, ...skuProtos, ...skuIoPorts].join(' ');
+      const skuHaystack = [sNum, sModel, sNameClean, ...sAttrs, ...skuIfaces, ...skuProtos, ...skuIoPorts].join(' ').toLowerCase();
       const isSingleSkuLookup = tokens.length === 1 && (sNum === tokens[0] || sNum === qLower);
-      const skuMatchesAll = tokens.every((t) => skuHaystack.includes(t));
-      const singleTokenHit = tokens.length === 1 && ((sModel && sModel.includes(tokens[0])) || skuHaystack.includes(tokens[0]));
+      const skuMatchesAll = tokens.every((t) => matchesTokenOrSynonym(skuHaystack, t));
+      const singleTokenHit = tokens.length === 1 && ((sModel && sModel.includes(tokens[0])) || matchesTokenOrSynonym(skuHaystack, tokens[0]));
 
       if (isSingleSkuLookup || skuMatchesAll) {
         matchedSkus.push(sku);
       } else if (tokens.length > 1) {
-        const combinedMatchesAll = tokens.every((t) => (famHaystack + ' ' + skuHaystack).includes(t));
-        const nonFamTokens = tokens.filter((t) => !famHaystack.includes(t));
-        if (combinedMatchesAll && (nonFamTokens.length === 0 || nonFamTokens.every((t) => skuHaystack.includes(t)))) {
+        const combinedMatchesAll = tokens.every((t) => matchesTokenOrSynonym(famHaystack + ' ' + skuHaystack, t));
+        const nonFamTokens = tokens.filter((t) => !matchesTokenOrSynonym(famHaystack, t));
+        if (combinedMatchesAll && (nonFamTokens.length === 0 || nonFamTokens.every((t) => matchesTokenOrSynonym(skuHaystack, t)))) {
           matchedSkus.push(sku);
         }
       } else if (singleTokenHit) {
@@ -1214,9 +1862,9 @@ export function searchProducts({ query = '', locale = 'zh', limit = 5 } = {}) {
     }
 
     // Require all query tokens to be satisfied either in the family or across member SKUs
-    const famMatchesAll = tokens.every((t) => famHaystack.includes(t));
+    const famMatchesAll = tokens.every((t) => matchesTokenOrSynonym(famHaystack, t));
     const allTokensSatisfiedInFamily = tokens.every((t) => {
-      return famHaystack.includes(t) || (fam.skus || []).some((s) => {
+      return matchesTokenOrSynonym(famHaystack, t) || (fam.skus || []).some((s) => {
         const sNameClean = String(s.name || '')
           .toLowerCase()
           .replace(/[（\(][^）\)]*not\s+supported[^）\)]*[）\)]?/gi, '')
@@ -1224,7 +1872,7 @@ export function searchProducts({ query = '', locale = 'zh', limit = 5 } = {}) {
         const sIfaces = (s.specs?.connectivity?.interfaces || s.interfaces || []).map((i) => String(i).toLowerCase());
         const sProtos = (s.specs?.connectivity?.protocols || s.protocols || []).map((p) => String(p).toLowerCase());
         const sPorts = (s.specs?.io_ports || []).map((p) => String(p.type || '').toLowerCase());
-        return [s.sku, s.model, sNameClean, ...Object.values(s.attrs || {}), ...sIfaces, ...sProtos, ...sPorts].join(' ').toLowerCase().includes(t);
+        return matchesTokenOrSynonym([s.sku, s.model, sNameClean, ...Object.values(s.attrs || {}), ...sIfaces, ...sProtos, ...sPorts].join(' ').toLowerCase(), t);
       });
     });
 
@@ -1253,152 +1901,150 @@ export function searchProducts({ query = '', locale = 'zh', limit = 5 } = {}) {
       interfaces: family.interfaces || [],
       protocols: family.protocols || [],
       supported_scenarios: family.supported_scenarios || [],
-      matched_skus: matchedSkus.map((s) => {
-        const specs = s.specs || {};
-        const pwr = specs.power || {};
-        const pkg = specs.package_contents || [];
-        const pkgText = pkg.join(' ').toLowerCase();
-
-        // Require positive evidence of an included operational battery (not just battery_powered capability or RTC battery)
-        const hasIncludedBattery = pkg.some((item) => {
-          if (!/\bbattery\b/i.test(item)) return false;
-          if (/(?:not\s+included|sold\s+separately|cr1220|rtc|coin)/i.test(item)) return false;
-          if (/(?:without|w\/o|no|exclude[ds]?)\s+[^()]*\bbattery/i.test(item)) return false;
-          return true;
-        });
+      matched_skus: matchedSkus.map((s) => normalizeSkuRecord(s, family)),
+    };
+  });
 
-        let adapterIncluded = pwr.adapter_included;
-        if (adapterIncluded === undefined || adapterIncluded === null) {
-          if (s.attrs?.power_adapter === 'not_included' || /w\/?o\s+power/i.test(s.name)) {
-            adapterIncluded = false;
-          } else if (s.attrs?.power_adapter === 'included' || /power\s+adapter/i.test(pkgText)) {
-            adapterIncluded = true;
-          } else {
-            adapterIncluded = hasIncludedBattery ? false : null;
-          }
-        }
+  return createCatalogDto({
+    source: 'bundled_manifest',
+    freshness: 'FRESH',
+    records: records.map((r) => pruneProductRecord(r, section)),
+    warnings: records.length === 0 ? [`未找到与 "${query}" 匹配的硬件产品或 SKU。`] : [],
+  });
+}
 
-        const cordExplicitlyExcluded =
-          s.attrs?.power_adapter === 'included_no_cord' ||
-          s.attrs?.power_cord === 'not_included' ||
-          /without\s+power\s+cord/i.test(pkgText) ||
-          /no\s+power\s+cord/i.test(pkgText) ||
-          /w\/?o\s+power\s+cord/i.test(pkgText) ||
-          /power\s+cord\s+(?:sold\s+separately|not\s+included|optional|excluded)/i.test(pkgText) ||
-          /without\s+power\s+cord/i.test(pwr.adapter_spec || '') ||
-          /without\s+power\s+cord/i.test(s.name || '');
-
-        let powerCordIncluded = null;
-        if (cordExplicitlyExcluded) {
-          powerCordIncluded = false;
-        } else if (s.attrs?.power_cord === 'included') {
-          powerCordIncluded = true;
-        } else if (pkg.length > 0) {
-          const hasExplicitCord = pkg.some((item) => {
-            const itemLower = item.toLowerCase();
-            return /power\s+cord/i.test(itemLower) &&
-              !/(?:without|sold\s+separately|not\s+included|optional|no\s+|w\/o|separately)/i.test(itemLower);
-          });
-          if (hasExplicitCord) {
-            powerCordIncluded = true;
-          } else if (adapterIncluded === true) {
-            const isIntegratedPlug =
-              /universal|wall\s*mount|plug/i.test(pwr.adapter_spec || '') ||
-              /universal\s+power\s+supply/i.test(pkgText) ||
-              /(?:with\s+[^()]*|\b(?:interchangeable|multi-country|global)\s+)plugs?\b/i.test(pkgText);
-            if (isIntegratedPlug) {
-              powerCordIncluded = true;
-            } else {
-              powerCordIncluded = null;
-            }
-          }
-        }
+/**
+ * Asynchronously searches products with online Typesense purchase_profile fallback.
+ *
+ * @param {Object} options
+ * @param {string} options.query
+ * @param {'zh' | 'en' | 'ja'} [options.locale='zh']
+ * @param {number} [options.limit=5]
+ * @param {string} [options.section='all']
+ * @returns {Promise<Object>}
+ */
+export async function searchProductsAsync({ query = '', locale = 'zh', limit = 5, section = 'all' } = {}) {
+  const localDto = searchProducts({ query, locale, limit, section });
+  if (localDto.records.length > 0 || process.env.SENSECRAFT_OFFLINE_ONLY) {
+    return localDto;
+  }
+
+  const clientConfig = loadClientConfig();
+  const host = process.env.TYPESENSE_HOST || clientConfig?.typesense?.host || 'https://rel-search.seeedstudio.com';
+  const keyPurchase = process.env.SENSECRAFT_TYPESENSE_PURCHASE_SEARCH_KEY || process.env.TYPESENSE_SEARCH_KEY_PURCHASE_PROFILE || clientConfig?.typesense?.search_key_purchase_profile;
 
-        let outOfTheBoxReady = false;
-        let readinessSummary = '';
+  if (!keyPurchase) {
+    return localDto;
+  }
 
-        const isDevBoard = /xiao|seeeduino|arduino/i.test(family.id) || /board|development\s+kit/i.test(s.name) || (pwr.input_voltage && /3\.7|5v/i.test(pwr.input_voltage));
+  try {
+    const qLower = (query || '').toLowerCase().trim();
+    const tokens = qLower.split(/\s+/).filter(Boolean);
+    const searchUrl = `${host}/collections/purchase_profile/documents/search?q=${encodeURIComponent(query)}&query_by=title,series,product_family&drop_tokens_mode=none&per_page=${limit}`;
+    const data = await fetchJson(searchUrl, { 'X-TYPESENSE-API-KEY': keyPurchase }, 2500);
+    const hits = data?.hits || [];
+    if (hits.length === 0) return localDto;
+
+    const core = loadKnowledgeCore();
+    const candidateFamIds = new Set();
+    for (const hit of hits) {
+      const doc = hit.document || {};
+      const famId = doc.family_id || doc.id;
+      if (famId) candidateFamIds.add(famId);
+    }
 
-        if (hasIncludedBattery) {
-          outOfTheBoxReady = true;
-          readinessSummary = `随附配套电池供电（${pwr.input_connector ? '支持 ' + pwr.input_connector : '支持太阳能/USB充电'}），开箱即可直接上电运行。`;
-        } else if (adapterIncluded === false) {
-          outOfTheBoxReady = false;
-          if (isDevBoard) {
-            readinessSummary = `开发板/套件（仅含主板与配件），需通过 ${pwr.input_connector || 'USB-C'} 供电或自备外接电源/电池。`;
-          } else {
-            readinessSummary = `仅含主机，不随附电源适配器。用户买回去无法直接开机，必须加配 ${pwr.adapter_spec || '合适规格电源适配器'}。`;
-          }
-        } else if (adapterIncluded === true) {
-          if (powerCordIncluded === false) {
-            outOfTheBoxReady = false;
-            readinessSummary = `随附电源适配器（${pwr.adapter_spec || '标配'}），但不随附 AC 电源线，开箱前需自备或加配电源线。`;
-          } else if (powerCordIncluded === true) {
-            outOfTheBoxReady = true;
-            readinessSummary = `随附电源适配器与电源线（或一体式插头），开箱即用。`;
-          } else {
-            outOfTheBoxReady = false;
-            readinessSummary = `随附电源适配器（${pwr.adapter_spec || '标配'}），包装清单未明确电源线随附情况，请核对是否需自备电源线。`;
-          }
-        } else {
-          outOfTheBoxReady = false;
-          readinessSummary = pwr.input_voltage ? `供电规格: ${pwr.input_voltage} ${pwr.input_connector || ''}，请核对是否自备电源。` : '电源随附情况未声明。';
+    if (candidateFamIds.size > 0) {
+      const onlineMatches = [];
+      for (const famId of candidateFamIds) {
+        const localFam = core.product_families?.[famId];
+        if (localFam) {
+          const titleZh = (localFam.title?.zh || '').toLowerCase();
+          const titleEn = (localFam.title?.en || '').toLowerCase();
+          const summaryZh = typeof localFam.summary === 'object' ? (localFam.summary?.zh || '') : (localFam.summary || '');
+          const summaryEn = typeof localFam.summary === 'object' ? (localFam.summary?.en || '') : '';
+          const series = (localFam.series || '').toLowerCase();
+          const pf = (localFam.product_family || '').toLowerCase();
+          const fid = (localFam.id || '').toLowerCase();
+          const famHaystack = [fid, titleZh, titleEn, summaryZh, summaryEn, series, pf].join(' ').toLowerCase();
+
+          // Reject false positives: require all query tokens to be satisfied either in the family or across member SKUs
+          const allTokensSatisfied = tokens.every((t) => {
+            return matchesTokenOrSynonym(famHaystack, t) || (localFam.skus || []).some((s) => {
+              const sNameClean = String(s.name || '').toLowerCase();
+              return matchesTokenOrSynonym([s.sku, s.model, sNameClean].join(' ').toLowerCase(), t);
+            });
+          });
+
+          if (!allTokensSatisfied) continue;
+
+          onlineMatches.push({
+            family: localFam,
+            matchedSkus: (localFam.skus || []).slice(0, 3),
+          });
         }
+      }
 
-        // Get matching required accessories
-        const requiredAccessories = (family.required_accessories || []).filter((acc) => {
-          if (!acc.applies_when) return true;
-          const attrVal = s.attrs?.[acc.applies_when.attr];
-          const target = acc.applies_when.value;
-          if (Array.isArray(target)) return target.includes(attrVal);
-          return attrVal === target;
-        }).map((acc) => ({
-          id: acc.id,
-          name: acc.name,
-          sku: acc.sku,
-          reason: acc.reason,
-          url: acc.url,
-        }));
+      if (onlineMatches.length > 0) {
+        const records = onlineMatches.slice(0, limit).map(({ family, matchedSkus }) => {
+          return {
+            family_id: family.id,
+            title: family.title?.[locale] || family.title?.zh || family.title?.en || family.id,
+            summary: family.summary || null,
+            default_sku: family.default_sku,
+            interfaces: family.interfaces || [],
+            protocols: family.protocols || [],
+            supported_scenarios: family.supported_scenarios || [],
+            matched_skus: matchedSkus.map((s) => {
+              const specs = s.specs || {};
+              const pwr = specs.power || {};
+              const pkg = specs.package_contents || [];
+              return {
+                sku: s.sku,
+                model: s.model || null,
+                name: s.name,
+                url: appendUtm(s.url, {
+                  source: 'sensecraft_agent',
+                  medium: 'product_search',
+                  campaign: family.id,
+                  content: `sku_${s.sku}`,
+                }),
+                package_profile: {
+                  power_adapter_included: pwr.adapter_included ?? null,
+                  power_cord_included: null,
+                  out_of_the_box_ready: Boolean(pwr.adapter_included),
+                  readiness_summary: pwr.adapter_included ? '随附电源适配器' : '需自备或加配电源供电',
+                },
+                required_accessories: [],
+                power: {
+                  adapter_included: pwr.adapter_included ?? null,
+                  adapter_spec: pwr.adapter_spec || null,
+                  input_voltage: pwr.input_voltage || null,
+                  input_connector: pwr.input_connector || null,
+                },
+                package_contents: pkg,
+                interfaces: specs.connectivity?.interfaces || family.interfaces || [],
+                io_ports: specs.io_ports || [],
+                expansion_slots: specs.expansion_slots || [],
+                ai_performance: specs.ai_performance || null,
+              };
+            }),
+          };
+        });
 
-        return {
-          sku: s.sku,
-          model: s.model || null,
-          name: s.name,
-          url: appendUtm(s.url, {
-            source: 'sensecraft_agent',
-            medium: 'product_search',
-            campaign: family.id,
-            content: `sku_${s.sku}`,
-          }),
-          package_profile: {
-            power_adapter_included: adapterIncluded,
-            power_cord_included: powerCordIncluded,
-            out_of_the_box_ready: outOfTheBoxReady,
-            readiness_summary: readinessSummary,
-          },
-          required_accessories: requiredAccessories,
-          power: {
-            adapter_included: adapterIncluded,
-            adapter_spec: pwr.adapter_spec || null,
-            input_voltage: pwr.input_voltage || null,
-            input_connector: pwr.input_connector || null,
-          },
-          package_contents: pkg,
-          interfaces: specs.connectivity?.interfaces || family.interfaces || [],
-          io_ports: specs.io_ports || [],
-          expansion_slots: specs.expansion_slots || [],
-          ai_performance: specs.ai_performance || null,
-        };
-      }),
-    };
-  });
+        return createCatalogDto({
+          source: 'typesense',
+          freshness: 'FRESH',
+          fieldCompleteness: { spec: true, compatibility: true, offer: true },
+          records: records.map((r) => pruneProductRecord(r, section)),
+          warnings: localDto.warnings || [],
+        });
+      }
+    }
+  } catch (_) {
+    // Graceful fallback
+  }
 
-  return createCatalogDto({
-    source: 'bundled_manifest',
-    freshness: 'FRESH',
-    records,
-    warnings: records.length === 0 ? [`未找到与 "${query}" 匹配的硬件产品或 SKU。`] : [],
-  });
+  return localDto;
 }
 
 /**