Skip to main content

Activity Interest Feature Documentation

Overview​

The Activity Interest feature provides a comprehensive system for managing retailer-defined activities and interests that influence consumer/customer purchasing behavior. This feature enables retailers to segment customers based on their leisure and professional activities, allowing for more targeted marketing and personalized product recommendations.

Business Context​

Activity interests are crucial for customer segmentation and personalization in retail environments. For example:

  • Consumers who play soccer will be interested in sportswear, sports shoes, soccer balls, and other soccer-related items
  • Customers interested in cooking will be more likely to purchase kitchen equipment, cookbooks, and gourmet ingredients
  • Photography enthusiasts will show interest in cameras, lenses, and photography accessories

Data Model​

Core Entity: ActivityInterest​

Table: ks_activity_interests

Primary Key: code (String)

Attributes:

  • code: A lookup value that designates a valid activity or interest code used to segment customers
  • description: A short narrative description of an activity/interest type
  • category: Optional categorization for grouping related activities

API Endpoints​

Activity Interest Management​

Create Activity Interest​

  • POST /api/v1/activity-interests/
  • Description: Create a new activity interest
  • Request Body: ActivityInterestCreate schema
  • Response: ActivityInterest schema

Get Activity Interest​

  • GET /api/v1/activity-interests/{code}
  • Description: Retrieve a specific activity interest by code
  • Response: ActivityInterest schema

Get All Activity Interests​

  • GET /api/v1/activity-interests/
  • Description: Retrieve all activity interests with optional filtering
  • Query Parameters:
    • skip: Number of records to skip (default: 0)
    • limit: Maximum number of records to return (default: 100)
    • category: Filter by category
  • Response: List of ActivityInterest schemas

Update Activity Interest​

  • PUT /api/v1/activity-interests/{code}
  • Description: Update an existing activity interest
  • Request Body: ActivityInterestUpdate schema
  • Response: ActivityInterest schema

Delete Activity Interest​

  • DELETE /api/v1/activity-interests/{code}
  • Description: Delete an activity interest
  • Response: Success message

Activity Interest Views (Materialized Views)​

Get Activity Interest Summary​

  • GET /api/v1/activity-interest-views/summary
  • Description: Get summary statistics for activity interests
  • Response: ActivityInterestSummary schema

Get Activity Interests by Category​

  • GET /api/v1/activity-interest-views/by-category
  • Description: Get activity interests grouped by category
  • Response: List of ActivityInterestByCategory schemas

Schemas​

ActivityInterestBase​

class ActivityInterestBase(BaseModel):
    code: str
    description: Optional[str] = None
    category: Optional[str] = None

ActivityInterestCreate​

class ActivityInterestCreate(ActivityInterestBase):
    pass

ActivityInterestUpdate​

class ActivityInterestUpdate(BaseModel):
    description: Optional[str] = None
    category: Optional[str] = None

ActivityInterestInDBBase​

class ActivityInterestInDBBase(ActivityInterestBase):
    class Config:
        from_attributes = True

ActivityInterest​

class ActivityInterest(ActivityInterestInDBBase):
    pass

ActivityInterestInDB​

class ActivityInterestInDB(ActivityInterestInDBBase):
    pass

CRUD Operations​

Create​

  • Validates input data
  • Checks for duplicate codes
  • Creates new activity interest record

Read​

  • Retrieves single activity interest by code
  • Retrieves multiple activity interests with filtering
  • Supports pagination

Update​

  • Updates existing activity interest
  • Validates input data
  • Maintains data integrity

Delete​

  • Removes activity interest record
  • Handles foreign key constraints

Materialized Views​

Activity Interest Summary View​

  • View Name: mv_activity_interest_summary
  • Purpose: Provides summary statistics for activity interests
  • Columns:
    • total_count: Total number of activity interests
    • category_count: Number of unique categories
    • most_common_category: Most frequently used category

