fix: add cardmarket order functionality

Author: Leoglme

api/core/database.py

@@ -6,7 +6,15 @@
 from sqlalchemy.orm import Session, sessionmaker
 
 from config import get_settings
-from models import Article, Base, Image, MarginSettings, User  # noqa: F401
+from models import (  # noqa: F401
+    Article,
+    Base,
+    CardmarketOrder,
+    CardmarketOrderLine,
+    Image,
+    MarginSettings,
+    User,
+)
 
 _settings = get_settings()
 engine = create_engine(

api/main.py

@@ -27,6 +27,7 @@
 from routes import settings_route
 from routes import shipping_route
 from routes import stats_route
+from routes import orders as orders_routes
 from routes import users as users_routes
 
 from core.win32_asyncio import ensure_proactor_event_loop
@@ -100,6 +101,7 @@ def health() -> dict[str, str]:
 app.include_router(users_routes.router)
 app.include_router(access_requests_routes.router)
 app.include_router(articles_routes.router)
+app.include_router(orders_routes.router)
 app.include_router(settings_route.router)
 app.include_router(ebay_route.router)
 app.include_router(ebay_market_route.router)

api/migrations/007_cardmarket_orders.sql

@@ -0,0 +1,46 @@
+-- Cardmarket purchase orders (PDF import) and link to articles
+
+CREATE TABLE IF NOT EXISTS cardmarket_orders (
+  id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
+  user_id BIGINT NOT NULL,
+  external_order_id VARCHAR(32) NOT NULL,
+  seller_username VARCHAR(255) NULL,
+  seller_display_name VARCHAR(255) NULL,
+  seller_country_code CHAR(2) NULL,
+  paid_at DATETIME(6) NULL,
+  shipped_at DATETIME(6) NULL,
+  delivered_at DATETIME(6) NULL,
+  items_subtotal DECIMAL(12, 2) NOT NULL DEFAULT 0,
+  shipping_fee DECIMAL(12, 2) NOT NULL DEFAULT 0,
+  order_total DECIMAL(12, 2) NOT NULL DEFAULT 0,
+  source_filename VARCHAR(512) NULL,
+  created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+  UNIQUE KEY uq_cardmarket_orders_user_external (user_id, external_order_id),
+  CONSTRAINT fk_cardmarket_orders_user FOREIGN KEY (user_id) REFERENCES users (id) ON DELETE CASCADE,
+  INDEX idx_cardmarket_orders_user_paid (user_id, paid_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+CREATE TABLE IF NOT EXISTS cardmarket_order_lines (
+  id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
+  order_id BIGINT NOT NULL,
+  line_index INT NOT NULL DEFAULT 0,
+  quantity INT NOT NULL DEFAULT 1,
+  raw_label VARCHAR(1024) NOT NULL,
+  pokemon_key VARCHAR(255) NULL,
+  card_number VARCHAR(64) NULL,
+  language_code VARCHAR(8) NULL,
+  condition_label VARCHAR(32) NULL,
+  set_code VARCHAR(64) NULL,
+  variant_token VARCHAR(32) NULL,
+  unit_price_eur DECIMAL(12, 2) NOT NULL,
+  UNIQUE KEY uq_cardmarket_order_lines_order_idx (order_id, line_index),
+  CONSTRAINT fk_cardmarket_order_lines_order FOREIGN KEY (order_id) REFERENCES cardmarket_orders (id) ON DELETE CASCADE,
+  INDEX idx_cardmarket_order_lines_match (pokemon_key, set_code, card_number)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+ALTER TABLE articles ADD COLUMN IF NOT EXISTS order_line_id BIGINT NULL;
+
+ALTER TABLE articles
+  ADD CONSTRAINT fk_articles_order_line
+  FOREIGN KEY (order_line_id) REFERENCES cardmarket_order_lines (id)
+  ON DELETE SET NULL;

api/migrations/008_cardmarket_order_lines_variants.sql

@@ -0,0 +1,6 @@
+-- Longer seller remarks after variant (e.g. "CHR bit of whitening in the back")
+
+ALTER TABLE cardmarket_order_lines
+  MODIFY COLUMN language_code VARCHAR(16) NULL,
+  MODIFY COLUMN condition_label VARCHAR(128) NULL,
+  MODIFY COLUMN variant_token VARCHAR(512) NULL;

api/models/__init__.py

@@ -2,8 +2,18 @@
 
 from models.article import Article
 from models.base import Base
+from models.cardmarket_order import CardmarketOrder
+from models.cardmarket_order_line import CardmarketOrderLine
 from models.image import Image
 from models.margin_settings import MarginSettings
 from models.user import User
 
-__all__ = ["Article", "Base", "Image", "MarginSettings", "User"]
+__all__ = [
+    "Article",
+    "Base",
+    "CardmarketOrder",
+    "CardmarketOrderLine",
+    "Image",
+    "MarginSettings",
+    "User",
+]

api/models/article.py

@@ -64,6 +64,12 @@ class Article(Base):
         DateTime(timezone=True),
         nullable=True,
     )
+    order_line_id: Mapped[int | None] = mapped_column(
+        ForeignKey("cardmarket_order_lines.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True,
+    )
 
     user: Mapped["User"] = relationship(back_populates="articles")
     images: Mapped[list["Image"]] = relationship(back_populates="article", cascade="all, delete-orphan")
+    order_line: Mapped["CardmarketOrderLine | None"] = relationship("CardmarketOrderLine", back_populates="articles")

api/models/cardmarket_order.py

@@ -0,0 +1,42 @@
+"""Cardmarket purchase order (imported from PDF)."""
+
+from __future__ import annotations
+
+import datetime as dt
+from decimal import Decimal
+
+from sqlalchemy import DateTime, ForeignKey, Numeric, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from models.base import Base
+
+
+class CardmarketOrder(Base):
+    """A Cardmarket order snapshot for one user."""
+
+    __tablename__ = "cardmarket_orders"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), index=True)
+    external_order_id: Mapped[str] = mapped_column(String(32), index=True)
+    seller_username: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    seller_display_name: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    seller_country_code: Mapped[str | None] = mapped_column(String(2), nullable=True)
+    paid_at: Mapped[dt.datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    shipped_at: Mapped[dt.datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    delivered_at: Mapped[dt.datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    items_subtotal: Mapped[Decimal] = mapped_column(Numeric(12, 2))
+    shipping_fee: Mapped[Decimal] = mapped_column(Numeric(12, 2))
+    order_total: Mapped[Decimal] = mapped_column(Numeric(12, 2))
+    source_filename: Mapped[str | None] = mapped_column(String(512), nullable=True)
+    created_at: Mapped[dt.datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: dt.datetime.now(dt.UTC),
+    )
+
+    lines: Mapped[list["CardmarketOrderLine"]] = relationship(
+        "CardmarketOrderLine",
+        back_populates="order",
+        cascade="all, delete-orphan",
+        order_by="CardmarketOrderLine.line_index",
+    )

api/models/cardmarket_order_line.py

@@ -0,0 +1,32 @@
+"""Single line item inside a Cardmarket order."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+
+from sqlalchemy import ForeignKey, Integer, Numeric, String, Text
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from models.base import Base
+
+
+class CardmarketOrderLine(Base):
+    """One purchased card row from a Cardmarket PDF."""
+
+    __tablename__ = "cardmarket_order_lines"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    order_id: Mapped[int] = mapped_column(ForeignKey("cardmarket_orders.id", ondelete="CASCADE"), index=True)
+    line_index: Mapped[int] = mapped_column(Integer(), default=0)
+    quantity: Mapped[int] = mapped_column(Integer(), default=1)
+    raw_label: Mapped[str] = mapped_column(Text())
+    pokemon_key: Mapped[str | None] = mapped_column(String(255), nullable=True, index=True)
+    card_number: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    language_code: Mapped[str | None] = mapped_column(String(16), nullable=True)
+    condition_label: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    set_code: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    variant_token: Mapped[str | None] = mapped_column(String(512), nullable=True)
+    unit_price_eur: Mapped[Decimal] = mapped_column(Numeric(12, 2))
+
+    order: Mapped["CardmarketOrder"] = relationship("CardmarketOrder", back_populates="lines")
+    articles: Mapped[list["Article"]] = relationship("Article", back_populates="order_line")

api/requirements.txt

@@ -30,3 +30,6 @@ vinted-scraper>=3.0.0
 
 # Shipping label PDF generation (Avery L7173 — 8 labels per A4)
 reportlab>=4.0.0
+
+# Cardmarket order PDF text extraction
+pypdf>=5.0.0

api/routes/articles.py

@@ -27,6 +27,7 @@
     VintedBatchStartBody,
 )
 from services import article_service
+from services.cardmarket_order_service import assign_article_order_line
 from services.combined_marketplace_service import CombinedMarketplaceService
 from services.ebay_background_service import EbayBackgroundService
 from services.user_settings_service import ebay_listing_config_complete, get_or_create_user_settings
@@ -53,6 +54,43 @@ def _parse_decimal_required(value: str) -> Decimal:
     return Decimal(str(value).strip())
 
 
+def _parse_optional_order_line_id(raw: str | None) -> int | None:
+    """Parse optional multipart ``order_line_id`` field."""
+    if raw is None or not str(raw).strip():
+        return None
+    try:
+        return int(str(raw).strip())
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Invalid order_line_id (expected integer).",
+        ) from exc
+
+
+def _apply_order_line_assignment(
+    db: Session,
+    user: User,
+    article: Article,
+    order_line_id: int | None,
+) -> None:
+    """Attach purchase line or translate validation errors."""
+    try:
+        assign_article_order_line(db, user.id, article, order_line_id)
+    except ValueError as exc:
+        code = str(exc)
+        if code == "purchase_line_not_found":
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Ligne d'achat introuvable ou non autorisée.",
+            ) from exc
+        if code == "purchase_line_full":
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Plus de quantité disponible sur cette ligne d'achat.",
+            ) from exc
+        raise
+
+
 def _form_bool(value: str | None) -> bool:
     if value is None or str(value).strip() == "":
         return False
@@ -466,6 +504,7 @@ async def create_article(
     graded_grader_value_id: str | None = Form(None),
     graded_grade_value_id: str | None = Form(None),
     graded_cert_number: str | None = Form(None),
+    order_line_id: str | None = Form(None),
     images: list[UploadFile] | None = File(None),
 ) -> dict[str, Any]:
     settings = get_settings()
@@ -519,6 +558,7 @@ async def create_article(
         sold_at=sold_at_dt if sold_flag else None,
     )
     _validate_graded_article_or_raise(article)
+    _apply_order_line_assignment(db, user, article, _parse_optional_order_line_id(order_line_id))
 
     if _form_bool(wardrobe_vinted_listed):
         article.published_on_vinted = True
@@ -644,6 +684,9 @@ def update_article(
         raise HTTPException(status_code=404, detail="Article not found")
     article_service.update_article_from_body(article, body)
     _validate_graded_article_or_raise(article)
+    unset = body.model_dump(exclude_unset=True)
+    if "order_line_id" in unset:
+        _apply_order_line_assignment(db, user, article, body.order_line_id)
     db.commit()
     db.refresh(article)
     return article_service.article_to_dict(article)