monkeybrain-runtime 1.0.0__py3-none-any.whl

services/shifts/models/timesheet.py

@@ -0,0 +1,196 @@
+from datetime import date, datetime, time
+from decimal import Decimal
+from typing import Annotated, Optional
+from uuid import uuid4
+
+from pydantic import BaseModel, Field, computed_field, model_validator
+
+from services.common.models.enums import ShiftType
+
+
+class BreakPeriod(BaseModel):
+    """A single break within a shift."""
+
+    break_start: time
+    break_end: time
+    paid: bool = False
+    reason: Optional[str] = Field(None, max_length=100, examples=["Lunch", "Short break"])
+
+    @model_validator(mode="after")
+    def end_after_start(self) -> "BreakPeriod":
+        if self.break_end <= self.break_start:
+            raise ValueError("break_end must be after break_start")
+        return self
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def duration_minutes(self) -> int:
+        start = datetime.combine(datetime.today(), self.break_start)
+        end = datetime.combine(datetime.today(), self.break_end)
+        return int((end - start).total_seconds() / 60)
+
+
+class TimeSheetEntry(BaseModel):
+    """A single day/shift entry for one worker."""
+
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    worker_id: str = Field(..., min_length=1, max_length=50, description="Employee ID or badge number")
+    worker_name: str = Field(..., min_length=1, max_length=150)
+    work_date: date
+    shift_type: ShiftType = ShiftType.MORNING
+    clock_in: datetime
+    clock_out: Optional[datetime] = None
+    breaks: list[BreakPeriod] = Field(default_factory=list)
+    delivery_note_ids: list[str] = Field(
+        default_factory=list,
+        description="Delivery notes this worker was involved in",
+    )
+    vehicle_id: Optional[str] = Field(None, description="Vehicle driven / operated during this shift")
+    warehouse_zone: Optional[str] = Field(None, max_length=50, description="Zone or bay assignment")
+    tasks_performed: list[str] = Field(
+        default_factory=list,
+        examples=[["Loading", "Unloading", "Pallet wrapping", "Forklift operation"]],
+    )
+    overtime_hours: Annotated[float, Field(ge=0)] = 0.0
+    overtime_approved_by: Optional[str] = Field(None, max_length=150)
+    supervisor_id: Optional[str] = Field(None, max_length=50)
+    approved: bool = False
+    approved_by: Optional[str] = Field(None, max_length=150)
+    approved_at: Optional[datetime] = None
+    notes: Optional[str] = None
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+
+    model_config = {"str_strip_whitespace": True}
+
+    @model_validator(mode="after")
+    def clock_out_after_clock_in(self) -> "TimeSheetEntry":
+        if self.clock_out is not None and self.clock_out <= self.clock_in:
+            raise ValueError("clock_out must be after clock_in")
+        return self
+
+    @model_validator(mode="after")
+    def overtime_needs_approver(self) -> "TimeSheetEntry":
+        if self.overtime_hours > 0 and self.overtime_approved_by is None:
+            raise ValueError("overtime_approved_by is required when overtime_hours > 0")
+        return self
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def total_break_minutes(self) -> int:
+        return sum(b.duration_minutes for b in self.breaks)
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def gross_hours_worked(self) -> Optional[float]:
+        if self.clock_out is None:
+            return None
+        delta = self.clock_out - self.clock_in
+        return round(delta.total_seconds() / 3600, 4)
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def net_hours_worked(self) -> Optional[float]:
+        """Gross hours minus unpaid breaks."""
+        gross = self.gross_hours_worked
+        if gross is None:
+            return None
+        unpaid_minutes = sum(b.duration_minutes for b in self.breaks if not b.paid)
+        return round(gross - unpaid_minutes / 60, 4)
+
+
+class TimeSheet(BaseModel):
+    """Aggregated time sheet for a worker covering a pay period."""
+
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    worker_id: str = Field(..., min_length=1, max_length=50)
+    worker_name: str = Field(..., min_length=1, max_length=150)
+    period_start: date
+    period_end: date
+    entries: list[TimeSheetEntry] = Field(default_factory=list)
+    total_regular_hours: float = Field(default=0.0, ge=0)
+    total_overtime_hours: float = Field(default=0.0, ge=0)
+    total_paid_hours: float = Field(default=0.0, ge=0)
+    currency: str = Field(default="USD", min_length=3, max_length=3, description="ISO 4217")
+    hourly_rate: Optional[Annotated[Decimal, Field(gt=0)]] = None
+    overtime_rate_multiplier: float = Field(default=1.5, gt=0)
+    submitted: bool = False
+    submitted_at: Optional[datetime] = None
+    approved: bool = False
+    approved_by: Optional[str] = Field(None, max_length=150)
+    approved_at: Optional[datetime] = None
+    payroll_reference: Optional[str] = Field(None, max_length=100)
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: Optional[datetime] = None
+
+    model_config = {"str_strip_whitespace": True}
+
+    @model_validator(mode="after")
+    def period_end_after_start(self) -> "TimeSheet":
+        if self.period_end < self.period_start:
+            raise ValueError("period_end must be on or after period_start")
+        return self
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def gross_pay(self) -> Optional[Decimal]:
+        if self.hourly_rate is None:
+            return None
+        regular_pay = Decimal(str(self.total_regular_hours)) * self.hourly_rate
+        overtime_pay = (
+            Decimal(str(self.total_overtime_hours))
+            * self.hourly_rate
+            * Decimal(str(self.overtime_rate_multiplier))
+        )
+        return round(regular_pay + overtime_pay, 2)
+
+    def recalculate_totals(self) -> None:
+        """Recompute hour totals from entries in place."""
+        regular = 0.0
+        overtime = 0.0
+        for entry in self.entries:
+            net = entry.net_hours_worked or 0.0
+            ot = entry.overtime_hours
+            regular += max(0.0, net - ot)
+            overtime += ot
+        self.total_regular_hours = round(regular, 4)
+        self.total_overtime_hours = round(overtime, 4)
+        self.total_paid_hours = round(regular + overtime, 4)
+
+
+class TimeSheetCreate(TimeSheet):
+    pass
+
+
+class TimeSheetUpdate(BaseModel):
+    worker_id: Optional[str] = Field(None, min_length=1, max_length=50)
+    worker_name: Optional[str] = Field(None, min_length=1, max_length=150)
+    period_start: Optional[date] = None
+    period_end: Optional[date] = None
+    entries: Optional[list[TimeSheetEntry]] = None
+    total_regular_hours: Optional[float] = Field(None, ge=0)
+    total_overtime_hours: Optional[float] = Field(None, ge=0)
+    total_paid_hours: Optional[float] = Field(None, ge=0)
+    currency: Optional[str] = Field(None, min_length=3, max_length=3)
+    hourly_rate: Optional[Annotated[Decimal, Field(gt=0)]] = None
+    overtime_rate_multiplier: Optional[float] = Field(None, gt=0)
+    submitted: Optional[bool] = None
+    submitted_at: Optional[datetime] = None
+    approved: Optional[bool] = None
+    approved_by: Optional[str] = Field(None, max_length=150)
+    approved_at: Optional[datetime] = None
+    payroll_reference: Optional[str] = Field(None, max_length=100)
+    updated_at: Optional[datetime] = None
+
+    model_config = {"str_strip_whitespace": True}
+
+
+class TimeSheetResponse(TimeSheet):
+    class Config:
+        from_attributes = True
+
+
+class PaginatedTimeSheetResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[TimeSheetResponse]

