feat: Implement Smart Tips feature with service, router, and schema

app/app.py

@@ -1,7 +1,7 @@
 from fastapi import FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.middleware.trustedhost import TrustedHostMiddleware
-from app.routers import auth_router, merchant_profile_router, merchant_router, merchant_settings_router, role_router,branch_router, location_router 
+from app.routers import auth_router, merchant_profile_router, merchant_router, merchant_settings_router, role_router, branch_router, location_router, smart_tips_router
 import logging
 from app.utils.logger import setup_logger
 
@@ -68,6 +68,18 @@ app.include_router(auth_router.router)
 app.include_router(role_router.router, prefix="/api", tags=["Roles"])
 app.include_router(branch_router.router,prefix="/api/branch",tags=["Branch"])
 app.include_router(location_router.router, prefix="/api", tags=["Locations"])
+app.include_router(smart_tips_router.router, prefix="/api", tags=["SmartTips"])
+
+@app.on_event("startup")
+async def startup_event():
+    """
+    Initialize necessary data at application startup
+    """
+    from app.services.smart_tips_service import SmartTipsService
+    logger.info("Initializing smart tips collection")
+    service = SmartTipsService()
+    await service.ensure_collection_exists()
+    logger.info("Smart tips initialization complete")
 
 @app.get("/")
 def root():

app/routers/smart_tips_router.py

