Init Repo

2026-02-28 03:22:04 +08:00
commit de59b57ee7
883 changed files with 156857 additions and 0 deletions
@@ -0,0 +1,26 @@
+# Product Overview
+
+VFX Project Management System - A comprehensive project management platform designed for the animation and VFX industry, similar to ftrack or ShotGrid.
+
+## Core Features
+
+- Role-based access control (Admin, Director, Coordinator, Artist, Developer)
+- Project, episode, and shot management
+- Asset management with categories and task tracking
+- Task assignment and status tracking
+- Review and approval workflows
+- File upload and version control
+- Real-time notifications
+- API key management for developers
+
+## User Roles
+
+- **Admin**: Full system access, user approval, global settings
+- **Director**: Review and approval workflows
+- **Coordinator**: Project management, user management
+- **Artist**: Task execution, file submissions
+- **Developer**: API access, analytics
+
+## Domain Model
+
+The system manages a hierarchy: Projects → Episodes → Shots/Assets → Tasks → Reviews
@@ -0,0 +1,75 @@
+# Project Structure
+
+## Backend Architecture (/backend)
+
+```
+backend/
+├── models/          # SQLAlchemy ORM models (User, Project, Asset, Task, etc.)
+├── schemas/         # Pydantic schemas for request/response validation
+├── routers/         # FastAPI route handlers (auth, users, projects, assets, etc.)
+├── services/        # Business logic layer
+├── utils/           # Utility functions (auth, file_handler, notifications)
+├── docs/            # API documentation
+├── uploads/         # File upload storage
+├── main.py          # FastAPI application entry point
+├── database.py      # Database configuration and session management
+└── requirements.txt # Python dependencies
+```
+
+### Backend Patterns
+
+- **Models**: SQLAlchemy declarative models with relationships
+- **Schemas**: Pydantic models for validation (separate from ORM models)
+- **Routers**: API endpoints organized by resource (auth, users, projects, etc.)
+- **Database**: Dependency injection pattern using `get_db()` generator
+- **Auth**: JWT tokens with Bearer authentication, role-based access control
+- **CORS**: Configured for localhost:5173 and localhost:5174
+
+## Frontend Architecture (/frontend)
+
+```
+frontend/
+├── src/
+│   ├── components/  # Vue components organized by feature
+│   │   ├── asset/   # Asset-related components
+│   │   ├── auth/    # Login/Register forms
+│   │   ├── episode/ # Episode management
+│   │   ├── layout/  # AppHeader, AppSidebar, UserMenu
+│   │   ├── project/ # Project management components
+│   │   ├── settings/# Settings panels
+│   │   ├── shot/    # Shot management
+│   │   ├── task/    # Task components
+│   │   ├── ui/      # shadcn-vue UI primitives
+│   │   └── user/    # User management
+│   ├── views/       # Page-level components (route targets)
+│   │   ├── auth/    # LoginView, RegisterView
+│   │   ├── project/ # Project detail sub-views
+│   │   └── developer/ # Developer portal views
+│   ├── stores/      # Pinia state management (auth, projects, assets, etc.)
+│   ├── services/    # API service layer (axios wrappers)
+│   ├── types/       # TypeScript type definitions
+│   ├── router/      # Vue Router configuration with guards
+│   ├── utils/       # Utility functions
+│   ├── App.vue      # Root component
+│   └── main.ts      # Application entry point
+├── components.json  # shadcn-vue configuration
+├── vite.config.ts   # Vite build configuration
+└── package.json     # Node.js dependencies
+```
+
+### Frontend Patterns
+
+- **Components**: Feature-based organization, composition API with `<script setup>`
+- **Stores**: Pinia stores using composition API pattern (ref, computed)
+- **Services**: Axios-based API clients with centralized error handling
+- **Routing**: Nested routes for project details, meta-based auth guards
+- **Auth**: Token stored in localStorage, axios interceptors for auth headers
+- **State**: Pinia for global state, local refs for component state
+- **Styling**: Tailwind utility classes, shadcn-vue for consistent UI
+
+## Key Conventions
+
+- **Enums**: Shared between backend (Python Enum) and frontend (TypeScript types)
+- **API Prefix**: All API calls use `/api` prefix (configured in Vite proxy)
+- **File Naming**: PascalCase for components/views, camelCase for services/utils
+- **Database**: SQLite with auto-generated tables via SQLAlchemy metadata
@@ -0,0 +1,113 @@
+# Technology Stack
+
+## Backend
+
+- **Framework**: FastAPI (Python web framework)
+- **ORM**: SQLAlchemy
+- **Database**: SQLite (vfx_project_management.db)
+- **Authentication**: JWT tokens (access + refresh)
+- **Validation**: Pydantic schemas
+- **Password Hashing**: passlib with bcrypt
+- **File Handling**: python-multipart, Pillow
+
+## Frontend
+
+- **Framework**: Vue 3 with Composition API
+- **Language**: TypeScript
+- **Build Tool**: Vite
+- **Styling**: Tailwind CSS
+- **UI Components**: shadcn-vue (based on Radix UI)
+- **State Management**: Pinia stores
+- **Routing**: Vue Router with navigation guards
+- **HTTP Client**: Axios with interceptors
+- **Icons**: lucide-vue-next
+
+## Common Commands
+
+### Backend (from /backend directory)
+
+```bash
+# Start development server
+uvicorn main:app --reload --host 0.0.0.0 --port 8000
+
+# Create virtual environment
+python -m venv venv
+
+# Activate virtual environment (Windows)
+venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Database utilities
+python create_fresh_database.py
+python create_admin.py
+python create_example_data.py
+```
+
+### Frontend (from /frontend directory)
+
+```bash
+# Start development server
+npm run dev
+
+# Build for production
+npm run build
+
+# Type checking
+npm run type-check
+
+# Install dependencies
+npm install
+```
+
+## API Documentation
+
+- Swagger UI: http://localhost:8000/docs
+- ReDoc: http://localhost:8000/redoc
+
+## Development Ports
+
+- Backend: http://localhost:8000
+- Frontend: http://localhost:5173
+
+## Important: FastAPI Trailing Slash Issue
+
+**CRITICAL:** When adding or modifying API routes, always ensure trailing slashes match between frontend and backend to avoid 307 redirects that lose authentication headers.
+
+### The Problem
+- FastAPI redirects requests when trailing slashes don't match route definitions
+- HTTP 307 redirects do NOT preserve the `Authorization` header
+- This causes authenticated requests to fail with 403 Forbidden
+
+### The Solution
+**Always match trailing slashes between frontend API calls and backend route definitions:**
+
+```typescript
+// Frontend - WITH trailing slash for query params
+apiClient.get(`/tasks/?shot_id=12`)
+
+// Backend - Route defined WITH trailing slash
+@router.get("/tasks/")
+```
+
+```typescript
+// Frontend - WITHOUT trailing slash for path params
+apiClient.get(`/tasks/${taskId}`)
+
+// Backend - Route defined WITHOUT trailing slash
+@router.get("/tasks/{task_id}")
+```
+
+### Quick Check
+Look for these patterns in backend logs:
+```
+❌ BAD (redirect happening):
+INFO: "GET /tasks?shot_id=12 HTTP/1.1" 307 Temporary Redirect
+INFO: "GET /tasks/?shot_id=12 HTTP/1.1" 403 Forbidden
+
+✅ GOOD (no redirect):
+INFO: "GET /tasks/?shot_id=12 HTTP/1.1" 200 OK
+```
+
+**See:** `backend/docs/fastapi-trailing-slash-issue.md` for complete documentation.