Backend API: auth, projects/images/annotations, R2 presign, tracing, thumbnails, pagination, tests, docs

This commit is contained in:
hailt 2026-11-12 15:12:26 +07:00
parent 5c5deed2f5
commit f8ed08b854
49 changed files with 2626 additions and 0 deletions

0
src/__init__.py Normal file
View file

0
src/api/__init__.py Normal file
View file

0
src/api/v1/__init__.py Normal file
View file

40
src/api/v1/activities.py Normal file
View file

@ -0,0 +1,40 @@
"""Activity feed derived from the action-event tracelog (no separate table)."""
from __future__ import annotations
from fastapi import APIRouter, Depends, Query
from sqlalchemy import desc, select
from sqlalchemy.ext.asyncio import AsyncSession
from models import ActionEvent, User
from src.core.db import get_session
router = APIRouter(prefix="/activities", tags=["activities"])
_ACTION_TEXT = {
"project.create": "đã tạo dự án mới",
"image.confirm": "đã tải ảnh mới lên",
"image.status": "đã đổi trạng thái ảnh",
"annotation.save": "đã lưu nhãn ảnh",
"dataset.export": "đã xuất dataset",
"image.next": "đã chuyển ảnh",
}
def _describe(e: ActionEvent, names: dict) -> str:
base = _ACTION_TEXT.get(e.action, f"đã thực hiện {e.action}")
who = names.get(e.user_id or "", None) or (e.user_id or "hệ thống")
detail = e.image_id or e.project_id or ""
return f"{who} {base} {detail}".strip()
@router.get("")
async def list_activities(limit: int = Query(default=30, le=200),
db: AsyncSession = Depends(get_session)):
rows = (await db.execute(select(ActionEvent).order_by(desc(ActionEvent.created_at)).limit(limit))).scalars().all()
users = (await db.execute(select(User))).scalars().all()
names = {u.id: u.name for u in users}
return [{"id": e.id,
"timestamp": e.created_at.isoformat() if e.created_at else "",
"userName": names.get(e.user_id or "", e.user_id or "hệ thống"),
"actionText": _describe(e, names),
"projectId": e.project_id} for e in rows]

21
src/api/v1/annotations.py Normal file
View file

@ -0,0 +1,21 @@
from __future__ import annotations
from fastapi import APIRouter, Depends
from sqlalchemy.ext.asyncio import AsyncSession
from shared.schemas import AnnotationUpsert
from src.core.db import get_session
from src.services import annotations as svc
router = APIRouter(prefix="/projects/{project_id}/images/{image_id}/annotation", tags=["annotations"])
@router.get("")
async def get_annotation(project_id: str, image_id: str, db: AsyncSession = Depends(get_session)):
return await svc.get_annotation(project_id, image_id, db)
@router.put("")
async def upsert_annotation(project_id: str, image_id: str, body: AnnotationUpsert,
db: AsyncSession = Depends(get_session)):
return await svc.upsert_annotation(project_id, image_id, body, db)

73
src/api/v1/auth.py Normal file
View file

@ -0,0 +1,73 @@
from __future__ import annotations
from fastapi import APIRouter, Depends, HTTPException
from pydantic import BaseModel, Field
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
from models import User
from src.core.db import get_session
from src.core.security import create_token, get_current_user, verify_password
router = APIRouter(prefix="/auth", tags=["auth"])
class LoginIn(BaseModel):
email: str
password: str = ""
@router.post("/login")
async def login(body: LoginIn, db: AsyncSession = Depends(get_session)):
user = (await db.execute(
select(User).where(User.email == body.email.strip().lower()))).scalar_one_or_none()
if user is None or not verify_password(body.password or "", user.password_hash or ""):
raise HTTPException(401, "email hoặc mật khẩu không đúng")
access = create_token(user.id, user.role)
refresh = create_token(user.id, user.role, expires_minutes=60 * 24 * 7)
return {"user": {"id": user.id, "name": user.name, "email": user.email,
"avatarInitials": "".join(p[0] for p in user.name.split()[:2]).upper(),
"avatarColor": "#3B82F6", "role": user.role, "status": user.status,
"isOnline": True, "lastActive": "Đang trực tuyến"},
"accessToken": access, "refreshToken": refresh}
@router.get("/me")
async def me(user: User = Depends(get_current_user)):
return {"id": user.id, "name": user.name, "email": user.email,
"avatarInitials": "".join(p[0] for p in user.name.split()[:2]).upper(),
"avatarColor": "#3B82F6", "role": user.role, "status": user.status,
"isOnline": True, "lastActive": "Đang trực tuyến"}
class InviteIn(BaseModel):
email: str
role: str = "annotator"
projectIds: list[str] = Field(default_factory=list)
class UserPatch(BaseModel):
role: str | None = None
status: str | None = None
projectIds: list[str] | None = None
users_router = APIRouter(prefix="/users", tags=["users"])
@users_router.get("")
async def list_users(db: AsyncSession = Depends(get_session)):
from src.services import users as svc
return await svc.list_users(db)
@users_router.post("", status_code=201)
async def invite(body: InviteIn, db: AsyncSession = Depends(get_session)):
from src.services import users as svc
return await svc.invite_user(body.email, body.role, body.projectIds, db)
@users_router.patch("/{user_id}")
async def patch_user(user_id: str, body: UserPatch, db: AsyncSession = Depends(get_session)):
from src.services import users as svc
return await svc.patch_user(user_id, body.model_dump(), db)