Activity Interest by Category View​

  • View Name: mv_activity_interests_by_category
  • Purpose: Groups activity interests by category
  • Columns:
    • category: Activity interest category
    • count: Number of activities in category
    • activities: List of activity codes in category

Database Migration​

Migration File: minierp_v1.1010_activity_interest_table.py​

Operations:

  1. Creates ks_activity_interests table
  2. Adds indexes for performance optimization
  3. Inserts sample data for testing

Sample Data:

  • Sports activities (soccer, basketball, tennis)
  • Hobbies (photography, cooking, gardening)
  • Professional interests (technology, finance, healthcare)

Usage Examples​

Creating an Activity Interest​

# Create a new activity interest
activity_data = {
    "code": "PHOTOGRAPHY",
    "description": "Photography and visual arts",
    "category": "HOBBIES"
}
response = client.post("/api/v1/activity-interests/", json=activity_data)

Retrieving Activity Interests​

# Get all activity interests
response = client.get("/api/v1/activity-interests/")

# Get activity interests by category
response = client.get("/api/v1/activity-interests/?category=SPORTS")

# Get specific activity interest
response = client.get("/api/v1/activity-interests/SOCCER")

Updating an Activity Interest​

# Update activity interest
update_data = {
    "description": "Soccer and football activities",
    "category": "SPORTS"
}
response = client.put("/api/v1/activity-interests/SOCCER", json=update_data)

Integration Points​

Customer Segmentation​

  • Activity interests can be linked to customer profiles
  • Enables targeted marketing campaigns
  • Supports personalized product recommendations

Product Catalog​

  • Products can be tagged with relevant activity interests
  • Facilitates cross-selling and upselling
  • Improves search and filtering capabilities

Marketing Campaigns​

  • Campaigns can target customers based on activity interests
  • Enables behavioral segmentation
  • Supports A/B testing for different interest groups

Performance Considerations​

Indexing​

  • Primary key index on code column
  • Index on category column for filtering
  • Composite indexes for complex queries

Materialized Views​

  • Pre-computed summaries for fast reporting
  • Regular refresh schedules for data consistency
  • Optimized for read-heavy workloads

Caching​

  • Frequently accessed activity interests can be cached
  • Category-based caching for improved performance
  • Redis integration for distributed caching

Security Considerations​

Access Control​

  • Role-based access control for activity interest management
  • Audit logging for all CRUD operations
  • Data validation and sanitization

Data Privacy​

  • Activity interest data may contain personal information
  • Compliance with data protection regulations
  • Secure data transmission and storage

Monitoring and Maintenance​

Health Checks​

  • Database connectivity monitoring
  • API endpoint availability checks
  • Performance metrics tracking

Data Quality​

  • Regular data validation
  • Duplicate detection and prevention
  • Data consistency checks

Backup and Recovery​

  • Regular database backups
  • Point-in-time recovery capabilities
  • Disaster recovery procedures

Future Enhancements​

Planned Features​

  • Activity interest hierarchies
  • Customer activity interest tracking
  • Recommendation engine integration
  • Analytics and reporting dashboards

Integration Opportunities​

  • Social media activity tracking
  • IoT device integration
  • Machine learning for interest prediction
  • Real-time personalization

Troubleshooting​

Common Issues​

  1. Duplicate Code Errors: Ensure unique codes when creating activity interests
  2. Category Filtering: Verify category values exist before filtering
  3. Performance Issues: Check database indexes and query optimization

Error Handling​

  • Comprehensive error messages
  • Proper HTTP status codes
  • Detailed logging for debugging

Conclusion​

The Activity Interest feature provides a robust foundation for customer segmentation and personalization in retail environments. By enabling retailers to define and manage activity interests, this feature supports targeted marketing, improved customer experiences, and data-driven business decisions.

The implementation includes comprehensive CRUD operations, RESTful APIs, materialized views for performance optimization, and proper database migrations. The feature is designed to be scalable, maintainable, and easily extensible for future enhancements.