feat: stock page and graded cards

Author: Leoglme

api/migrations/006_article_graded.sql

@@ -0,0 +1,6 @@
+-- Cartes gradées (slab) : société + note eBay + certificat optionnel ; Vinted « Neuf avec étiquette ».
+
+ALTER TABLE articles ADD COLUMN IF NOT EXISTS is_graded TINYINT(1) NOT NULL DEFAULT 0;
+ALTER TABLE articles ADD COLUMN IF NOT EXISTS graded_grader_value_id VARCHAR(16) NULL;
+ALTER TABLE articles ADD COLUMN IF NOT EXISTS graded_grade_value_id VARCHAR(16) NULL;
+ALTER TABLE articles ADD COLUMN IF NOT EXISTS graded_cert_number VARCHAR(32) NULL;

api/models/article.py

@@ -23,6 +23,15 @@ class Article(Base):
     set_code: Mapped[str | None] = mapped_column(String(64), nullable=True)
     card_number: Mapped[str | None] = mapped_column(String(64), nullable=True)
     condition: Mapped[str] = mapped_column(String(64), default="Near Mint")
+    is_graded: Mapped[bool] = mapped_column(
+        Boolean(),
+        default=False,
+        server_default="0",
+        nullable=False,
+    )
+    graded_grader_value_id: Mapped[str | None] = mapped_column(String(16), nullable=True)
+    graded_grade_value_id: Mapped[str | None] = mapped_column(String(16), nullable=True)
+    graded_cert_number: Mapped[str | None] = mapped_column(String(32), nullable=True)
     purchase_price: Mapped[Decimal] = mapped_column(Numeric(12, 2))
     sell_price: Mapped[Decimal | None] = mapped_column(Numeric(12, 2), nullable=True)
     # Actual proceeds; sale_source is vinted | ebay

api/routes/articles.py

@@ -27,6 +27,10 @@
 from services.vinted_batch_session_service import VintedBatchSessionService as vinted_batch_hub
 from services.vinted_progress_session_service import VintedProgressSessionService as vinted_progress_hub
 from services import supabase_storage_service
+from services.ebay_trading_card_grading import (
+    is_valid_grade_value_id,
+    is_valid_grader_value_id,
+)
 from services.vinted_background_service import VintedBackgroundService
 from services.vinted_batch_background_service import VintedBatchBackgroundService
 
@@ -66,6 +70,18 @@ def _parse_sold_at_iso(value: str | None) -> dt.datetime | None:
         ) from exc
 
 
+def _validate_graded_article_or_raise(article: Article) -> None:
+    if not article.is_graded:
+        return
+    if not is_valid_grader_value_id(article.graded_grader_value_id) or not is_valid_grade_value_id(
+        article.graded_grade_value_id
+    ):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Carte gradée : choisissez une société de grading et une note (identifiants eBay).",
+        )
+
+
 def _parse_optional_iso_dt(value: str | None) -> dt.datetime | None:
     """Parse ISO-ish datetime without raising (e.g. wardrobe import)."""
     if value is None or not str(value).strip():
@@ -421,6 +437,10 @@ async def create_article(
     sold_at: str | None = Form(None),
     wardrobe_vinted_listed: str | None = Form(None),
     vinted_published_at: str | None = Form(None),
+    is_graded: str | None = Form(None),
+    graded_grader_value_id: str | None = Form(None),
+    graded_grade_value_id: str | None = Form(None),
+    graded_cert_number: str | None = Form(None),
     images: list[UploadFile] | None = File(None),
 ) -> dict[str, Any]:
     settings = get_settings()