39
src/api/v1/events.py Normal file
View file

@ -0,0 +1,39 @@
"""Client action ingest: operations the backend never sees (UI-only actions).
Batch format keeps high-frequency UI affordable: the frontend buffers and sends
up to 200 events per call. session_id is required — an event without a session
cannot be replayed.
"""
from __future__ import annotations
from fastapi import APIRouter, Depends, HTTPException
from pydantic import BaseModel, Field
from sqlalchemy.ext.asyncio import AsyncSession
from shared import events
from shared.tracing import new_id
router = APIRouter(prefix="/events", tags=["events"])
class ClientEvent(BaseModel):
action: str = Field(min_length=1, max_length=64)
project_id: str | None = None
image_id: str | None = None
payload: dict = Field(default_factory=dict)
class EventsIn(BaseModel):
session_id: str = Field(min_length=1, max_length=64)
events: list[ClientEvent] = Field(min_length=1, max_length=200)
@router.post("", status_code=202)
async def ingest(body: EventsIn):
if not body.session_id.strip():
raise HTTPException(400, "session_id is required")
for e in body.events:
await events.emit(e.action, project_id=e.project_id, image_id=e.image_id,
payload=e.payload, session_id=body.session_id,
trace_id=new_id())
return {"accepted": len(body.events)}

37
src/api/v1/images.py Normal file
View file

@ -0,0 +1,37 @@
from __future__ import annotations
from fastapi import APIRouter, Depends, Query
from sqlalchemy.ext.asyncio import AsyncSession
from shared.schemas import ImageConfirm, PresignRequest
from src.core.db import get_session
from src.services import images as svc
router = APIRouter(prefix="/projects/{project_id}/images", tags=["images"])
@router.get("")
async def list_images(project_id: str, status: str | None = Query(default=None),
search: str | None = Query(default=None),
assignee: str | None = Query(default=None),
limit: int = Query(default=50, ge=1, le=200),
offset: int = Query(default=0, ge=0),
db: AsyncSession = Depends(get_session)):
return await svc.list_images(project_id, status, db, search=search,
assignee=assignee, limit=limit, offset=offset)
@router.post("/presign")
async def presign_upload(project_id: str, body: PresignRequest):
return svc.build_presign(project_id, body.fileName, body.contentType)
@router.post("", status_code=201)
async def confirm_image(project_id: str, body: ImageConfirm, db: AsyncSession = Depends(get_session)):
return await svc.confirm_image(project_id, body, db)
@router.patch("/{image_id}")
async def update_status(project_id: str, image_id: str, status: str,
db: AsyncSession = Depends(get_session)):
return await svc.update_status(project_id, image_id, status, db)

47
src/api/v1/projects.py Normal file
View file