services/shifts/routers/__init__.py

@@ -0,0 +1,7 @@
+"""shifts service routers package."""
+
+__all__ = [
+    "shift_templates",
+    "shifts",
+    "timesheets",
+]

services/shifts/routers/shift_templates.py

@@ -0,0 +1,97 @@
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from motor.motor_asyncio import AsyncIOMotorDatabase
+
+from services.common.db import get_database
+from services.common.auth import get_current_user, require_permission
+from services.shifts.helpers import shift_templates as crud
+from services.shifts.models.shift_template import (
+    PaginatedShiftTemplateResponse,
+    ShiftTemplateCreate,
+    ShiftTemplateResponse,
+    ShiftTemplateUpdate,
+)
+
+router = APIRouter()
+
+
+@router.get("/", response_model=PaginatedShiftTemplateResponse)
+async def list_shift_templates(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100),
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(get_current_user),
+):
+    templates, total = await crud.get_all(db, page=page, page_size=page_size)
+    return PaginatedShiftTemplateResponse(
+        total=total,
+        page=page,
+        page_size=page_size,
+        results=templates,
+    )
+
+
+@router.get("/by-factory/{factory_id}", response_model=list[ShiftTemplateResponse])
+async def list_shift_templates_by_factory(
+    factory_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(get_current_user),
+):
+    return await crud.get_by_factory(db, factory_id)
+
+
+@router.get("/{template_id}", response_model=ShiftTemplateResponse)
+async def get_shift_template(
+    template_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(get_current_user),
+):
+    record = await crud.get_by_id(db, template_id)
+    if not record:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Shift template '{template_id}' not found",
+        )
+    return record
+
+
+@router.post("/", response_model=ShiftTemplateResponse, status_code=status.HTTP_201_CREATED)
+async def create_shift_template(
+    data: ShiftTemplateCreate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-create-shift-templates")),
+):
+    if await crud.get_by_id(db, str(data.id)):
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"Shift template '{data.id}' already exists",
+        )
+    return await crud.create(db, data)
+
+
+@router.patch("/{template_id}", response_model=ShiftTemplateResponse)
+async def update_shift_template(
+    template_id: str,
+    data: ShiftTemplateUpdate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-update-shift-templates")),
+):
+    updated = await crud.update(db, template_id, data)
+    if not updated:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Shift template '{template_id}' not found",
+        )
+    return updated
+
+
+@router.delete("/{template_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_shift_template(
+    template_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-delete-shift-templates")),
+):
+    if not await crud.delete(db, template_id):
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Shift template '{template_id}' not found",
+        )

