agentic-dev 0.1.0 → 0.2.1

package/server/contexts/fulfillment/infrastructure/repository.py

@@ -0,0 +1,97 @@
+from datetime import datetime
+
+from contexts.fulfillment.domain import (
+    FulfillmentEvent,
+    FulfillmentNote,
+    FulfillmentTaskRecord,
+    FulfillmentTaskStatusTransition,
+    FulfillmentTaskStatusTransitionCommand,
+)
+from data.bootstrap_loader import load_bootstrap_json
+
+_task_store: list[FulfillmentTaskRecord] | None = None
+_event_store: list[FulfillmentEvent] | None = None
+_note_store: list[FulfillmentNote] | None = None
+
+
+def _get_task_store() -> list[FulfillmentTaskRecord]:
+    global _task_store
+    if _task_store is None:
+        _task_store = [
+            FulfillmentTaskRecord(**entry)
+            for entry in load_bootstrap_json("fulfillment_tasks.json")
+        ]
+    return _task_store
+
+
+def _get_event_store() -> list[FulfillmentEvent]:
+    global _event_store
+    if _event_store is None:
+        _event_store = [
+            FulfillmentEvent(**entry)
+            for entry in load_bootstrap_json("fulfillment_events.json")
+        ]
+    return _event_store
+
+
+def _get_note_store() -> list[FulfillmentNote]:
+    global _note_store
+    if _note_store is None:
+        _note_store = [
+            FulfillmentNote(**entry)
+            for entry in load_bootstrap_json("fulfillment_notes.json")
+        ]
+    return _note_store
+
+
+def list_seed_fulfillment_tasks() -> list[FulfillmentTaskRecord]:
+    return [task.model_copy(deep=True) for task in _get_task_store()]
+
+
+def list_seed_fulfillment_events() -> list[FulfillmentEvent]:
+    return [event.model_copy(deep=True) for event in _get_event_store()]
+
+
+def list_seed_fulfillment_notes() -> list[FulfillmentNote]:
+    return [note.model_copy(deep=True) for note in _get_note_store()]
+
+
+def transition_seed_fulfillment_task_status(
+    task_id: str, command: FulfillmentTaskStatusTransitionCommand
+) -> FulfillmentTaskStatusTransition:
+    tasks = _get_task_store()
+    for index, task in enumerate(tasks):
+        if task.id != task_id:
+            continue
+
+        updated_task = task.model_copy(
+            update={"status": command.status, "stage": command.stage or task.stage}
+        )
+        tasks[index] = updated_task
+        _get_event_store().insert(
+            0,
+            FulfillmentEvent(
+                time=datetime.now().strftime("%H:%M"),
+                title=f"{updated_task.order_id} {updated_task.title} -> {updated_task.status}",
+                tone=_map_event_tone(updated_task.status),
+            ),
+        )
+        return FulfillmentTaskStatusTransition(
+            task_id=updated_task.id,
+            previous_status=task.status,
+            status=updated_task.status,
+            previous_stage=task.stage,
+            stage=updated_task.stage,
+        )
+
+    raise LookupError(f"Fulfillment task {task_id} not found")
+
+
+def _map_event_tone(status: str) -> str:
+    tone_map = {
+        "Queued": "accent",
+        "In progress": "warning",
+        "Blocked": "warning",
+        "Completed": "success",
+    }
+    return tone_map.get(status, "neutral")

package/server/contexts/health/__init__.py

@@ -0,0 +1 @@
+__all__ = ["application", "presentation"]

package/server/contexts/health/application/__init__.py

@@ -0,0 +1,3 @@
+from .services import get_status_payload
+
+__all__ = ["get_status_payload"]

package/server/contexts/health/application/services.py

@@ -0,0 +1,2 @@
+def get_status_payload() -> dict[str, str]:
+    return {"service": "template-server", "status": "healthy"}

package/server/contexts/health/contracts/__init__.py

@@ -0,0 +1,3 @@
+from .http.router import router
+
+__all__ = ["router"]

package/server/contexts/health/contracts/http/__init__.py

@@ -0,0 +1,3 @@
+from .router import router
+
+__all__ = ["router"]

