refactor(catalog)!: decouple materials from categories (v2.7)

Materials are now global and category-free. The category lives only on the supplier (suppliers.category_id); every category-facing query goes through the supplier edge instead of the material row. Schema (migration.sql + init_db DDL): - drop the materials.category_id column, its FK, and the v2.5 first-link-wins automation (fn_derive_material_category + trg_supplier_materials_derive_category) — the DDL runs idempotently at API startup Backend: - GET /materials?category_id=… now filters via EXISTS(supplier_materials ⋈ suppliers.category_id) - quote category filters (quotes list) use the quote's supplier category - /pm/on-the-way derives the display category from the supplier of the quote - supplier_materials links no longer derive/return a material category - expand_service: material expand=category resolves to null (kept for contract compatibility) - material create/update no longer validates or stores category_id; seed.py aligned Frontend: - material creation no longer sends category_id - formatMaterialTitle reworked to a strict order with « . » separator: [Brand] . [Material] . [Spec 1] . [Spec 2], brand deduped when the stored name already starts with it; specs separator switched from « · » to « . » Validated: python compile, api + frontend image builds (tsc + vite) clean; branch cut from the tip of prod_v4 (= origin/production, 5a9ef40 — the team's merge made them identical).
2026-09-19 13:19:26 +03:30
parent 5a9ef408ff
commit 8adfd2267f
19 changed files with 92 additions and 201 deletions
@@ -379,16 +379,16 @@ async def ensure_v26(engine: AsyncEngine) -> None:
            "VALUES (:code, :name_fa, :dimension, :si_factor, :is_base) ON CONFLICT (code) DO NOTHING",
            u,
        )
-    # v2.5 automation triggers (idempotent — DROP + CREATE keeps them in sync).
+    # v2.5/v2.6 category decoupling from materials: drop trigger, function, and column.
    await run_statement("DROP TRIGGER IF EXISTS trg_supplier_materials_derive_category ON supplier_materials")
-    await run_statement("""
-        CREATE TRIGGER trg_supplier_materials_derive_category
-            AFTER INSERT ON supplier_materials
-            FOR EACH ROW EXECUTE FUNCTION fn_derive_material_category()
-    """)
+    await run_statement("DROP FUNCTION IF EXISTS fn_derive_material_category()")
+    await run_statement("ALTER TABLE materials DROP CONSTRAINT IF EXISTS materials_category_id_fkey")
+    await run_statement("ALTER TABLE materials DROP COLUMN IF EXISTS category_id")
+
    await run_statement("DROP TRIGGER IF EXISTS trg_item_decisions_sync_price ON item_decisions")
    await run_statement("""
        CREATE TRIGGER trg_item_decisions_sync_price
            AFTER INSERT OR UPDATE OF status ON item_decisions
            FOR EACH ROW EXECUTE FUNCTION fn_sync_last_quoted_price()
    """)
+
@@ -130,14 +130,11 @@ class CategoryAttribute(Base):

 class Material(Base):
    __tablename__ = "materials"
-    # v2.5/2.6: name is GLOBALLY unique; category_id is nullable + derived.
+    # v2.6/v2.7: name is GLOBALLY unique; decoupled from categories.
    __table_args__ = (UniqueConstraint("name", name="uq_material_name"),)
    __mapper_args__ = {"eager_defaults": True}

    id: Mapped[uuid.UUID] = _uuid_pk()
-    category_id: Mapped[uuid.UUID | None] = mapped_column(
-        ForeignKey("material_categories.id", ondelete="RESTRICT")
-    )
    name: Mapped[str] = mapped_column(Text, nullable=False)
    topic: Mapped[str | None] = mapped_column(Text)  # تاپیک جلوی برنامه (Persian) — legacy
    canonical_unit_id: Mapped[int] = mapped_column(
@@ -149,7 +146,6 @@ class Material(Base):
        DateTime(timezone=True), nullable=False, server_default=func.now(), onupdate=func.now()
    )