services/shifts/routers/shifts.py

@@ -0,0 +1,117 @@
+from datetime import date
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from motor.motor_asyncio import AsyncIOMotorDatabase
+
+from services.common.db import get_database
+from services.common.auth import require_permission
+from services.shifts.helpers import shifts as crud
+from services.shifts.models.shift import (
+    PaginatedShiftScheduleResponse,
+    ShiftScheduleCreate,
+    ShiftScheduleResponse,
+    ShiftScheduleUpdate,
+)
+
+router = APIRouter()
+
+
+@router.get("/", response_model=PaginatedShiftScheduleResponse)
+async def list_shifts(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100),
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-shifts")),
+):
+    shifts, total = await crud.get_all(db, page=page, page_size=page_size)
+    return PaginatedShiftScheduleResponse(
+        total=total,
+        page=page,
+        page_size=page_size,
+        results=shifts,
+    )
+
+
+@router.get("/by-factory/{factory_id}", response_model=list[ShiftScheduleResponse])
+async def list_shifts_by_factory(
+    factory_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-shifts")),
+):
+    return await crud.get_by_factory(db, factory_id)
+
+
+@router.get("/by-template/{template_id}", response_model=list[ShiftScheduleResponse])
+async def list_shifts_by_template(
+    template_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-shifts")),
+):
+    return await crud.get_by_template(db, template_id)
+
+
+@router.get("/by-date/{shift_date}", response_model=list[ShiftScheduleResponse])
+async def list_shifts_by_date(
+    shift_date: date,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-shifts")),
+):
+    return await crud.get_by_date(db, shift_date)
+
+
+@router.get("/{shift_id}", response_model=ShiftScheduleResponse)
+async def get_shift(
+    shift_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-shifts")),
+):
+    record = await crud.get_by_id(db, shift_id)
+    if not record:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Shift '{shift_id}' not found",
+        )
+    return record
+
+
+@router.post("/", response_model=ShiftScheduleResponse, status_code=status.HTTP_201_CREATED)
+async def create_shift(
+    data: ShiftScheduleCreate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-create-shifts")),
+):
+    if await crud.get_by_id(db, str(data.id)):
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"Shift '{data.id}' already exists",
+        )
+    return await crud.create(db, data)
+
+
+@router.patch("/{shift_id}", response_model=ShiftScheduleResponse)
+async def update_shift(
+    shift_id: str,
+    data: ShiftScheduleUpdate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-update-shifts")),
+):
+    updated = await crud.update(db, shift_id, data)
+    if not updated:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Shift '{shift_id}' not found",
+        )
+    return updated
+
+
+@router.delete("/{shift_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_shift(
+    shift_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-delete-shifts")),
+):
+    if not await crud.delete(db, shift_id):
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Shift '{shift_id}' not found",
+        )