@ -0,0 +1,47 @@
from __future__ import annotations
from fastapi import APIRouter, Depends
from sqlalchemy.ext.asyncio import AsyncSession
from shared.schemas import LabelClassIn, ProjectCreate
from src.core.db import get_session
from src.services import projects as svc
router = APIRouter(prefix="/projects", tags=["projects"])
@router.get("")
async def list_projects(db: AsyncSession = Depends(get_session)):
return await svc.list_projects(db)
@router.post("", status_code=201)
async def create_project(body: ProjectCreate, db: AsyncSession = Depends(get_session)):
return await svc.create_project(body, db)
@router.get("/{project_id}")
async def get_project(project_id: str, db: AsyncSession = Depends(get_session)):
return await svc.get_project_detail(project_id, db)
@router.patch("/{project_id}")
async def patch_project(project_id: str, body: dict, db: AsyncSession = Depends(get_session)):
return await svc.patch_project(project_id, body, db)
@router.delete("/{project_id}")
async def delete_project(project_id: str, db: AsyncSession = Depends(get_session)):
return await svc.delete_project(project_id, db)
@router.post("/{project_id}/classes", status_code=201)
async def add_class(project_id: str, body: LabelClassIn, db: AsyncSession = Depends(get_session)):
return await svc.add_label_class(project_id, body, db)
@router.put("/{project_id}/classes")
async def replace_classes(project_id: str, body: list[dict],
db: AsyncSession = Depends(get_session)):
"""Bulk replace backing LabelsTab onUpdateClasses (add/edit/delete in one call)."""
return await svc.replace_classes(project_id, body, db)

60
src/api/v1/system.py Normal file
View file

@ -0,0 +1,60 @@
from __future__ import annotations
from fastapi import APIRouter, Depends
from sqlalchemy import select, text
from sqlalchemy.ext.asyncio import AsyncSession
from shared.traffic import get_snapshot
from src.core.db import Base, get_engine, get_session, get_session_factory
router = APIRouter(tags=["system"])
@router.get("/health")
async def health(db: AsyncSession = Depends(get_session)):
await db.execute(text("SELECT 1"))
return {"ok": True}
@router.get("/metrics")
async def metrics():
"""Phase-1 traffic counters (Phase-2: Prometheus export). No auth on dev; protect in prod."""
return get_snapshot()
@router.post("/admin/backfill-thumbnails")
async def backfill_thumbnails(limit: int = 100, db: AsyncSession = Depends(get_session)):
"""Mint thumbs for images uploaded before thumbnailing existed. Dev-only."""
from models import Image
from shared import thumbnails
rows = (await db.execute(
select(Image).where(Image.thumbnail_r2_key.is_(None)).limit(limit))).scalars().all()
minted = 0
for im in rows:
keys = await thumbnails.mint_thumbnails_for_image(im.project_id, im.id, im.r2_key)
if keys["thumbnail"]:
im.thumbnail_r2_key = keys["thumbnail"]
if keys["small"]:
im.thumbnail_small_r2_key = keys["small"]
if keys["thumbnail"] or keys["small"]:
minted += 1
await db.commit()
return {"scanned": len(rows), "minted": minted}
@router.post("/admin/init-db")
async def init_db():
"""Create tables from models. Replaced by Alembic once migrations exist."""
from models import User
from src.core.security import hash_password
async with get_engine().begin() as conn:
await conn.run_sync(Base.metadata.create_all)
factory = get_session_factory()
async with factory() as s:
admin = (await s.execute(select(User).where(User.email == "admin@danable.local"))).scalar_one_or_none()
if admin is None:
s.add(User(email="admin@danable.local", name="Admin", role="admin",
status="active", password_hash=hash_password("Admin123!"),
assigned_project_ids=[]))
await s.commit()
return {"ok": True, "seeded_admin": "admin@danable.local"}

0
src/core/__init__.py Normal file
View file

65
src/core/config.py Normal file
View file

@ -0,0 +1,65 @@
"""Central settings: .env (secrets) + config.yaml (shape). Env wins on conflict."""
from __future__ import annotations
import os
from functools import lru_cache
from pathlib import Path
import yaml
from dotenv import load_dotenv
BACKEND_DIR = Path(__file__).resolve().parents[2]
load_dotenv(BACKEND_DIR / ".env")
def _load_yaml() -> dict:
for name in ("config.yaml", "config.example.yaml"):
p = BACKEND_DIR / name
if p.exists():
return yaml.safe_load(p.read_text()) or {}
return {}
class Settings:
def __init__(self) -> None:
self.yaml = _load_yaml()
app = self.yaml.get("app", {})
storage = self.yaml.get("storage", {})
self.app_name: str = app.get("name", "danable")
self.api_prefix: str = app.get("api_prefix", "/api/v1")
self.database_url: str = os.getenv(
"DATABASE_URL", "postgresql+asyncpg://danable:danable@localhost:5432/danable"
)
self.redis_url: str = os.getenv("REDIS_URL", "redis://localhost:6379/0")
self.jwt_secret: str = os.getenv("JWT_SECRET", "change-me")
self.jwt_expire_minutes: int = int(os.getenv("JWT_EXPIRE_MINUTES", "720"))
self.r2_endpoint: str = os.getenv("R2_ENDPOINT", "")
self.r2_key_id: str = os.getenv("R2_ACCESS_KEY_ID", "")
self.r2_secret: str = os.getenv("R2_SECRET_ACCESS_KEY", "")
self.r2_bucket: str = os.getenv(
"R2_BUCKET", storage.get("bucket_default", "danagble")
)
self.r2_public_base: str = os.getenv("R2_PUBLIC_BASE_URL", "")
layout = storage.get("layout", {})
presigned = storage.get("presigned_ttl", {})
self.r2_layout: dict = layout
thumb = storage.get("thumbnail", {})
self.thumbnail_enabled: bool = bool(thumb.get("enabled", True))
self.thumbnail_max_side: int = int(thumb.get("max_side", 512))
self.thumbnail_quality: int = int(thumb.get("quality", 70))
self.presign_put_ttl: int = int(presigned.get("put_seconds", 900))
self.presign_get_ttl: int = int(presigned.get("get_seconds", 3600))
self.traffic = self.yaml.get("traffic", {"enabled": True})
@property
def r2_configured(self) -> bool:
return bool(self.r2_endpoint and self.r2_key_id and self.r2_secret)
@lru_cache
def get_settings() -> Settings:
return Settings()

