@miravia_test/miravia-publish-skill 0.1.7 → 0.1.8

package/dist/SKILL.md

@@ -112,6 +112,7 @@ description: Miravia 商品发布 AI Skill。仅负责商品创建（手动一
 | `need_brand_create` | 品牌未找到，需去 Seller Center 处理 | 先引导查看已有品牌及审核状态（https://sellercenter.miravia.es/apps/setting/seller/brandlist，可能已在审核中），确无再创建（https://sellercenter.miravia.es/apps/product/publish/brand）；创建后重新运行命令 |
 | `need_mandatory_fields` | 缺少必填字段；**图片缺失为硬阻断（不可 Draft）**，价格/重量/尺寸缺失可 `--draft` | 补充字段后重跑 |
 | `need_category_attributes` | 类目必填属性缺失（AI抽取模式） | 通过 `--attribute-data` 补充或使用 `--draft` |
+| `need_attribute_mapping` | Excel/CSV 列未能自动匹配到类目属性（不静默丢弃），返回该列及其候选属性 | 向用户展示候选属性，确认后用 `--attribute-data '{"<属性名>":"<值>"}'` 重跑；非商品属性则删除该列 |
 | `need_field_summary` | 需要确认字段摘要或选择草稿模式 | 回传 `field_summary_token`，可加 `--draft` |
 | `need_compliance` | 制造商/EU 负责人匹配失败 | 按返回候选选择或补充信息后重跑 |
 | `compliance_missing_suggest_draft` | 合规字段缺失（制造商/欧代/Safety Warning内容/合规文档） | 补充合规字段或加 `--draft` 发布为草稿 |

package/dist/VERSION

@@ -1 +1 @@
-0.1.7
+0.1.8

package/dist/scripts/extraction_engine.py