package/server/contexts/health/contracts/http/router.py

@@ -0,0 +1,10 @@
+from fastapi import APIRouter
+
+from contexts.health.application import get_status_payload
+
+router = APIRouter(tags=["health"])
+
+
+@router.get("/status")
+def status() -> dict[str, str]:
+    return get_status_payload()

package/server/contexts/inventory/__init__.py

@@ -0,0 +1 @@
+__all__ = ["application", "contracts", "domain", "infrastructure"]

package/server/contexts/inventory/application/__init__.py

@@ -0,0 +1,28 @@
+from .services import (
+    adjust_inventory_level_or_404,
+    get_inventory_level_or_404,
+    list_inventory_levels,
+    prepare_inventory_store,
+    release_inventory_level_or_404,
+    reserve_inventory_or_404,
+    set_inventory_level_or_404,
+)
+
+adjust_inventory_level = adjust_inventory_level_or_404
+release_inventory_level = release_inventory_level_or_404
+reserve_inventory_level = reserve_inventory_or_404
+set_inventory_level = set_inventory_level_or_404
+
+__all__ = [
+    "adjust_inventory_level",
+    "adjust_inventory_level_or_404",
+    "get_inventory_level_or_404",
+    "list_inventory_levels",
+    "prepare_inventory_store",
+    "release_inventory_level",
+    "release_inventory_level_or_404",
+    "reserve_inventory_level",
+    "reserve_inventory_or_404",
+    "set_inventory_level",
+    "set_inventory_level_or_404",
+]

package/server/contexts/inventory/application/ports.py

@@ -0,0 +1,11 @@
+from typing import Protocol
+
+from contexts.inventory.domain import InventoryLevelRecord
+
+
+class InventoryRepository(Protocol):
+    def initialize(self) -> None: ...
+    def seed_levels(self, levels: list[InventoryLevelRecord]) -> None: ...
+    def list_levels(self) -> list[InventoryLevelRecord]: ...
+    def get_level(self, sku: str, location_id: str) -> InventoryLevelRecord | None: ...
+    def upsert_level(self, level: InventoryLevelRecord) -> InventoryLevelRecord: ...

package/server/contexts/inventory/application/services.py