36
src/core/db.py Normal file
View file

@ -0,0 +1,36 @@
"""Async SQLAlchemy engine/session. Postgres only (per project decision)."""
from __future__ import annotations
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
from sqlalchemy.orm import DeclarativeBase
from src.core.config import get_settings
class Base(DeclarativeBase):
pass
_engine = None
_session_factory = None
def get_engine():
global _engine
if _engine is None:
s = get_settings()
_engine = create_async_engine(s.database_url, pool_pre_ping=True)
return _engine
def get_session_factory() -> async_sessionmaker[AsyncSession]:
global _session_factory
if _session_factory is None:
_session_factory = async_sessionmaker(get_engine(), expire_on_commit=False)
return _session_factory
async def get_session():
factory = get_session_factory()
async with factory() as session:
yield session

63
src/core/security.py Normal file
View file

@ -0,0 +1,63 @@
"""JWT + bcrypt auth. Passwords never leave the hash; tokens carry sub/role/exp."""
from __future__ import annotations
from datetime import datetime, timedelta, timezone
import bcrypt
import jwt
from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from sqlalchemy.ext.asyncio import AsyncSession
from src.core.config import get_settings
from src.core.db import get_session
_bearer = HTTPBearer(auto_error=False)
def hash_password(password: str) -> str:
return bcrypt.hashpw(password.encode(), bcrypt.gensalt()).decode()
def verify_password(password: str, hashed: str) -> bool:
try:
return bcrypt.checkpw(password.encode(), hashed.encode())
except Exception:
return False
def create_token(user_id: str, role: str, expires_minutes: int | None = None) -> str:
s = get_settings()
exp = datetime.now(timezone.utc) + timedelta(
minutes=expires_minutes if expires_minutes is not None else s.jwt_expire_minutes)
return jwt.encode({"sub": user_id, "role": role, "exp": exp}, s.jwt_secret, algorithm="HS256")
def decode_token(token: str) -> dict | None:
"""No DB hit: used by tracing middleware to attribute the session user."""
try:
return jwt.decode(token, get_settings().jwt_secret, algorithms=["HS256"])
except Exception:
return None
def _unauthorized(detail: str = "not authenticated") -> HTTPException:
return HTTPException(status.HTTP_401_UNAUTHORIZED, detail,
headers={"WWW-Authenticate": "Bearer"})
async def get_current_user(
creds: HTTPAuthorizationCredentials | None = Depends(_bearer),
db: AsyncSession = Depends(get_session),
):
from models import User # late import: avoids cycle at module load
if creds is None or not creds.credentials:
raise _unauthorized()
payload = decode_token(creds.credentials)
if not payload or not payload.get("sub"):
raise _unauthorized("invalid or expired token")
from sqlalchemy import select
user = (await db.execute(select(User).where(User.id == payload["sub"]))).scalar_one_or_none()
if user is None or user.status == "suspended":
raise _unauthorized("user not found or suspended")
return user

69
src/main.py Normal file
View file

