monkeybrain-runtime 1.0.0__py3-none-any.whl

services/pm/routers/maintainance.py

@@ -0,0 +1,241 @@
+from typing import Optional
+from fastapi import APIRouter, HTTPException, Depends, Query, status
+from motor.motor_asyncio import AsyncIOMotorDatabase
+from services.common.db import get_database
+from services.common.auth import require_permission
+from services.pm.models.maintainanceLog import (
+    MaintenanceLogCreate,
+    MaintenanceLogUpdate,
+    MaintenanceLogResponse,
+    PaginatedMaintenanceLogResponse,
+)
+from services.pm.helpers import maintainance as crud
+from services.common.config import settings
+import json
+from urllib.request import Request, urlopen
+from urllib.parse import urlencode
+
+router = APIRouter()
+
+
+def _query_influx_maintenance() -> list[dict]:
+    """Query maintenance records from InfluxDB."""
+    query = (
+        "SELECT * FROM maintenance_log "
+        "WHERE time >= now() - INTERVAL '365 days' "
+        "ORDER BY time DESC "
+        "LIMIT 500"
+    )
+    params = urlencode({"db": settings.INFLUXDB_BUCKET, "q": query})
+    url = f"{settings.INFLUXDB_URL.rstrip('/')}/api/v3/query_sql?{params}"
+    headers = {"Content-Type": "application/json"}
+    if settings.INFLUXDB_TOKEN:
+        headers["Authorization"] = f"Bearer {settings.INFLUXDB_TOKEN}"
+    request = Request(url, headers=headers, method="GET")
+    try:
+        with urlopen(request, timeout=10) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except Exception:
+        return []
+
+
+def _influx_to_maintenance_log(row: dict) -> dict:
+    """Convert InfluxDB row to maintenance log format."""
+    payload_str = row.get("payload_json", "{}")
+    try:
+        payload = json.loads(payload_str) if payload_str else {}
+    except json.JSONDecodeError:
+        payload = {}
+
+    # Use tags if available, fall back to payload
+    maint_type = row.get("maintenance_type") or payload.get("maintenance_type", "Preventive")
+    status_val = row.get("log_status") or row.get("status") or payload.get("status", "Scheduled")
+    severity = row.get("severity") or payload.get("severity", "Medium")
+    machine_name = row.get("equipment_name") or payload.get("machine_name", "")
+    machine_id = row.get("machine_id") or payload.get("machine_id", "")
+    equipment_id = row.get("equipment_id") or payload.get("id", row.get("equipment_id", ""))
+    performed = row.get("performed_by") or payload.get("performed_by", "")
+    resolution = payload.get("resolution", "Completed per procedure" if status_val == "Completed" else None)
+
+    # Compute next_due_date
+    interval = payload.get("maintenance_interval_days")
+    actual_start = row.get("time", payload.get("actual_start", ""))[:10] if row.get("time", payload.get("actual_start", "")) else None
+    next_due = None
+    if actual_start and interval:
+        from datetime import datetime as dt, timedelta
+        try:
+            p_date = dt.strptime(actual_start, "%Y-%m-%d")
+            next_due = (p_date + timedelta(days=int(interval))).strftime("%Y-%m-%d")
+        except (ValueError, TypeError):
+            pass
+
+    return {
+        "id": equipment_id,
+        "machine_id": machine_id,
+        "equipment_id": equipment_id,
+        "machine_name": machine_name,
+        "maintenance_type": maint_type,
+        "status": status_val,
+        "severity": severity,
+        "description": payload.get("description", ""),
+        "issue_reported": payload.get("issue_reported"),
+        "resolution": resolution,
+        "scheduled_start": row.get("scheduled_start", payload.get("scheduled_start")),
+        "scheduled_end": row.get("scheduled_end", payload.get("scheduled_end")),
+        "actual_start": actual_start,
+        "actual_end": row.get("actual_end", payload.get("actual_end", ""))[:10] if row.get("actual_end", payload.get("actual_end", "")) else None,
+        "next_due_date": next_due,
+        "maintenance_interval_days": interval,
+        "performed_by": performed,
+        "reviewed_by": payload.get("reviewed_by"),
+        "approved_by": None,
+        "downtime": {"start_time": actual_start, "end_time": row.get("actual_end", "")[:10] if row.get("actual_end") else None} if actual_start and status_val in ("Completed", "In Progress") else None,
+        "parts_used": payload.get("parts_used", []),
+        "work_order_id": payload.get("work_order_id"),
+        "created_at": row.get("time", ""),
+        "updated_at": row.get("time", ""),
+    }
+
+
+# ── List ──────────────────────────────────────────────────────────────────────
+
+@router.get("/", response_model=PaginatedMaintenanceLogResponse)
+async def list_logs(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100),
+    machine_id: Optional[str] = Query(None, description="Filter by machine ID"),
+    status: Optional[str] = Query(None, description="Scheduled | In Progress | Completed | Cancelled | Delayed"),
+    maintenance_type: Optional[str] = Query(None, description="Preventive | Corrective | Predictive | Inspection"),
+    severity: Optional[str] = Query(None, description="Low | Medium | High | Critical"),
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-maintenance")),
+):
+    rows = _query_influx_maintenance()
+    logs = [_influx_to_maintenance_log(row) for row in rows]
+
+    # Enrich with expected_completion from linked work orders
+    wo_ids = list({l.get("work_order_id") for l in logs if l.get("work_order_id")})
+    if wo_ids:
+        wos = await db["work_orders"].find({"work_order_id": {"$in": wo_ids}}).to_list(100)
+        wo_map = {wo["work_order_id"]: wo for wo in wos}
+        for log in logs:
+            wo = wo_map.get(log.get("work_order_id"))
+            if wo and wo.get("expected_completion"):
+                log["next_due_date"] = wo["expected_completion"].strftime("%Y-%m-%d") if hasattr(wo["expected_completion"], "strftime") else str(wo["expected_completion"])[:10]
+
+    # Apply filters
+    if machine_id:
+        logs = [l for l in logs if l.get("machine_id") == machine_id]
+    if status:
+        logs = [l for l in logs if l.get("status") == status]
+    if maintenance_type:
+        logs = [l for l in logs if l.get("maintenance_type") == maintenance_type]
+    if severity:
+        logs = [l for l in logs if l.get("severity") == severity]
+    total = len(logs)
+    start = (page - 1) * page_size
+    page_logs = logs[start:start + page_size]
+    return PaginatedMaintenanceLogResponse(
+        total=total, page=page, page_size=page_size, results=page_logs
+    )
+
+
+# ── Get by machine ────────────────────────────────────────────────────────────
+
+@router.get("/by-machine/{machine_id}", response_model=list[MaintenanceLogResponse])
+async def list_logs_by_machine(
+    machine_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-maintenance")),
+):
+    rows = _query_influx_maintenance()
+    logs = [_influx_to_maintenance_log(row) for row in rows if row.get("machine_id") == machine_id]
+    return logs
+    return await crud.get_by_machine(db, machine_id)
+
+@router.get("/by-equipment/{equipment_id}", response_model=list[MaintenanceLogResponse])
+async def list_logs_by_machine(
+    equipment_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-maintenance")),
+):
+    return await crud.get_by_equipment_id(db, equipment_id)
+
+# ── Get open logs ─────────────────────────────────────────────────────────────
+
+@router.get("/open", response_model=list[MaintenanceLogResponse])
+async def list_open_logs(
+    machine_id: Optional[str] = Query(None, description="Optionally scope to a specific machine"),
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-maintenance")),
+):
+    return await crud.get_open(db, machine_id=machine_id)
+
+
+# ── Get one ───────────────────────────────────────────────────────────────────
+
+@router.get("/{log_id}", response_model=MaintenanceLogResponse)
+async def get_log(
+    log_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-maintenance")),
+):
+    record = await crud.get_by_id(db, log_id)
+    if not record:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"MaintenanceLog '{log_id}' not found",
+        )
+    return record
+
+
+# ── Create ────────────────────────────────────────────────────────────────────
+
+@router.post("/", response_model=MaintenanceLogResponse, status_code=status.HTTP_201_CREATED)
+async def create_log(
+    data: MaintenanceLogCreate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-create-maintenance")),
+):
+    if await crud.get_by_id(db, data.id):
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"MaintenanceLog '{data.id}' already exists",
+        )
+    return await crud.create(db, data)
+
+
+# ── Update ────────────────────────────────────────────────────────────────────
+
+@router.patch("/{log_id}", response_model=MaintenanceLogResponse)
+async def update_log(
+    log_id: str,
+    data: MaintenanceLogUpdate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-update-maintenance")),
+):
+    updated = await crud.update(db, log_id, data)
+    if not updated:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"MaintenanceLog '{log_id}' not found",
+        )
+    return updated
+
+
+# ── Delete ────────────────────────────────────────────────────────────────────
+
+@router.delete("/{log_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_log(
+    log_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-delete-maintenance")),
+):
+    if not await crud.delete(db, log_id):
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"MaintenanceLog '{log_id}' not found",
+        )
+
+# TODO: GET /api/v1/maintenance/{log_id}/parts — list all parts used in a specific log
+# TODO: GET /api/v1/maintenance/{log_id}/technicians — list all technicians assigned to a log