@@ -0,0 +1,214 @@
+from datetime import datetime, timezone
+from functools import lru_cache
+
+from fastapi import HTTPException, status as http_status
+
+from contexts.inventory.domain import (
+    AdjustInventoryCommand,
+    InventoryAvailabilityStatus,
+    InventoryLevel,
+    InventoryLevelRecord,
+    InventoryMutationReceipt,
+    ReleaseInventoryCommand,
+    ReserveInventoryCommand,
+    SetInventoryLevelCommand,
+)
+from contexts.inventory.infrastructure import get_inventory_repository
+from data.bootstrap_loader import load_bootstrap_json
+
+
+def list_inventory_levels(
+    sku: str | None = None,
+    product_id: str | None = None,
+    location_id: str | None = None,
+    availability_status: InventoryAvailabilityStatus | None = None,
+) -> list[InventoryLevel]:
+    prepare_inventory_store()
+    repository = get_inventory_repository()
+    levels = repository.list_levels()
+
+    if sku is not None:
+        normalized_sku = sku.strip().casefold()
+        levels = [level for level in levels if level.sku.casefold() == normalized_sku]
+    if product_id is not None:
+        normalized_product_id = product_id.strip().casefold()
+        levels = [level for level in levels if level.product_id.casefold() == normalized_product_id]
+    if location_id is not None:
+        normalized_location_id = location_id.strip().casefold()
+        levels = [level for level in levels if level.location_id.casefold() == normalized_location_id]
+    if availability_status is not None:
+        levels = [level for level in levels if _availability_status(level) == availability_status]
+
+    return [_to_level(level) for level in levels]
+
+
+def get_inventory_level_or_404(sku: str, location_id: str) -> InventoryLevel:
+    prepare_inventory_store()
+    repository = get_inventory_repository()
+    level = repository.get_level(sku, location_id)
+    if level is None:
+        raise HTTPException(status_code=http_status.HTTP_404_NOT_FOUND, detail="Inventory level not found")
+    return _to_level(level)
+
+
+def adjust_inventory_level_or_404(
+    sku: str,
+    location_id: str,
+    command: AdjustInventoryCommand,
+) -> InventoryMutationReceipt:
+    prepare_inventory_store()
+    repository = get_inventory_repository()
+    level = repository.get_level(sku, location_id)
+    if level is None:
+        raise HTTPException(status_code=http_status.HTTP_404_NOT_FOUND, detail="Inventory level not found")
+    if command.quantity_delta == 0:
+        raise HTTPException(status_code=http_status.HTTP_400_BAD_REQUEST, detail="Adjustment delta must not be zero")
+
+    next_on_hand = level.on_hand + command.quantity_delta
+    if next_on_hand < level.reserved:
+        raise HTTPException(
+            status_code=http_status.HTTP_409_CONFLICT,
+            detail="Adjustment would reduce on-hand stock below reserved stock",
+        )
+
+    updated = level.model_copy(update={"on_hand": next_on_hand, "updated_at": _now_iso()})
+    repository.upsert_level(updated)
+    return InventoryMutationReceipt(
+        action="adjusted",
+        sku=updated.sku,
+        location_id=updated.location_id,
+        quantity=command.quantity_delta,
+        reference_id=command.reference_id,
+        reason=command.reason,
+        level=_to_level(updated),
+    )
+
+
+def reserve_inventory_or_404(
+    sku: str,
+    location_id: str,
+    command: ReserveInventoryCommand,
+) -> InventoryMutationReceipt:
+    prepare_inventory_store()
+    repository = get_inventory_repository()
+    level = repository.get_level(sku, location_id)
+    if level is None:
+        raise HTTPException(status_code=http_status.HTTP_404_NOT_FOUND, detail="Inventory level not found")
+    available_to_sell = level.on_hand - level.reserved
+    if command.quantity > available_to_sell:
+        raise HTTPException(status_code=http_status.HTTP_409_CONFLICT, detail="Not enough available stock to reserve")
+
+    updated = level.model_copy(update={"reserved": level.reserved + command.quantity, "updated_at": _now_iso()})
+    repository.upsert_level(updated)
+    return InventoryMutationReceipt(
+        action="reserved",
+        sku=updated.sku,
+        location_id=updated.location_id,
+        quantity=command.quantity,
+        reference_id=command.reference_id,
+        reason=command.channel,
+        level=_to_level(updated),
+    )
+
+
+def release_inventory_level_or_404(
+    sku: str,
+    location_id: str,
+    command: ReleaseInventoryCommand,
+) -> InventoryMutationReceipt:
+    prepare_inventory_store()
+    repository = get_inventory_repository()
+    level = repository.get_level(sku, location_id)
+    if level is None:
+        raise HTTPException(status_code=http_status.HTTP_404_NOT_FOUND, detail="Inventory level not found")
+    if command.quantity > level.reserved:
+        raise HTTPException(status_code=http_status.HTTP_409_CONFLICT, detail="Release quantity exceeds reserved stock")
+
+    updated = level.model_copy(update={"reserved": level.reserved - command.quantity, "updated_at": _now_iso()})
+    repository.upsert_level(updated)
+    return InventoryMutationReceipt(
+        action="released",
+        sku=updated.sku,
+        location_id=updated.location_id,
+        quantity=command.quantity,
+        reference_id=command.reference_id,
+        reason=command.reason,
+        level=_to_level(updated),
+    )
+
+
+def set_inventory_level_or_404(
+    sku: str,
+    location_id: str,
+    command: SetInventoryLevelCommand,
+) -> InventoryMutationReceipt:
+    prepare_inventory_store()
+    repository = get_inventory_repository()
+    current = repository.get_level(sku, location_id)
+    if current is None:
+        raise HTTPException(status_code=http_status.HTTP_404_NOT_FOUND, detail="Inventory level not found")
+
+    updated = current.model_copy(
+        update={
+            "on_hand": command.on_hand,
+            "reserved": command.reserved,
+            "safety_stock": command.safety_stock,
+            "reorder_point": command.reorder_point,
+            "updated_at": _now_iso(),
+        }
+    )
+    repository.upsert_level(updated)
+    return InventoryMutationReceipt(
+        action="set",
+        sku=updated.sku,
+        location_id=updated.location_id,
+        quantity=updated.on_hand - current.on_hand,
+        reference_id=command.reference_id,
+        reason=command.reason,
+        level=_to_level(updated),
+    )
+
+
+def prepare_inventory_store() -> None:
+    _seed_inventory_store()
+
+
+@lru_cache
+def _seed_inventory_store() -> None:
+    repository = get_inventory_repository()
+    repository.initialize()
+    levels = [InventoryLevelRecord(**entry) for entry in load_bootstrap_json("inventory_levels.json")]
+    repository.seed_levels(levels)
+
+
+def _to_level(level: InventoryLevelRecord) -> InventoryLevel:
+    available_to_sell = max(level.on_hand - level.reserved, 0)
+    return InventoryLevel(
+        sku=level.sku,
+        product_id=level.product_id,
+        product_name=level.product_name,
+        variant_name=level.variant_name,
+        location_id=level.location_id,
+        location_name=level.location_name,
+        on_hand=level.on_hand,
+        reserved=level.reserved,
+        available_to_sell=available_to_sell,
+        safety_stock=level.safety_stock,
+        reorder_point=level.reorder_point,
+        needs_reorder=available_to_sell <= level.reorder_point,
+        status=_availability_status(level),
+        updated_at=level.updated_at,
+    )
+
+
+def _availability_status(level: InventoryLevelRecord) -> InventoryAvailabilityStatus:
+    available_to_sell = max(level.on_hand - level.reserved, 0)
+    if available_to_sell == 0:
+        return "out_of_stock"
+    if available_to_sell <= level.reorder_point:
+        return "low_stock"
+    return "in_stock"
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()

