feat: multi-source label index, parse_title_fields, OrderPage data split

Address structural-parsing recall problems found via live engine testing
on funpaybotengine PR #35: structure built from data-fields JSON keeps
English IDs while OfferPage / OrderPage render localized labels, leaving
get_structured_fields with ~1/8 recall on real data.

- SubcategoryFieldDef gains casefolded `aliases: set[str]`; OfferFieldsParser
  registers field id and form <label> as aliases. label_map / lower_label_map
  now index aliases. New `lookup_field_id`, `add_alias`, and heuristic
  `enrich_from_offer` (matches by SELECT/DROPDOWN option value).

- OfferPreview / OrderPreview gain `parse_title_fields(structure)` (cherry-
  picked from the lost feature/subcategory-structure-parser commits and
  adapted to the dict-based fields layout). SELECT/DROPDOWN segments are
  validated against `options`; unmatched segments are dropped.

- OrderPage data is split into `metadata` (canonical RU/EN/UA-aware order
  fields) and `lot_fields` (everything else). `get_structured_fields` now
  reads `lot_fields` only, eliminating false positives from order-metadata
  labels colliding with structural ones. `data` is preserved for back-compat.

- FieldCondition and SubcategoryStructure now extend FunPayObject with
  `raw_source`, removing the need for the asdict() shim in engine
  pydantic validators.

- Bump 0.8.0 -> 0.8.2.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Flummy1

funpayparsers/parsers/offer_fields_parser.py