services/shifts/routers/timesheets.py

@@ -0,0 +1,117 @@
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from motor.motor_asyncio import AsyncIOMotorDatabase
+
+from services.common.auth import get_current_user, require_permission
+from services.common.db import get_database
+from services.shifts.helpers import timesheets as crud
+from services.shifts.models.timesheet import (
+    PaginatedTimeSheetResponse,
+    TimeSheetCreate,
+    TimeSheetResponse,
+    TimeSheetUpdate,
+)
+
+router = APIRouter()
+
+
+@router.get("/", response_model=PaginatedTimeSheetResponse)
+async def list_timesheets(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100),
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(get_current_user),
+):
+    records, total = await crud.get_all(db, page=page, page_size=page_size)
+    return PaginatedTimeSheetResponse(total=total, page=page, page_size=page_size, results=records)
+
+
+@router.get("/by-worker/{worker_id}", response_model=list[TimeSheetResponse])
+async def list_timesheets_by_worker(
+    worker_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(get_current_user),
+):
+    return await crud.get_by_worker(db, worker_id)
+
+
+@router.get("/by-payroll-reference/{payroll_reference}", response_model=TimeSheetResponse)
+async def get_timesheet_by_payroll_reference(
+    payroll_reference: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(get_current_user),
+):
+    record = await crud.get_by_payroll_reference(db, payroll_reference)
+    if not record:
+        raise HTTPException(
+            status.HTTP_404_NOT_FOUND,
+            detail=f"Timesheet with payroll reference '{payroll_reference}' not found",
+        )
+    return record
+
+
+@router.get("/by-approval/{approved}", response_model=list[TimeSheetResponse])
+async def list_timesheets_by_approval(
+    approved: bool,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(get_current_user),
+):
+    return await crud.get_by_approval(db, approved)
+
+
+@router.get("/{timesheet_id}", response_model=TimeSheetResponse)
+async def get_timesheet(
+    timesheet_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(get_current_user),
+):
+    record = await crud.get_by_id(db, timesheet_id)
+    if not record:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"Timesheet '{timesheet_id}' not found")
+    return record
+
+
+@router.post("/", response_model=TimeSheetResponse, status_code=status.HTTP_201_CREATED)
+async def create_timesheet(
+    data: TimeSheetCreate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-create-shifts")),
+):
+    timesheet_id = str(data.id)
+    if await crud.get_by_id(db, timesheet_id):
+        raise HTTPException(status.HTTP_409_CONFLICT, detail=f"Timesheet '{timesheet_id}' already exists")
+    if data.payroll_reference and await crud.get_by_payroll_reference(db, data.payroll_reference):
+        raise HTTPException(
+            status.HTTP_409_CONFLICT,
+            detail=f"Timesheet with payroll reference '{data.payroll_reference}' already exists",
+        )
+    return await crud.create(db, data)
+
+
+@router.patch("/{timesheet_id}", response_model=TimeSheetResponse)
+async def update_timesheet(
+    timesheet_id: str,
+    data: TimeSheetUpdate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-update-shifts")),
+):
+    if data.payroll_reference:
+        existing = await crud.get_by_payroll_reference(db, data.payroll_reference)
+        if existing and existing.get("id") != timesheet_id:
+            raise HTTPException(
+                status.HTTP_409_CONFLICT,
+                detail=f"Timesheet with payroll reference '{data.payroll_reference}' already exists",
+            )
+    updated = await crud.update(db, timesheet_id, data)
+    if not updated:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"Timesheet '{timesheet_id}' not found")
+    return updated
+
+
+@router.delete("/{timesheet_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_timesheet(
+    timesheet_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-delete-shifts")),
+):
+    if not await crud.delete(db, timesheet_id):
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"Timesheet '{timesheet_id}' not found")