package/server/contexts/inventory/contracts/__init__.py

@@ -0,0 +1,3 @@
+from .http.router import router
+
+__all__ = ["router"]

package/server/contexts/inventory/contracts/http/__init__.py

@@ -0,0 +1,3 @@
+from .router import router
+
+__all__ = ["router"]

package/server/contexts/inventory/contracts/http/router.py

@@ -0,0 +1,82 @@
+from fastapi import APIRouter, Depends, Query
+
+from contexts.auth.contracts.http.dependencies import require_admin_user
+from contexts.inventory.application import (
+    adjust_inventory_level_or_404,
+    get_inventory_level_or_404,
+    list_inventory_levels,
+    release_inventory_level_or_404,
+    reserve_inventory_or_404,
+    set_inventory_level_or_404,
+)
+from contexts.inventory.domain import (
+    AdjustInventoryCommand,
+    InventoryAvailabilityStatus,
+    InventoryLevel,
+    InventoryMutationReceipt,
+    ReleaseInventoryCommand,
+    ReserveInventoryCommand,
+    SetInventoryLevelCommand,
+)
+
+router = APIRouter(
+    prefix="/inventory",
+    tags=["inventory"],
+    dependencies=[Depends(require_admin_user)],
+)
+
+
+@router.get("/levels", response_model=list[InventoryLevel])
+def list_levels(
+    sku: str | None = Query(default=None),
+    product_id: str | None = Query(default=None),
+    location_id: str | None = Query(default=None),
+    status: InventoryAvailabilityStatus | None = Query(default=None),
+) -> list[InventoryLevel]:
+    return list_inventory_levels(
+        sku=sku,
+        product_id=product_id,
+        location_id=location_id,
+        availability_status=status,
+    )
+
+
+@router.get("/levels/{sku}/{location_id}", response_model=InventoryLevel)
+def get_level(sku: str, location_id: str) -> InventoryLevel:
+    return get_inventory_level_or_404(sku, location_id)
+
+
+@router.post("/levels/{sku}/{location_id}/adjustments", response_model=InventoryMutationReceipt)
+def post_adjustment(
+    sku: str,
+    location_id: str,
+    command: AdjustInventoryCommand,
+) -> InventoryMutationReceipt:
+    return adjust_inventory_level_or_404(sku, location_id, command)
+
+
+@router.post("/levels/{sku}/{location_id}/reservations", response_model=InventoryMutationReceipt)
+def post_reservation(
+    sku: str,
+    location_id: str,
+    command: ReserveInventoryCommand,
+) -> InventoryMutationReceipt:
+    return reserve_inventory_or_404(sku, location_id, command)
+
+
+@router.post("/levels/{sku}/{location_id}/releases", response_model=InventoryMutationReceipt)
+def post_release(
+    sku: str,
+    location_id: str,
+    command: ReleaseInventoryCommand,
+) -> InventoryMutationReceipt:
+    return release_inventory_level_or_404(sku, location_id, command)
+
+
+@router.put("/levels/{sku}/{location_id}", response_model=InventoryMutationReceipt)
+def put_level(
+    sku: str,
+    location_id: str,
+    command: SetInventoryLevelCommand,
+) -> InventoryMutationReceipt:
+    return set_inventory_level_or_404(sku, location_id, command)