@@ -442,6 +462,16 @@ async def create_article(
         elif _form_bool(wardrobe_vinted_listed):
             sale_src = "vinted"
 
+    graded_flag = _form_bool(is_graded)
+    grader_vid = (graded_grader_value_id or "").strip() or None
+    grade_vid = (graded_grade_value_id or "").strip() or None
+    cert_raw = (graded_cert_number or "").strip()
+    cert_norm = cert_raw[:30] if cert_raw else None
+    if not graded_flag:
+        grader_vid = None
+        grade_vid = None
+        cert_norm = None
+
     article = Article(
         user_id=user.id,
         title=title.strip(),
@@ -450,13 +480,18 @@ async def create_article(
         set_code=set_code.strip() if set_code else None,
         card_number=card_number.strip() if card_number else None,
         condition=condition.strip() or "Near Mint",
+        is_graded=graded_flag,
+        graded_grader_value_id=grader_vid,
+        graded_grade_value_id=grade_vid,
+        graded_cert_number=cert_norm,
         purchase_price=_parse_decimal_required(purchase_price),
         sell_price=sell_dec,
         sold_price=proceeds_dec if sold_flag else None,
         sale_source=sale_src,
         is_sold=sold_flag,
         sold_at=sold_at_dt if sold_flag else None,
     )
+    _validate_graded_article_or_raise(article)
 
     if _form_bool(wardrobe_vinted_listed):
         article.published_on_vinted = True
@@ -580,17 +615,8 @@ def update_article(
     article = article_service.get_article(db, article_id, user.id)
     if article is None:
         raise HTTPException(status_code=404, detail="Article not found")
-    article_service.update_article_fields(
-        article,
-        title=body.title,
-        description=body.description,
-        pokemon_name=body.pokemon_name,
-        set_code=body.set_code,
-        card_number=body.card_number,
-        condition=body.condition,
-        purchase_price=body.purchase_price,
-        sell_price=body.sell_price,
-    )
+    article_service.update_article_from_body(article, body)
+    _validate_graded_article_or_raise(article)
     db.commit()
     db.refresh(article)
     return article_service.article_to_dict(article)

api/schemas/articles.py

@@ -11,6 +11,10 @@ class ArticleUpdate(BaseModel):
     set_code: str | None = None
     card_number: str | None = None
     condition: str | None = None
+    is_graded: bool | None = None
+    graded_grader_value_id: str | None = None
+    graded_grade_value_id: str | None = None
+    graded_cert_number: str | None = None
     purchase_price: Decimal | None = None
     sell_price: Decimal | None = None
 

api/services/article_service.py

@@ -10,6 +10,7 @@
 
 from core.database import SessionLocal
 from models.article import Article
+from schemas.articles import ArticleUpdate
 
 
 def list_articles_for_user(db: Session, user_id: int) -> list[Article]:
@@ -40,6 +41,10 @@ def article_to_dict(article: Article) -> dict[str, Any]:
         "set_code": article.set_code,
         "card_number": article.card_number,
         "condition": article.condition,
+        "is_graded": bool(article.is_graded),
+        "graded_grader_value_id": article.graded_grader_value_id,
+        "graded_grade_value_id": article.graded_grade_value_id,
+        "graded_cert_number": article.graded_cert_number,
         "purchase_price": float(article.purchase_price),
         "sell_price": float(article.sell_price) if article.sell_price is not None else None,
         "sold_price": float(article.sold_price) if article.sold_price is not None else None,
@@ -105,31 +110,41 @@ def delete_articles_by_ids(db: Session, user_id: int, ids: list[int]) -> int:
     return int(deleted)
 
 
-def update_article_fields(
-    article: Article,
-    *,
-    title: str | None = None,
-    description: str | None = None,
-    pokemon_name: str | None = None,
-    set_code: str | None = None,
-    card_number: str | None = None,
-    condition: str | None = None,
-    purchase_price: Decimal | None = None,
-    sell_price: Decimal | None = None,
-) -> None:
-    if title is not None:
-        article.title = title
-    if description is not None:
-        article.description = description
-    if pokemon_name is not None:
-        article.pokemon_name = pokemon_name
-    if set_code is not None:
-        article.set_code = set_code
-    if card_number is not None:
-        article.card_number = card_number
-    if condition is not None:
-        article.condition = condition
-    if purchase_price is not None:
-        article.purchase_price = purchase_price
-    if sell_price is not None:
-        article.sell_price = sell_price
+def update_article_from_body(article: Article, body: ArticleUpdate) -> None:
+    """Apply a partial update from ``ArticleUpdate`` (only set fields are changed)."""
+    data = body.model_dump(exclude_unset=True)
+    if "is_graded" in data:
+        article.is_graded = bool(data["is_graded"])
+        if not article.is_graded:
+            article.graded_grader_value_id = None
+            article.graded_grade_value_id = None
+            article.graded_cert_number = None
+    if "title" in data and data["title"] is not None:
+        article.title = data["title"]
+    if "description" in data and data["description"] is not None:
+        article.description = data["description"]
+    if "pokemon_name" in data:
+        article.pokemon_name = data["pokemon_name"]
+    if "set_code" in data:
+        article.set_code = data["set_code"]
+    if "card_number" in data:
+        article.card_number = data["card_number"]
+    if "condition" in data and data["condition"] is not None:
+        article.condition = data["condition"]
+    if "purchase_price" in data and data["purchase_price"] is not None:
+        article.purchase_price = data["purchase_price"]
+    if "sell_price" in data:
+        article.sell_price = data["sell_price"]
+    if "graded_grader_value_id" in data:
+        gid = data["graded_grader_value_id"]
+        article.graded_grader_value_id = (gid.strip() if isinstance(gid, str) else None) or None
+    if "graded_grade_value_id" in data:
+        tid = data["graded_grade_value_id"]
+        article.graded_grade_value_id = (tid.strip() if isinstance(tid, str) else None) or None
+    if "graded_cert_number" in data:
+        cert = data["graded_cert_number"]
+        if cert is None:
+            article.graded_cert_number = None
+        else:
+            c = str(cert).strip()[:30]
+            article.graded_cert_number = c or None

api/services/desktop_stubs_service.py

@@ -23,6 +23,10 @@ def article_from_api_dict(d: dict[str, Any]) -> Article:
         a.set_code = d.get("set_code")
         a.card_number = d.get("card_number")
         a.condition = d.get("condition") or "Near Mint"
+        a.is_graded = bool(d.get("is_graded", False))
+        a.graded_grader_value_id = d.get("graded_grader_value_id")
+        a.graded_grade_value_id = d.get("graded_grade_value_id")
+        a.graded_cert_number = d.get("graded_cert_number")
         a.purchase_price = Decimal(str(d["purchase_price"]))
         sp = d.get("sell_price")
         a.sell_price = Decimal(str(sp)) if sp is not None else None

api/services/ebay_publish_service.py

@@ -19,6 +19,12 @@
 from models.margin_settings import MarginSettings
 from models.user import User
 from services.ebay_oauth_service import _api_base_url, refresh_user_access_token
+from services.ebay_trading_card_grading import (
+    EBAY_CONDITION_GRADED,
+    graded_condition_descriptor_payloads,
+    is_valid_grade_value_id,
+    is_valid_grader_value_id,
+)
 from services.user_settings_service import ebay_listing_config_complete, effective_ebay_category_id
 
 logger = logging.getLogger(__name__)
@@ -321,15 +327,55 @@ async def publish_article_to_ebay(
     price_str = f"{price.quantize(Decimal('0.01'))}"
 
     category_id = effective_ebay_category_id(ms).strip()
+    if article.is_graded:
+        if category_id not in _TCG_LEAF_CATEGORY_IDS:
+            await _emit_ebay(
+                progress,
+                "error",
+                "Carte gradée : la catégorie eBay doit être une feuille « cartes à jouer / TCG » (183050, 183454 ou 261328).",
+                detail="ebay_graded_requires_tcg_leaf_category",
+            )
+            return {"ok": False, "detail": "ebay_graded_requires_tcg_leaf_category"}
+        if not is_valid_grader_value_id(article.graded_grader_value_id) or not is_valid_grade_value_id(
+            article.graded_grade_value_id
+        ):
+            await _emit_ebay(
+                progress,
+                "error",
+                "Carte gradée incomplète : société et note requis.",
+                detail="ebay_graded_incomplete",
+            )
+            return {"ok": False, "detail": "ebay_graded_incomplete"}
+
     core_aspects = _product_aspects_core(article, category_id=category_id, marketplace_id=marketplace_id)
     optional_fr_aspects = _product_aspects_optional_fr(
         article, category_id=category_id, marketplace_id=marketplace_id
     )
 
+    if article.is_graded and category_id in _TCG_LEAF_CATEGORY_IDS:
+        list_condition = EBAY_CONDITION_GRADED
+        list_desc = "Carte professionnellement gradée (slab)."
+        cond_descriptors: list[dict[str, Any]] = graded_condition_descriptor_payloads(
+            grader_value_id=str(article.graded_grader_value_id),
+            grade_value_id=str(article.graded_grade_value_id),
+            certification_text=article.graded_cert_number,
+        )
+    else:
+        list_condition = _ebay_condition_for_category(category_id, article.condition)
+        list_desc = (article.condition or "")[:1000]
+        cond_descriptors = []
+        if category_id in _TCG_LEAF_CATEGORY_IDS:
+            cond_descriptors = [
+                {
+                    "name": _CARD_CONDITION_DESCRIPTOR_NAME,
+                    "values": [_card_condition_descriptor_value_id(article.condition)],
+                }
+            ]
+
     inv_payload: dict[str, Any] = {
         "availability": {"shipToLocationAvailability": {"quantity": 1}},
-        "condition": _ebay_condition_for_category(category_id, article.condition),
-        "conditionDescription": html.escape((article.condition or "")[:1000]),
+        "condition": list_condition,
+        "conditionDescription": html.escape(list_desc),
         "product": {
             "title": title,
             "description": _description_html(article),
@@ -338,13 +384,8 @@ async def publish_article_to_ebay(
         },
     }
 
-    if category_id in _TCG_LEAF_CATEGORY_IDS:
-        inv_payload["conditionDescriptors"] = [
-            {
-                "name": _CARD_CONDITION_DESCRIPTOR_NAME,
-                "values": [_card_condition_descriptor_value_id(article.condition)],
-            }
-        ]
+    if cond_descriptors:
+        inv_payload["conditionDescriptors"] = cond_descriptors
 
     headers = {
         "Authorization": f"Bearer {token}",