@ -0,0 +1,69 @@
from __future__ import annotations
import asyncio
from contextlib import asynccontextmanager
from fastapi import Depends, FastAPI, Request
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import JSONResponse
from shared import events
from shared.logger import get_logger
from shared.tracing import TraceMiddleware
from shared.traffic import TrafficMiddleware
from src.api.v1 import activities, annotations, auth, events as events_api, images, projects, system
from src.api.v1.auth import users_router
from src.core.config import get_settings
from src.core.security import get_current_user
s = get_settings()
log = get_logger("danable")
@asynccontextmanager
async def lifespan(app: FastAPI):
drainer = asyncio.create_task(events.drain_forever())
yield
drainer.cancel()
app = FastAPI(title=s.app_name, lifespan=lifespan)
app.add_middleware(
CORSMiddleware,
allow_origins=["http://localhost:5173", "http://localhost:3000"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
if s.traffic.get("enabled", True):
app.add_middleware(TrafficMiddleware)
app.add_middleware(TraceMiddleware)
@app.exception_handler(RuntimeError)
async def _config_error(request: Request, exc: RuntimeError):
# Missing R2 creds etc: 503 with actionable message instead of 500.
return JSONResponse(status_code=503, detail=str(exc))
prefix = s.api_prefix
authed: list = [Depends(get_current_user)]
# Public: health/metrics, auth, client-event ingest (session telemetry).
app.include_router(system.router, prefix=prefix)
app.include_router(auth.router, prefix=prefix)
app.include_router(users_router, prefix=prefix, dependencies=authed)
app.include_router(events_api.router, prefix=prefix)
app.include_router(activities.router, prefix=prefix, dependencies=authed)
# Domain: require JWT.
app.include_router(projects.router, prefix=prefix, dependencies=authed)
app.include_router(images.router, prefix=prefix, dependencies=authed)
app.include_router(annotations.router, prefix=prefix, dependencies=authed)
@app.get("/")
async def root():
log.info("serving api prefix=%s", prefix)
return {"name": s.app_name, "docs": "/docs", "health": f"{prefix}/health"}

View file

@ -0,0 +1,58 @@
"""Annotation business logic: one row per image (upsert)."""
from __future__ import annotations
import time
from fastapi import HTTPException
from sqlalchemy.ext.asyncio import AsyncSession
from models import Annotation, Image
from shared import events
from shared.schemas import AnnotationUpsert
async def _require_image(project_id: str, image_id: str, db: AsyncSession) -> Image:
im = await db.get(Image, image_id)
if im is None or im.project_id != project_id:
raise HTTPException(404, "image not found")
return im
async def get_annotation(project_id: str, image_id: str, db: AsyncSession) -> dict:
ann = await db.get(Annotation, image_id)
if ann is None:
return {"imageId": image_id, "projectId": project_id,
"classificationLabelId": None,
"flags": {"blurryOrUncertain": False, "needsRecheck": False}, "shapes": []}
return {"imageId": ann.image_id, "projectId": ann.project_id,
"classificationLabelId": ann.classification_label_id,
"flags": ann.flags, "shapes": ann.shapes}
async def upsert_annotation(project_id: str, image_id: str, body: AnnotationUpsert,
db: AsyncSession) -> dict:
im = await _require_image(project_id, image_id, db)
t0 = time.perf_counter()
ann = await db.get(Annotation, image_id)
payload = {"project_id": project_id,
"classification_label_id": body.classificationLabelId,
"flags": body.flags.model_dump(),
"shapes": [s.model_dump() for s in body.shapes]}
if ann is None:
ann = Annotation(image_id=image_id, **payload)
db.add(ann)
else:
for k, v in payload.items():
setattr(ann, k, v)
im = await db.get(Image, image_id)
if im is not None:
im.object_count = len(body.shapes)
im.classification_label_id = body.classificationLabelId
im.flags = body.flags.model_dump()
await db.commit()
await events.emit("annotation.save", project_id=project_id, image_id=image_id,
payload={"shapeCount": len(body.shapes),
"label": body.classificationLabelId},
result={"saved": True},
latency_ms=(time.perf_counter() - t0) * 1000)
return {"imageId": image_id, "saved": True, "shapeCount": len(body.shapes)}

104
src/services/images.py Normal file
View file

@ -0,0 +1,104 @@
"""Image business logic: presign (direct-to-R2), confirm, status."""
from __future__ import annotations
import time
from fastapi import HTTPException
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
from models import Image
from shared import events, keys, r2
from shared.schemas import ImageConfirm
def _thumb_url(*candidates: str | None) -> str:
for key in candidates:
if key:
return r2.presign_get(key)
return ""
async def list_images(project_id: str, status: str | None, db: AsyncSession,
search: str | None = None, assignee: str | None = None,
limit: int = 50, offset: int = 0) -> dict:
"""Paginated image list. One page = one screenful; never the whole dataset."""
from models import User
from sqlalchemy import func
limit = max(1, min(limit, 200))
offset = max(0, offset)
q = select(Image).where(Image.project_id == project_id)
count_q = select(func.count()).where(Image.project_id == project_id)
if status and status != "all":
q = q.where(Image.status == status)
count_q = count_q.where(Image.status == status)
if search and search.strip():
like = f"%{search.strip()}%"
q = q.where(Image.file_name.ilike(like))
count_q = count_q.where(Image.file_name.ilike(like))
if assignee and assignee != "all":
q = q.join(User, User.id == Image.assigned_to).where(User.name == assignee)
count_q = count_q.join(User, User.id == Image.assigned_to).where(User.name == assignee)
total = (await db.execute(count_q)).scalar() or 0
rows = (await db.execute(q.order_by(Image.created_at.desc()).limit(limit).offset(offset))).scalars().all()
users = (await db.execute(select(User))).scalars().all()
names = {u.id: u.name for u in users}
items = [{"id": im.id, "projectId": im.project_id, "fileName": im.file_name,
"url": r2.presign_get(im.r2_key),
"thumbnailUrl": _thumb_url(im.thumbnail_r2_key, im.r2_key),
"thumbnailSmallUrl": _thumb_url(im.thumbnail_small_r2_key,
im.thumbnail_r2_key, im.r2_key),
"width": im.width, "height": im.height, "status": im.status,
"objectCount": im.object_count, "assignedTo": im.assigned_to,
"assignedToName": names.get(im.assigned_to or "", ""),
"reviewerName": im.reviewer_name,
"classificationLabelId": im.classification_label_id, "flags": im.flags}
for im in rows]
return {"items": items, "total": total}
def build_presign(project_id: str, file_name: str, content_type: str) -> dict:
"""Step 1/2 direct upload: frontend PUTs bytes straight to R2 with this URL."""
key = keys.image_key(project_id, "tmp", file_name) # real id assigned on confirm
return {"putUrl": r2.presign_put(key, content_type), "r2Key": key}
async def confirm_image(project_id: str, body: ImageConfirm, db: AsyncSession) -> dict:
"""Step 2/2: metadata row after the R2 PUT succeeds."""
if not r2.head_exists(body.r2Key):
raise HTTPException(400, "object not found in R2; upload first via presign PUT")
im = Image(project_id=project_id, file_name=body.fileName, r2_key=body.r2Key,
width=body.width, height=body.height, status="in_progress", flags={})
db.add(im)
t0 = time.perf_counter()
await db.commit()
await db.refresh(im)
try:
from shared import thumbnails
minted = await thumbnails.mint_thumbnails_for_image(project_id, im.id, im.r2_key)
if minted["thumbnail"]:
im.thumbnail_r2_key = minted["thumbnail"]
if minted["small"]:
im.thumbnail_small_r2_key = minted["small"]
if minted["thumbnail"] or minted["small"]:
await db.commit()
except Exception:
pass # card falls back to the full image
await events.emit("image.confirm", project_id=project_id, image_id=im.id,
payload={"fileName": body.fileName, "r2Key": body.r2Key},
latency_ms=(time.perf_counter() - t0) * 1000)
return {"id": im.id, "r2Key": im.r2_key, "url": r2.presign_get(im.r2_key)}
async def update_status(project_id: str, image_id: str, status: str, db: AsyncSession) -> dict:
im = await db.get(Image, image_id)
if im is None or im.project_id != project_id:
raise HTTPException(404, "image not found")
prev = im.status
im.status = status
t0 = time.perf_counter()
await db.commit()
await events.emit("image.status", project_id=project_id, image_id=im.id,
payload={"from": prev, "to": status},
latency_ms=(time.perf_counter() - t0) * 1000)
return {"id": im.id, "status": im.status}

184
src/services/projects.py Normal file
View file

@ -0,0 +1,184 @@
"""Project + label-class business logic (called by the API layer)."""
from __future__ import annotations
import time
from fastapi import HTTPException
from sqlalchemy import func, select
from sqlalchemy.ext.asyncio import AsyncSession
from models import AIJob, ActionEvent, Annotation, ExportJob, Image, LabelClass, Project, User
from shared import events
from shared.schemas import LabelClassIn, ProjectCreate
_MEMBER_COLORS = ["#E0E7FF", "#DBEAFE", "#FCE7F3", "#FFEDD5", "#EDE9FE", "#DCFCE7"]
def _initials(name: str) -> str:
parts = name.split()
if len(parts) >= 2:
return f"{parts[0][0]}{parts[-1][0]}".upper()
return (name[:2] or "??").upper()
async def list_projects(db: AsyncSession) -> list[dict]:
rows = (await db.execute(select(Project).order_by(Project.created_at.desc()))).scalars().all()
return [await _project_card(p, db) for p in rows]
async def create_project(body: ProjectCreate, db: AsyncSession) -> dict:
exists = (await db.execute(select(Project).where(Project.slug == body.slug))).scalar_one_or_none()
if exists:
raise HTTPException(409, "slug already exists")
p = Project(slug=body.slug, name=body.name, description=body.description,
task_type=body.taskType, status="annotating")
db.add(p)
t0 = time.perf_counter()
await db.commit()
await db.refresh(p)
await events.emit("project.create", project_id=p.id,
payload={"slug": p.slug, "taskType": p.task_type},
result={"id": p.id},
latency_ms=(time.perf_counter() - t0) * 1000)
return {"id": p.id, "slug": p.slug, "name": p.name, "taskType": p.task_type, "status": p.status}
async def _stats(project_id: str, db: AsyncSession) -> dict:
counts: dict[str, int] = {}
for st in ("unassigned", "in_progress", "pending_review", "completed"):
counts[st] = (await db.execute(
select(func.count()).where(Image.project_id == project_id, Image.status == st))).scalar() or 0
total = sum(counts.values())
objects = (await db.execute(
select(func.coalesce(func.sum(Image.object_count), 0)).where(Image.project_id == project_id))).scalar() or 0
return {"totalImages": total, "unassigned": counts["unassigned"], "inProgress": counts["in_progress"],
"pendingReview": counts["pending_review"], "completed": counts["completed"],
"totalObjects": int(objects)}
async def _members(project_id: str, db: AsyncSession) -> list[dict]:
users = (await db.execute(select(User).order_by(User.created_at))).scalars().all()
assigned = [u for u in users if project_id in (u.assigned_project_ids or [])]
out = []
for i, u in enumerate(assigned):
n = (await db.execute(select(func.count()).where(
Image.project_id == project_id, Image.assigned_to == u.id))).scalar() or 0
out.append({"id": u.id, "name": u.name, "initials": _initials(u.name),
"color": _MEMBER_COLORS[i % len(_MEMBER_COLORS)],
"role": u.role if u.role in ("annotator", "reviewer", "manager") else "annotator",
"assignedCount": n,
**({"pendingReviewCount": n} if u.role == "reviewer" else {})})
return out
async def _thumbnail_url(project_id: str, db: AsyncSession) -> str:
"""Project cover: dedicated thumb when present, else first image itself.
Trusts DB keys without R2 HEAD checks: a HEAD per card is 100-300ms of
API latency. Stale keys render nothing thanks to the UI onError fallback.
"""
from shared import r2
row = (await db.execute(
select(Image.thumbnail_r2_key, Image.r2_key)
.where(Image.project_id == project_id)
.order_by(Image.created_at).limit(1))).first()
if not row:
return ""
for key in (row[0], row[1]):
if not key:
continue
try:
return r2.presign_get(key)
except Exception:
continue
return ""
async def _project_card(p: Project, db: AsyncSession) -> dict:
classes = (await db.execute(select(LabelClass).where(LabelClass.project_id == p.id))).scalars().all()
return {"id": p.id, "slug": p.slug, "name": p.name, "taskType": p.task_type,
"status": p.status, "description": p.description,
"thumbnailUrl": await _thumbnail_url(p.id, db),
"updatedAt": p.updated_at.isoformat() if p.updated_at else "",
"classes": [{"id": c.id, "name": c.name, "color": c.color} for c in classes],
"stats": await _stats(p.id, db),
"members": await _members(p.id, db)}
async def get_project_detail(project_id: str, db: AsyncSession) -> dict:
p = await db.get(Project, project_id)
if p is None:
raise HTTPException(404, "project not found")
return await _project_card(p, db)
async def patch_project(project_id: str, patch: dict, db: AsyncSession) -> dict:
p = await db.get(Project, project_id)
if p is None:
raise HTTPException(404, "project not found")
for field in ("name", "slug", "description", "task_type", "status"):
if patch.get(field) is not None:
setattr(p, field, patch[field])
await db.commit()
return await get_project_detail(project_id, db)
async def delete_project(project_id: str, db: AsyncSession) -> dict:
p = await db.get(Project, project_id)
if p is None:
raise HTTPException(404, "project not found")
img_ids = (await db.execute(select(Image.id).where(Image.project_id == project_id))).scalars().all()
for img_id in img_ids:
ann = await db.get(Annotation, img_id)
if ann is not None:
await db.delete(ann)
im = await db.get(Image, img_id)
if im is not None:
await db.delete(im)
for model, col in ((ExportJob, ExportJob.project_id), (AIJob, AIJob.project_id),
(ActionEvent, ActionEvent.project_id), (LabelClass, LabelClass.project_id)):
rows = (await db.execute(select(model).where(col == project_id))).scalars().all()
for r in rows:
await db.delete(r)
await db.delete(p)
await db.commit()
return {"deleted": project_id}
async def replace_classes(project_id: str, classes: list[dict], db: AsyncSession) -> list[dict]:
"""Bulk replace: matches LabelsTab onUpdateClasses semantics (add/edit/delete in one call)."""
if await db.get(Project, project_id) is None:
raise HTTPException(404, "project not found")
existing = (await db.execute(select(LabelClass).where(LabelClass.project_id == project_id))).scalars().all()
by_id = {c.id: c for c in existing}
seen: set[str] = set()
out = []
for c in classes:
cid = c.get("id")
if cid in by_id:
obj = by_id[cid]
obj.name = c.get("name", obj.name)
obj.color = c.get("color", obj.color)
seen.add(cid)
else:
obj = LabelClass(project_id=project_id, name=c.get("name", "Untitled"),
color=c.get("color", "#888888"))
db.add(obj)
out.append(obj)
for cid, obj in by_id.items():
if cid not in seen:
await db.delete(obj)
await db.commit()
for obj in out:
await db.refresh(obj)
return [{"id": o.id, "name": o.name, "color": o.color} for o in out]
async def add_label_class(project_id: str, body: LabelClassIn, db: AsyncSession) -> dict:
if await db.get(Project, project_id) is None:
raise HTTPException(404, "project not found")
c = LabelClass(project_id=project_id, name=body.name, color=body.color, shortcut_key=body.shortcutKey)
db.add(c)
await db.commit()
await db.refresh(c)
return {"id": c.id, "name": c.name, "color": c.color}

60
src/services/users.py Normal file
View file

@ -0,0 +1,60 @@
"""User business logic: list / invite / patch role-status-assignment."""
from __future__ import annotations
import secrets
from fastapi import HTTPException
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
from models import User
from src.core.security import hash_password
INVITE_PREFIX = "invite.local"
def to_public(u: User) -> dict:
return {"id": u.id, "email": u.email, "name": u.name, "role": u.role,
"status": u.status, "assignedProjectIds": u.assigned_project_ids or []}
async def list_users(db: AsyncSession) -> list[dict]:
rows = (await db.execute(select(User).order_by(User.created_at))).scalars().all()
return [to_public(u) for u in rows]
async def invite_user(email: str, role: str, project_ids: list[str], db: AsyncSession) -> dict:
email = email.strip().lower()
if not email or "@" not in email:
raise HTTPException(400, "invalid email")
exists = (await db.execute(select(User).where(User.email == email))).scalar_one_or_none()
if exists:
raise HTTPException(409, "email already invited")
name = " ".join(p.capitalize() for p in email.split("@")[0].replace(".", " ").replace("_", " ").split()) or email
u = User(email=email, name=name, role=role, status="invited",
# Unusable until password is set; login with it always fails.
password_hash=hash_password(secrets.token_urlsafe(32)),
assigned_project_ids=list(project_ids or []))
db.add(u)
await db.commit()
await db.refresh(u)
return to_public(u)
async def patch_user(user_id: str, patch: dict, db: AsyncSession) -> dict:
u = await db.get(User, user_id)
if u is None:
raise HTTPException(404, "user not found")
if patch.get("role") is not None:
if patch["role"] not in ("admin", "manager", "annotator", "reviewer"):
raise HTTPException(400, "invalid role")
u.role = patch["role"]
if patch.get("status") is not None:
if patch["status"] not in ("active", "invited", "suspended"):
raise HTTPException(400, "invalid status")
u.status = patch["status"]
if patch.get("projectIds") is not None:
u.assigned_project_ids = list(patch["projectIds"])
await db.commit()
await db.refresh(u)
return to_public(u)