246 lines
8.2 KiB
Markdown
246 lines
8.2 KiB
Markdown
# Pricing Configuration Feature
|
|
|
|
This document describes the new configurable pricing feature that allows MASTER instances to manage pricing plans through the admin interface.
|
|
|
|
## Overview
|
|
|
|
The pricing configuration feature allows administrators on MASTER instances to:
|
|
- Create, edit, and delete pricing plans
|
|
- Configure plan features, prices, and settings
|
|
- Set resource quotas for rooms, conversations, storage, and users
|
|
- Mark plans as "Most Popular" or "Custom"
|
|
- Control plan visibility and ordering
|
|
- Update pricing without code changes
|
|
|
|
## Features
|
|
|
|
### Pricing Plan Management
|
|
- **Plan Name**: Display name for the pricing plan
|
|
- **Description**: Optional description shown below the plan name
|
|
- **Pricing**: Monthly and annual prices (annual prices are typically 20% lower)
|
|
- **Features**: Dynamic list of features with checkmarks
|
|
- **Button Configuration**: Customizable button text and URL
|
|
- **Plan Types**: Regular plans with prices or custom plans
|
|
- **Popular Plans**: Mark one plan as "Most Popular" with special styling
|
|
- **Active/Inactive**: Toggle plan visibility
|
|
- **Ordering**: Control the display order of plans
|
|
|
|
### Resource Quotas
|
|
- **Room Quota**: Maximum number of rooms allowed (0 = unlimited)
|
|
- **Conversation Quota**: Maximum number of conversations allowed (0 = unlimited)
|
|
- **Storage Quota**: Maximum storage in gigabytes (0 = unlimited)
|
|
- **Manager Quota**: Maximum number of manager users allowed (0 = unlimited)
|
|
- **Admin Quota**: Maximum number of admin users allowed (0 = unlimited)
|
|
|
|
### Admin Interface
|
|
- **Pricing Tab**: New tab in admin settings (MASTER instances only)
|
|
- **Add/Edit Modals**: User-friendly forms for plan management
|
|
- **Real-time Updates**: Changes are reflected immediately
|
|
- **Feature Management**: Add/remove features dynamically
|
|
- **Quota Configuration**: Set resource limits for each plan
|
|
- **Status Toggles**: Quick switches for plan properties
|
|
|
|
## Setup Instructions
|
|
|
|
### 1. Database Migration
|
|
Run the migrations to create the pricing_plans table and add quota fields:
|
|
|
|
```bash
|
|
# Apply the migrations
|
|
alembic upgrade head
|
|
```
|
|
|
|
### 2. Initialize Default Plans (Optional)
|
|
Run the initialization script to create default pricing plans:
|
|
|
|
```bash
|
|
# Set MASTER environment variable
|
|
export MASTER=true
|
|
|
|
# Run the initialization script
|
|
python init_pricing_plans.py
|
|
```
|
|
|
|
This will create four default plans with quotas:
|
|
- **Starter**: 5 rooms, 10 conversations, 10GB storage, 10 managers, 1 admin
|
|
- **Professional**: 25 rooms, 50 conversations, 100GB storage, 50 managers, 3 admins
|
|
- **Enterprise**: 100 rooms, 200 conversations, 500GB storage, 200 managers, 10 admins
|
|
- **Custom**: Unlimited everything
|
|
|
|
### 3. Access Admin Interface
|
|
1. Log in as an admin user on a MASTER instance
|
|
2. Go to Settings
|
|
3. Click on the "Pricing" tab
|
|
4. Configure your pricing plans
|
|
|
|
## Usage
|
|
|
|
### Creating a New Plan
|
|
1. Click "Add New Plan" in the pricing tab
|
|
2. Fill in the plan details:
|
|
- **Name**: Plan display name
|
|
- **Description**: Optional description
|
|
- **Monthly Price**: Price per month
|
|
- **Annual Price**: Price per month when billed annually
|
|
- **Quotas**: Set resource limits (0 = unlimited)
|
|
- **Features**: Add features using the "Add Feature" button
|
|
- **Button Text**: Text for the call-to-action button
|
|
- **Button URL**: URL the button should link to
|
|
- **Options**: Check "Most Popular", "Custom Plan", or "Active" as needed
|
|
3. Click "Create Plan"
|
|
|
|
### Editing a Plan
|
|
1. Click the "Edit" button on any plan card
|
|
2. Modify the plan details in the modal
|
|
3. Click "Update Plan"
|
|
|
|
### Managing Plan Status
|
|
- **Active/Inactive**: Use the toggle switch in the plan header
|
|
- **Most Popular**: Check the "Most Popular" checkbox (only one plan can be popular)
|
|
- **Custom Plan**: Check "Custom Plan" for plans without fixed pricing
|
|
|
|
### Deleting a Plan
|
|
1. Click the "Delete" button on a plan card
|
|
2. Confirm the deletion in the modal
|
|
|
|
## Technical Details
|
|
|
|
### Database Schema
|
|
The `pricing_plans` table includes:
|
|
- `id`: Primary key
|
|
- `name`: Plan name (required)
|
|
- `description`: Optional description
|
|
- `monthly_price`: Monthly price (float)
|
|
- `annual_price`: Annual price (float)
|
|
- `features`: JSON array of feature strings
|
|
- `button_text`: Button display text
|
|
- `button_url`: Button link URL
|
|
- `is_popular`: Boolean for "Most Popular" styling
|
|
- `is_custom`: Boolean for custom plans
|
|
- `is_active`: Boolean for plan visibility
|
|
- `order_index`: Integer for display ordering
|
|
- `room_quota`: Maximum rooms (0 = unlimited)
|
|
- `conversation_quota`: Maximum conversations (0 = unlimited)
|
|
- `storage_quota_gb`: Maximum storage in GB (0 = unlimited)
|
|
- `manager_quota`: Maximum managers (0 = unlimited)
|
|
- `admin_quota`: Maximum admins (0 = unlimited)
|
|
- `created_by`: Foreign key to user who created the plan
|
|
- `created_at`/`updated_at`: Timestamps
|
|
|
|
### API Endpoints
|
|
- `POST /api/admin/pricing-plans` - Create new plan
|
|
- `GET /api/admin/pricing-plans/<id>` - Get plan details
|
|
- `PUT /api/admin/pricing-plans/<id>` - Update plan
|
|
- `DELETE /api/admin/pricing-plans/<id>` - Delete plan
|
|
- `PATCH /api/admin/pricing-plans/<id>/status` - Update plan status
|
|
|
|
### Template Integration
|
|
The pricing page automatically uses configured plans:
|
|
- Falls back to hardcoded plans if no plans are configured
|
|
- Supports dynamic feature lists
|
|
- Handles custom plans without pricing
|
|
- Shows/hides billing toggle based on plan types
|
|
- Displays quota information in plan cards
|
|
|
|
### Quota Enforcement
|
|
The PricingPlan model includes utility methods for quota checking:
|
|
- `check_quota(quota_type, current_count)`: Returns True if quota allows the operation
|
|
- `get_quota_remaining(quota_type, current_count)`: Returns remaining quota
|
|
- `format_quota_display(quota_type)`: Formats quota for display
|
|
- `get_storage_quota_bytes()`: Converts GB to bytes for storage calculations
|
|
|
|
Example usage in your application:
|
|
```python
|
|
# Check if user can create a new room
|
|
plan = PricingPlan.query.get(user_plan_id)
|
|
current_rooms = Room.query.filter_by(created_by=user.id).count()
|
|
if plan.check_quota('room_quota', current_rooms):
|
|
# Allow room creation
|
|
pass
|
|
else:
|
|
# Show upgrade message
|
|
pass
|
|
```
|
|
|
|
## Security
|
|
|
|
- Only admin users can access pricing configuration
|
|
- Only MASTER instances can configure pricing
|
|
- All API endpoints require authentication and admin privileges
|
|
- CSRF protection is enabled for all forms
|
|
|
|
## Customization
|
|
|
|
### Styling
|
|
The pricing plans use the existing CSS variables:
|
|
- `--primary-color`: Main brand color
|
|
- `--secondary-color`: Secondary brand color
|
|
- `--shadow-color`: Card shadows
|
|
|
|
### Button URLs
|
|
Configure button URLs to point to:
|
|
- Contact forms
|
|
- Payment processors
|
|
- Sales pages
|
|
- Custom landing pages
|
|
|
|
### Features
|
|
Features can include:
|
|
- Storage limits
|
|
- User limits
|
|
- Feature availability
|
|
- Support levels
|
|
- Integration options
|
|
|
|
### Quota Integration
|
|
To integrate quotas into your application:
|
|
|
|
1. **User Plan Assignment**: Associate users with pricing plans
|
|
2. **Quota Checking**: Use the `check_quota()` method before operations
|
|
3. **Upgrade Prompts**: Show upgrade messages when quotas are exceeded
|
|
4. **Usage Tracking**: Track current usage for quota calculations
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **Pricing tab not visible**
|
|
- Ensure you're on a MASTER instance (`MASTER=true`)
|
|
- Ensure you're logged in as an admin user
|
|
|
|
2. **Plans not showing on pricing page**
|
|
- Check that plans are marked as "Active"
|
|
- Verify the database migration was applied
|
|
- Check for JavaScript errors in browser console
|
|
|
|
3. **Features not saving**
|
|
- Ensure at least one feature is provided
|
|
- Check that feature text is not empty
|
|
|
|
4. **Quota fields not working**
|
|
- Verify the quota migration was applied
|
|
- Check that quota values are integers
|
|
- Ensure quota fields are included in form submissions
|
|
|
|
5. **API errors**
|
|
- Verify CSRF token is included in requests
|
|
- Check that all required fields are provided
|
|
- Ensure proper JSON formatting for features
|
|
|
|
### Debugging
|
|
- Check browser console for JavaScript errors
|
|
- Review server logs for API errors
|
|
- Verify database connectivity
|
|
- Test with default plans first
|
|
|
|
## Future Enhancements
|
|
|
|
Potential future improvements:
|
|
- Plan categories/tiers
|
|
- Regional pricing
|
|
- Currency support
|
|
- Promotional pricing
|
|
- Plan comparison features
|
|
- Analytics and usage tracking
|
|
- Automatic quota enforcement middleware
|
|
- Usage dashboard for quota monitoring |