package/server/contexts/inventory/domain/__init__.py

@@ -0,0 +1,33 @@
+from .models import (
+    AdjustInventoryCommand,
+    InventoryAdjustmentCommand,
+    InventoryAvailabilityStatus,
+    InventoryLevel,
+    InventoryLevelRecord,
+    InventoryLevelView,
+    InventoryMutationAction,
+    InventoryMutationReceipt,
+    InventoryReleaseCommand,
+    InventoryReservationCommand,
+    InventorySetLevelCommand,
+    ReleaseInventoryCommand,
+    ReserveInventoryCommand,
+    SetInventoryLevelCommand,
+)
+
+__all__ = [
+    "AdjustInventoryCommand",
+    "InventoryAdjustmentCommand",
+    "InventoryAvailabilityStatus",
+    "InventoryLevel",
+    "InventoryLevelRecord",
+    "InventoryLevelView",
+    "InventoryMutationAction",
+    "InventoryMutationReceipt",
+    "InventoryReleaseCommand",
+    "InventoryReservationCommand",
+    "InventorySetLevelCommand",
+    "ReleaseInventoryCommand",
+    "ReserveInventoryCommand",
+    "SetInventoryLevelCommand",
+]

package/server/contexts/inventory/domain/models.py

@@ -0,0 +1,93 @@
+from typing import Literal, TypeAlias
+
+from pydantic import BaseModel, Field, model_validator
+
+InventoryAvailabilityStatus = Literal["in_stock", "low_stock", "out_of_stock"]
+InventoryMutationAction = Literal["adjusted", "reserved", "released", "set"]
+
+
+class InventoryLevelRecord(BaseModel):
+    sku: str = Field(min_length=1)
+    product_id: str = Field(min_length=1)
+    product_name: str = Field(min_length=1)
+    variant_name: str = Field(min_length=1)
+    location_id: str = Field(min_length=1)
+    location_name: str = Field(min_length=1)
+    on_hand: int = Field(ge=0)
+    reserved: int = Field(ge=0)
+    safety_stock: int = Field(ge=0)
+    reorder_point: int = Field(ge=0)
+    updated_at: str
+
+    @model_validator(mode="after")
+    def validate_stock_levels(self) -> "InventoryLevelRecord":
+        if self.reserved > self.on_hand:
+            raise ValueError("reserved stock cannot exceed on-hand stock")
+        return self
+
+
+class InventoryLevelView(BaseModel):
+    sku: str
+    product_id: str
+    product_name: str
+    variant_name: str
+    location_id: str
+    location_name: str
+    on_hand: int
+    reserved: int
+    available_to_sell: int
+    safety_stock: int
+    reorder_point: int
+    needs_reorder: bool
+    status: InventoryAvailabilityStatus
+    updated_at: str
+
+
+class AdjustInventoryCommand(BaseModel):
+    quantity_delta: int
+    reason: str = Field(min_length=1)
+    reference_id: str | None = Field(default=None, min_length=1)
+
+
+class ReserveInventoryCommand(BaseModel):
+    quantity: int = Field(gt=0)
+    reference_id: str = Field(min_length=1)
+    channel: str | None = Field(default=None, min_length=1)
+
+
+class ReleaseInventoryCommand(BaseModel):
+    quantity: int = Field(gt=0)
+    reference_id: str = Field(min_length=1)
+    reason: str | None = Field(default=None, min_length=1)
+
+
+class SetInventoryLevelCommand(BaseModel):
+    on_hand: int = Field(ge=0)
+    reserved: int = Field(ge=0)
+    safety_stock: int = Field(ge=0)
+    reorder_point: int = Field(ge=0)
+    reason: str | None = Field(default=None, min_length=1)
+    reference_id: str | None = Field(default=None, min_length=1)
+
+    @model_validator(mode="after")
+    def validate_stock_levels(self) -> "SetInventoryLevelCommand":
+        if self.reserved > self.on_hand:
+            raise ValueError("reserved stock cannot exceed on-hand stock")
+        return self
+
+
+class InventoryMutationReceipt(BaseModel):
+    action: InventoryMutationAction
+    sku: str
+    location_id: str
+    quantity: int
+    reference_id: str | None = None
+    reason: str | None = None
+    level: InventoryLevelView
+
+
+InventoryLevel = InventoryLevelView
+InventoryAdjustmentCommand: TypeAlias = AdjustInventoryCommand
+InventoryReservationCommand: TypeAlias = ReserveInventoryCommand
+InventoryReleaseCommand: TypeAlias = ReleaseInventoryCommand
+InventorySetLevelCommand: TypeAlias = SetInventoryLevelCommand

