🐍 Python/Django - Standardy Kodu¶

Ten dokument opisuje standardy kodu Python i Django dla Panel Księgowy.

📋 Code Style¶

PEP 8¶

Limit linii: 120 znaków
Indentacja: 4 spacje
Cudzysłowy: Podwójne ("string")
Importy: Sortowane przez isort (via ruff)

Type Hints¶

def create_client(team: Team, name: str) -> Client:
    """Tworzy klienta."""
    return Client.objects.create(team=team, name=name)

Uwaga: Type hints są opcjonalne, ale zalecane dla nowego kodu.

🏗️ Django Models¶

BaseTeamModel¶

Wszystkie modele biznesowe dziedziczą po BaseTeamModel:

from apps.teams.models import BaseTeamModel

class Client(BaseTeamModel):
    name = models.CharField(max_length=200)
    # team field jest automatycznie dodany

BaseModel¶

Modele globalne dziedziczą po BaseModel:

from apps.utils.models import BaseModel

class Currency(BaseModel):
    code = models.CharField(max_length=3)
    # created_at i updated_at są automatycznie dodane

Meta Options¶

class Meta:
    verbose_name = _("Client")
    verbose_name_plural = _("Clients")
    ordering = ["-created_at"]
    indexes = [
        models.Index(fields=["team", "-created_at"]),
    ]

🎯 Views¶

Function-based Views¶

Preferowane nad class-based views:

from apps.teams.decorators import login_and_team_required

@login_and_team_required
def client_list(request, team_slug):
    """Lista klientów."""
    team = request.team
    clients = Client.objects.filter(team=team)
    return render(request, 'crm/client_list.html', {
        'clients': clients
    })

Decorators¶

@login_and_team_required  # Wymaga logowania i członkostwa w team
@team_admin_required       # Wymaga roli administratora
def settings(request, team_slug):
    # ...

🔍 Queries¶

Zawsze filtruj po team¶

# ✅ DOBRZE
clients = Client.objects.filter(team=request.team)

# ❌ ŹLE
clients = Client.objects.all()  # DANGEROUS!

Optymalizacja¶

# ✅ DOBRZE - select_related dla FK
clients = Client.objects.filter(team=team).select_related('created_by')

# ✅ DOBRZE - prefetch_related dla M2M
clients = Client.objects.filter(team=team).prefetch_related('contacts')

🌐 Translation¶

Zawsze używaj gettext_lazy:

from django.utils.translation import gettext_lazy as _

class Client(BaseTeamModel):
    name = models.CharField(_("Name"), max_length=200)

📚 Więcej informacji¶

Zobacz .cursor/rules/python-guidelines.mdc dla szczegółowych wytycznych.

Ostatnia aktualizacja: 2025-11-29
Wersja dokumentacji: 1.0