Files
2026-10-22 10:24:33 +02:00

417 lines
22 KiB
Python

import hashlib
import json
from uuid import UUID
from django.core.exceptions import PermissionDenied, ValidationError
from django.db import transaction
from django.db.models import Q, Max
from django.core.validators import URLValidator
from django.shortcuts import get_object_or_404
from django.utils import timezone
from django.utils.text import slugify
from .models import Activity, Board, BulkUpdateKey, Card, CardRevision, Column, CreationKey, Membership, Project, ProjectMoveKey, Tag
class RevisionConflict(Exception):
def __init__(self, current):
self.current = current
def accessible(user):
if not user.is_authenticated:
return Project.objects.none()
return Project.objects.filter(Q(owner=user) | Q(memberships__user=user)).distinct()
def project_for(user, identifier, write=False):
project = get_object_or_404(accessible(user), pk=identifier)
if write and project.owner_id != user.pk and not Membership.objects.filter(project=project, user=user, role='editor').exists():
raise PermissionDenied
return project
def card_for(user, identifier, write=False):
card = get_object_or_404(Card.objects.select_related('project', 'column'), pk=identifier, project__in=accessible(user))
if write:
project_for(user, card.project_id, write=True)
return card
@transaction.atomic
def create_project(user, *, name, description='', git_repository_url=''):
if not name.strip():
raise ValidationError('Project name is required.')
if Project.objects.filter(owner=user, name__iexact=name.strip()).exists():
raise ValidationError('You already have a project with this name.')
if git_repository_url:
URLValidator(schemes=['https'])(git_repository_url)
base = slugify(name) or 'project'
slug = base
n = 2
while Project.objects.filter(owner=user, slug=slug).exists():
slug = f'{base}-{n}'
n += 1
project = Project(owner=user, name=name, slug=slug, description=description, git_repository_url=git_repository_url)
project.full_clean()
project.save()
board = Board.objects.create(project=project)
for index, title in enumerate(('To-do', 'In Progress', 'Done')):
Column.objects.create(board=board, name=title, position=index, is_default=index == 0, is_done=index == 2)
Activity.objects.create(project=project, actor=user, action='project.created')
return project
@transaction.atomic
def create_card(user, project, *, title, markdown='', column=None, priority='medium', card_type='task', origin='web', idempotency_key=None):
project_for(user, project.pk, write=True)
if priority not in dict(Card.PRIORITY) or card_type not in dict(Card.TYPE):
raise ValidationError('Invalid priority or card type.')
if not title.strip():
raise ValidationError('Card title is required.')
if idempotency_key:
if len(idempotency_key) > 128:
raise ValidationError('Idempotency key is too long.')
payload = json.dumps({'project': str(project.pk), 'title': title, 'markdown': markdown, 'column': str(column.pk) if column else None, 'priority': priority, 'card_type': card_type}, sort_keys=True)
payload_hash = hashlib.sha256(payload.encode()).hexdigest()
existing = CreationKey.objects.filter(user=user, key=idempotency_key).select_related('card').first()
if existing:
if existing.payload_hash != payload_hash:
raise ValidationError('Idempotency key was already used with different card details.')
return existing.card
column = column or project.board.columns.get(is_default=True, archived=False)
if column.board_id != project.board.pk or column.archived:
raise ValidationError('Column is not available in this project.')
position = (Card.objects.filter(column=column, archived=False).aggregate(Max('position'))['position__max'] or 0) + 1
card = Card(project=project, column=column, title=title, description_markdown=markdown,
priority=priority, card_type=card_type, position=position, created_by=user,
completed_at=timezone.now() if column.is_done else None)
card.full_clean()
card.save()
CardRevision.objects.create(card=card, revision=1, markdown=markdown, actor=user)
Activity.objects.create(project=project, card=card, actor=user, action='card.created', origin=origin)
if idempotency_key:
CreationKey.objects.create(user=user, key=idempotency_key, payload_hash=payload_hash, card=card)
return card
@transaction.atomic
def update_card(user, card, *, expected_revision=None, origin='web', **changes):
card = Card.objects.select_for_update().get(pk=card.pk)
project_for(user, card.project_id, write=True)
allowed = {'title', 'description_markdown', 'priority', 'card_type', 'is_blocked', 'blocked_reason', 'archived', 'due_date'}
if set(changes) - allowed:
raise ValidationError('Unsupported card field.')
if 'priority' in changes and changes['priority'] not in dict(Card.PRIORITY):
raise ValidationError('Invalid priority.')
markdown_changed = 'description_markdown' in changes and changes['description_markdown'] != card.description_markdown
if changes and (expected_revision is None or int(expected_revision) != card.revision):
raise RevisionConflict(card.revision)
changed = []
for field, value in changes.items():
if getattr(card, field) != value:
setattr(card, field, value)
changed.append(field)
if changed:
card.revision += 1
card.full_clean()
card.save()
CardRevision.objects.create(card=card, revision=card.revision, markdown=card.description_markdown, actor=user)
Activity.objects.create(project=card.project, card=card, actor=user, action='card.updated', detail={'fields': changed}, origin=origin)
return card
@transaction.atomic
def move_card(user, card, column, position=None, origin='web', record_revision=True):
card = Card.objects.select_for_update().get(pk=card.pk)
project_for(user, card.project_id, write=True)
if column.board.project_id != card.project_id or column.archived:
raise ValidationError('Column is not available in this project.')
old_column = card.column_id
old_position = card.position
card.column = column
card.completed_at = timezone.now() if column.is_done and not card.completed_at else (None if not column.is_done else card.completed_at)
siblings = list(Card.objects.filter(column=column, archived=False).exclude(pk=card.pk).order_by('position', 'created_at'))
index = len(siblings) if position is None else max(0, min(int(position), len(siblings)))
siblings.insert(index, card)
for i, item in enumerate(siblings):
item.position = i
item.save(update_fields=['position'])
moved = old_column != column.pk or old_position != card.position
if moved and record_revision:
card.revision += 1
card.save()
if moved and record_revision:
CardRevision.objects.create(card=card, revision=card.revision, markdown=card.description_markdown, actor=user)
Activity.objects.create(project=card.project, card=card, actor=user, action='card.moved', detail={'from': str(old_column), 'to': str(column.pk)}, origin=origin)
return card
@transaction.atomic
def move_card_to_project(user, card, target_project, *, target_column=None, expected_revision,
idempotency_key=None, origin='web'):
"""Move a card between editable projects without replacing its identity or children."""
if idempotency_key:
if len(idempotency_key) > 128:
raise ValidationError('Idempotency key is too long.')
payload = json.dumps({'card': str(card.pk), 'target_project': str(target_project.pk),
'target_column': str(target_column.pk) if target_column else None,
'expected_revision': int(expected_revision)}, sort_keys=True)
payload_hash = hashlib.sha256(payload.encode()).hexdigest()
user.__class__.objects.select_for_update().get(pk=user.pk)
existing = ProjectMoveKey.objects.select_for_update().filter(user=user, key=idempotency_key).first()
if existing:
if existing.payload_hash != payload_hash:
raise ValidationError('Idempotency key was already used with different move details.')
current = Card.objects.select_for_update().select_related('project').get(pk=card.pk)
project_for(user, current.project_id, write=True)
if current.project_id != target_project.pk:
raise ValidationError('The original move is no longer available to replay.')
return current, existing.result
card = Card.objects.select_for_update().select_related('project', 'column').get(pk=card.pk)
source = project_for(user, card.project_id, write=True)
target_project = project_for(user, target_project.pk, write=True)
if source.pk == target_project.pk:
raise ValidationError('Choose a different project. Use the column move for this project.')
if source.archived or target_project.archived:
raise ValidationError('Cards cannot be moved from or into an archived project.')
if card.revision != int(expected_revision):
raise RevisionConflict(card.revision)
if target_column is None:
active_columns = target_project.board.columns.filter(archived=False)
target_column = active_columns.filter(is_default=True).first() or active_columns.first()
if (target_column is None or target_column.board_id != target_project.board.pk or target_column.archived):
raise ValidationError('Column is not available in the destination project.')
warnings = []
if card.assignee_id and card.assignee_id != target_project.owner_id and not Membership.objects.filter(project=target_project, user_id=card.assignee_id).exists():
warnings.append(f"Assignee {card.assignee.get_full_name() or card.assignee.username} was cleared because they do not have access to the destination project.")
card.assignee = None
old_tags = list(card.tags.all())
target_tags = list(Tag.objects.filter(project=target_project).order_by('pk'))
tags_by_name = {tag.name.casefold(): tag for tag in target_tags}
mapped_tags = []
for tag in old_tags:
match = tags_by_name.get(tag.name.casefold())
if match:
mapped_tags.append(match)
else:
warnings.append(f"Tag “{tag.name}” was cleared because it does not exist in the destination project.")
old_column_id = card.column_id
old_column_name = card.column.name
original_updated_at = card.updated_at
siblings = list(Card.objects.filter(column=target_column, archived=False).exclude(pk=card.pk).order_by('position', 'created_at'))
card.project = target_project
card.column = target_column
card.position = len(siblings)
card.completed_at = timezone.now() if target_column.is_done else None
card.revision += 1
card.full_clean()
card.save(update_fields=['project', 'column', 'position', 'completed_at', 'revision', 'assignee'])
card.updated_at = original_updated_at
card.tags.set(mapped_tags)
for index, sibling in enumerate(Card.objects.filter(column_id=old_column_id, archived=False).order_by('position', 'created_at')):
if sibling.position != index:
sibling.position = index
sibling.save(update_fields=['position'])
for index, sibling in enumerate(siblings):
if sibling.position != index:
sibling.position = index
sibling.save(update_fields=['position'])
# The card's prior activity follows its stable UUID into the destination.
Activity.objects.filter(card=card).update(project=target_project)
CardRevision.objects.create(card=card, revision=card.revision, markdown=card.description_markdown, actor=user)
detail = {'from_project': str(source.pk), 'from_column': str(old_column_id),
'from_column_name': old_column_name, 'to_project': str(target_project.pk),
'to_column': str(target_column.pk), 'to_column_name': target_column.name}
Activity.objects.create(project=source, actor=user, action='card.moved_project_out',
detail={'card_id': str(card.pk), 'title': card.title, **detail}, origin=origin)
Activity.objects.create(project=target_project, card=card, actor=user, action='card.moved_project',
detail=detail, origin=origin)
result = {'source_project_id': str(source.pk), 'source_project_name': source.name,
'source_column_id': str(old_column_id),
'target_project_id': str(target_project.pk), 'target_column_id': str(target_column.pk),
'target_project_name': target_project.name, 'target_column_name': target_column.name,
'revision': card.revision, 'url': f'/projects/cards/{card.pk}/', 'warnings': warnings}
if idempotency_key:
ProjectMoveKey.objects.create(user=user, key=idempotency_key, payload_hash=payload_hash, result=result)
return card, result
@transaction.atomic
def set_default(user, column):
project_for(user, column.board.project_id, write=True)
if column.archived:
raise ValidationError('Archived column cannot be the default.')
Column.objects.filter(board=column.board, is_default=True).update(is_default=False)
column.is_default = True
column.save(update_fields=['is_default'])
return column
@transaction.atomic
def archive_column(user, column):
project_for(user, column.board.project_id, write=True)
if column.is_default or column.cards.filter(archived=False).exists():
raise ValidationError('Choose another default and move cards before archiving this column.')
column.archived = True
column.save(update_fields=['archived'])
return column
@transaction.atomic
def reorder_columns(user, project, ids):
project_for(user, project.pk, write=True)
columns = list(project.board.columns.filter(archived=False))
if len(ids) != len(columns) or set(map(str, ids)) != {str(c.pk) for c in columns}:
raise ValidationError('Invalid column order.')
for index, identifier in enumerate(ids):
Column.objects.filter(pk=identifier, board=project.board).update(position=index)
return columns
@transaction.atomic
def shift_column(user, column, direction):
project = project_for(user, column.board.project_id, write=True)
ids = [str(c.pk) for c in project.board.columns.filter(archived=False)]
index = ids.index(str(column.pk))
target = max(0, min(index + direction, len(ids) - 1))
ids[index], ids[target] = ids[target], ids[index]
reorder_columns(user, project, ids)
return column
@transaction.atomic
def update_column(user, column, *, name=None, color=None, is_done=None, origin='web'):
column = Column.objects.select_for_update().get(pk=column.pk)
project = project_for(user, column.board.project_id, write=True)
if name is not None:
column.name = name
if color is not None:
column.color = color
completion_changed = is_done is not None and column.is_done != is_done
if is_done is not None:
column.is_done = is_done
column.full_clean()
column.save()
if completion_changed:
Card.objects.filter(column=column, archived=False).update(completed_at=timezone.now() if is_done else None)
Activity.objects.create(project=project, actor=user, action='column.updated', detail={'column_id': str(column.pk)}, origin=origin)
return column
def set_assignee(user, card, assignee, origin='web'):
project_for(user, card.project_id, write=True)
if assignee and assignee.pk != card.project.owner_id and not Membership.objects.filter(project=card.project, user=assignee).exists():
raise ValidationError('Assignee must have access to this project.')
card.assignee = assignee
card.save(update_fields=['assignee', 'updated_at'])
Activity.objects.create(project=card.project, card=card, actor=user, action='card.assigned', detail={'assignee': assignee.pk if assignee else None}, origin=origin)
return card
@transaction.atomic
def set_tags(user, card, tags, origin='web'):
project_for(user, card.project_id, write=True)
tags = list(tags)
if any(tag.project_id != card.project_id for tag in tags):
raise ValidationError('Tags must belong to this project.')
card.tags.set(tags)
Activity.objects.create(project=card.project, card=card, actor=user, action='card.tags_changed', origin=origin)
return card
@transaction.atomic
def bulk_update_cards(user, project, card_ids, expected_revisions, changes, *, dry_run=False, idempotency_key=None, origin='web'):
"""Validate the entire batch before writing; every mutation shares one transaction."""
project_for(user, project.pk, write=True)
if not isinstance(card_ids, list) or not 1 <= len(card_ids) <= 100:
raise ValidationError('Select between 1 and 100 cards.')
try:
ids = [str(UUID(str(value))) for value in card_ids]
except (ValueError, TypeError, AttributeError):
raise ValidationError('Invalid card ID.')
if len(set(ids)) != len(ids):
raise ValidationError('Duplicate card IDs are not allowed.')
if not isinstance(changes, dict) or not changes or set(changes) - {'column_id', 'priority', 'assignee_id', 'tag_ids'}:
raise ValidationError('Supply supported changes: column_id, priority, assignee_id or tag_ids.')
if 'priority' in changes and changes['priority'] not in dict(Card.PRIORITY):
raise ValidationError('Invalid priority.')
payload_hash = hashlib.sha256(json.dumps({'project': str(project.pk), 'ids': ids, 'revisions': expected_revisions, 'changes': changes}, sort_keys=True).encode()).hexdigest()
if idempotency_key and not dry_run:
if len(idempotency_key) > 128:
raise ValidationError('Idempotency key is too long.')
user.__class__.objects.select_for_update().get(pk=user.pk)
existing = BulkUpdateKey.objects.select_for_update().filter(user=user, key=idempotency_key).first()
if existing:
if existing.payload_hash != payload_hash:
raise ValidationError('Idempotency key was already used with different changes.')
return existing.result
cards = {str(card.pk): card for card in Card.objects.select_for_update().filter(pk__in=ids, project=project, archived=False).select_related('column')}
if len(cards) != len(ids):
raise ValidationError('One or more cards are unavailable in this project.')
if not isinstance(expected_revisions, dict):
raise ValidationError('Expected revisions are required for every card.')
conflicts = [{'id': identifier, 'expected': expected_revisions.get(identifier), 'current': cards[identifier].revision}
for identifier in ids if expected_revisions.get(identifier) != cards[identifier].revision]
if conflicts:
raise ValidationError({'revision_conflicts': conflicts})
column = None
if 'column_id' in changes:
try:
column = Column.objects.get(pk=UUID(str(changes['column_id'])), board=project.board, archived=False)
except (Column.DoesNotExist, ValueError, TypeError):
raise ValidationError('Column is not available in this project.')
assignee = None
if 'assignee_id' in changes and changes['assignee_id'] is not None:
try:
assignee = user.__class__.objects.get(pk=changes['assignee_id'])
except (user.__class__.DoesNotExist, ValueError, TypeError):
raise ValidationError('Invalid assignee.')
if assignee.pk != project.owner_id and not Membership.objects.filter(project=project, user=assignee).exists():
raise ValidationError('Assignee must have access to this project.')
tags = None
if 'tag_ids' in changes:
tag_ids = changes['tag_ids']
if not isinstance(tag_ids, list) or any(type(value) is not int for value in tag_ids) or len(tag_ids) != len(set(tag_ids)):
raise ValidationError('Tag IDs must be a unique list.')
tags = list(Tag.objects.filter(project=project, pk__in=tag_ids))
if len(tags) != len(tag_ids):
raise ValidationError('Tags must belong to this project.')
results = []
for identifier in ids:
card = cards[identifier]
before = {'column_id': str(card.column_id), 'priority': card.priority, 'assignee_id': card.assignee_id,
'tag_ids': sorted(card.tags.values_list('pk', flat=True))}
after = dict(before)
if column is not None: after['column_id'] = str(column.pk)
if 'priority' in changes: after['priority'] = changes['priority']
if 'assignee_id' in changes: after['assignee_id'] = assignee.pk if assignee else None
if tags is not None: after['tag_ids'] = sorted(tag.pk for tag in tags)
delta = {field: {'from': before[field], 'to': after[field]} for field in changes if field in before and before[field] != after[field]}
results.append({'id': identifier, 'title': card.title, 'revision': card.revision + bool(delta), 'changes': delta, 'changed': bool(delta)})
if not dry_run:
for result in results:
if not result['changed']:
continue
card = cards[result['id']]
delta = result['changes']
if 'column_id' in delta:
move_card(user, card, column, origin=origin, record_revision=False)
card.refresh_from_db()
if 'priority' in delta: card.priority = changes['priority']
if 'assignee_id' in delta: card.assignee = assignee
if 'tag_ids' in delta: card.tags.set(tags)
card.revision += 1
card.full_clean()
card.save()
CardRevision.objects.create(card=card, revision=card.revision, markdown=card.description_markdown, actor=user)
Activity.objects.create(project=project, card=card, actor=user, action='card.bulk_updated', detail={'changes': delta}, origin=origin)
response = {'dry_run': dry_run, 'total': len(ids), 'changed_count': sum(item['changed'] for item in results),
'unchanged_count': sum(not item['changed'] for item in results), 'items': results}
if idempotency_key and not dry_run:
BulkUpdateKey.objects.create(user=user, key=idempotency_key, payload_hash=payload_hash, result=response)
return response