package/server/contexts/inventory/infrastructure/__init__.py

@@ -0,0 +1,4 @@
+from .adapters.memory import MemoryInventoryRepository
+from .repository import get_inventory_repository
+
+__all__ = ["MemoryInventoryRepository", "get_inventory_repository"]

package/server/contexts/inventory/infrastructure/adapters/memory.py

@@ -0,0 +1,24 @@
+from contexts.inventory.domain import InventoryLevelRecord
+
+
+class MemoryInventoryRepository:
+    def __init__(self) -> None:
+        self._levels: dict[tuple[str, str], InventoryLevelRecord] = {}
+
+    def initialize(self) -> None:
+        return None
+
+    def seed_levels(self, levels: list[InventoryLevelRecord]) -> None:
+        for level in levels:
+            self._levels[(level.sku, level.location_id)] = level.model_copy(deep=True)
+
+    def list_levels(self) -> list[InventoryLevelRecord]:
+        return [level.model_copy(deep=True) for level in self._levels.values()]
+
+    def get_level(self, sku: str, location_id: str) -> InventoryLevelRecord | None:
+        level = self._levels.get((sku, location_id))
+        return level.model_copy(deep=True) if level is not None else None
+
+    def upsert_level(self, level: InventoryLevelRecord) -> InventoryLevelRecord:
+        self._levels[(level.sku, level.location_id)] = level.model_copy(deep=True)
+        return level.model_copy(deep=True)

package/server/contexts/inventory/infrastructure/repository.py

@@ -0,0 +1,8 @@
+from functools import lru_cache
+
+from contexts.inventory.infrastructure.adapters.memory import MemoryInventoryRepository
+
+
+@lru_cache
+def get_inventory_repository() -> MemoryInventoryRepository:
+    return MemoryInventoryRepository()

package/server/contexts/orders/__init__.py

@@ -0,0 +1 @@
+__all__ = ["application", "contracts", "domain", "infrastructure"]

package/server/contexts/orders/application/__init__.py

@@ -0,0 +1,19 @@
+from .services import (
+    create_order,
+    get_admin_order_overview,
+    get_admin_queue,
+    get_order_list,
+    get_order_overview,
+    prepare_order_store,
+    update_order_status,
+)
+
+__all__ = [
+    "create_order",
+    "get_admin_order_overview",
+    "get_admin_queue",
+    "get_order_list",
+    "get_order_overview",
+    "prepare_order_store",
+    "update_order_status",
+]