feat: 后端新增产品收口接口(已入库/已出库,管理员,含扫码节点与操作日志,可反向纠错与强收口)

backend/app/api/v1/endpoints/products.py

@@ -14,7 +14,7 @@ from app.schemas.product import (
     ProductResponse,
     ProductScanResponse,
 )
-from app.services import product_service
+from app.services import product_service, product_finalize_service
 from app.services.auth_service import get_current_user
 from app.services.qrcode_service import generate_qrcode_png
 
@@ -147,6 +147,42 @@ async def update_product_overall_status(
     )
 
 
+# ============================================================
+# 产品收口 — 管理员将产品修正为「已入库」/「已出库」（可反向纠错）
+# ============================================================
+
+class ProductFinalizeRequest(BaseModel):
+    """管理员收口入参"""
+    status: str = Field(..., min_length=1, max_length=20, description="收口目标: 已入库 | 已出库")
+    note: str | None = Field(None, max_length=200, description="备注(选填)")
+
+
+@router.post("/scan/{serial_number}/finalize", response_model=ProductScanResponse)
+async def finalize_product_status_endpoint(
+    serial_number: str,
+    data: ProductFinalizeRequest,
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """管理员将产品整体收口为「已入库」或「已出库」（支持 入库<->出库 反向互切纠错）。
+
+    与 MOM 出入库回调落库语义一致：同步 product.overall_status/status、写
+    warehouse_inbound/outbound 日志、幂等追加「扫码入库/扫码出库」主线收尾节点。
+    权限：仅 SUPER_ADMIN / SUPERVISOR。
+    """
+    from fastapi import HTTPException, status
+    from app.services.task_service import ADMIN_ROLES
+
+    if (current_user or {}).get("role") not in ADMIN_ROLES:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="仅超级管理员或主管可执行入库/出库收口",
+        )
+    return await product_finalize_service.finalize_product_status(
+        db, serial_number, data.status, current_user, data.note,
+    )
+
+
 # ============================================================
 # 协同留言板
 # ============================================================