pricing

2025-06-24 11:25:10 +02:00
parent 6412d9f01a
commit 996adb4bce
15 changed files with 1695 additions and 4 deletions
--- a/PRICING_CONFIGURATION.md
+++ b/PRICING_CONFIGURATION.md
@@ -0,0 +1,246 @@
+# 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