-    category: Mapped["MaterialCategory | None"] = relationship(lazy="raise")
    canonical_unit: Mapped["Unit"] = relationship(lazy="raise")
    attribute_values: Mapped[list["MaterialAttributeValue"]] = relationship(
        back_populates="material", lazy="raise", passive_deletes=True
@@ -18,7 +18,7 @@ from app.models.catalog import (
    MaterialUnit,
    Unit,
 )
-from app.models.procurement import LineItem
+from app.models.procurement import LineItem, Supplier, SupplierMaterial
 from app.schemas.catalog import (
    MaterialAttributeValuesPut,
    MaterialCreate,
@@ -108,7 +108,16 @@ async def list_materials(
 ):
    stmt = select(Material)
    if category_id:
-        stmt = stmt.where(Material.category_id == category_id)
+        sub = (
+            select(1)
+            .select_from(SupplierMaterial)
+            .join(Supplier, Supplier.id == SupplierMaterial.supplier_id)
+            .where(
+                SupplierMaterial.material_id == Material.id,
+                Supplier.category_id == category_id,
+            )
+        )
+        stmt = stmt.where(exists(sub))
    if brand_id:
        # WHERE EXISTS brand_materials with that brand_id
        sub = select(1).where(
@@ -195,17 +195,11 @@ async def pm_on_the_way(
    # unit / category lookups for display
    unit_ids = {d.LineItem.unit_id for d in decisions}
    units = {u.id: u for u in (await db.execute(select(Unit).where(Unit.id.in_(unit_ids)))).scalars()}
-    mat_ids = {d.Material.id for d in decisions}
+    sup_cat_ids = {d.Supplier.category_id for d in decisions if d.Supplier.category_id}
    cats = {}
-    if mat_ids:
-        rows = (
-            await db.execute(
-                select(Material.id, MaterialCategory)
-                .join(MaterialCategory, MaterialCategory.id == Material.category_id)
-                .where(Material.id.in_(mat_ids))
-            )
-        ).all()
-        cats = {m_id: c for m_id, c in rows}
+    if sup_cat_ids:
+        rows = (await db.execute(select(MaterialCategory).where(MaterialCategory.id.in_(sup_cat_ids)))).scalars().all()
+        cats = {c.id: c for c in rows}

    out = []
    for d, li, q, m, sup, proj in decisions:
@@ -220,7 +214,7 @@ async def pm_on_the_way(
            "project": {"id": str(proj.id), "name": proj.name} if proj else None,
            "decided_at": to_iso(d.decided_at),
            "material": {"id": str(m.id), "name": m.name,
-                         "category": {"id": str(c.id), "name": c.name} if (c := cats.get(m.id)) else None},
+                         "category": {"id": str(c.id), "name": c.name} if (c := cats.get(sup.category_id)) else None},
            "unit": {"id": units[li.unit_id].id, "code": units[li.unit_id].code,
                     "name_fa": units[li.unit_id].name_fa} if li.unit_id in units else None,
            "ordered_qty": str(li.quantity),
@@ -39,9 +39,8 @@ router = APIRouter(prefix="/quotes", tags=["quotes"])
 def _quote_category_exists(category_id) -> exists:
    return exists(
        select(1).where(
-            LineItem.quote_id == Quote.id,
-            Material.id == LineItem.material_id,
-            Material.category_id == category_id,
+            Supplier.id == Quote.supplier_id,
+            Supplier.category_id == category_id,
        )
    )

@@ -58,11 +58,7 @@ async def list_supplier_materials(
    items, meta = await paginate(stmt, page, page_size, db)
    mat_ids = {l.material_id for l in items}
    materials = {m.id: m for m in (await db.execute(select(Material).where(Material.id.in_(mat_ids)))).scalars()}
-    cat_ids = {m.category_id for m in materials.values() if m.category_id}
-    cats = {}
-    if cat_ids:
-        cats = {c.id: c for c in (await db.execute(select(MaterialCategory).where(MaterialCategory.id.in_(cat_ids)))).scalars()}
-    return {"data": [link_to_dict(l, materials.get(l.material_id), cats.get(materials.get(l.material_id).category_id if l.material_id in materials else None)) for l in items], "meta": meta}
+    return {"data": [link_to_dict(l, materials.get(l.material_id), None) for l in items], "meta": meta}


@router.post("/suppliers/{supplier_id}/materials", status_code=201)
@@ -72,8 +68,7 @@ async def create_supplier_material(
    async with db.begin():
        link = await link_supplier_material(db, supplier_id, payload.material_id)
        material = await db.get(Material, payload.material_id)
-        category = await db.get(MaterialCategory, material.category_id) if material and material.category_id else None
-    return {"data": link_to_dict(link, material, category)}
+    return {"data": link_to_dict(link, material, None)}


@router.delete("/suppliers/{supplier_id}/materials/{material_id}")
@@ -89,7 +89,6 @@ class MaterialAttributeIn(APIModel):


 class MaterialCreate(APIModel):
-    category_id: UUID | None = None  # v2.5: optional — derived from first linked supplier
    name: str = Field(min_length=1)
    topic: str | None = None  # تاپیک جلوی برنامه (Persian) — legacy
    canonical_unit_id: int
@@ -37,7 +37,7 @@ class SupplierUpdate(APIModel):


 class SupplierMaterialCreate(APIModel):
-    """Link a global material to a supplier (derives materials.category_id)."""
+    """Link a global material to a supplier."""

    material_id: UUID

@@ -206,11 +206,6 @@ async def _load_material_maps(db: AsyncSession, materials: list[Material], expan
    material_ids = [m.id for m in materials]
    maps: dict = {"categories": {}, "units": {}, "brands": {}, "material_brands": {}, "mavs": {}, "attr_defs": {}}

-    if "category" in expand:
-        cat_ids = {m.category_id for m in materials}
-        rows = (await db.execute(select(MaterialCategory).where(MaterialCategory.id.in_(cat_ids)))).scalars().all()
-        maps["categories"] = {c.id: c for c in rows}
-
    unit_ids: set[int] = set()
    if "canonical_unit" in expand:
        unit_ids |= {m.canonical_unit_id for m in materials}
@@ -258,9 +253,9 @@ def _material_to_dict(m: Material, expand: set[str], maps: dict) -> dict:
        "updated_at": to_iso(m.updated_at),
    }
    if "category" in expand:
-        d["category"] = category_brief(maps["categories"].get(m.category_id))
+        d["category"] = None
    else:
-        d["category_id"] = str(m.category_id)
+        d["category_id"] = None
    if "canonical_unit" in expand:
        d["canonical_unit"] = unit_to_dict(maps["units"].get(m.canonical_unit_id))
    else:
@@ -326,9 +321,6 @@ async def _load_line_item_data(db: AsyncSession, line_items: list[LineItem], exp
        material_ids = {li.material_id for li in line_items}
        materials = (await db.execute(select(Material).where(Material.id.in_(material_ids)))).scalars().all()
        data.materials = {m.id: m for m in materials}
-        cat_ids = {m.category_id for m in materials}
-        cats = (await db.execute(select(MaterialCategory).where(MaterialCategory.id.in_(cat_ids)))).scalars().all()
-        data.categories = {c.id: c for c in cats}
        bms = (await db.execute(select(BrandMaterial).where(BrandMaterial.material_id.in_(material_ids)))).scalars().all()
        brand_ids: set[uuid.UUID] = set()
        for bm in bms:
@@ -450,7 +442,7 @@ def _line_item_expanded(li: LineItem, expand: set[str], data: _LineItemData, inc
            d["material"] = {
                "id": str(m.id),
                "name": m.name,
-                "category": category_brief(data.categories.get(m.category_id)),
+                "category": None,
                "brands": [
                    {"id": str(bm.brand_id), "name": data.brands[bm.brand_id].name, "catalog_code": bm.catalog_code}
                    for bm in data.material_brands.get(m.id, [])
@@ -12,7 +12,6 @@ from app.models.catalog import (
    BrandMaterial,
    Material,
    MaterialAttributeValue,
-    MaterialCategory,
    Unit,
 )
 from app.schemas.catalog import MaterialAttributeIn, MaterialCreate, MaterialUpdate
@@ -110,9 +109,7 @@ async def validate_attributes(
 async def create_material(db: AsyncSession, payload: MaterialCreate) -> Material:
    """Create a material + brand_materials rows + EAV values in ONE transaction.

-    v2.5/2.6: category_id is OPTIONAL — a global material may be created
-    without a category (it gets derived automatically from the first linked
-    supplier). name is GLOBALLY unique.
+    v2.6/v2.7: materials are global and category-free. name is GLOBALLY unique.
    """
    async with db.begin():
        duplicate = await db.scalar(
@@ -121,14 +118,10 @@ async def create_material(db: AsyncSession, payload: MaterialCreate) -> Material
        if duplicate is not None:
            raise ConflictError("متریالی با این نام در کل کاتالوگ قبلاً ثبت شده است", field="name")

-        if payload.category_id is not None:
-            if await db.get(MaterialCategory, payload.category_id) is None:
-                raise NotFoundError("دسته‌بندی یافت نشد", field="category_id")
        if not await db.get(Unit, payload.canonical_unit_id):
            raise NotFoundError("واحد مرجع یافت نشد", field="canonical_unit_id")

        material = Material(
-            category_id=payload.category_id,
            name=payload.name,
            topic=payload.topic,
            canonical_unit_id=payload.canonical_unit_id,
@@ -903,15 +903,12 @@ async def quote_stats(


 def _quote_has_category(category_id: UUID):
-    """EXISTS: quote has a line item whose material belongs to category_id."""
-    from app.models.catalog import Material
-
+    """EXISTS: quote's supplier belongs to category_id."""
    sub = (
        select(1)
        .where(
-            LineItem.quote_id == Quote.id,
-            Material.id == LineItem.material_id,
-            Material.category_id == category_id,
+            Supplier.id == Quote.supplier_id,
+            Supplier.category_id == category_id,
        )
    )
    return func.exists(sub)
@@ -1,10 +1,6 @@
-"""Supplier ↔ material link service (v2.5) — the direct edge of the new flow.
+"""Supplier ↔ material link service (v2.6/v2.7) — the direct edge of the catalog flow.

-Linking a material to a supplier derives materials.category_id from the
-supplier's category when the material has none (first-link-wins). The same
-rule is enforced by the DB trigger trg_supplier_materials_derive_category;
-this service applies it in the application layer so the ORM state is
-consistent inside the same transaction.
+Suppliers can supply any global material across categories.
 """
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
@@ -17,7 +13,7 @@ from app.utils.errors import NotFoundError, ValidationError
 async def link_supplier_material(
    db: AsyncSession, supplier_id, material_id, is_active: bool = True
 ) -> SupplierMaterial:
-    """Upsert a supplier<->material link (idempotent) + derive category (first-link-wins).
+    """Upsert a supplier<->material link (idempotent).

    Caller is responsible for the surrounding transaction.
    """
@@ -42,15 +38,11 @@ async def link_supplier_material(
    link = SupplierMaterial(supplier_id=supplier_id, material_id=material_id, is_active=is_active)
    db.add(link)
    await db.flush()
-
-    # First-link-wins: only when the material has no category yet.
-    if material.category_id is None:
-        material.category_id = supplier.category_id
    return link


 async def unlink_supplier_material(db: AsyncSession, supplier_id, material_id) -> None:
-    """Remove the link. The material's category is NEVER auto-cleared (documented rule)."""
+    """Remove the link."""
    link = await db.scalar(
        select(SupplierMaterial).where(
            SupplierMaterial.supplier_id == supplier_id,