@@ -119,13 +119,19 @@ def _parse_field_def(
 
         options = cls._parse_options(form_group, field_type)
 
+        # Index the field's own ID and the form ``<label>`` text as aliases
+        # so cross-locale label lookups (data-fields JSON key vs. localized
+        # ``<label>``) resolve to the same field via ``label_map``.
+        aliases = {field_id, label}
+
         return SubcategoryFieldDef(
             raw_source=raw_source,
             id=field_id,
             type=field_type,
             label=label,
             conditions=conditions,
             options=options,
+            aliases=aliases,
         )
 
     @staticmethod
@@ -141,7 +147,13 @@ def _parse_conditions(raw_conditions: list[dict[str, Any]]) -> list[FieldConditi
                     f'Unrecognized condition format: {cond!r}. '
                     f"Expected one of 'list' or 'value' keys."
                 )
-            result.append(FieldCondition(field_id=cond['id'], values=set(values)))
+            result.append(
+                FieldCondition(
+                    raw_source=json.dumps(cond, ensure_ascii=False),
+                    field_id=cond['id'],
+                    values=set(values),
+                )
+            )
         return result
 
     @staticmethod

funpayparsers/parsers/page_parsers/order_page_parser.py

@@ -13,6 +13,7 @@
 from funpayparsers.parsers.chat_parser import ChatParser, ChatParsingOptions
 from funpayparsers.parsers.appdata_parser import AppDataParser, AppDataParsingOptions
 from funpayparsers.parsers.reviews_parser import ReviewsParser, ReviewsParsingOptions
+from funpayparsers.types.pages.order_page import _split_order_data
 from funpayparsers.parsers.page_header_parser import (
     PageHeaderParser,
     PageHeaderParsingOptions,
@@ -90,6 +91,8 @@ def _parse(self) -> OrderPage:
 
             data[name[0].text().strip().lower()] = value[-1].text().strip()
 
+        metadata, lot_fields = _split_order_data(data)
+
         subcategory_url: str = self.tree.css_first(  # type: ignore[assignment,union-attr]
             'div.param-item:has(h5):not(:has(ul, ol)) a',
             strict=False,
@@ -127,4 +130,6 @@ def _parse(self) -> OrderPage:
                 options=self.options.chat_parsing_options,
             ).parse(),
             data=data,
+            metadata=metadata,
+            lot_fields=lot_fields,
         )

funpayparsers/parsers/page_parsers/subcategory_page_parser.py

@@ -88,6 +88,7 @@ def _parse(self) -> SubcategoryPage:
         if lot_fields_div is not None:
             field_schema = OfferFieldsParser.parse_field_schema(lot_fields_div)
             structure = SubcategoryStructure(
+                raw_source=lot_fields_div.html or '',
                 subcategory_id=int(subcategory_id_str.split('-')[-1]),
                 fields={f.id: f for f in field_schema},
             )

funpayparsers/types/offers.py

@@ -105,6 +105,23 @@ class OfferPreview(FunPayObject):
     subcategory_type: SubcategoryType = SubcategoryType.UNKNOWN
     """Type of the subcategory (OFFERS/CHIPS), derived from the offer URL."""
 
+    def parse_title_fields(
+        self, structure: SubcategoryStructure
+    ) -> dict[str, str | int]:
+        """
+        Extract structural field values from this preview's ``title``.
+
+        FunPay appends ``NUMERIC_RANGE``, ``SELECT``, and ``DROPDOWN`` field
+        values to the offer title in declaration order. This method matches
+        the trailing comma-separated segments of ``title`` against
+        *structure*'s field definitions and returns a mapping of
+        ``field_id`` → value.
+
+        Returns an empty dict if ``title`` is ``None`` or no segment matches.
+        """
+        from funpayparsers.types.subcategory_structure import _parse_title_fields
+        return _parse_title_fields(self.title, structure)
+
 
 T = TypeVar('T')
 P = ParamSpec('P')

funpayparsers/types/orders.py

@@ -14,6 +14,7 @@
 
 if TYPE_CHECKING:
     from funpayparsers.types.common import UserPreview
+    from funpayparsers.types.subcategory_structure import SubcategoryStructure
 
 
 @dataclass
@@ -41,6 +42,18 @@ class OrderPreview(FunPayObject):
     counterparty: UserPreview
     """Associated counterparty info."""
 
+    def parse_title_fields(
+        self, structure: SubcategoryStructure
+    ) -> dict[str, str | int]:
+        """
+        Extract structural field values from this preview's ``title``.
+
+        See :meth:`OfferPreview.parse_title_fields` for details — order titles
+        share the same comma-separated suffix layout as offer titles.
+        """
+        from funpayparsers.types.subcategory_structure import _parse_title_fields
+        return _parse_title_fields(self.title, structure)
+
     @property
     def timestamp(self) -> int:
         """

funpayparsers/types/pages/order_page.py

@@ -1,11 +1,11 @@
 from __future__ import annotations
 
 
-__all__ = ('OrderPage',)
+__all__ = ('OrderPage', 'ORDER_METADATA_LABELS')
 
 import re
 from typing import TYPE_CHECKING
-from dataclasses import dataclass
+from dataclasses import field, dataclass
 
 from funpayparsers.types.chat import Chat
 from funpayparsers.types.enums import OrderStatus, SubcategoryType
@@ -19,6 +19,55 @@
     from funpayparsers.types.subcategory_structure import SubcategoryStructure
 
 
+# Stable order-metadata labels rendered by FunPay regardless of the lot's
+# subcategory. Keys are the canonical metadata names, values are the set of
+# casefolded label variants that may appear in ``param-list`` (RU/EN/UA).
+# Anything not in this map is treated as a lot-specific field and routed to
+# ``OrderPage.lot_fields`` instead of ``OrderPage.metadata``.
+ORDER_METADATA_LABELS: dict[str, frozenset[str]] = {
+    'game': frozenset({'game', 'игра', 'гра'}),
+    'category': frozenset({'category', 'категория', 'категорія'}),
+    'short_description': frozenset(
+        {'short description', 'краткое описание', 'короткий опис'}
+    ),
+    'detailed_description': frozenset(
+        {'detailed description', 'подробное описание', 'докладний опис'}
+    ),
+    'amount': frozenset({'amount', 'количество', 'кількість'}),
+    'open': frozenset({'open', 'открыт', 'відкрито'}),
+    'closed': frozenset({'closed', 'закрыт', 'закрито'}),
+    'total': frozenset({'total', 'сумма', 'сума'}),
+}
+
+_LABEL_TO_METADATA_KEY: dict[str, str] = {
+    label: canonical
+    for canonical, variants in ORDER_METADATA_LABELS.items()
+    for label in variants
+}
+
+
+def _split_order_data(
+    data: dict[str, str],
+) -> tuple[dict[str, str], dict[str, str]]:
+    """
+    Split ``param-list`` data into ``(metadata, lot_fields)``.
+
+    *data* keys are casefolded labels as parsed by ``OrderPageParser``.
+    Metadata labels (see :data:`ORDER_METADATA_LABELS`) are extracted under
+    their canonical key; everything else is preserved verbatim in
+    ``lot_fields``. The two resulting dicts are disjoint.
+    """
+    metadata: dict[str, str] = {}
+    lot_fields: dict[str, str] = {}
+    for label, value in data.items():
+        canonical = _LABEL_TO_METADATA_KEY.get(label)
+        if canonical is not None and canonical not in metadata:
+            metadata[canonical] = value
+        else:
+            lot_fields[label] = value
+    return metadata, lot_fields
+
+
 @dataclass
 class OrderPage(FunPayPage):
     """Represents an order page (`https://funpay.com/orders/<order_id>/`)."""
@@ -42,43 +91,55 @@ class OrderPage(FunPayPage):
     """Order subcategory type."""
 
     data: dict[str, str]
-    """Order data (short description, full description, etc.)"""
+    """
+    Raw, flat ``param-list`` data — keys are casefolded labels.
+
+    Kept for backwards compatibility. Prefer ``metadata`` for stable
+    order-level fields and ``lot_fields`` for lot-specific fields.
+    """
 
     review: Review | None
     """Order review."""
 
     chat: Chat
     """Chat with counterparty."""
 
+    metadata: dict[str, str] = field(default_factory=dict)
+    """
+    Stable order metadata, keyed by canonical name (see
+    :data:`ORDER_METADATA_LABELS`). Possible keys: ``game``, ``category``,
+    ``short_description``, ``detailed_description``, ``amount``, ``open``,
+    ``closed``, ``total``. Only keys actually present on the page are stored.
+    """
+
+    lot_fields: dict[str, str] = field(default_factory=dict)
+    """
+    Lot-specific fields from ``param-list`` — everything in ``data`` that is
+    not part of ``metadata``. Keys are casefolded labels, values are display
+    strings. This is the input for :meth:`get_structured_fields`.
+    """
+
     def get_structured_fields(self, structure: SubcategoryStructure) -> dict[str, str]:
-        """Return ``data`` remapped to FunPay field IDs using *structure*'s label map."""
+        """Return ``lot_fields`` remapped to FunPay field IDs using *structure*'s label map."""
         return {
             structure.lower_label_map[label][0]: val
-            for label, val in self.data.items()
+            for label, val in self.lot_fields.items()
             if label in structure.lower_label_map
         }
 
-    def _first_found(self, names: list[str]) -> str | None:
-        for i in names:
-            if self.data.get(i) is not None:
-                return self.data[i]
-        return None
-
     @property
     def short_description(self) -> str | None:
         """Order short description (title)."""
-
-        return self._first_found(['short description', 'краткое описание', 'короткий опис'])
+        return self.metadata.get('short_description')
 
     @property
     def full_description(self) -> str | None:
         """Order full description (detailed description)."""
-
-        return self._first_found(['detailed description', 'подробное описание', 'докладний опис'])
+        return self.metadata.get('detailed_description')
 
     @property
     def amount(self) -> int | None:
-        amount_str = self._first_found(['amount', 'количество', 'кількість'])
+        amount_str = self.metadata.get('amount')
         if not amount_str:
             return None
         return int(re.search(r'\d+', amount_str).group())  # type: ignore[union-attr]
@@ -87,39 +148,35 @@ def amount(self) -> int | None:
     @property
     def open_date_text(self) -> str | None:
         """Order open date."""
-
-        date_str = self._first_found(['open', 'открыт', 'відкрито'])
+        date_str = self.metadata.get('open')
         if not date_str:
             return None
         return date_str.split('\n')[0].strip()
 
     @property
     def close_date_text(self) -> str | None:
         """Order close date."""
-
-        date_str = self._first_found(['closed', 'закрыт', 'закрито'])
+        date_str = self.metadata.get('closed')
         if not date_str:
             return None
         return date_str.split('\n')[0].strip()
 
     @property
     def order_category_name(self) -> str | None:
         """Order category name."""
-
-        return self._first_found(['game', 'игра', 'гра'])
+        return self.metadata.get('game')
 
     @property
     def order_subcategory_name(self) -> str | None:
         """Order subcategory name."""
-
-        return self._first_found(['category', 'категория', 'категорія'])
+        return self.metadata.get('category')
 
     @property
     def order_total(self) -> MoneyValue | None:
         """Order total."""
         from funpayparsers.parsers.utils import parse_money_value_string
 
-        value = self._first_found(['total', 'сумма', 'сума'])
+        value = self.metadata.get('total')
         if not value:
             return None
         return parse_money_value_string(value)