@@ -371,6 +371,7 @@ _TABLE_FIELD_SYNONYMS: Dict[str, tuple] = {
     "length_cm": ("长度", "长cm", "长", "length", "largura"),
     "width_cm": ("宽度", "宽cm", "宽", "width", "ancho"),
     "height_cm": ("高度", "高cm", "高", "height", "altura"),
+    "delivery_method": ("deliverymethod", "delivery", "shippingmethod", "shipping", "物流方式", "物流", "发货方式", "配送方式", "metododeenvío", "metododeenvio", "envío", "envio", "spedizione", "metododiconsegna"),
     "manufacturer_name": ("制造商", "厂家", "manufacturer", "fabricante"),
     "eu_responsible_person_name": ("欧盟负责人", "欧代", "euresponsibleperson", "eurp"),
     "variation_1": ("颜色", "color", "colour", "variation1", "variation", "款式"),
@@ -389,6 +390,7 @@ _PRODUCT_LEVEL_FIELDS = {
     "length_cm",
     "width_cm",
     "height_cm",
+    "delivery_method",
     "manufacturer_name",
     "eu_responsible_person_name",
 }

package/dist/scripts/i18n.py

@@ -249,6 +249,7 @@ TRANSLATIONS: Dict[str, Dict[str, str]] = {
         "pub_dbm_dim_sum_exceeded": "Dimension sum {dim_sum} exceeds DBM limit {limit}cm.",
         "pub_dbm_volume_exceeded": "Volumetric weight {volume} exceeds DBM limit {limit}.",
         "pub_dbm_auto_switch_to_dbs": "Package exceeds DBM limits. Delivery method auto-switched to DBS.",
+        "pub_dbs_no_permission_downgrade": "Seller requested DBS but this account has no DBS permission; the delivery method was set to DBM.",
         "pub_dbm_no_dbs_permission": "Package exceeds DBM limits but seller has no DBS permission. Cannot auto-switch to DBS.",
         "pub_dbm_fix_or_apply_dbs": "Please reduce package size/weight to meet DBM limits, or apply for DBS permission in Seller Center.",
         # SKU already exists (concurrency conflict)
@@ -338,6 +339,9 @@ TRANSLATIONS: Dict[str, Dict[str, str]] = {
         "pub_need_category_attributes_description": "The category {category_id} requires the following attributes that were not found in the extracted data. Please provide them via --attribute-data or rerun with --draft to publish as an inactive draft.",
         "pub_need_category_attributes_item": "{idx}. {label} ({en_name}) - {input_type}",
         "pub_need_category_attributes_next": "Provide the missing attributes and rerun with --attribute-data '<json>', or use --draft to publish as inactive draft and complete them later.",
+        "pub_need_attribute_mapping_title": "Some columns could not be matched automatically",
+        "pub_need_attribute_mapping_description": "These Excel/CSV columns did not clearly match a category attribute, so they were not bound. Please confirm which attribute each column should map to, then rerun with --attribute-data using the canonical attribute names shown below (or drop the column if it is not a product attribute).",
+        "pub_need_attribute_mapping_next": "Rerun with --attribute-data '{\"<attribute_name>\": \"<value>\"}' using one of the suggested attribute names, or remove the column if it is not needed.",
         "pub_html_cleaned_notice": "The product description has been cleaned: unsafe HTML tags (script, iframe, style attributes, etc.) were removed. Only safe formatting tags (p, br, b, ul, li, etc.) are kept.",
         "pub_create_pending_review": "Product submitted successfully. It is currently under Miravia review and temporarily unavailable for sale; approval may take up to 48 hours, especially if package photos or documents are required. Once approved, it will be activated automatically. If rejected, please check the Suspended tab.",
         "pub_pdp_link": "Product detail page: {url}",
@@ -914,6 +918,7 @@ TRANSLATIONS: Dict[str, Dict[str, str]] = {
         "pub_dbm_dim_sum_exceeded": "三边之和 {dim_sum} 超过 DBM 限制 {limit}cm。",
         "pub_dbm_volume_exceeded": "体积重 {volume} 超过 DBM 限制 {limit}。",
         "pub_dbm_auto_switch_to_dbs": "包裹超出 DBM 限制，物流方式自动转为 DBS。",
+        "pub_dbs_no_permission_downgrade": "商家请求使用 DBS，但当前账号没有 DBS 权限，物流方式已设为 DBM。",
         "pub_dbm_no_dbs_permission": "包裹超出 DBM 限制，但卖家无 DBS 权限，无法自动转为 DBS。",
         "pub_dbm_fix_or_apply_dbs": "请减小包裹尺寸/重量以满足 DBM 限制，或在 Seller Center 申请 DBS 权限。",
         # SKU already exists (concurrency conflict)
@@ -968,6 +973,9 @@ TRANSLATIONS: Dict[str, Dict[str, str]] = {
         "pub_need_category_attributes_description": "类目 {category_id} 要求以下属性，但 AI 抽取的数据中未包含。请通过 --attribute-data 补充，或使用 --draft 发布为未激活草稿。",
         "pub_need_category_attributes_item": "{idx}. {label}（{en_name}）- {input_type}",
         "pub_need_category_attributes_next": "补充缺失属性后使用 --attribute-data '<json>' 重新运行，或使用 --draft 发布为未激活草稿稍后补充。",
+        "pub_need_attribute_mapping_title": "部分列未能自动匹配",
+        "pub_need_attribute_mapping_description": "以下 Excel/CSV 列未能明确匹配到类目属性，因此未绑定。请确认每列应对应哪个属性，然后用下方展示的规范属性名通过 --attribute-data 重新运行（若该列不是商品属性则可删除）。",
+        "pub_need_attribute_mapping_next": "使用下方建议的属性名之一，通过 --attribute-data '{\"<属性名>\": \"<值>\"}' 重新运行；若不需要该列则删除。",
         "pub_html_cleaned_notice": "商品描述已清理：不安全的 HTML 标签（script、iframe、style 属性等）已被移除。仅保留安全格式标签（p、br、b、ul、li 等）。",
         "pub_create_pending_review": "商品提交成功，目前正在接受 Miravia 审核，暂不可售；审核最长可能需要 48 小时，特别是需要包装照片或文件时。审核通过后会自动激活，如被拒绝请在“已暂停(Suspended)”选项卡中查看。",
         "pub_pdp_link": "商品详情页：{url}",

package/dist/scripts/product_client.py

@@ -365,8 +365,10 @@ class ProductClient:
         # when absent, publish_module._check_dbm_limits applies the default
         # (DBM generally, DBS if the seller has DBS permission).
         _dm = str(data.get("delivery_method") or "").strip().upper()
-        if _dm in ("DBM", "DBS"):
-            attributes["deliverySof"] = _dm
+        if "DBS" in _dm:
+            attributes["deliverySof"] = "DBS"
+        elif "DBM" in _dm:
+            attributes["deliverySof"] = "DBM"
 
         product_payload: Dict[str, Any] = {
             "PrimaryCategory": category_id,

package/dist/scripts/product_skill.py

@@ -373,6 +373,25 @@ def _print_conversational_result(result: Dict[str, Any]) -> None:
             print(f"• {action}")
         return
 
+    # Unmapped Excel/CSV columns needing a confirmed attribute mapping
+    if status == "need_attribute_mapping":
+        print(result.get("title", ""))
+        print(result.get("message", ""))
+        print()
+        for item in result.get("unmapped_columns", []):
+            print(f"  列 \"{item.get('header')}\" = {item.get('value')} 可能对应：")
+            for c in item.get("candidates", []):
+                mand = "（必填）" if str(c.get("is_mandatory")) == "1" else ""
+                print(
+                    f"    - {c.get('label')} "
+                    f"[name={c.get('name')}, en_name={c.get('en_name')}, "
+                    f"type={c.get('attribute_type')}]{mand}"
+                )
+            print()
+        for action in result.get("next_actions", []):
+            print(f"• {action}")
+        return
+
     if status == "need_images":
         print(result.get("message", ""))
         if result.get("failed_images"):

package/dist/scripts/publish_module.py

@@ -813,12 +813,20 @@ class PublishModule:
         """
         attrs = product_payload.setdefault("Attributes", {})
         delivery_method = str(attrs.get("deliverySof") or "").strip().upper()
+        downgraded_from_dbs = False
 
-        # Default when there is no explicit entry: DBS if the seller is
-        # permitted, otherwise DBM.
         if delivery_method not in ("DBM", "DBS"):
+            # No explicit entry: default to DBS when the seller is permitted,
+            # otherwise DBM.
             delivery_method = "DBS" if has_dbs_permission else "DBM"
             attrs["deliverySof"] = delivery_method
+        elif delivery_method == "DBS" and not has_dbs_permission:
+            # Seller explicitly chose DBS but the account has no DBS permission:
+            # never grant DBS without permission — fall back to DBM and still
+            # enforce the DBM package limits below.
+            delivery_method = "DBM"
+            attrs["deliverySof"] = "DBM"
+            downgraded_from_dbs = True
 
         # Only DBM carries package limits.
         if delivery_method != "DBM":
@@ -856,6 +864,11 @@ class PublishModule:
             )
 
         if not exceeded:
+            if downgraded_from_dbs:
+                return {
+                    "downgraded_to_dbm": True,
+                    "message": i18n._("pub_dbs_no_permission_downgrade"),
+                }
             return None
 
         # Exceeded DBM limits — check DBS permission
@@ -907,6 +920,7 @@ class PublishModule:
         # Check DBM limits — auto-switch to DBS if exceeded (requires DBS permission)
         has_dbs = self.product.get_shipping_permission()
         dbm_result = self._check_dbm_limits(product_payload, has_dbs_permission=has_dbs)
+        dbm_notes: List[str] = []
         if dbm_result:
             if dbm_result.get("blocked"):
                 # No DBS permission and exceeds DBM limits — block
@@ -919,10 +933,12 @@ class PublishModule:
                     ],
                 }
             if dbm_result.get("switched_to_dbs"):
-                if draft_issues is not None:
-                    draft_issues.append(dbm_result["message"])
-                    for reason in dbm_result.get("reasons", []):
-                        draft_issues.append(f"  - {reason}")
+                dbm_notes.append(dbm_result["message"])
+                dbm_notes.extend(f"  - {r}" for r in dbm_result.get("reasons", []))
+            if dbm_result.get("downgraded_to_dbm"):
+                # Seller asked for DBS but has no DBS permission — explain the
+                # fallback so the delivery-method change is not silent.
+                dbm_notes.append(dbm_result["message"])
 
         # Run pre-validate early so errors are visible in the preview
         prevalidate_result = self._run_prevalidate(product_payload)
@@ -935,6 +951,7 @@ class PublishModule:
 
         # Merge all issues for preview
         all_issues = list(draft_issues or [])
+        all_issues.extend(dbm_notes)
         if prevalidate_errors:
             all_issues.extend(prevalidate_errors)
 
@@ -1340,11 +1357,25 @@ class PublishModule:
             draft=draft_requested,
         )
 
+        # Explicit --attribute-data must reach the AI payload too (it used to be
+        # honored only in the manual flow, so AI-mode values were silently
+        # dropped). Applied before unmatched-column binding so explicit values win.
+        self._apply_attribute_data_override(product_payload)
+
         # Bind extra Excel/CSV columns that the whitelist did not recognize,
         # using the category attribute definitions fetched above.
-        self._unmapped_columns = self._apply_unmatched_category_attributes(
+        unmapped_cols = self._apply_unmatched_category_attributes(
             product_payload, schema, category_attributes
         )
+        self._unmapped_columns = unmapped_cols
+
+        # If a provided column could not be confidently matched but plausibly
+        # maps to one or more category attributes, ask the seller to confirm the
+        # mapping instead of silently dropping it (which would otherwise surface
+        # later as a cryptic batchValidate "missing attribute" error).
+        mapping_check = self._check_unmapped_columns(unmapped_cols, product_payload)
+        if mapping_check:
+            return mapping_check
 
         # Stage 3b: unified compliance check (GPSR + Safety Warning + compliance docs)
         draft_issues: list = []
@@ -1672,15 +1703,19 @@ class PublishModule:
         """
         confirmed_brand_id = getattr(self.args, "confirmed_brand_id", None)
         if confirmed_brand_id:
+            # Honor an explicitly passed --brand-name too (aligns with the
+            # manual flow's _resolve_brand_interactive). Otherwise a seller who
+            # confirms by ID but whose source lacks the brand name would have
+            # the brand silently dropped from the payload.
             return {
                 "brand_id": int(confirmed_brand_id),
-                "brand_name": schema.brand_name or "",
+                "brand_name": getattr(self.args, "brand_name", None) or schema.brand_name or "",
             }
 
         if schema.brand_id:
             return {
                 "brand_id": int(schema.brand_id),
-                "brand_name": schema.brand_name or "",
+                "brand_name": getattr(self.args, "brand_name", None) or schema.brand_name or "",
             }
 
         brand_name = self.args.brand_name or schema.brand_name
@@ -2179,8 +2214,9 @@ class PublishModule:
         value under the attribute's canonical key — into each SKU for
         ``attribute_type == 'sku'``, otherwise into the product-level
         ``Attributes``. Existing keys are never overwritten (whitelist/LLM
-        values win). Returns the headers that matched no category attribute
-        so the caller can surface them instead of silently dropping them.
+        values win). Returns a list of ``{header, value, candidates}`` for the
+        headers that matched no category attribute confidently, so the caller can
+        ask the seller to confirm the mapping instead of silently dropping them.
 
         We intentionally bind ONLY the non-whitelisted columns here. Columns
         the whitelist already consumed (Title/Price/Image/Color/Stock/...) are
@@ -2196,11 +2232,31 @@ class PublishModule:
             return []
         attributes = product_payload.setdefault("Attributes", {})
         skus = (product_payload.get("Skus") or {}).get("Sku") or []
-        unmapped: List[str] = []
+        unmapped: List[Dict[str, Any]] = []
         for header, value in unmatched.items():
             attr = self._find_category_attribute(category_attributes, (header,))
             if not attr:
-                unmapped.append(header)
+                # No confident match: collect the header with fuzzy candidates so
+                # the caller can ask the seller to confirm the intended attribute
+                # instead of silently dropping the column.
+                unmapped.append(
+                    {
+                        "header": header,
+                        "value": value,
+                        "candidates": [
+                            {
+                                "name": c.get("name"),
+                                "en_name": c.get("en_name"),
+                                "label": c.get("label") or c.get("en_name") or c.get("name"),
+                                "attribute_type": c.get("attribute_type") or "normal",
+                                "is_mandatory": str(c.get("is_mandatory", "0")),
+                            }
+                            for c in self._suggest_attribute_candidates(
+                                header, category_attributes
+                            )
+                        ],
+                    }
+                )
                 continue
             key = attr.get("name") or attr.get("en_name") or header
             if (attr.get("attribute_type") or "normal") == "sku":
@@ -2212,11 +2268,122 @@ class PublishModule:
                     attributes[key] = value
         if unmapped:
             logger.info(
-                "Excel/CSV columns not matching any category attribute: %s",
-                ", ".join(unmapped),
+                "Excel/CSV columns not confidently matched: %s",
+                ", ".join(u["header"] for u in unmapped),
             )
         return unmapped
 
+    def _suggest_attribute_candidates(
+        self,
+        header: str,
+        category_attributes: List[Dict[str, Any]],
+        max_candidates: int = 8,
+    ) -> List[Dict[str, Any]]:
+        """Fuzzy-suggest category attributes a free-text column header might map
+        to — for the confirmation prompt only, never auto-bound.
+
+        Uses a shared-prefix (stem) heuristic so e.g. header ``packaging``
+        suggests ``Package_Label_Photo_EU``. Deliberately looser than
+        ``_find_category_attribute`` because a human confirms the result.
+        """
+        def _words(text: Any) -> List[str]:
+            return [w for w in re.split(r"[^a-z0-9]+", str(text).lower()) if len(w) >= 4]
+
+        header_words = set(_words(header))
+        h_sq = self._squash_attr_name(header)
+        if h_sq:
+            header_words.add(h_sq)
+        out: List[Dict[str, Any]] = []
+        for attr in category_attributes or []:
+            attr_words: List[str] = []
+            for key in ("name", "en_name", "label", "attribute_name"):
+                if attr.get(key):
+                    attr_words.extend(_words(attr.get(key)))
+                    attr_words.append(self._squash_attr_name(attr.get(key)))
+            hit = False
+            for hw in header_words:
+                for aw in attr_words:
+                    if (
+                        len(hw) >= 5
+                        and len(aw) >= 5
+                        and hw[:5] == aw[:5]
+                    ) or hw in aw or aw in hw:
+                        hit = True
+                        break
+                if hit:
+                    break
+            if hit:
+                out.append(attr)
+                if len(out) >= max_candidates:
+                    break
+        return out
+
+    def _apply_attribute_data_override(self, product_payload: Dict[str, Any]) -> None:
+        """Merge ``--attribute-data`` into the AI-built payload.
+
+        The AI flow builds Attributes/Skus from the extracted schema and never
+        consulted ``--attribute-data``, so values passed there were silently
+        dropped. ``--attribute-data`` is the seller's own explicit input, so it
+        overrides extracted values; SKU-level keys are merged into every SKU.
+        """
+        raw = getattr(self.args, "attribute_data", None)
+        if not raw:
+            return
+        try:
+            data = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"--attribute-data is not valid JSON: {exc}") from exc
+        if not isinstance(data, dict):
+            raise ValueError("--attribute-data must be a JSON object")
+        attributes = product_payload.setdefault("Attributes", {})
+        skus = (product_payload.get("Skus") or {}).get("Sku") or []
+        for key, value in data.items():
+            if key in _SKU_LEVEL_ATTRIBUTE_NAMES:
+                for sku in skus:
+                    sku[key] = value
+            else:
+                attributes[key] = value
+
+    def _check_unmapped_columns(
+        self,
+        unmapped_cols: List[Dict[str, Any]],
+        product_payload: Dict[str, Any],
+    ) -> Optional[Dict[str, Any]]:
+        """Return a ``need_attribute_mapping`` prompt when an unmapped column
+        looks like a category attribute the seller intended, so they confirm the
+        mapping instead of us dropping it silently (which would later surface as
+        a cryptic batchValidate "missing attribute" error). Columns with no
+        plausible candidate — or whose candidates are already filled via
+        ``--attribute-data`` — are ignored.
+        """
+        attributes = product_payload.get("Attributes") or {}
+        skus = (product_payload.get("Skus") or {}).get("Sku") or []
+
+        def _filled(cand: Dict[str, Any]) -> bool:
+            names = [cand.get("name"), cand.get("en_name")]
+
+            def _present(container: Dict[str, Any]) -> bool:
+                return any(n and str(container.get(n) or "").strip() for n in names)
+
+            if (cand.get("attribute_type") or "normal") == "sku":
+                return bool(skus) and all(_present(s) for s in skus)
+            return _present(attributes)
+
+        need: List[Dict[str, Any]] = []
+        for item in unmapped_cols or []:
+            open_cands = [c for c in (item.get("candidates") or []) if not _filled(c)]
+            if open_cands:
+                need.append({**item, "candidates": open_cands})
+        if not need:
+            return None
+        return {
+            "status": "need_attribute_mapping",
+            "title": i18n._("pub_need_attribute_mapping_title"),
+            "message": i18n._("pub_need_attribute_mapping_description"),
+            "unmapped_columns": need,
+            "next_actions": [i18n._("pub_need_attribute_mapping_next")],
+        }
+
     def _field_is_required(
         self,
         field_key: str,
@@ -2503,7 +2670,7 @@ class PublishModule:
         confirmed_brand_id = getattr(self.args, "confirmed_brand_id", None)
         if confirmed_brand_id:
             return {
-                "brand_name": schema.brand_name or "",
+                "brand_name": getattr(self.args, "brand_name", None) or schema.brand_name or "",
                 "brand_id": int(confirmed_brand_id),
             }
 
@@ -2642,7 +2809,11 @@ class PublishModule:
 
         Per the Miravia ``/product/create`` documentation:
 
-        - ``SellerSku`` is mandatory for every SKU.
+        - ``SellerSku`` is NOT hard-coded mandatory: whether it must be filled is
+          governed by the category attribute API and enforced once in
+          :meth:`_validate_create_payload` (via ``seller_sku_required``), which
+          applies to both Draft and online publishes. Here we simply omit an
+          empty SellerSku so ``/product/create`` can auto-generate a value.
         - Package dimensions/weight are per-SKU fields
           (``package_length/width/height/weight``).
         - Sales properties are flat SKU fields, not a nested ``Variation``
@@ -2671,11 +2842,11 @@ class PublishModule:
             seller_sku = raw.get("seller_sku") or (
                 schema.seller_skus[idx] if idx < len(schema.seller_skus) else None
             )
-            if not seller_sku:
-                raise ValueError(
-                    i18n._("pub_seller_sku_required", idx=idx + 1)
-                )
-            sku["SellerSku"] = seller_sku
+            # Do NOT hard-require SellerSku here. Its mandatory-ness comes from
+            # the category attribute API and is enforced in _validate_create_payload
+            # (not relaxed by draft). Omit empty values so create can auto-generate.
+            if seller_sku:
+                sku["SellerSku"] = seller_sku
 
             ean_code = raw.get("ean_code") or (
                 schema.ean_codes[idx] if idx < len(schema.ean_codes) else None
@@ -3186,10 +3357,11 @@ class PublishModule:
                 processed["SellerSku"] = processed.pop("seller_sku")
             elif "seller_sku" in processed:
                 processed.pop("seller_sku")  # SellerSku already set
+            # SellerSku is optional (governed by the category attribute API and
+            # enforced in _validate_create_payload, not relaxed by draft). When
+            # empty, drop the key so /product/create can auto-generate it.
             if not processed.get("SellerSku"):
-                raise ValueError(
-                    i18n._("pub_seller_sku_required", idx=idx + 1)
-                )
+                processed.pop("SellerSku", None)
             # Migrate SKU-level images
             sku_images = processed.get("Images", {}).get("Image", [])
             if sku_images:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miravia_test/miravia-publish-skill",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Miravia Product Publish Skill installer — one command to install the Miravia AI product listing skill into any AI Agent (Qoder / Cursor / Claude Code). Upload materials and let the AI extract data and publish products automatically.",
   "bin": {
     "miravia-publish-skill": "bin/cli.js"