mirror of
https://github.com/pacnpal/thrillwiki_django_no_react.git
synced 2025-12-20 06:11:07 -05:00
docs
This commit is contained in:
pacnpal
290
docs/moderation_guide.md
Normal file
290
docs/moderation_guide.md
Normal file
@@ -0,0 +1,290 @@
|
||||
# ThrillWiki Moderation Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This guide covers the moderation systems in ThrillWiki, including:
|
||||
- Content edit submissions
|
||||
- Photo submissions
|
||||
- User reviews
|
||||
- Report handling
|
||||
- Moderation best practices
|
||||
|
||||
## Moderation Dashboard
|
||||
|
||||
Access the moderation dashboard at `/moderation/` to view:
|
||||
- Pending edit submissions
|
||||
- Photo submissions awaiting review
|
||||
- Reported content
|
||||
- Moderation statistics
|
||||
|
||||
## Content Edit Moderation
|
||||
|
||||
### Edit Submission Types
|
||||
1. **Edit Existing**
|
||||
- Changes to existing parks, rides, or other content
|
||||
- Shows diff of proposed changes
|
||||
- Requires source verification
|
||||
|
||||
2. **Create New**
|
||||
- New park, ride, or content submissions
|
||||
- Requires complete information
|
||||
- Needs source verification
|
||||
|
||||
### Review Process
|
||||
1. **Initial Assessment**
|
||||
- Check submission completeness
|
||||
- Verify sources
|
||||
- Review user history
|
||||
|
||||
2. **Status Options**
|
||||
```python
|
||||
STATUS_CHOICES = [
|
||||
('NEW', 'New'),
|
||||
('APPROVED', 'Approved'),
|
||||
('REJECTED', 'Rejected'),
|
||||
('ESCALATED', 'Escalated'),
|
||||
]
|
||||
```
|
||||
|
||||
3. **Actions**
|
||||
- Approve: Apply changes after verification
|
||||
- Reject: Provide clear reason
|
||||
- Escalate: For complex cases needing admin review
|
||||
|
||||
### Approval Guidelines
|
||||
- Verify information accuracy
|
||||
- Check reliable sources
|
||||
- Ensure formatting consistency
|
||||
- Review for completeness
|
||||
|
||||
### Rejection Guidelines
|
||||
- Provide clear explanation
|
||||
- Reference guidelines
|
||||
- Suggest improvements
|
||||
- Be constructive
|
||||
|
||||
## Photo Moderation
|
||||
|
||||
### Submission Types
|
||||
- Park photos
|
||||
- Ride photos
|
||||
- Attraction photos
|
||||
- Historical photos
|
||||
|
||||
### Review Process
|
||||
1. **Initial Check**
|
||||
- Image quality
|
||||
- Appropriate content
|
||||
- Copyright concerns
|
||||
- Metadata accuracy
|
||||
|
||||
2. **Status Options**
|
||||
```python
|
||||
STATUS_CHOICES = [
|
||||
('NEW', 'New'),
|
||||
('APPROVED', 'Approved'),
|
||||
('REJECTED', 'Rejected'),
|
||||
('AUTO_APPROVED', 'Auto Approved'),
|
||||
]
|
||||
```
|
||||
|
||||
3. **Actions**
|
||||
- Approve: Add to main gallery
|
||||
- Reject: Explain issues
|
||||
- Auto-approve: For trusted users
|
||||
|
||||
### Photo Guidelines
|
||||
- Minimum resolution requirements
|
||||
- No watermarks
|
||||
- Clear and focused
|
||||
- Appropriate content
|
||||
- Proper attribution
|
||||
|
||||
## Review Moderation
|
||||
|
||||
### Review Components
|
||||
- Rating (1-10)
|
||||
- Written content
|
||||
- Visit date
|
||||
- Optional photos
|
||||
|
||||
### Moderation Criteria
|
||||
1. **Content Standards**
|
||||
- Constructive feedback
|
||||
- No personal attacks
|
||||
- Family-friendly language
|
||||
- Factual accuracy
|
||||
|
||||
2. **Rating Consistency**
|
||||
- Check against written content
|
||||
- Compare with average ratings
|
||||
- Look for rating abuse
|
||||
|
||||
3. **Photo Guidelines**
|
||||
- Relevant to review
|
||||
- Appropriate content
|
||||
- Quality standards
|
||||
|
||||
### Report Handling
|
||||
1. **Review Reports**
|
||||
- Assess reported content
|
||||
- Check reporter history
|
||||
- Verify claims
|
||||
|
||||
2. **Actions**
|
||||
- Remove inappropriate content
|
||||
- Edit/update if needed
|
||||
- Notify users
|
||||
- Document actions
|
||||
|
||||
## Best Practices
|
||||
|
||||
### General Guidelines
|
||||
1. **Consistency**
|
||||
- Follow established guidelines
|
||||
- Apply rules uniformly
|
||||
- Document decisions
|
||||
|
||||
2. **Communication**
|
||||
- Clear explanations
|
||||
- Professional tone
|
||||
- Constructive feedback
|
||||
|
||||
3. **Escalation**
|
||||
- Know when to escalate
|
||||
- Document complex cases
|
||||
- Seek admin input
|
||||
|
||||
### Quality Control
|
||||
1. **Content Standards**
|
||||
- Accuracy
|
||||
- Completeness
|
||||
- Formatting
|
||||
- Source verification
|
||||
|
||||
2. **User Management**
|
||||
- Track user history
|
||||
- Identify trusted contributors
|
||||
- Handle problem users
|
||||
|
||||
3. **Documentation**
|
||||
- Record decisions
|
||||
- Note special cases
|
||||
- Track patterns
|
||||
|
||||
## Moderation Tools
|
||||
|
||||
### Edit Submission Tools
|
||||
```python
|
||||
def approve(self, user):
|
||||
"""Approve and apply changes"""
|
||||
# Validates and applies changes
|
||||
# Updates status
|
||||
# Records moderator action
|
||||
|
||||
def reject(self, user):
|
||||
"""Reject submission"""
|
||||
# Updates status
|
||||
# Records moderator action
|
||||
# Notifies user
|
||||
|
||||
def escalate(self, user):
|
||||
"""Escalate to admin"""
|
||||
# Marks for admin review
|
||||
# Records moderator action
|
||||
```
|
||||
|
||||
### Photo Submission Tools
|
||||
```python
|
||||
def approve(self, moderator, notes=''):
|
||||
"""Approve photo"""
|
||||
# Moves to main gallery
|
||||
# Updates status
|
||||
# Records approval
|
||||
|
||||
def reject(self, moderator, notes):
|
||||
"""Reject photo"""
|
||||
# Updates status
|
||||
# Records rejection reason
|
||||
# Notifies user
|
||||
```
|
||||
|
||||
## Special Cases
|
||||
|
||||
### Content Disputes
|
||||
1. **Handling Conflicts**
|
||||
- Review all perspectives
|
||||
- Check reliable sources
|
||||
- Document decisions
|
||||
- Consider escalation
|
||||
|
||||
2. **Resolution Process**
|
||||
- Gather evidence
|
||||
- Consult experts if needed
|
||||
- Make documented decision
|
||||
- Communicate clearly
|
||||
|
||||
### Emergency Situations
|
||||
1. **Immediate Action Needed**
|
||||
- Inappropriate content
|
||||
- Copyright violations
|
||||
- Personal information
|
||||
- Harmful content
|
||||
|
||||
2. **Response Protocol**
|
||||
- Remove content immediately
|
||||
- Document action taken
|
||||
- Notify administrators
|
||||
- Follow up as needed
|
||||
|
||||
## Moderation Workflow
|
||||
|
||||
1. **Daily Tasks**
|
||||
- Review new submissions
|
||||
- Check reported content
|
||||
- Handle escalations
|
||||
- Update documentation
|
||||
|
||||
2. **Weekly Tasks**
|
||||
- Review moderation patterns
|
||||
- Check for recurring issues
|
||||
- Update guidelines if needed
|
||||
- Team communication
|
||||
|
||||
3. **Monthly Tasks**
|
||||
- Review statistics
|
||||
- Assess guidelines
|
||||
- Plan improvements
|
||||
- Team training
|
||||
|
||||
## Resources
|
||||
|
||||
### Reference Materials
|
||||
- Content guidelines
|
||||
- Photo standards
|
||||
- Review policies
|
||||
- Escalation procedures
|
||||
|
||||
### Support Channels
|
||||
- Admin contact information
|
||||
- Team communication
|
||||
- Emergency procedures
|
||||
- Legal resources
|
||||
|
||||
## Training and Development
|
||||
|
||||
1. **New Moderator Training**
|
||||
- Platform overview
|
||||
- Tools introduction
|
||||
- Guidelines review
|
||||
- Supervised practice
|
||||
|
||||
2. **Ongoing Development**
|
||||
- Regular updates
|
||||
- Case studies
|
||||
- Best practices
|
||||
- Team feedback
|
||||
|
||||
## Conclusion
|
||||
|
||||
Effective moderation is crucial for maintaining ThrillWiki's quality and community. Follow these guidelines consistently while using good judgment for special cases. Document decisions and seek help when needed.
|
||||
244
docs/project_documentation.md
Normal file
244
docs/project_documentation.md
Normal file
@@ -0,0 +1,244 @@
|
||||
# ThrillWiki Project Documentation
|
||||
|
||||
## Overview
|
||||
ThrillWiki is a comprehensive Django-based web application for managing and sharing information about amusement parks, rides, and attractions. The platform allows users to explore parks, review rides, share photos, and track various statistics about amusement parks and rides worldwide.
|
||||
|
||||
## System Architecture
|
||||
|
||||
### Core Applications
|
||||
|
||||
1. **Parks App**
|
||||
- Manages amusement park information
|
||||
- Handles park areas and locations
|
||||
- Tracks park statistics and operating status
|
||||
|
||||
2. **Rides App**
|
||||
- Manages ride information and categories
|
||||
- Tracks detailed roller coaster statistics
|
||||
- Links rides to parks, manufacturers, and designers
|
||||
|
||||
3. **Companies App**
|
||||
- Handles park ownership information
|
||||
- Manages ride manufacturers
|
||||
- Tracks company statistics and history
|
||||
|
||||
4. **Designers App**
|
||||
- Manages ride designer/engineering firm information
|
||||
- Tracks designer contributions and history
|
||||
|
||||
5. **Media App**
|
||||
- Handles photo uploads and management
|
||||
- Supports generic relationships for photos
|
||||
- Manages media storage and organization
|
||||
|
||||
6. **Reviews App**
|
||||
- Manages user reviews and ratings
|
||||
- Handles review moderation
|
||||
- Supports review images and likes
|
||||
|
||||
7. **Analytics App**
|
||||
- Tracks page views and user interactions
|
||||
- Identifies trending content
|
||||
- Provides analytics data for the platform
|
||||
|
||||
### Authentication & User Management
|
||||
- Custom user model through accounts app
|
||||
- Social authentication support (Google, Discord)
|
||||
- User profiles and settings management
|
||||
|
||||
## Data Models
|
||||
|
||||
### Park Models
|
||||
```python
|
||||
class Park:
|
||||
- name, slug, description
|
||||
- status (Operating, Closed, etc.)
|
||||
- location (latitude, longitude, address)
|
||||
- operating details (season, dates)
|
||||
- statistics (total rides, coasters)
|
||||
- ownership information
|
||||
```
|
||||
|
||||
### Ride Models
|
||||
```python
|
||||
class Ride:
|
||||
- name, slug, description
|
||||
- category (Roller Coaster, Dark Ride, etc.)
|
||||
- status and operating dates
|
||||
- manufacturer and designer links
|
||||
- park and area location
|
||||
- accessibility and capacity info
|
||||
|
||||
class RollerCoasterStats:
|
||||
- height, length, speed metrics
|
||||
- track type and materials
|
||||
- launch system details
|
||||
- train configuration
|
||||
```
|
||||
|
||||
### Company Models
|
||||
```python
|
||||
class Company:
|
||||
- name, slug, description
|
||||
- headquarters and contact info
|
||||
- park ownership tracking
|
||||
- historical records
|
||||
|
||||
class Manufacturer:
|
||||
- name, slug, description
|
||||
- ride production statistics
|
||||
- historical records
|
||||
```
|
||||
|
||||
### Media Management
|
||||
```python
|
||||
class Photo:
|
||||
- Generic relationship to content
|
||||
- Image storage and organization
|
||||
- Caption and metadata
|
||||
- Upload tracking
|
||||
```
|
||||
|
||||
### Review System
|
||||
```python
|
||||
class Review:
|
||||
- Generic relationship to content
|
||||
- Rating and content
|
||||
- Moderation support
|
||||
- Image attachments
|
||||
- Like/report functionality
|
||||
```
|
||||
|
||||
### Analytics
|
||||
```python
|
||||
class PageView:
|
||||
- Content tracking
|
||||
- Timestamp and user info
|
||||
- Trending content calculation
|
||||
```
|
||||
|
||||
## Key Features
|
||||
|
||||
### Content Management
|
||||
- Comprehensive park and ride information
|
||||
- Historical tracking of all content changes
|
||||
- Rich media support with photo management
|
||||
- Detailed statistics and specifications
|
||||
|
||||
### User Interaction
|
||||
- User reviews and ratings
|
||||
- Photo uploads and sharing
|
||||
- Content moderation system
|
||||
- Social features (likes, reports)
|
||||
|
||||
### Analytics and Trending
|
||||
- Page view tracking
|
||||
- Trending content identification
|
||||
- Usage statistics and metrics
|
||||
|
||||
### Location Features
|
||||
- Geographic coordinates
|
||||
- Address management
|
||||
- Park area organization
|
||||
|
||||
## Technical Implementation
|
||||
|
||||
### Database Design
|
||||
- PostgreSQL database
|
||||
- Generic relations for flexible content relationships
|
||||
- Comprehensive indexing for performance
|
||||
- Historical record tracking
|
||||
|
||||
### Authentication
|
||||
- Django allauth integration
|
||||
- Multiple social auth providers
|
||||
- Custom user model and authentication flow
|
||||
|
||||
### Media Handling
|
||||
- Custom storage backend
|
||||
- Organized file structure
|
||||
- Automatic file naming and organization
|
||||
|
||||
### Performance Features
|
||||
- Caching configuration
|
||||
- Database query optimization
|
||||
- Efficient media handling
|
||||
|
||||
### Security Features
|
||||
- CSRF protection
|
||||
- Secure authentication
|
||||
- Content moderation
|
||||
- User input validation
|
||||
|
||||
## Management Commands
|
||||
|
||||
### Analytics
|
||||
- `update_trending.py`: Updates trending content calculations
|
||||
|
||||
### Parks
|
||||
- `update_park_counts.py`: Updates park statistics and ride counts
|
||||
|
||||
## Frontend Integration
|
||||
|
||||
### Templates
|
||||
- Organized template structure
|
||||
- Partial templates for reusability
|
||||
- Photo gallery integration
|
||||
|
||||
### Static Files
|
||||
- CSS with Tailwind integration
|
||||
- JavaScript for interactive features
|
||||
- Photo gallery functionality
|
||||
|
||||
## Development Guidelines
|
||||
|
||||
### Code Organization
|
||||
- Modular app structure
|
||||
- Clear separation of concerns
|
||||
- Consistent naming conventions
|
||||
|
||||
### Best Practices
|
||||
- Generic relations for flexibility
|
||||
- Historical tracking for all major models
|
||||
- Comprehensive validation
|
||||
- Efficient query patterns
|
||||
|
||||
### Security Considerations
|
||||
- Secure content storage
|
||||
- User permission management
|
||||
- Input validation and sanitization
|
||||
- Protected user data
|
||||
|
||||
## Deployment Considerations
|
||||
|
||||
### Environment Configuration
|
||||
- Environment-specific settings
|
||||
- Secure key management
|
||||
- Database configuration
|
||||
|
||||
### Media Storage
|
||||
- Organized upload structure
|
||||
- Efficient file handling
|
||||
- Backup considerations
|
||||
|
||||
### Performance Optimization
|
||||
- Caching strategy
|
||||
- Database indexing
|
||||
- Query optimization
|
||||
|
||||
## Future Considerations
|
||||
|
||||
### Scalability
|
||||
- Database optimization opportunities
|
||||
- Caching improvements
|
||||
- Media handling optimization
|
||||
|
||||
### Feature Expansion
|
||||
- Additional social features
|
||||
- Enhanced analytics
|
||||
- Mobile app integration possibilities
|
||||
|
||||
### Integration Opportunities
|
||||
- API development
|
||||
- Third-party service integration
|
||||
- Mobile app support
|
||||
153
docs/quickstart.md
Normal file
153
docs/quickstart.md
Normal file
@@ -0,0 +1,153 @@
|
||||
# ThrillWiki Quick Start Guide
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python 3.8+
|
||||
- PostgreSQL
|
||||
- Node.js (for Tailwind CSS)
|
||||
|
||||
## Setup Instructions
|
||||
|
||||
1. **Clone the Repository**
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd thrillwiki
|
||||
```
|
||||
|
||||
2. **Create Virtual Environment**
|
||||
```bash
|
||||
python -m venv venv
|
||||
source venv/bin/activate # On Windows: venv\Scripts\activate
|
||||
```
|
||||
|
||||
3. **Install Dependencies**
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
4. **Database Setup**
|
||||
```bash
|
||||
# Update database settings in thrillwiki/settings.py
|
||||
python manage.py migrate
|
||||
```
|
||||
|
||||
5. **Create Superuser**
|
||||
```bash
|
||||
python manage.py createsuperuser
|
||||
```
|
||||
|
||||
6. **Install Frontend Dependencies**
|
||||
```bash
|
||||
# Install Tailwind CSS
|
||||
npm install
|
||||
```
|
||||
|
||||
7. **Environment Configuration**
|
||||
- Copy example environment file
|
||||
- Update necessary settings
|
||||
- Configure social auth providers
|
||||
|
||||
8. **Run Development Server**
|
||||
```bash
|
||||
python manage.py runserver
|
||||
```
|
||||
|
||||
## Key URLs
|
||||
|
||||
- Admin Interface: `/admin/`
|
||||
- Home Page: `/`
|
||||
- Parks List: `/parks/`
|
||||
- Rides List: `/rides/`
|
||||
|
||||
## Development Guidelines
|
||||
|
||||
1. **Model Changes**
|
||||
```bash
|
||||
python manage.py makemigrations
|
||||
python manage.py migrate
|
||||
```
|
||||
|
||||
2. **Running Tests**
|
||||
```bash
|
||||
python manage.py test
|
||||
```
|
||||
|
||||
3. **Update Trending Content**
|
||||
```bash
|
||||
python manage.py update_trending
|
||||
```
|
||||
|
||||
4. **Update Park Statistics**
|
||||
```bash
|
||||
python manage.py update_park_counts
|
||||
```
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Adding a New Park
|
||||
1. Access admin interface
|
||||
2. Navigate to Parks section
|
||||
3. Click "Add Park"
|
||||
4. Fill required information
|
||||
5. Save
|
||||
|
||||
### Adding a New Ride
|
||||
1. Access admin interface
|
||||
2. Navigate to Rides section
|
||||
3. Click "Add Ride"
|
||||
4. Fill required information
|
||||
5. Add roller coaster stats if applicable
|
||||
6. Save
|
||||
|
||||
### Managing Photos
|
||||
1. Photos can be added to parks, rides, or companies
|
||||
2. Use the photo upload form on respective detail pages
|
||||
3. Set primary photo as needed
|
||||
|
||||
### Moderating Reviews
|
||||
1. Access admin interface
|
||||
2. Navigate to Reviews section
|
||||
3. Review flagged content
|
||||
4. Take appropriate moderation action
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Database Connection**
|
||||
- Verify PostgreSQL is running
|
||||
- Check database credentials
|
||||
- Ensure database exists
|
||||
|
||||
2. **Media Upload Issues**
|
||||
- Check file permissions
|
||||
- Verify media storage configuration
|
||||
- Ensure proper file types
|
||||
|
||||
3. **Social Auth**
|
||||
- Verify provider credentials
|
||||
- Check callback URLs
|
||||
- Review auth settings
|
||||
|
||||
### Getting Help
|
||||
|
||||
- Check existing documentation in `/docs`
|
||||
- Review error logs
|
||||
- Contact development team
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Code Style**
|
||||
- Follow PEP 8
|
||||
- Use type hints
|
||||
- Document functions and classes
|
||||
|
||||
2. **Git Workflow**
|
||||
- Create feature branches
|
||||
- Write descriptive commits
|
||||
- Keep changes focused
|
||||
|
||||
3. **Testing**
|
||||
- Write unit tests
|
||||
- Test all new features
|
||||
- Verify existing functionality
|
||||
77
docs/technical_architecture.md
Normal file
77
docs/technical_architecture.md
Normal file
@@ -0,0 +1,77 @@
|
||||
# ThrillWiki Technical Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ ThrillWiki Platform │
|
||||
├─────────────────┬─────────────────────┬───────────────────┤
|
||||
│ Frontend Layer │ Application Layer │ Storage Layer │
|
||||
├─────────────────┤ │ │
|
||||
│ - Templates │ Django Apps │ - PostgreSQL DB │
|
||||
│ - Tailwind CSS │ ┌──────────┐ │ - Media Storage │
|
||||
│ - JavaScript │ │ Parks │ │ - Static Files │
|
||||
│ │ │ Rides │ │ │
|
||||
│ Components │ │Companies │ │ │
|
||||
│ - Photo Gallery │ │Designers │ │ │
|
||||
│ - Review Forms │ └──────────┘ │ │
|
||||
│ │ │ │
|
||||
├─────────────────┼─────────────────────┼───────────────────┤
|
||||
│ Auth Layer │ Service Layer │ Analytics Layer │
|
||||
├─────────────────┤ │ │
|
||||
│ - Django Auth │ Core Services │ - Page Tracking │
|
||||
│ - Social Auth │ ┌──────────┐ │ - Trending Calc │
|
||||
│ - Permissions │ │ Reviews │ │ - Usage Stats │
|
||||
│ │ │ Media │ │ │
|
||||
│ │ │Analytics │ │ │
|
||||
│ │ └──────────┘ │ │
|
||||
└─────────────────┴─────────────────────┴───────────────────┘
|
||||
|
||||
Data Flow:
|
||||
User Request → URL Router → View → Model → Database
|
||||
↓
|
||||
Template → Response
|
||||
|
||||
Content Relations:
|
||||
Park ──┬── Areas
|
||||
└── Rides ─┬── Manufacturer
|
||||
└── Designer
|
||||
|
||||
Media Storage:
|
||||
Content ─→ Generic Relation ─→ Photos
|
||||
|
||||
Analytics Flow:
|
||||
Page View → Tracking → Trending Calculation
|
||||
```
|
||||
|
||||
## Key Components
|
||||
|
||||
1. **Frontend Layer**
|
||||
- Template-based rendering
|
||||
- Tailwind CSS styling
|
||||
- JavaScript enhancements
|
||||
- Interactive components
|
||||
|
||||
2. **Application Layer**
|
||||
- Core domain apps
|
||||
- Business logic
|
||||
- Data validation
|
||||
- Content management
|
||||
|
||||
3. **Storage Layer**
|
||||
- Database persistence
|
||||
- Media file storage
|
||||
- Caching system
|
||||
|
||||
4. **Authentication Layer**
|
||||
- User management
|
||||
- Social authentication
|
||||
- Permission control
|
||||
|
||||
5. **Service Layer**
|
||||
- Review system
|
||||
- Media handling
|
||||
- Email services
|
||||
|
||||
6. **Analytics Layer**
|
||||
- View tracking
|
||||
- Trend analysis
|
||||
- Usage statistics
|
||||
Reference in New Issue
Block a user