services/pm/routers/sop.py

@@ -0,0 +1,437 @@
+from fastapi import APIRouter, HTTPException, Depends, Query, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from motor.motor_asyncio import AsyncIOMotorDatabase
+from jose import JWTError
+
+from services.common.auth import permission_ids
+from services.common.db import get_database
+from services.auth.helpers.tokens import decode_access_token
+from services.pm.models.sop import (
+    SOPCreate,
+    SOPUpdate,
+    SOPResponse,
+    PaginatedSOPResponse,
+    SOPChangeImpactRequest,
+    SOPChangeImpactResponse,
+)
+from services.pm.helpers import sop as crud
+from services.pm.helpers.sop_cdc import sync_sop_to_process_definition
+from services.process_definitions.models.process_definition import (
+    ProcessDefinitionCanvasFlowSimulationRequest,
+    ProcessDefinitionCanvasFlowSimulationResponse,
+)
+from services.process_definitions.node_services.flow_simulator import simulate_sop_flow
+
+router = APIRouter()
+
+bearer_scheme = HTTPBearer()
+
+
+# ── Auth helpers ──────────────────────────────────────────────────────────────
+
+def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Depends(bearer_scheme),
+) -> dict:
+    try:
+        return decode_access_token(credentials.credentials)
+    except JWTError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid or expired token",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+
+def require_permission(required: str):
+    def _check(current_user: dict = Depends(get_current_user)):
+        granted = permission_ids(current_user)
+        if required not in granted:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Permission '{required}' required",
+            )
+        return current_user
+    return _check
+
+
+# ── List (paginated) ──────────────────────────────────────────────────────────
+
+@router.get("/", response_model=PaginatedSOPResponse)
+async def list_sops(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1),
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-sops")),
+):
+    """Return a paginated list of all SOPs."""
+    sops, total = await crud.get_all(db, page=page, page_size=page_size)
+    return PaginatedSOPResponse(
+        total=total,
+        page=page,
+        page_size=page_size,
+        results=sops,
+    )
+
+
+# ── Filtered list endpoints ───────────────────────────────────────────────────
+
+@router.get("/by-author/{authored_by}", response_model=list[SOPResponse])
+async def list_sops_by_author(
+    authored_by: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-sops")),
+):
+    """Return all SOPs created by the given author."""
+    return await crud.get_by_author(db, authored_by)
+
+
+@router.get("/by-approver/{approved_by}", response_model=list[SOPResponse])
+async def list_sops_by_approver(
+    approved_by: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-sops")),
+):
+    """Return all SOPs approved by the given approver."""
+    return await crud.get_by_approver(db, approved_by)
+
+
+@router.get("/by-tag/{tag}", response_model=list[SOPResponse])
+async def list_sops_by_tag(
+    tag: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-sops")),
+):
+    """Return all SOPs that carry the given tag."""
+    return await crud.get_by_tag(db, tag)
+
+
+@router.get("/by-version/{version}", response_model=PaginatedSOPResponse)
+async def list_sops_by_version(
+    version: str,
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1),
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-sops")),
+):
+    """Return a paginated list of SOPs matching the given version string."""
+    sops, total = await crud.get_by_version(db, version, page=page, page_size=page_size)
+    return PaginatedSOPResponse(
+        total=total,
+        page=page,
+        page_size=page_size,
+        results=sops,
+    )
+
+
+@router.get("/by-process_definition/{process_definition_id}", response_model=SOPResponse)
+async def get_sop_by_process_definition(
+    process_definition_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-sops")),
+):
+    """Fetch the SOP that wraps the given process_definition_id."""
+    record = await crud.get_by_process_definition_id(db, process_definition_id)
+    if not record:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"No SOP found for process_definition '{process_definition_id}'",
+        )
+    return record
+
+
+@router.get("/search", response_model=list[SOPResponse])
+async def search_sops(
+    q: str = Query(..., min_length=1),
+    limit: int = Query(20, ge=1, le=100),
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-sops")),
+):
+    """Search SOP nodes by free text across SOP and embedded process sections."""
+    return await crud.search(db, q, limit=limit)
+
+
+@router.post("/{sop_id}/change-impact", response_model=SOPChangeImpactResponse)
+async def analyze_sop_change_impact(
+    sop_id: str,
+    data: SOPChangeImpactRequest,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    current_user: dict = Depends(require_permission("perm-update-sops")),
+):
+    """
+    Analyze a proposed SOP update against production connections/material flow.
+
+    The response contains the linked SOP graph and proposed changes. When
+    create_change_control is true, those changes are staged as proposed nodes
+    and only apply after the normal change-control approval flow.
+    """
+    impact = await crud.analyze_sop_change_impact(
+        db,
+        sop_id,
+        data.proposed_values,
+        change_reason=data.change_reason,
+        include_upstream=data.include_upstream,
+        include_downstream=data.include_downstream,
+        max_depth=data.max_depth,
+    )
+    if not impact:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"SOP '{sop_id}' not found",
+        )
+
+    change_control = None
+    if data.create_change_control:
+        change_control = await crud.create_sop_change_control(
+            db,
+            impact,
+            current_user=current_user,
+            change_type=data.change_type,
+            risk_score=data.risk_score,
+            approval_chain=data.approval_chain,
+        )
+    return SOPChangeImpactResponse(**impact, change_control=change_control)
+
+
+# ── Single record ─────────────────────────────────────────────────────────────
+
+@router.get("/{sop_id}", response_model=SOPResponse)
+async def get_sop(
+    sop_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-sops")),
+):
+    """Fetch a single SOP by its unique id."""
+    record = await crud.get_by_id(db, sop_id)
+    if not record:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"SOP '{sop_id}' not found",
+        )
+    return record
+
+
+# ── Create ────────────────────────────────────────────────────────────────────
+
+@router.post("/", response_model=SOPResponse, status_code=status.HTTP_201_CREATED)
+async def create_sop(
+    data: SOPCreate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-create-sops")),
+):
+    """Register a new SOP. Returns 409 if the SOP id already exists."""
+    if await crud.get_by_id(db, data.id):
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"SOP '{data.id}' already exists",
+        )
+    result = await crud.create(db, data)
+    try:
+        await sync_sop_to_process_definition(db, result)
+    except Exception:
+        pass
+    return result
+
+
+# ── Update ────────────────────────────────────────────────────────────────────
+
+@router.patch("/{sop_id}", response_model=SOPResponse)
+async def update_sop(
+    sop_id: str,
+    data: SOPUpdate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-update-sops")),
+):
+    """Partially update a SOP's fields. Returns 404 if the SOP does not exist."""
+    updated = await crud.update(db, sop_id, data)
+    if not updated:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"SOP '{sop_id}' not found",
+        )
+    try:
+        await sync_sop_to_process_definition(db, updated)
+    except Exception:
+        pass
+    return updated
+
+
+@router.patch("/{sop_id}/process_definition", response_model=SOPResponse)
+async def update_sop_process_definition(
+    sop_id: str,
+    process_definition: dict,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-update-sops")),
+):
+    """Replace the embedded process_definition sub-document of a SOP."""
+    updated = await crud.update_process_definition(db, sop_id, process_definition)
+    if not updated:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"SOP '{sop_id}' not found",
+        )
+    try:
+        await sync_sop_to_process_definition(db, updated)
+    except Exception:
+        pass
+    return updated
+
+
+@router.patch("/{sop_id}/prechecks", response_model=SOPResponse)
+async def update_sop_prechecks(
+    sop_id: str,
+    prechecks: dict,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-update-sops")),
+):
+    """Replace the embedded prechecks sub-document of a SOP."""
+    updated = await crud.update_prechecks(db, sop_id, prechecks)
+    if not updated:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"SOP '{sop_id}' not found",
+        )
+    try:
+        await sync_sop_to_process_definition(db, updated)
+    except Exception:
+        pass
+    return updated
+
+
+@router.patch("/{sop_id}/postchecks", response_model=SOPResponse)
+async def update_sop_postchecks(
+    sop_id: str,
+    postchecks: dict,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-update-sops")),
+):
+    """Replace the embedded postchecks sub-document of a SOP."""
+    updated = await crud.update_postchecks(db, sop_id, postchecks)
+    if not updated:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"SOP '{sop_id}' not found",
+        )
+    try:
+        await sync_sop_to_process_definition(db, updated)
+    except Exception:
+        pass
+    return updated
+
+
+@router.patch("/{sop_id}/constraints", response_model=SOPResponse)
+async def update_sop_constraints(
+    sop_id: str,
+    constraints: dict,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-update-sops")),
+):
+    """Replace the embedded constraints sub-document of a SOP."""
+    updated = await crud.update_constraints(db, sop_id, constraints)
+    if not updated:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"SOP '{sop_id}' not found",
+        )
+    try:
+        await sync_sop_to_process_definition(db, updated)
+    except Exception:
+        pass
+    return updated
+
+
+@router.patch("/{sop_id}/corrective-actions", response_model=SOPResponse)
+async def update_sop_corrective_actions(
+    sop_id: str,
+    corrective_actions: dict,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-update-sops")),
+):
+    """Replace the embedded corrective_actions sub-document of a SOP."""
+    updated = await crud.update_corrective_actions(db, sop_id, corrective_actions)
+    if not updated:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"SOP '{sop_id}' not found",
+        )
+    try:
+        await sync_sop_to_process_definition(db, updated)
+    except Exception:
+        pass
+    return updated
+
+
+@router.post("/{sop_id}/simulate", response_model=ProcessDefinitionCanvasFlowSimulationResponse)
+async def simulate_sop_process_flow(
+    sop_id: str,
+    data: ProcessDefinitionCanvasFlowSimulationRequest,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-sops")),
+):
+    """Compile a SOP's process sections into a transient canvas and simulate it."""
+    record = await crud.get_by_id(db, sop_id)
+    if not record:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"SOP '{sop_id}' not found",
+        )
+    result = await simulate_sop_flow(
+        db=db,
+        sop=record,
+        payload=data.payload,
+        start_node_id=data.start_node_id,
+        max_steps=data.max_steps,
+        persist_trace=data.persist_trace,
+    )
+    return ProcessDefinitionCanvasFlowSimulationResponse(**result)
+
+
+# ── References ────────────────────────────────────────────────────────────────
+
+@router.post("/{sop_id}/references", response_model=SOPResponse)
+async def add_sop_reference(
+    sop_id: str,
+    reference: str = Query(...),
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-update-sops")),
+):
+    """Append a reference URL/document to the SOP's references array (no duplicates)."""
+    updated = await crud.add_reference(db, sop_id, reference)
+    if not updated:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"SOP '{sop_id}' not found",
+        )
+    return updated
+
+
+@router.delete("/{sop_id}/references", response_model=SOPResponse)
+async def remove_sop_reference(
+    sop_id: str,
+    reference: str = Query(...),
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-update-sops")),
+):
+    """Remove a specific reference from the SOP's references array."""
+    updated = await crud.remove_reference(db, sop_id, reference)
+    if not updated:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"SOP '{sop_id}' not found",
+        )
+    return updated
+
+
+# ── Delete ────────────────────────────────────────────────────────────────────
+
+@router.delete("/{sop_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_sop(
+    sop_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-delete-sops")),
+):
+    """Permanently remove a SOP record. Returns 404 if the SOP does not exist."""
+    if not await crud.delete(db, sop_id):
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"SOP '{sop_id}' not found",
+        )