123

tmp-md-files/DJANGO_ADMIN_ACTIONS_QUICK_REFERENCE.md

@@ -0,0 +1,511 @@
+# Django Admin Bulk Actions - Quick Reference Guide
+
+## Overview
+This guide provides a quick reference for all bulk actions implemented across 39 Django admin models in the IGNY8 platform.
+
+---
+
+## Common Action Patterns
+
+### 1. Status Toggle Actions
+**Pattern**: `bulk_activate` / `bulk_deactivate`
+
+**Models**: Account, Plan, Site, Sector, Clusters, ContentTaxonomy, CreditPackage, AIPrompt, IntegrationSettings, AuthorProfile, Strategy, and more
+
+**Usage**:
+1. Select records in admin list view
+2. Choose "Activate/Deactivate selected" from actions dropdown
+3. Click "Go"
+4. Confirmation message shows count of updated records
+
+### 2. Soft Delete Actions
+**Pattern**: `bulk_soft_delete`
+
+**Models**: Account, Content, Keywords, Tasks, Site, Sector, Clusters, ContentIdeas, Images, Industry, IndustrySector, SeedKeyword, Subscription, User
+
+**Usage**:
+1. Select records to delete
+2. Choose "Soft delete selected" action
+3. Records marked as deleted, not removed from database
+4. Preserves data for audit trails
+
+### 3. Import/Export Operations
+**Export Only**: 21 models (logs, payment methods, deployment records, etc.)
+**Import & Export**: 18 models (content, ideas, keywords, plans, etc.)
+
+**Usage**:
+- **Export**: Click "Export" button → Select format (CSV/XLSX) → Download
+- **Import**: Click "Import" button → Upload file → Preview → Confirm
+
+### 4. Form-Based Actions
+**Pattern**: Actions requiring user input via intermediate form
+
+**Examples**:
+- `bulk_add_credits` / `bulk_subtract_credits` (Account)
+- `bulk_assign_cluster` (ContentIdeas)
+- `bulk_assign_to_user` (Tasks)
+- `bulk_upgrade_plan` (Subscription)
+- `bulk_update_frequency` (AutomationConfig)
+
+**Usage**:
+1. Select records
+2. Choose action from dropdown
+3. Fill in form on intermediate page
+4. Click "Apply" to execute
+
+---
+
+## Model-Specific Actions Guide
+
+### Account Management
+
+#### Account
+- **Bulk add credits** (Form: amount to add)
+- **Bulk subtract credits** (Form: amount to remove)
+- **Bulk activate accounts**
+- **Bulk suspend accounts**
+- **Bulk soft delete**
+
+**Use Cases**:
+- Credit adjustments for promotions
+- Account suspension for policy violations
+- Account activation after verification
+
+#### User
+- **Bulk activate users**
+- **Bulk deactivate users**
+- **Bulk assign to group** (Form: select group)
+- **Bulk reset password**
+- **Bulk verify email**
+- **Bulk soft delete**
+
+**Use Cases**:
+- Team member management
+- Role assignments via groups
+- Password resets for security
+
+#### Plan & Subscription
+**Plan**:
+- Bulk activate/deactivate
+- Bulk clone plans
+
+**Subscription**:
+- Bulk activate/cancel
+- Bulk renew (extends expiry)
+- Bulk upgrade plan (Form: select new plan)
+- Bulk soft delete
+
+**Use Cases**:
+- Plan modifications
+- Subscription renewals
+- Plan upgrades for customers
+
+---
+
+### Content Management
+
+#### Content
+- **Bulk publish to WordPress**
+- **Bulk mark as published**
+- **Bulk mark as draft**
+- **Bulk add taxonomy** (Form: multi-select taxonomies)
+- **Bulk soft delete**
+
+**Use Cases**:
+- Content publishing workflow
+- Status management
+- Taxonomy assignments
+
+#### Tasks
+- **Bulk assign to user** (Form: select user)
+- **Bulk mark as completed**
+- **Bulk mark as in progress**
+- **Bulk cancel tasks**
+- **Bulk soft delete**
+
+**Use Cases**:
+- Task distribution to writers
+- Workflow state management
+- Task cleanup
+
+#### Images
+- **Bulk approve/reject**
+- **Bulk mark as featured**
+- **Bulk unmark as featured**
+- **Bulk soft delete**
+
+**Use Cases**:
+- Image moderation
+- Featured image management
+
+---
+
+### Planning & SEO
+
+#### Keywords
+- **Bulk mark as reviewed**
+- **Bulk approve keywords**
+- **Bulk reject keywords**
+- **Bulk soft delete**
+
+**Use Cases**:
+- Keyword research review
+- SEO strategy approval
+
+#### Clusters
+- **Bulk activate/deactivate**
+- **Bulk soft delete**
+
+**Use Cases**:
+- Content cluster management
+- Topic organization
+
+#### ContentIdeas
+- **Bulk approve/reject**
+- **Bulk assign cluster** (Form: select cluster)
+- **Bulk update content type** (Form: select type)
+- **Bulk update priority** (Form: select priority)
+- **Bulk soft delete**
+
+**Use Cases**:
+- Content pipeline management
+- Editorial planning
+- Priority adjustments
+
+---
+
+### Taxonomy & Organization
+
+#### ContentTaxonomy
+- **Bulk activate**
+- **Bulk merge taxonomies** (Form: select target, handles relations)
+
+**Use Cases**:
+- Taxonomy consolidation
+- Category management
+
+#### ContentAttribute
+- **Bulk activate**
+- **Bulk update attribute type** (Form: select type)
+
+**Use Cases**:
+- Attribute management
+- Schema updates
+
+#### ContentTaxonomyRelation
+- **Bulk delete relations**
+- **Bulk reassign taxonomy** (Form: select new taxonomy)
+
+**Use Cases**:
+- Relationship cleanup
+- Taxonomy reassignment
+
+#### ContentClusterMap
+- **Bulk delete maps**
+- **Bulk update role** (Form: pillar/supporting/related)
+- **Bulk reassign cluster** (Form: select cluster)
+
+**Use Cases**:
+- Content structure management
+- Cluster reorganization
+
+---
+
+### Billing & Finance
+
+#### Invoice
+- **Bulk mark as paid**
+- **Bulk mark as pending**
+- **Bulk mark as cancelled**
+- **Bulk send reminders**
+- **Bulk apply late fee**
+
+**Use Cases**:
+- Payment processing
+- Invoice management
+- Collections workflow
+
+#### Payment
+- **Bulk mark as verified**
+- **Bulk mark as failed**
+- **Bulk refund** (updates status)
+
+**Use Cases**:
+- Payment reconciliation
+- Refund processing
+
+#### CreditUsageLog
+- **Bulk delete old logs** (>90 days)
+
+**Use Cases**:
+- Database cleanup
+- Log maintenance
+
+#### CreditPackage
+- **Bulk activate/deactivate**
+
+**Use Cases**:
+- Package availability management
+
+#### AccountPaymentMethod
+- **Bulk enable/disable**
+- **Bulk set as default** (Form: respects account-level uniqueness)
+- **Bulk delete methods**
+
+**Use Cases**:
+- Payment method management
+- Default method updates
+
+#### PlanLimitUsage
+- **Bulk reset usage**
+- **Bulk delete old records** (>90 days)
+
+**Use Cases**:
+- Usage tracking reset
+- Data cleanup
+
+---
+
+### Publishing & Integration
+
+#### PublishingRecord
+- **Bulk retry failed**
+- **Bulk cancel pending**
+- **Bulk mark as published**
+
+**Use Cases**:
+- Publishing workflow
+- Error recovery
+
+#### DeploymentRecord
+- **Bulk rollback**
+- **Bulk mark as successful**
+- **Bulk retry failed**
+
+**Use Cases**:
+- Deployment management
+- Error recovery
+
+#### SiteIntegration
+- **Bulk activate/deactivate**
+- **Bulk test connection**
+- **Bulk refresh tokens**
+
+**Use Cases**:
+- Integration management
+- Connection testing
+- Token maintenance
+
+#### SyncEvent
+- **Bulk mark as processed**
+- **Bulk delete old events** (>30 days)
+
+**Use Cases**:
+- Event processing
+- Log cleanup
+
+---
+
+### Automation
+
+#### AutomationConfig
+- **Bulk activate/deactivate**
+- **Bulk update frequency** (Form: select frequency)
+- **Bulk update delays** (Form: enter delay values)
+
+**Use Cases**:
+- Automation scheduling
+- Workflow configuration
+
+#### AutomationRun
+- **Bulk mark as completed**
+- **Bulk retry failed**
+- **Bulk delete old runs** (>90 days)
+
+**Use Cases**:
+- Run status management
+- Error recovery
+- Cleanup
+
+---
+
+### AI & System Configuration
+
+#### AITaskLog
+- **Bulk delete old logs** (>90 days)
+- **Bulk mark as reviewed**
+
+**Use Cases**:
+- Log maintenance
+- Review tracking
+
+#### AIPrompt
+- **Bulk activate/deactivate**
+- **Bulk reset to default values**
+
+**Use Cases**:
+- Prompt management
+- Configuration reset
+
+#### IntegrationSettings
+- **Bulk activate/deactivate**
+- **Bulk test connection**
+
+**Use Cases**:
+- Integration setup
+- Connection validation
+
+#### AuthorProfile
+- **Bulk activate/deactivate**
+- **Bulk clone profiles**
+
+**Use Cases**:
+- Profile management
+- Profile duplication
+
+#### Strategy
+- **Bulk activate/deactivate**
+- **Bulk clone strategies**
+
+**Use Cases**:
+- Strategy management
+- Strategy templates
+
+#### OptimizationTask
+- **Bulk mark as completed/failed**
+- **Bulk retry failed tasks**
+
+**Use Cases**:
+- Optimization workflow
+- Error recovery
+
+---
+
+### Site & Sector Management
+
+#### Site
+- **Bulk activate/deactivate**
+- **Bulk update settings** (Form: JSON settings)
+- **Bulk soft delete**
+
+**Use Cases**:
+- Site management
+- Configuration updates
+
+#### Sector
+- **Bulk activate/deactivate**
+- **Bulk soft delete**
+
+**Use Cases**:
+- Sector management
+- Multi-tenant organization
+
+#### Industry & IndustrySector
+- **Bulk activate/deactivate**
+- **Bulk soft delete**
+
+**Use Cases**:
+- Industry taxonomy management
+- Sector organization
+
+#### SeedKeyword
+- **Bulk approve/reject**
+- **Bulk assign to sector** (Form: select sector)
+- **Bulk soft delete**
+
+**Use Cases**:
+- Seed keyword management
+- Sector assignments
+
+---
+
+## Best Practices
+
+### Selection
+1. Use filters and search before bulk actions
+2. Preview selected records count
+3. Test with small batches first
+
+### Form Actions
+1. Read help text carefully
+2. Validate input before applying
+3. Cannot undo after confirmation
+
+### Export/Import
+1. Export before major changes (backup)
+2. Test imports on staging first
+3. Review preview before confirming import
+
+### Soft Delete
+1. Prefer soft delete over hard delete
+2. Maintains audit trails
+3. Can be recovered if needed
+
+### Performance
+1. Batch operations work efficiently up to 10,000 records
+2. For larger operations, consider database-level operations
+3. Monitor query performance with Django Debug Toolbar
+
+---
+
+## Troubleshooting
+
+### Action Not Appearing
+- Check user permissions
+- Verify model admin registration
+- Clear browser cache
+
+### Import Failures
+- Verify file format (CSV/XLSX)
+- Check field mappings
+- Ensure required fields present
+- Validate data types
+
+### Form Validation Errors
+- Review error messages
+- Check required fields
+- Verify foreign key references exist
+
+### Performance Issues
+- Reduce batch size
+- Add database indexes
+- Use `.select_related()` for foreign keys
+- Consider background task queue for large operations
+
+---
+
+## Security Notes
+
+1. **Permissions**: All actions respect Django's built-in permissions system
+2. **Account Isolation**: Multi-tenant actions automatically filter by account
+3. **CSRF Protection**: All forms include CSRF tokens
+4. **Audit Logging**: Consider enabling Django admin log for all actions
+5. **Soft Deletes**: Preserve data integrity and compliance requirements
+
+---
+
+## Quick Action Shortcuts
+
+### Most Used Actions
+1. **Content Publishing**: Content → Bulk publish to WordPress
+2. **Credit Management**: Account → Bulk add credits
+3. **Task Assignment**: Tasks → Bulk assign to user
+4. **Invoice Processing**: Invoice → Bulk mark as paid
+5. **Automation Control**: AutomationConfig → Bulk activate/deactivate
+
+### Maintenance Actions
+1. **Log Cleanup**: AITaskLog/CreditUsageLog → Delete old logs
+2. **Event Cleanup**: SyncEvent → Delete old events
+3. **Run Cleanup**: AutomationRun → Delete old runs
+4. **Usage Reset**: PlanLimitUsage → Bulk reset usage
+
+### Emergency Actions
+1. **Account Suspension**: Account → Bulk suspend accounts
+2. **Task Cancellation**: Tasks → Bulk cancel tasks
+3. **Publishing Rollback**: DeploymentRecord → Bulk rollback
+4. **Integration Disable**: SiteIntegration → Bulk deactivate
+
+---
+
+*Last Updated: 2025*
+*IGNY8 Platform - Django Admin Operations Guide*