@@ -0,0 +1,53 @@
+import logging
+from fastapi import APIRouter, HTTPException, Depends, Query
+from typing import List, Optional
+from app.schemas.smart_tips_schema import SmartTip
+from app.services.smart_tips_service import SmartTipsService
+
+logger = logging.getLogger("smart_tips_router")
+router = APIRouter(tags=["SmartTips"])
+
+# Define mandatory features
+MANDATORY_FEATURES = ["asset", "associate"]
+
+async def get_smart_tips_service():
+    """
+    Dependency to get a configured SmartTipsService instance
+    """
+    service = SmartTipsService()
+    await service.ensure_collection_exists()
+    return service
+
+@router.get("/smart-tips", response_model=List[SmartTip])
+async def get_smart_tips(
+    features: Optional[List[str]] = Query(None, description="Filter tips by feature(s)"),
+    include_mandatory: bool = Query(True, description="Include mandatory features (asset, associate)"),
+    smart_tips_service: SmartTipsService = Depends(get_smart_tips_service)
+):
+    """
+    Get a list of smart tips for different features.
+    
+    - Optional query parameter to filter by features
+    - Always includes mandatory features if include_mandatory=True
+    """
+    try:
+        logger.info("Fetching smart tips from MongoDB")
+        
+        # Handle mandatory features
+        if include_mandatory:
+            if features:
+                # Include mandatory features with user-requested features
+                request_features = list(set(features + MANDATORY_FEATURES))
+                return await smart_tips_service.get_smart_tips_by_features(request_features)
+            else:
+                # Include mandatory features with all other features
+                return await smart_tips_service.get_smart_tips_with_mandatory(MANDATORY_FEATURES)
+        else:
+            # Filter by features if provided, otherwise return all
+            if features:
+                return await smart_tips_service.get_smart_tips_by_features(features)
+            else:
+                return await smart_tips_service.get_all_smart_tips()
+    except Exception as e:
+        logger.error(f"Error fetching smart tips: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))

app/schemas/smart_tips_schema.py

@@ -0,0 +1,12 @@
+from typing import List, Optional
+from pydantic import BaseModel, Field, RootModel
+
+class SmartTip(BaseModel):
+    id: str
+    title: str
+    description: str
+    icon: Optional[str] = Field(None, description="Must match a valid Lucide icon name: Target, BookOpen, AlertCircle, Clock, FileText, Save, Tag, BarChart3, Users, Settings, Lightbulb")
+    feature: str = Field(..., description="Feature category this tip belongs to (e.g., asset, associate, catalogue)")
+
+class SmartTipsResponse(RootModel):
+    root: List[SmartTip]

app/services/smart_tips_service.py

@@ -0,0 +1,93 @@
+import logging
+from typing import List, Optional
+from app.nosql import db
+from app.schemas.smart_tips_schema import SmartTip
+
+logger = logging.getLogger("smart_tips_service")
+
+class SmartTipsService:
+    def __init__(self):
+        self.collection = db["smart_tips"]
+    
+    async def ensure_collection_exists(self):
+        """
+        Check if the collection exists and has data. If not, seed with initial data.
+        """
+        count = await self.collection.count_documents({})
+        if count == 0:
+            await self.seed_initial_data()
+            logger.info("Smart tips collection seeded with initial data")
+    
+    async def seed_initial_data(self):
+        """
+        Seed the collection with initial smart tips data
+        """
+        initial_tips = [
+            {
+                "id": "tip-1",
+                "title": "Complete in Order",
+                "description": "Fill out sections sequentially for the best experience.",
+                "icon": "Target",
+                "feature": "general"
+            },
+            {
+                "id": "tip-2",
+                "title": "Associate Management",
+                "description": "Add all your team members for better role management.",
+                "icon": "Users",
+                "feature": "associate"
+            },
+            {
+                "id": "tip-3",
+                "title": "Catalogue Best Practices",
+                "description": "Keep your product details consistent for better customer experience.",
+                "icon": "BookOpen",
+                "feature": "catalogue"
+            },
+            {
+                "id": "tip-4",
+                "title": "Asset Management",
+                "description": "Regularly update your asset inventory for accurate financial reporting.",
+                "icon": "FileText",
+                "feature": "asset"
+            },
+            {
+                "id": "tip-5",
+                "title": "Time Management",
+                "description": "Schedule regular inventory checks to maintain accuracy.",
+                "icon": "Clock",
+                "feature": "general"
+            }
+        ]
+        await self.collection.insert_many(initial_tips)
+    
+    async def get_all_smart_tips(self) -> List[SmartTip]:
+        """
+        Get all smart tips from the database
+        """
+        cursor = self.collection.find({})
+        tips = await cursor.to_list(length=100)
+        return [SmartTip(**tip) for tip in tips]
+    
+    async def get_smart_tips_by_features(self, features: List[str]) -> List[SmartTip]:
+        """
+        Get smart tips filtered by a list of features
+        """
+        cursor = self.collection.find({"feature": {"$in": features}})
+        tips = await cursor.to_list(length=100)
+        return [SmartTip(**tip) for tip in tips]
+
+    async def get_smart_tips_with_mandatory(self, mandatory_features: List[str]) -> List[SmartTip]:
+        """
+        Get all smart tips ensuring mandatory features are included
+        """
+        # First, get tips from mandatory features
+        mandatory_tips = await self.get_smart_tips_by_features(mandatory_features)
+        
+        # Then get all other tips
+        cursor = self.collection.find({"feature": {"$nin": mandatory_features}})
+        other_tips = await cursor.to_list(length=100)
+        other_tips = [SmartTip(**tip) for tip in other_tips]
+        
+        # Combine both sets
+        return mandatory_tips + other_tips

seed_smart_tips.py

@@ -0,0 +1,28 @@
+"""
+Script to seed the smart_tips collection in MongoDB
+Run this script to initialize the collection if needed
+"""
+import asyncio
+import logging
+import sys
+import os
+
+# Add the parent directory to sys.path to import app modules
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from app.services.smart_tips_service import SmartTipsService
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+async def seed_smart_tips():
+    """
+    Seed the smart_tips collection with initial data
+    """
+    logger.info("Starting smart tips collection seeding process")
+    service = SmartTipsService()
+    await service.ensure_collection_exists()
+    logger.info("Smart tips collection seeding completed")
+
+if __name__ == "__main__":
+    asyncio.run(seed_smart_tips())