services/shipping/helpers/__init__.py

@@ -0,0 +1,15 @@
+"""shipping service helpers package."""
+
+__all__ = [
+    "carrier",
+    "customs_declaration",
+    "delivery_note",
+    "package",
+    "pallet",
+    "route",
+    "shipping_information",
+    "shipping_provider_details",
+    "shipping_provider_metadata",
+    "vehicle",
+    "waybill",
+]

services/shipping/helpers/carrier.py

@@ -0,0 +1,78 @@
+from datetime import date, datetime, timezone
+from typing import Optional
+from uuid import UUID
+
+from motor.motor_asyncio import AsyncIOMotorDatabase
+from pymongo import ReturnDocument
+
+from services.shipping.models.carrier import CarrierCreate, CarrierUpdate, utc_now
+
+COLLECTION = "carriers"
+
+
+def _serialize(doc: Optional[dict]) -> Optional[dict]:
+    if not doc:
+        return None
+    doc = dict(doc)
+    doc.pop("_id", None)
+    return doc
+
+
+def _prepare(value):
+    if isinstance(value, UUID):
+        return str(value)
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            return value.replace(tzinfo=timezone.utc)
+        return value.astimezone(timezone.utc)
+    if isinstance(value, date):
+        return datetime(value.year, value.month, value.day, tzinfo=timezone.utc)
+    if isinstance(value, dict):
+        return {key: _prepare(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_prepare(item) for item in value]
+    return value
+
+
+async def get_all(db: AsyncIOMotorDatabase, page: int = 1, page_size: int = 20) -> tuple[list[dict], int]:
+    query: dict = {}
+    total = await db[COLLECTION].count_documents(query)
+    cursor = db[COLLECTION].find(query).skip((page - 1) * page_size).limit(page_size)
+    return [_serialize(doc) async for doc in cursor], total
+
+
+async def get_by_id(db: AsyncIOMotorDatabase, carrier_id: str) -> Optional[dict]:
+    return _serialize(await db[COLLECTION].find_one({"id": carrier_id}))
+
+
+async def get_by_code(db: AsyncIOMotorDatabase, code: str) -> Optional[dict]:
+    return _serialize(await db[COLLECTION].find_one({"code": code}))
+
+
+async def get_by_name(db: AsyncIOMotorDatabase, name: str) -> list[dict]:
+    cursor = db[COLLECTION].find({"name": {"$regex": name, "$options": "i"}})
+    return [_serialize(doc) async for doc in cursor]
+
+
+async def create(db: AsyncIOMotorDatabase, data: CarrierCreate) -> dict:
+    doc = _prepare(data.model_dump(mode="python"))
+    await db[COLLECTION].insert_one(doc)
+    return _serialize(doc)
+
+
+async def update(db: AsyncIOMotorDatabase, carrier_id: str, data: CarrierUpdate) -> Optional[dict]:
+    fields = _prepare(data.model_dump(mode="python", exclude_unset=True))
+    if not fields:
+        return await get_by_id(db, carrier_id)
+    fields["updated_at"] = utc_now()
+    result = await db[COLLECTION].find_one_and_update(
+        {"id": carrier_id},
+        {"$set": fields},
+        return_document=ReturnDocument.AFTER,
+    )
+    return _serialize(result)
+
+
+async def delete(db: AsyncIOMotorDatabase, carrier_id: str) -> bool:
+    result = await db[COLLECTION].delete_one({"id": carrier_id})
+    return result.deleted_count == 1