mirror of
https://github.com/pacnpal/thrillwiki_django_no_react.git
synced 2025-12-20 05:11:09 -05:00
feat: major API restructure and Vue.js frontend integration
- Centralize API endpoints in dedicated api app with v1 versioning - Remove individual API modules from parks and rides apps - Add event tracking system with analytics functionality - Integrate Vue.js frontend with Tailwind CSS v4 and TypeScript - Add comprehensive database migrations for event tracking - Implement user authentication and social provider setup - Add API schema documentation and serializers - Configure development environment with shared scripts - Update project structure for monorepo with frontend/backend separation
This commit is contained in:
pacnpal
465
shared/docs/api/README.md
Normal file
465
shared/docs/api/README.md
Normal file
@@ -0,0 +1,465 @@
|
||||
# ThrillWiki API Documentation
|
||||
|
||||
Complete API reference for the ThrillWiki Django REST API backend.
|
||||
|
||||
## Overview
|
||||
|
||||
The ThrillWiki API provides comprehensive access to theme park and roller coaster data through a RESTful interface designed specifically for the Vue.js frontend. The API uses Django REST Framework with custom frontend-compatible serializers that convert Django's snake_case to JavaScript's camelCase convention.
|
||||
|
||||
**Base URL:** `http://localhost:8000/api/`
|
||||
|
||||
## Authentication
|
||||
|
||||
The API currently supports anonymous access for read operations. Authentication will be added in future versions for write operations and user-specific features.
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Parks
|
||||
|
||||
#### List Parks
|
||||
```http
|
||||
GET /api/parks/
|
||||
```
|
||||
|
||||
**Response Format:**
|
||||
```json
|
||||
{
|
||||
"count": 150,
|
||||
"next": "http://localhost:8000/api/parks/?page=2",
|
||||
"previous": null,
|
||||
"results": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Cedar Point",
|
||||
"slug": "cedar-point",
|
||||
"location": "Sandusky, Ohio",
|
||||
"operator": "Cedar Fair",
|
||||
"openingYear": 1870,
|
||||
"status": "open",
|
||||
"description": "America's Roller Coast",
|
||||
"website": "https://www.cedarpoint.com",
|
||||
"imageUrl": "/placeholder-park.jpg"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
- `page` - Page number for pagination
|
||||
- `search` - Search parks by name or location
|
||||
- `status` - Filter by park status (`open`, `closed`, `seasonal`)
|
||||
- `operator` - Filter by operator name
|
||||
|
||||
#### Get Park Details
|
||||
```http
|
||||
GET /api/parks/{id}/
|
||||
```
|
||||
|
||||
**Response Format:**
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Cedar Point",
|
||||
"slug": "cedar-point",
|
||||
"location": "Sandusky, Ohio",
|
||||
"operator": "Cedar Fair",
|
||||
"openingYear": 1870,
|
||||
"status": "open",
|
||||
"description": "America's Roller Coast",
|
||||
"website": "https://www.cedarpoint.com",
|
||||
"imageUrl": "/placeholder-park.jpg",
|
||||
"averageRating": 4.5,
|
||||
"rideCount": 72,
|
||||
"coasterCount": 17,
|
||||
"sizeAcres": 364,
|
||||
"operatingSeason": "May-October"
|
||||
}
|
||||
```
|
||||
|
||||
### Rides
|
||||
|
||||
#### List Rides
|
||||
```http
|
||||
GET /api/rides/
|
||||
```
|
||||
|
||||
**Response Format:**
|
||||
```json
|
||||
{
|
||||
"count": 500,
|
||||
"next": "http://localhost:8000/api/rides/?page=2",
|
||||
"previous": null,
|
||||
"results": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Millennium Force",
|
||||
"slug": "millennium-force",
|
||||
"parkId": 1,
|
||||
"parkName": "Cedar Point",
|
||||
"parkSlug": "cedar-point",
|
||||
"category": "roller_coaster",
|
||||
"manufacturer": "Intamin",
|
||||
"designer": "Werner Stengel",
|
||||
"openingYear": 2000,
|
||||
"height": 310,
|
||||
"speed": 93,
|
||||
"length": 6595,
|
||||
"inversions": 0,
|
||||
"status": "operating",
|
||||
"description": "World's tallest complete-circuit roller coaster",
|
||||
"imageUrl": "/placeholder-ride.jpg",
|
||||
"thrillLevel": "extreme"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
- `page` - Page number for pagination
|
||||
- `search` - Search rides by name
|
||||
- `park` - Filter by park ID
|
||||
- `category` - Filter by ride category (`roller_coaster`, `dark_ride`, `flat_ride`, `water_ride`, `transport`, `other`)
|
||||
- `status` - Filter by ride status (`operating`, `closed`, `sbno`, `under_construction`)
|
||||
- `manufacturer` - Filter by manufacturer name
|
||||
- `thrill_level` - Filter by thrill level (`family`, `moderate`, `intense`, `extreme`)
|
||||
|
||||
#### Get Ride Details
|
||||
```http
|
||||
GET /api/rides/{id}/
|
||||
```
|
||||
|
||||
**Response Format:**
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Millennium Force",
|
||||
"slug": "millennium-force",
|
||||
"parkId": 1,
|
||||
"parkName": "Cedar Point",
|
||||
"parkSlug": "cedar-point",
|
||||
"category": "roller_coaster",
|
||||
"manufacturer": "Intamin",
|
||||
"designer": "Werner Stengel",
|
||||
"openingYear": 2000,
|
||||
"height": 310,
|
||||
"speed": 93,
|
||||
"length": 6595,
|
||||
"inversions": 0,
|
||||
"status": "operating",
|
||||
"description": "World's tallest complete-circuit roller coaster",
|
||||
"imageUrl": "/placeholder-ride.jpg",
|
||||
"thrillLevel": "extreme",
|
||||
"minHeightIn": 48,
|
||||
"maxHeightIn": 78,
|
||||
"capacityPerHour": 1300,
|
||||
"rideDurationSeconds": 120,
|
||||
"averageRating": 4.8,
|
||||
"closingDate": null,
|
||||
"statusSince": "2000-05-13",
|
||||
"coasterStats": {
|
||||
"trackMaterial": "steel",
|
||||
"coasterType": "hypercoaster",
|
||||
"launchType": "chain_lift",
|
||||
"maxDropHeightFt": 300,
|
||||
"rideTimeSeconds": 120,
|
||||
"trainsCount": 2,
|
||||
"carsPerTrain": 9,
|
||||
"seatsPerCar": 4,
|
||||
"trainStyle": "open_air",
|
||||
"trackType": "complete_circuit"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Get Rides by Park
|
||||
```http
|
||||
GET /api/parks/{park_id}/rides/
|
||||
```
|
||||
|
||||
Returns all rides for a specific park using the same format as the main rides endpoint.
|
||||
|
||||
## Data Models
|
||||
|
||||
### Park Data Structure
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | integer | Unique park identifier |
|
||||
| `name` | string | Park name |
|
||||
| `slug` | string | URL-friendly park identifier |
|
||||
| `location` | string | Formatted location (e.g., "Sandusky, Ohio") |
|
||||
| `operator` | string | Park operating company |
|
||||
| `openingYear` | integer | Year park opened |
|
||||
| `status` | string | Park status: `open`, `closed`, `seasonal` |
|
||||
| `description` | string | Park description |
|
||||
| `website` | string | Official website URL |
|
||||
| `imageUrl` | string | Primary park image URL |
|
||||
| `averageRating` | float | Average user rating (detail view only) |
|
||||
| `rideCount` | integer | Total number of rides (detail view only) |
|
||||
| `coasterCount` | integer | Number of roller coasters (detail view only) |
|
||||
| `sizeAcres` | float | Park size in acres (detail view only) |
|
||||
| `operatingSeason` | string | Operating season description (detail view only) |
|
||||
|
||||
### Ride Data Structure
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | integer | Unique ride identifier |
|
||||
| `name` | string | Ride name |
|
||||
| `slug` | string | URL-friendly ride identifier |
|
||||
| `parkId` | integer | Parent park ID |
|
||||
| `parkName` | string | Parent park name |
|
||||
| `parkSlug` | string | Parent park slug |
|
||||
| `category` | string | Ride category |
|
||||
| `manufacturer` | string | Ride manufacturer |
|
||||
| `designer` | string | Ride designer |
|
||||
| `openingYear` | integer | Year ride opened |
|
||||
| `height` | float | Height in feet (coasters only) |
|
||||
| `speed` | float | Speed in mph (coasters only) |
|
||||
| `length` | float | Length in feet (coasters only) |
|
||||
| `inversions` | integer | Number of inversions (coasters only) |
|
||||
| `status` | string | Ride status |
|
||||
| `description` | string | Ride description |
|
||||
| `imageUrl` | string | Primary ride image URL |
|
||||
| `thrillLevel` | string | Calculated thrill level |
|
||||
| `minHeightIn` | integer | Minimum height requirement (detail view only) |
|
||||
| `maxHeightIn` | integer | Maximum height requirement (detail view only) |
|
||||
| `capacityPerHour` | integer | Hourly capacity (detail view only) |
|
||||
| `rideDurationSeconds` | integer | Ride duration in seconds (detail view only) |
|
||||
| `averageRating` | float | Average user rating (detail view only) |
|
||||
| `closingDate` | date | Date ride closed (detail view only) |
|
||||
| `statusSince` | date | Date status changed (detail view only) |
|
||||
| `coasterStats` | object | Detailed coaster statistics (detail view only) |
|
||||
|
||||
### Coaster Statistics Structure
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `trackMaterial` | string | Track material (steel, wood) |
|
||||
| `coasterType` | string | Coaster type (hypercoaster, inverted, etc.) |
|
||||
| `launchType` | string | Launch mechanism |
|
||||
| `maxDropHeightFt` | float | Maximum drop height in feet |
|
||||
| `rideTimeSeconds` | integer | Total ride time in seconds |
|
||||
| `trainsCount` | integer | Number of trains |
|
||||
| `carsPerTrain` | integer | Cars per train |
|
||||
| `seatsPerCar` | integer | Seats per car |
|
||||
| `trainStyle` | string | Train style (open_air, enclosed) |
|
||||
| `trackType` | string | Track configuration |
|
||||
|
||||
## Field Mappings
|
||||
|
||||
### Django to Frontend Field Conversion
|
||||
|
||||
The API automatically converts Django's snake_case field names to JavaScript's camelCase convention:
|
||||
|
||||
| Django Model | Frontend API |
|
||||
|--------------|--------------|
|
||||
| `opening_date` | `openingYear` |
|
||||
| `min_height_in` | `minHeightIn` |
|
||||
| `max_height_in` | `maxHeightIn` |
|
||||
| `capacity_per_hour` | `capacityPerHour` |
|
||||
| `ride_duration_seconds` | `rideDurationSeconds` |
|
||||
| `coaster_stats` | `coasterStats` |
|
||||
| `size_acres` | `sizeAcres` |
|
||||
| `ride_count` | `rideCount` |
|
||||
| `coaster_count` | `coasterCount` |
|
||||
| `average_rating` | `averageRating` |
|
||||
|
||||
### Status Mappings
|
||||
|
||||
#### Park Status
|
||||
| Django | Frontend |
|
||||
|--------|----------|
|
||||
| `OPERATING` | `open` |
|
||||
| `CLOSED_TEMP` | `seasonal` |
|
||||
| `CLOSED_PERM` | `closed` |
|
||||
| `UNDER_CONSTRUCTION` | `closed` |
|
||||
| `DEMOLISHED` | `closed` |
|
||||
| `RELOCATED` | `closed` |
|
||||
|
||||
#### Ride Status
|
||||
| Django | Frontend |
|
||||
|--------|----------|
|
||||
| `OPERATING` | `operating` |
|
||||
| `CLOSED_TEMP` | `closed` |
|
||||
| `SBNO` | `sbno` |
|
||||
| `CLOSING` | `closed` |
|
||||
| `CLOSED_PERM` | `closed` |
|
||||
| `UNDER_CONSTRUCTION` | `under_construction` |
|
||||
| `DEMOLISHED` | `closed` |
|
||||
| `RELOCATED` | `closed` |
|
||||
|
||||
### Category Mappings
|
||||
|
||||
#### Ride Categories
|
||||
| Django | Frontend |
|
||||
|--------|----------|
|
||||
| `RC` | `roller_coaster` |
|
||||
| `DR` | `dark_ride` |
|
||||
| `FR` | `flat_ride` |
|
||||
| `WR` | `water_ride` |
|
||||
| `TR` | `transport` |
|
||||
| `OT` | `other` |
|
||||
|
||||
## Error Handling
|
||||
|
||||
The API returns standard HTTP status codes with detailed error information:
|
||||
|
||||
### Error Response Format
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "NOT_FOUND",
|
||||
"message": "Park with id 999 not found",
|
||||
"details": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Common HTTP Status Codes
|
||||
- `200 OK` - Successful request
|
||||
- `201 Created` - Resource created successfully
|
||||
- `400 Bad Request` - Invalid request data
|
||||
- `401 Unauthorized` - Authentication required
|
||||
- `403 Forbidden` - Insufficient permissions
|
||||
- `404 Not Found` - Resource not found
|
||||
- `429 Too Many Requests` - Rate limit exceeded
|
||||
- `500 Internal Server Error` - Server error
|
||||
|
||||
## Pagination
|
||||
|
||||
List endpoints support pagination with the following format:
|
||||
|
||||
```json
|
||||
{
|
||||
"count": 150,
|
||||
"next": "http://localhost:8000/api/parks/?page=2",
|
||||
"previous": null,
|
||||
"results": [...]
|
||||
}
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
- `page` - Page number (default: 1)
|
||||
- `page_size` - Items per page (default: 20, max: 100)
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
The API implements rate limiting to prevent abuse:
|
||||
- **Anonymous users:** 100 requests per hour
|
||||
- **Authenticated users:** 1000 requests per hour
|
||||
|
||||
Rate limit headers are included in responses:
|
||||
- `X-RateLimit-Limit` - Request limit per hour
|
||||
- `X-RateLimit-Remaining` - Remaining requests
|
||||
- `X-RateLimit-Reset` - Time until reset (Unix timestamp)
|
||||
|
||||
## CORS Configuration
|
||||
|
||||
The API is configured to work with the Vue.js frontend:
|
||||
- **Allowed origins:** `http://localhost:5174` (development)
|
||||
- **Allowed methods:** `GET`, `POST`, `PUT`, `DELETE`, `OPTIONS`
|
||||
- **Allowed headers:** `Content-Type`, `Authorization`, `X-Requested-With`
|
||||
|
||||
## Frontend Integration
|
||||
|
||||
### Vue.js Service Layer
|
||||
|
||||
The frontend uses dedicated service functions for API communication:
|
||||
|
||||
```typescript
|
||||
// services/parkService.ts
|
||||
export const parkService = {
|
||||
async getParks(params?: ParkQueryParams): Promise<PaginatedResponse<Park>> {
|
||||
const response = await apiClient.get('/parks/', { params });
|
||||
return response.data;
|
||||
},
|
||||
|
||||
async getPark(id: number): Promise<ParkDetail> {
|
||||
const response = await apiClient.get(`/parks/${id}/`);
|
||||
return response.data;
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### Pinia Store Integration
|
||||
|
||||
API responses are managed through Pinia stores:
|
||||
|
||||
```typescript
|
||||
// stores/parks.ts
|
||||
export const useParksStore = defineStore('parks', () => {
|
||||
const parks = ref<Park[]>([]);
|
||||
const loading = ref(false);
|
||||
|
||||
const fetchParks = async () => {
|
||||
loading.value = true;
|
||||
try {
|
||||
const response = await parkService.getParks();
|
||||
parks.value = response.results;
|
||||
} finally {
|
||||
loading.value = false;
|
||||
}
|
||||
};
|
||||
|
||||
return { parks, loading, fetchParks };
|
||||
});
|
||||
```
|
||||
|
||||
## Development & Testing
|
||||
|
||||
### API Testing with curl
|
||||
|
||||
```bash
|
||||
# Get list of parks
|
||||
curl "http://localhost:8000/api/parks/"
|
||||
|
||||
# Get specific park
|
||||
curl "http://localhost:8000/api/parks/1/"
|
||||
|
||||
# Search parks
|
||||
curl "http://localhost:8000/api/parks/?search=cedar"
|
||||
|
||||
# Filter by status
|
||||
curl "http://localhost:8000/api/parks/?status=open"
|
||||
```
|
||||
|
||||
### Django REST Framework Browsable API
|
||||
|
||||
When `DEBUG=True`, the API provides a browsable interface at each endpoint URL. This interface allows:
|
||||
- Interactive API browsing
|
||||
- Form-based testing
|
||||
- Authentication testing
|
||||
- Request/response inspection
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Planned Features
|
||||
- **Authentication & Authorization** - JWT-based user authentication
|
||||
- **User Preferences** - Personalized park/ride recommendations
|
||||
- **Image Upload** - User-contributed photos
|
||||
- **Review System** - User ratings and reviews
|
||||
- **Social Features** - Following parks/rides, activity feeds
|
||||
- **Advanced Search** - Full-text search with filters
|
||||
- **Real-time Updates** - WebSocket support for live data
|
||||
|
||||
### API Versioning
|
||||
Future API versions will be supported via URL versioning:
|
||||
- `/api/v1/parks/` - Version 1 (current)
|
||||
- `/api/v2/parks/` - Version 2 (future)
|
||||
|
||||
## Support
|
||||
|
||||
For API-related questions or issues:
|
||||
- Check the [Django REST Framework documentation](https://www.django-rest-framework.org/)
|
||||
- Review the [frontend integration guide](../frontend/README.md)
|
||||
- Create an issue in the project repository
|
||||
|
||||
## Changelog
|
||||
|
||||
### Version 1.0.0
|
||||
- Initial API release
|
||||
- Parks and rides endpoints
|
||||
- Frontend-compatible serialization
|
||||
- Pagination and filtering support
|
||||
- CORS configuration for Vue.js integration
|
||||
649
shared/docs/development/workflow.md
Normal file
649
shared/docs/development/workflow.md
Normal file
@@ -0,0 +1,649 @@
|
||||
# Development Workflow
|
||||
|
||||
Comprehensive guide to daily development processes, Git workflow, and team collaboration for the ThrillWiki monorepo.
|
||||
|
||||
## Overview
|
||||
|
||||
This document outlines the development workflow for the ThrillWiki Django + Vue.js monorepo. Following these practices ensures consistent code quality, smooth collaboration, and reliable deployments.
|
||||
|
||||
## 🏗️ Project Structure
|
||||
|
||||
```
|
||||
thrillwiki-monorepo/
|
||||
├── backend/ # Django REST API
|
||||
├── frontend/ # Vue.js SPA
|
||||
├── shared/ # Shared resources and scripts
|
||||
├── architecture/ # Architecture documentation
|
||||
└── profiles/ # Development profiles
|
||||
```
|
||||
|
||||
## 🚀 Daily Development Workflow
|
||||
|
||||
### 1. Environment Setup
|
||||
|
||||
#### First Time Setup
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone <repository-url>
|
||||
cd thrillwiki-monorepo
|
||||
|
||||
# Run the automated setup script
|
||||
./shared/scripts/dev/setup-dev.sh
|
||||
|
||||
# Or set up manually
|
||||
cd backend && uv sync && cd ..
|
||||
pnpm install
|
||||
```
|
||||
|
||||
#### Daily Setup
|
||||
```bash
|
||||
# Start all development servers
|
||||
./shared/scripts/dev/start-all.sh
|
||||
|
||||
# Or start individually
|
||||
pnpm run dev:backend # Django on :8000
|
||||
pnpm run dev:frontend # Vue.js on :5174
|
||||
```
|
||||
|
||||
### 2. Development Process
|
||||
|
||||
#### Feature Development
|
||||
1. **Create a feature branch**
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
|
||||
2. **Make your changes**
|
||||
- Follow the coding standards for your language
|
||||
- Write tests for new functionality
|
||||
- Update documentation as needed
|
||||
|
||||
3. **Test your changes**
|
||||
```bash
|
||||
# Backend tests
|
||||
cd backend && uv run manage.py test
|
||||
|
||||
# Frontend tests
|
||||
cd frontend && pnpm test:unit
|
||||
cd frontend && pnpm test:e2e
|
||||
|
||||
# Full test suite
|
||||
pnpm run test
|
||||
```
|
||||
|
||||
4. **Code quality checks**
|
||||
```bash
|
||||
# Backend
|
||||
cd backend && uv run black . && uv run flake8 .
|
||||
|
||||
# Frontend
|
||||
cd frontend && pnpm lint && pnpm type-check
|
||||
```
|
||||
|
||||
#### Bug Fixes
|
||||
1. **Create a bug fix branch**
|
||||
```bash
|
||||
git checkout -b bugfix/issue-description
|
||||
```
|
||||
|
||||
2. **Reproduce the issue**
|
||||
- Add test cases that reproduce the bug
|
||||
- Verify the fix resolves the issue
|
||||
|
||||
3. **Implement the fix**
|
||||
- Keep changes minimal and focused
|
||||
- Ensure no regressions
|
||||
|
||||
### 3. Code Review Process
|
||||
|
||||
#### Before Submitting
|
||||
- [ ] All tests pass
|
||||
- [ ] Code follows style guidelines
|
||||
- [ ] Documentation updated
|
||||
- [ ] No linting errors
|
||||
- [ ] TypeScript types correct (frontend)
|
||||
- [ ] Database migrations created (backend)
|
||||
|
||||
#### Pull Request Process
|
||||
1. **Create Pull Request**
|
||||
- Use descriptive title
|
||||
- Fill out PR template
|
||||
- Link related issues
|
||||
- Add screenshots for UI changes
|
||||
|
||||
2. **Code Review**
|
||||
- At least one approval required
|
||||
- Address all review comments
|
||||
- Rebase and resolve conflicts
|
||||
|
||||
3. **Merge Process**
|
||||
- Use "Squash and merge" for feature branches
|
||||
- Use "Rebase and merge" for maintenance branches
|
||||
- Delete branch after merge
|
||||
|
||||
## 🔄 Git Workflow
|
||||
|
||||
### Branch Naming Convention
|
||||
|
||||
```
|
||||
feature/feature-name # New features
|
||||
bugfix/issue-description # Bug fixes
|
||||
hotfix/critical-issue # Critical production fixes
|
||||
refactor/component-name # Code refactoring
|
||||
docs/update-documentation # Documentation updates
|
||||
test/add-test-coverage # Test improvements
|
||||
```
|
||||
|
||||
### Commit Message Format
|
||||
|
||||
```
|
||||
type(scope): description
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer]
|
||||
```
|
||||
|
||||
**Types:**
|
||||
- `feat` - New feature
|
||||
- `fix` - Bug fix
|
||||
- `docs` - Documentation
|
||||
- `style` - Code style changes
|
||||
- `refactor` - Code refactoring
|
||||
- `test` - Adding tests
|
||||
- `chore` - Maintenance tasks
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
feat: add park search functionality
|
||||
fix: resolve ride detail page crash
|
||||
docs: update API documentation
|
||||
refactor: simplify park service layer
|
||||
```
|
||||
|
||||
### Git Workflow
|
||||
|
||||
#### Feature Development
|
||||
```bash
|
||||
# Start from main
|
||||
git checkout main
|
||||
git pull origin main
|
||||
|
||||
# Create feature branch
|
||||
git checkout -b feature/new-park-search
|
||||
|
||||
# Make changes and commit
|
||||
git add .
|
||||
git commit -m "feat: implement park search with filters"
|
||||
|
||||
# Push and create PR
|
||||
git push origin feature/new-park-search
|
||||
```
|
||||
|
||||
#### Handling Conflicts
|
||||
```bash
|
||||
# Update your branch with latest main
|
||||
git fetch origin
|
||||
git rebase origin/main
|
||||
|
||||
# Resolve conflicts if any
|
||||
# Test your changes
|
||||
# Force push if needed
|
||||
git push --force-with-lease origin feature/new-park-search
|
||||
```
|
||||
|
||||
## 🧪 Testing Strategy
|
||||
|
||||
### Backend Testing
|
||||
|
||||
#### Unit Tests
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# Run all tests
|
||||
uv run manage.py test
|
||||
|
||||
# Run specific app tests
|
||||
uv run manage.py test apps.parks
|
||||
|
||||
# Run with coverage
|
||||
uv run coverage run manage.py test
|
||||
uv run coverage report
|
||||
```
|
||||
|
||||
#### Test Structure
|
||||
```
|
||||
backend/tests/
|
||||
├── test_models.py # Model tests
|
||||
├── test_views.py # View tests
|
||||
├── test_serializers.py # Serializer tests
|
||||
└── test_services.py # Service layer tests
|
||||
```
|
||||
|
||||
### Frontend Testing
|
||||
|
||||
#### Unit Tests (Vitest)
|
||||
```bash
|
||||
cd frontend
|
||||
|
||||
# Run unit tests
|
||||
pnpm test:unit
|
||||
|
||||
# Run with coverage
|
||||
pnpm test:unit --coverage
|
||||
|
||||
# Watch mode for development
|
||||
pnpm test:unit --watch
|
||||
```
|
||||
|
||||
#### End-to-End Tests (Playwright)
|
||||
```bash
|
||||
cd frontend
|
||||
|
||||
# Run E2E tests
|
||||
pnpm test:e2e
|
||||
|
||||
# Run specific test
|
||||
pnpm test:e2e tests/park-search.spec.ts
|
||||
|
||||
# Debug mode
|
||||
pnpm test:e2e --debug
|
||||
```
|
||||
|
||||
#### Test Structure
|
||||
```
|
||||
frontend/src/__tests__/
|
||||
├── components/ # Component tests
|
||||
├── views/ # Page tests
|
||||
├── services/ # Service tests
|
||||
└── stores/ # Store tests
|
||||
```
|
||||
|
||||
### Test Coverage Requirements
|
||||
|
||||
- **Backend:** Minimum 80% coverage
|
||||
- **Frontend:** Minimum 70% coverage
|
||||
- **Critical paths:** 90%+ coverage
|
||||
|
||||
## 🔧 Code Quality
|
||||
|
||||
### Backend Standards
|
||||
|
||||
#### Python Code Style
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# Format code
|
||||
uv run black .
|
||||
|
||||
# Check style
|
||||
uv run flake8 .
|
||||
|
||||
# Sort imports
|
||||
uv run isort .
|
||||
```
|
||||
|
||||
#### Django Best Practices
|
||||
- Use Django REST Framework best practices
|
||||
- Implement proper error handling
|
||||
- Add database indexes for performance
|
||||
- Use select_related and prefetch_related for optimization
|
||||
|
||||
### Frontend Standards
|
||||
|
||||
#### Vue.js Best Practices
|
||||
```bash
|
||||
cd frontend
|
||||
|
||||
# Lint code
|
||||
pnpm lint
|
||||
|
||||
# Type checking
|
||||
pnpm type-check
|
||||
|
||||
# Format code
|
||||
pnpm format
|
||||
```
|
||||
|
||||
#### Code Organization
|
||||
- Use Composition API with `<script setup>`
|
||||
- Implement proper component structure
|
||||
- Follow Vue.js style guide
|
||||
- Use TypeScript for type safety
|
||||
|
||||
## 🚀 Deployment Process
|
||||
|
||||
### Development Environment
|
||||
|
||||
#### Automated Deployment
|
||||
```bash
|
||||
# Deploy to development
|
||||
./shared/scripts/deploy/deploy.sh dev
|
||||
|
||||
# Check deployment status
|
||||
./shared/scripts/deploy/check-status.sh dev
|
||||
```
|
||||
|
||||
#### Manual Deployment
|
||||
1. **Build frontend**
|
||||
```bash
|
||||
cd frontend
|
||||
pnpm build
|
||||
```
|
||||
|
||||
2. **Run backend migrations**
|
||||
```bash
|
||||
cd backend
|
||||
uv run manage.py migrate
|
||||
```
|
||||
|
||||
3. **Collect static files**
|
||||
```bash
|
||||
cd backend
|
||||
uv run manage.py collectstatic
|
||||
```
|
||||
|
||||
### Staging Environment
|
||||
|
||||
#### Deployment Checklist
|
||||
- [ ] All tests pass
|
||||
- [ ] Code review completed
|
||||
- [ ] Documentation updated
|
||||
- [ ] Database migrations tested
|
||||
- [ ] Environment variables configured
|
||||
|
||||
#### Deployment Steps
|
||||
```bash
|
||||
# Build for staging
|
||||
pnpm run build:staging
|
||||
|
||||
# Deploy to staging
|
||||
./shared/scripts/deploy/deploy.sh staging
|
||||
|
||||
# Run smoke tests
|
||||
./shared/scripts/deploy/smoke-test.sh staging
|
||||
```
|
||||
|
||||
### Production Environment
|
||||
|
||||
#### Pre-Deployment
|
||||
1. **Create release branch**
|
||||
```bash
|
||||
git checkout -b release/v1.2.3
|
||||
```
|
||||
|
||||
2. **Update version numbers**
|
||||
- Update `package.json`
|
||||
- Update `pyproject.toml`
|
||||
- Tag the release
|
||||
|
||||
3. **Final testing**
|
||||
```bash
|
||||
# Run full test suite
|
||||
pnpm run test
|
||||
|
||||
# Performance testing
|
||||
./shared/scripts/test/performance-test.sh
|
||||
```
|
||||
|
||||
#### Production Deployment
|
||||
```bash
|
||||
# Build for production
|
||||
pnpm run build:production
|
||||
|
||||
# Deploy to production
|
||||
./shared/scripts/deploy/deploy.sh production
|
||||
|
||||
# Verify deployment
|
||||
./shared/scripts/deploy/health-check.sh production
|
||||
|
||||
# Rollback if needed
|
||||
./shared/scripts/deploy/rollback.sh production
|
||||
```
|
||||
|
||||
## 🔍 Monitoring and Debugging
|
||||
|
||||
### Development Debugging
|
||||
|
||||
#### Backend Debugging
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# Django shell for debugging
|
||||
uv run manage.py shell
|
||||
|
||||
# Django debug toolbar (development only)
|
||||
# Access at http://localhost:8000/__debug__/
|
||||
|
||||
# Logging
|
||||
tail -f logs/django.log
|
||||
```
|
||||
|
||||
#### Frontend Debugging
|
||||
```bash
|
||||
cd frontend
|
||||
|
||||
# Vue DevTools browser extension
|
||||
# Access at http://localhost:5174/__devtools__/
|
||||
|
||||
# Browser developer tools
|
||||
# - Console for errors
|
||||
# - Network tab for API calls
|
||||
# - Vue tab for component inspection
|
||||
```
|
||||
|
||||
### Production Monitoring
|
||||
|
||||
#### Health Checks
|
||||
```bash
|
||||
# API health check
|
||||
curl http://localhost:8000/api/health/
|
||||
|
||||
# Database connectivity
|
||||
./shared/scripts/monitor/db-check.sh
|
||||
|
||||
# Background job status
|
||||
./shared/scripts/monitor/job-status.sh
|
||||
```
|
||||
|
||||
#### Error Tracking
|
||||
- Check application logs
|
||||
- Monitor error rates
|
||||
- Review performance metrics
|
||||
- User feedback and bug reports
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
### Documentation Updates
|
||||
|
||||
#### When to Update Documentation
|
||||
- New features implemented
|
||||
- API changes
|
||||
- Configuration changes
|
||||
- Deployment process changes
|
||||
|
||||
#### Documentation Standards
|
||||
- Use clear, concise language
|
||||
- Include code examples
|
||||
- Provide step-by-step instructions
|
||||
- Update README files
|
||||
- Maintain API documentation
|
||||
|
||||
### Documentation Files
|
||||
- `README.md` - Main project documentation
|
||||
- `backend/README.md` - Backend-specific documentation
|
||||
- `frontend/README.md` - Frontend-specific documentation
|
||||
- `shared/docs/api/README.md` - API documentation
|
||||
- `shared/docs/development/workflow.md` - This file
|
||||
|
||||
## 🤝 Team Collaboration
|
||||
|
||||
### Communication
|
||||
|
||||
#### Daily Standup
|
||||
- What did you work on yesterday?
|
||||
- What are you working on today?
|
||||
- Any blockers or issues?
|
||||
|
||||
#### Code Reviews
|
||||
- Be constructive and respectful
|
||||
- Focus on code quality and best practices
|
||||
- Suggest improvements, don't demand changes
|
||||
- Explain reasoning behind suggestions
|
||||
|
||||
### Knowledge Sharing
|
||||
|
||||
#### Documentation
|
||||
- Update README files
|
||||
- Document complex business logic
|
||||
- Create troubleshooting guides
|
||||
|
||||
#### Pair Programming
|
||||
- Share knowledge through pair programming
|
||||
- Rotate team members on different parts of the system
|
||||
- Cross-train on both backend and frontend
|
||||
|
||||
## 🛠️ Development Tools
|
||||
|
||||
### Essential Tools
|
||||
|
||||
#### Version Control
|
||||
- **Git** - Version control system
|
||||
- **GitHub** - Repository hosting and collaboration
|
||||
- **GitHub Actions** - CI/CD pipeline
|
||||
|
||||
#### Code Quality
|
||||
- **ESLint** - JavaScript/TypeScript linting
|
||||
- **Prettier** - Code formatting
|
||||
- **Black** - Python code formatting
|
||||
- **Flake8** - Python linting
|
||||
|
||||
#### Testing
|
||||
- **Vitest** - Frontend unit testing
|
||||
- **Playwright** - E2E testing
|
||||
- **pytest** - Backend testing
|
||||
|
||||
### Development Environment
|
||||
|
||||
#### IDE Configuration
|
||||
- **VSCode** with recommended extensions
|
||||
- **Vue Language Features** extension
|
||||
- **Python** extension
|
||||
- **Prettier** extension
|
||||
|
||||
#### Local Development
|
||||
- **Docker** for consistent environments
|
||||
- **direnv** for environment variables
|
||||
- **nodenv** for Node.js version management
|
||||
|
||||
## 🚨 Emergency Procedures
|
||||
|
||||
### Critical Issues
|
||||
|
||||
#### Production Outage
|
||||
1. **Assess the situation**
|
||||
- Identify the scope of the issue
|
||||
- Determine impact on users
|
||||
|
||||
2. **Communication**
|
||||
- Notify team members
|
||||
- Update status page if applicable
|
||||
|
||||
3. **Resolution**
|
||||
```bash
|
||||
# Quick rollback if needed
|
||||
./shared/scripts/deploy/rollback.sh production
|
||||
|
||||
# Or hotfix
|
||||
git checkout -b hotfix/critical-issue
|
||||
# Implement fix
|
||||
./shared/scripts/deploy/deploy.sh production
|
||||
```
|
||||
|
||||
#### Security Issues
|
||||
1. **Assess vulnerability**
|
||||
- Determine severity and impact
|
||||
- Check for exploitation
|
||||
|
||||
2. **Response**
|
||||
- Implement temporary mitigation
|
||||
- Develop permanent fix
|
||||
- Deploy security patch
|
||||
|
||||
3. **Post-mortem**
|
||||
- Document the incident
|
||||
- Update security procedures
|
||||
- Improve monitoring
|
||||
|
||||
## 📈 Performance Optimization
|
||||
|
||||
### Frontend Performance
|
||||
|
||||
#### Bundle Optimization
|
||||
```bash
|
||||
# Analyze bundle size
|
||||
cd frontend
|
||||
pnpm build --analyze
|
||||
|
||||
# Code splitting
|
||||
const ParkDetail = () => import('./views/ParkDetail.vue')
|
||||
```
|
||||
|
||||
#### Image Optimization
|
||||
- Use WebP format for images
|
||||
- Implement lazy loading
|
||||
- Optimize image sizes
|
||||
|
||||
### Backend Performance
|
||||
|
||||
#### Database Optimization
|
||||
```python
|
||||
# Use select_related for foreign keys
|
||||
parks = Park.objects.select_related('operator')
|
||||
|
||||
# Use prefetch_related for many-to-many
|
||||
parks = Park.objects.prefetch_related('rides')
|
||||
```
|
||||
|
||||
#### Caching Strategy
|
||||
- Cache frequently accessed data
|
||||
- Use Redis for session storage
|
||||
- Implement database query caching
|
||||
|
||||
## 🔒 Security Best Practices
|
||||
|
||||
### Code Security
|
||||
- Regular dependency updates
|
||||
- Security scanning with tools like Snyk
|
||||
- Code review security checklist
|
||||
- Input validation and sanitization
|
||||
|
||||
### Infrastructure Security
|
||||
- HTTPS everywhere
|
||||
- Secure headers implementation
|
||||
- Regular security audits
|
||||
- Access control and authentication
|
||||
|
||||
## 📋 Checklist
|
||||
|
||||
### Before Committing Code
|
||||
- [ ] Tests pass
|
||||
- [ ] Code follows style guidelines
|
||||
- [ ] No linting errors
|
||||
- [ ] Documentation updated
|
||||
- [ ] Commit message follows convention
|
||||
|
||||
### Before Creating Pull Request
|
||||
- [ ] Feature branch up to date with main
|
||||
- [ ] All tests pass
|
||||
- [ ] Code review checklist completed
|
||||
- [ ] Documentation updated
|
||||
- [ ] No merge conflicts
|
||||
|
||||
### Before Merging to Main
|
||||
- [ ] CI/CD pipeline passes
|
||||
- [ ] Code review approved
|
||||
- [ ] Tests pass in CI environment
|
||||
- [ ] No critical security issues
|
||||
|
||||
This workflow ensures consistent, high-quality development across the ThrillWiki monorepo while maintaining excellent collaboration and deployment practices.
|
||||
Reference in New Issue
Block a user