sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add feature gating system documentation

Browse Source 
- Add comprehensive feature-gating-system.md documenting:
  - Database models (Feature, VendorFeatureOverride)
  - 30 features across 8 categories with tier requirements
  - FeatureService and UsageService APIs
  - Backend enforcement (decorator, dependency patterns)
  - Frontend integration (Alpine stores, Jinja macros)
  - Admin and vendor API endpoints
- Update subscription-workflow-plan.md with completion status
- Add feature-gating-system.md to mkdocs.yml navigation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Samir Boulahtit
2025-12-31 21:38:33 +01:00
parent 265c71f597
commit 1743b2bddf
3 changed files with 473 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

377
docs/implementation/feature-gating-system.md Normal file
View File

@@ -0,0 +1,377 @@
# Feature Gating System
## Overview
The feature gating system provides tier-based access control for platform features. It allows restricting functionality based on vendor subscription tiers (Essential, Professional, Business, Enterprise) with contextual upgrade prompts when features are locked.
**Implemented:** December 31, 2025
## Architecture
### Database Models
Located in `models/database/feature.py`:
| Model | Purpose |
|-------|---------|
| `Feature` | Feature definitions with tier requirements |
| `VendorFeatureOverride` | Per-vendor feature overrides (enable/disable) |
### Feature Model Structure
```python
class Feature(Base):
__tablename__ = "features"
id: int # Primary key
code: str # Unique feature code (e.g., "analytics_dashboard")
name: str # Display name
description: str # User-facing description
category: str # Feature category
minimum_tier_code: str # Minimum tier required (essential/professional/business/enterprise)
minimum_tier_order: int # Tier order for comparison (1-4)
is_active: bool # Whether feature is available
created_at: datetime
updated_at: datetime
```
### Tier Ordering
| Tier | Order | Code |
|------|-------|------|
| Essential | 1 | `essential` |
| Professional | 2 | `professional` |
| Business | 3 | `business` |
| Enterprise | 4 | `enterprise` |
## Feature Categories
30 features organized into 8 categories:
### 1. Analytics
| Feature Code | Name | Min Tier |
|-------------|------|----------|
| `basic_analytics` | Basic Analytics | Essential |
| `analytics_dashboard` | Analytics Dashboard | Professional |
| `advanced_analytics` | Advanced Analytics | Business |
| `custom_reports` | Custom Reports | Enterprise |
### 2. Product Management
| Feature Code | Name | Min Tier |
|-------------|------|----------|
| `basic_products` | Product Management | Essential |
| `bulk_product_edit` | Bulk Product Edit | Professional |
| `product_variants` | Product Variants | Professional |
| `product_bundles` | Product Bundles | Business |
| `inventory_alerts` | Inventory Alerts | Professional |
### 3. Order Management
| Feature Code | Name | Min Tier |
|-------------|------|----------|
| `basic_orders` | Order Management | Essential |
| `order_automation` | Order Automation | Professional |
| `advanced_fulfillment` | Advanced Fulfillment | Business |
| `multi_warehouse` | Multi-Warehouse | Enterprise |
### 4. Marketing
| Feature Code | Name | Min Tier |
|-------------|------|----------|
| `discount_codes` | Discount Codes | Professional |
| `abandoned_cart` | Abandoned Cart Recovery | Business |
| `email_marketing` | Email Marketing | Business |
| `loyalty_program` | Loyalty Program | Enterprise |
### 5. Support
| Feature Code | Name | Min Tier |
|-------------|------|----------|
| `basic_support` | Email Support | Essential |
| `priority_support` | Priority Support | Professional |
| `phone_support` | Phone Support | Business |
| `dedicated_manager` | Dedicated Account Manager | Enterprise |
### 6. Integration
| Feature Code | Name | Min Tier |
|-------------|------|----------|
| `basic_api` | Basic API Access | Professional |
| `advanced_api` | Advanced API Access | Business |
| `webhooks` | Webhooks | Business |
| `custom_integrations` | Custom Integrations | Enterprise |
### 7. Branding
| Feature Code | Name | Min Tier |
|-------------|------|----------|
| `basic_theme` | Theme Customization | Essential |
| `custom_domain` | Custom Domain | Professional |
| `white_label` | White Label | Enterprise |
| `custom_checkout` | Custom Checkout | Enterprise |
### 8. Team
| Feature Code | Name | Min Tier |
|-------------|------|----------|
| `team_management` | Team Management | Professional |
| `role_permissions` | Role Permissions | Business |
| `audit_logs` | Audit Logs | Business |
## Services
### FeatureService
Located in `app/services/feature_service.py`:
```python
class FeatureService:
"""Service for managing tier-based feature access."""
# In-memory caching (refreshed every 5 minutes)
_feature_cache: dict[str, Feature] = {}
_cache_timestamp: datetime | None = None
CACHE_TTL_SECONDS = 300
def has_feature(self, db: Session, vendor_id: int, feature_code: str) -> bool:
"""Check if vendor has access to a feature."""
def get_available_features(self, db: Session, vendor_id: int) -> list[str]:
"""Get list of feature codes available to vendor."""
def get_all_features_with_status(self, db: Session, vendor_id: int) -> list[dict]:
"""Get all features with availability status for vendor."""
def get_feature_info(self, db: Session, feature_code: str) -> dict | None:
"""Get full feature information including tier requirements."""
```
### UsageService
Located in `app/services/usage_service.py`:
```python
class UsageService:
"""Service for tracking and managing vendor usage against tier limits."""
def get_usage_summary(self, db: Session, vendor_id: int) -> dict:
"""Get comprehensive usage summary with limits and upgrade info."""
def check_limit(self, db: Session, vendor_id: int, limit_type: str) -> dict:
"""Check specific limit with detailed info."""
def get_upgrade_info(self, db: Session, vendor_id: int) -> dict:
"""Get upgrade recommendations based on current usage."""
```
## Backend Enforcement
### Decorator Pattern
```python
from app.core.feature_gate import require_feature
@router.get("/analytics/advanced")
@require_feature("advanced_analytics")
async def get_advanced_analytics(
db: Session = Depends(get_db),
vendor_id: int = Depends(get_current_vendor_id)
):
# Only accessible if vendor has advanced_analytics feature
pass
```
### Dependency Pattern
```python
from app.core.feature_gate import RequireFeature
@router.get("/marketing/loyalty")
async def get_loyalty_program(
db: Session = Depends(get_db),
_: None = Depends(RequireFeature("loyalty_program"))
):
# Only accessible if vendor has loyalty_program feature
pass
```
### Exception Handling
When a feature is not available, `FeatureNotAvailableException` is raised:
```python
class FeatureNotAvailableException(Exception):
def __init__(self, feature_code: str, required_tier: str):
self.feature_code = feature_code
self.required_tier = required_tier
super().__init__(f"Feature '{feature_code}' requires {required_tier} tier")
```
HTTP Response (403):
```json
{
"detail": "Feature 'advanced_analytics' requires Professional tier or higher",
"feature_code": "advanced_analytics",
"required_tier": "Professional",
"upgrade_url": "/vendor/wizamart/billing"
}
```
## API Endpoints
### Vendor Features API
Base: `/api/v1/vendor/features`
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/features/available` | GET | List available feature codes |
| `/features` | GET | All features with availability status |
| `/features/{code}` | GET | Single feature info |
| `/features/{code}/check` | GET | Quick availability check |
### Vendor Usage API
Base: `/api/v1/vendor/usage`
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/usage` | GET | Full usage summary with limits |
| `/usage/check/{limit_type}` | GET | Check specific limit (orders/products/team_members) |
| `/usage/upgrade-info` | GET | Upgrade recommendations |
### Admin Features API
Base: `/api/v1/admin/features`
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/features` | GET | List all features |
| `/features/{id}` | GET | Get feature details |
| `/features/{id}` | PUT | Update feature |
| `/features/{id}/toggle` | POST | Toggle feature active status |
| `/features/vendors/{vendor_id}/overrides` | GET | Get vendor overrides |
| `/features/vendors/{vendor_id}/overrides` | POST | Create override |
## Frontend Integration
### Alpine.js Feature Store
Located in `static/shared/js/feature-store.js`:
```javascript
// Usage in templates
$store.features.has('analytics_dashboard') // Check feature
$store.features.loaded // Loading state
$store.features.getFeature('advanced_api') // Get feature details
```
### Alpine.js Upgrade Store
Located in `static/shared/js/upgrade-prompts.js`:
```javascript
// Usage in templates
$store.upgrade.shouldShowLimitWarning('orders')
$store.upgrade.getUsageString('products')
$store.upgrade.hasUpgradeRecommendation
```
### Jinja2 Macros
Located in `app/templates/shared/macros/feature_gate.html`:
#### Feature Gate Container
```jinja2
{% from "shared/macros/feature_gate.html" import feature_gate %}
{% call feature_gate("analytics_dashboard") %}
<div>Analytics content here - only visible if feature available</div>
{% endcall %}
```
#### Feature Locked Card
```jinja2
{% from "shared/macros/feature_gate.html" import feature_locked %}
{{ feature_locked("advanced_analytics", "Advanced Analytics", "Get deeper insights") }}
```
#### Upgrade Banner
```jinja2
{% from "shared/macros/feature_gate.html" import upgrade_banner %}
{{ upgrade_banner("custom_domain") }}
```
#### Usage Limit Warning
```jinja2
{% from "shared/macros/feature_gate.html" import limit_warning %}
{{ limit_warning("orders") }} {# Shows warning when approaching limit #}
```
#### Usage Progress Bar
```jinja2
{% from "shared/macros/feature_gate.html" import usage_bar %}
{{ usage_bar("products", "Products") }}
```
#### Tier Badge
```jinja2
{% from "shared/macros/feature_gate.html" import tier_badge %}
{{ tier_badge() }} {# Shows current tier as colored badge #}
```
## Vendor Dashboard Integration
The vendor dashboard (`/vendor/{code}/dashboard`) now includes:
1. **Tier Badge**: Shows current subscription tier in header
2. **Usage Bars**: Visual progress bars for orders, products, team members
3. **Upgrade Prompts**: Contextual upgrade recommendations when approaching limits
4. **Feature Gates**: Locked sections for premium features
## Admin Features Page
Located at `/admin/features`:
- View all 30 features in categorized table
- Toggle features on/off globally
- Filter by category
- Search by name/code
- View tier requirements
## Migration
The features are seeded via Alembic migration:
```
alembic/versions/n2c3d4e5f6a7_add_features_table.py
```
This creates:
- `features` table with 30 default features
- `vendor_feature_overrides` table for per-vendor exceptions
## Testing
Unit tests located in:
- `tests/unit/services/test_feature_service.py`
- `tests/unit/services/test_usage_service.py`
Run tests:
```bash
pytest tests/unit/services/test_feature_service.py -v
pytest tests/unit/services/test_usage_service.py -v
```
## Architecture Compliance
All JavaScript files follow architecture rules:
- JS-003: Alpine components use `vendor*` naming convention
- JS-005: Init guards prevent duplicate initialization
- JS-006: Async operations have try/catch error handling
- JS-008: API calls use `apiClient` (not raw `fetch()`)
- JS-009: Notifications use `Utils.showToast()`
## Related Documentation
- [Subscription Billing](../features/subscription-billing.md) - Core subscription system
- [Subscription Workflow Plan](./subscription-workflow-plan.md) - Implementation roadmap

137
docs/implementation/subscription-workflow-plan.md
View File

@@ -294,61 +294,114 @@ class VendorAddOn(Base):
## 5. Implementation Phases
### Phase 1: Database & Core (Day 1-2)
- [ ] Add `tier_id` FK to VendorSubscription
- [ ] Create migration with data backfill
- [ ] Update subscription service to use tier relationship
- [ ] Update admin subscription endpoints
**Last Updated:** December 31, 2025
### Phase 2: Admin Vendor Page (Day 2-3)
- [ ] Add subscription card to vendor detail page
- [ ] Show usage meters (orders, products, team)
### Phase 1: Database & Core (COMPLETED)
- [x] Add `tier_id` FK to VendorSubscription
- [x] Create migration with data backfill
- [x] Update subscription service to use tier relationship
- [x] Update admin subscription endpoints
- [x] **NEW:** Add Feature model with 30 features across 8 categories
- [x] **NEW:** Create FeatureService with caching for tier-based feature checking
- [x] **NEW:** Add UsageService for limit tracking and upgrade recommendations
### Phase 2: Admin Vendor Page (PARTIALLY COMPLETE)
- [x] Add subscription card to vendor detail page
- [x] Show usage meters (orders, products, team)
- [ ] Add "Edit Subscription" modal
- [ ] Implement tier change API (admin)
- [x] **NEW:** Add Admin Features page (`/admin/features`)
- [x] **NEW:** Admin features API (list, update, toggle)
### Phase 3: Vendor Billing Page (Day 3-4)
- [ ] Create `/vendor/{code}/billing` page
- [ ] Show current plan and usage
- [ ] Add tier comparison/change UI
- [ ] Implement tier change API (vendor)
- [ ] Add Stripe checkout integration for upgrades
### Phase 3: Vendor Billing Page (COMPLETED)
- [x] Create `/vendor/{code}/billing` page
- [x] Show current plan and usage
- [x] Add tier comparison/change UI
- [x] Implement tier change API (vendor)
- [x] Add Stripe checkout integration for upgrades
- [x] **NEW:** Add feature gate macros for templates
- [x] **NEW:** Add Alpine.js feature store
- [x] **NEW:** Add Alpine.js upgrade prompts store
- [x] **FIX:** Resolved 89 JS architecture violations (JS-005 through JS-009)
### Phase 4: Add-ons (Day 4-5)
- [ ] Seed add-on products in database
- [ ] Add "Available Add-ons" section to billing page
- [ ] Implement add-on purchase flow
- [ ] Create VendorAddOn management
- [ ] Add contextual upsell prompts
### Phase 4: Add-ons (COMPLETED)
- [x] Seed add-on products in database
- [x] Add "Available Add-ons" section to billing page
- [x] Implement add-on purchase flow
- [x] Create VendorAddOn management (via billing page)
- [x] Add contextual upsell prompts
- [x] **FIX:** Fix Stripe webhook to create VendorAddOn records
### Phase 5: Polish & Testing (Day 5-6)
### Phase 5: Polish & Testing (IN PROGRESS)
- [ ] Email notifications for tier changes
- [ ] Webhook handling for Stripe events
- [ ] Usage limit enforcement updates
- [ ] End-to-end testing
- [ ] Documentation
- [x] Webhook handling for Stripe events
- [x] Usage limit enforcement updates
- [ ] End-to-end testing (manual testing required)
- [x] Documentation (feature-gating-system.md created)
### Phase 6: Remaining Work (NEW)
- [ ] Admin tier change modal (upgrade/downgrade vendors)
- [ ] Admin subscription override UI (custom limits for enterprise)
- [ ] Trial extension from admin panel
- [ ] Email notifications for tier changes
- [ ] Email notifications for approaching limits
- [ ] Grace period handling for failed payments
- [ ] Integration tests for full billing workflow
- [ ] Stripe test mode checkout verification
---
## 6. Files to Create/Modify
## 6. Files Created/Modified
### New Files
| File | Purpose |
|------|---------|
| `app/templates/vendor/billing.html` | Vendor billing page |
| `static/vendor/js/billing.js` | Billing page JS |
| `app/api/v1/vendor/billing.py` | Vendor billing endpoints |
| `app/services/addon_service.py` | Add-on management |
**Last Updated:** December 31, 2025
### New Files (Created)
| File | Purpose | Status |
|------|---------|--------|
| `app/templates/vendor/billing.html` | Vendor billing page | DONE |
| `static/vendor/js/billing.js` | Billing page JS | DONE |
| `app/api/v1/vendor/billing.py` | Vendor billing endpoints | DONE |
| `models/database/feature.py` | Feature & VendorFeatureOverride models | DONE |
| `app/services/feature_service.py` | Feature access control service | DONE |
| `app/services/usage_service.py` | Usage tracking & limits service | DONE |
| `app/core/feature_gate.py` | @require_feature decorator & dependency | DONE |
| `app/api/v1/vendor/features.py` | Vendor features API | DONE |
| `app/api/v1/vendor/usage.py` | Vendor usage API | DONE |
| `app/api/v1/admin/features.py` | Admin features API | DONE |
| `app/templates/admin/features.html` | Admin features management page | DONE |
| `app/templates/shared/macros/feature_gate.html` | Jinja2 feature gate macros | DONE |
| `static/shared/js/feature-store.js` | Alpine.js feature store | DONE |
| `static/shared/js/upgrade-prompts.js` | Alpine.js upgrade prompts | DONE |
| `alembic/versions/n2c3d4e5f6a7_add_features_table.py` | Features migration | DONE |
| `docs/implementation/feature-gating-system.md` | Feature gating documentation | DONE |
### Modified Files
| File | Changes |
|------|---------|
| `models/database/subscription.py` | Add tier_id FK |
| `app/templates/admin/vendor-detail.html` | Add subscription card |
| `static/admin/js/vendor-detail.js` | Load subscription data |
| `app/api/v1/admin/vendors.py` | Include subscription in response |
| `app/api/v1/admin/subscriptions.py` | Add tier change endpoint |
| `app/services/subscription_service.py` | Tier change logic |
| `app/templates/vendor/partials/sidebar.html` | Add Billing link |
| File | Changes | Status |
|------|---------|--------|
| `models/database/subscription.py` | Add tier_id FK | DONE |
| `models/database/__init__.py` | Export Feature models | DONE |
| `app/templates/admin/vendor-detail.html` | Add subscription card | DONE |
| `static/admin/js/vendor-detail.js` | Load subscription data | DONE |
| `app/api/v1/admin/vendors.py` | Include subscription in response | DONE |
| `app/api/v1/admin/__init__.py` | Register features router | DONE |
| `app/api/v1/vendor/__init__.py` | Register features/usage routers | DONE |
| `app/services/subscription_service.py` | Tier change logic | DONE |
| `app/templates/vendor/partials/sidebar.html` | Add Billing link | DONE |
| `app/templates/vendor/base.html` | Load feature/upgrade stores | DONE |
| `app/templates/vendor/dashboard.html` | Add tier badge & usage bars | DONE |
| `app/handlers/stripe_webhook.py` | Create VendorAddOn on purchase | DONE |
| `app/routes/admin_pages.py` | Add features page route | DONE |
| `static/shared/js/api-client.js` | Add postFormData() & getBlob() | DONE |
### Architecture Fixes (48 files)
| Rule | Files Fixed | Description |
|------|-------------|-------------|
| JS-003 | billing.js | Rename billingData→vendorBilling |
| JS-005 | 15 files | Add init guards |
| JS-006 | 39 files | Add try/catch to async init |
| JS-008 | 5 files | Use apiClient not fetch |
| JS-009 | 30 files | Use Utils.showToast |
| TPL-009 | validate_architecture.py | Check vendor templates too |
---