Jul 30 - Update backend for iPad - inspector can re-inspect and create follow-up

app/api/inspections.py

@@ -421,6 +421,19 @@ def create_inspection():
         sched = _resolve_schedule(data['scheduled_inspection_id'], user)
         scheduled_inspection_id = sched.id if sched else None
 
+        # phase45 — inherit the follow-up link from the schedule when the
+        # client did not send one. A schedule created by "Schedule Follow-up"
+        # knows which inspection it answers, so the link should not depend on
+        # the client remembering to pass it: an older build, or a draft resumed
+        # after the cached row was refreshed, would otherwise submit a plain
+        # inspection and leave the parent flagged forever. Never overrides an
+        # explicit parent_inspection_id.
+        if not parent_inspection_id and sched and sched.parent_inspection_id:
+            parent_inspection_id = sched.parent_inspection_id
+            logger.info('API INSPECTIONS | parent inherited from schedule | '
+                        'schedule=%s | parent=%s | user=%s',
+                        sched.id, parent_inspection_id, user.username)
+
     # ── Score calculation ─────────────────────────────────────────────────
     overall_score = data.get('overall_score')
     if overall_score is None and status == 'completed':

app/api/scheduled.py

@@ -17,12 +17,16 @@ app/models/scheduled_inspection.py for the full lifecycle.
 """
 
 import logging
+from datetime import datetime
 
 from flask import Blueprint, request, g
+from app import db
 from app.models.scheduled_inspection import ScheduledInspection
+from app.models.inspection import Inspection
 from app.api.errors import api_ok, api_error
 from app.api.decorators import jwt_required
 from app.utils.scope import get_inspector_scope
+from app.utils.time_utils import now_eastern
 
 logger = logging.getLogger(__name__)
 
@@ -56,6 +60,11 @@ def _scheduled_payload(s):
         'end_date':        s.end_date.isoformat() if s.end_date else None,
         'is_overdue':      s.is_overdue(),
         'notes':           s.notes or None,
+        # phase45. Set when this schedule is a planned follow-up of a specific
+        # inspection; the iPad carries it onto the inspection it starts so the
+        # run lands as a linked re-inspection. Additive — older builds decode
+        # explicit CodingKeys and ignore it.
+        'parent_inspection_id': s.parent_inspection_id,
     }
 
 
@@ -113,3 +122,118 @@ def list_scheduled():
 
     return api_ok({'scheduled': payload, 'total': total,
                    'limit': limit, 'offset': offset})
+
+
+# ── Create a scheduled follow-up (phase45) ────────────────────────────────────
+
+@bp.route('/scheduled-inspections/follow-up', methods=['POST'])
+@jwt_required
+def create_follow_up():
+    """
+    Plan a follow-up re-inspection of a completed inspection for a later date.
+
+    Backs "Schedule Follow-up" in the iPad's inspection history detail, the
+    deferred twin of "Re-inspect Now". Creates a one-time schedule carrying
+    `parent_inspection_id`, so the inspection eventually started from it is a
+    true linked re-inspection.
+
+    Deliberately narrow: this is not a general schedule-creation endpoint. The
+    facility, template and assignee are all derived from the parent inspection
+    rather than taken from the client, so a follow-up can only ever target the
+    thing it is a follow-up of. Recurring schedules stay web-only
+    (`@project_manager_required`).
+
+    Request body
+    ------------
+    parent_inspection_id  int  required — the completed inspection to follow up
+    due_date              str  required — ISO date (YYYY-MM-DD), today or later
+    notes                 str  optional — what the follow-up should address
+
+    Response 200/201
+    ----------------
+    { "ok": true, "data": { "scheduled": {...}, "created": true } }
+    """
+    user = g.api_user
+
+    # Auditor is read-only everywhere else; keep it that way here.
+    if user.role not in {'admin', 'director', 'inspector', 'project_manager'}:
+        return api_error('Access denied', 403)
+
+    body = request.get_json(silent=True) or {}
+
+    parent_id = body.get('parent_inspection_id')
+    if not isinstance(parent_id, int):
+        return api_error('parent_inspection_id is required', 400)
+
+    parent = db.session.get(Inspection, parent_id)
+    if parent is None:
+        return api_error('Inspection not found', 404)
+
+    # An inspector may only schedule a follow-up of their own work, and only
+    # within their assigned contracts — the same two gates the rest of the
+    # mobile API applies. Managers are unrestricted, matching the web.
+    if user.role == 'inspector':
+        if parent.inspector_id != user.id:
+            return api_error('Access denied', 403)
+        fids = get_inspector_scope(user)
+        if not fids or parent.facility_id not in fids:
+            return api_error('Access denied', 403)
+
+    # A follow-up only makes sense once there is something to follow up on.
+    if parent.status != 'completed':
+        return api_error('Only a completed inspection can have a follow-up '
+                         'scheduled', 400)
+
+    due_raw = (body.get('due_date') or '').strip()
+    try:
+        due_date = datetime.strptime(due_raw, '%Y-%m-%d').date()
+    except ValueError:
+        return api_error('due_date must be an ISO date (YYYY-MM-DD)', 400)
+
+    # Today is allowed — "later today" is a legitimate plan; yesterday is not.
+    if due_date < now_eastern().date():
+        return api_error('due_date cannot be in the past', 400)
+
+    notes = (body.get('notes') or '').strip() or None
+
+    # Idempotent: the iPad may retry a request whose response was lost, and a
+    # second identical schedule would put a duplicate row in the inspector's
+    # Scheduled list with no way to tell them apart. Reuse the existing active
+    # follow-up for this parent instead, updating the date they just picked.
+    existing = (ScheduledInspection.query
+                .filter_by(parent_inspection_id=parent.id, active=True)
+                .order_by(ScheduledInspection.id.desc())
+                .first())
+    if existing is not None:
+        existing.next_due_date = due_date
+        if notes:
+            existing.notes = notes
+        db.session.commit()
+        logger.info('API SCHEDULED | follow-up updated | schedule=%s | '
+                    'parent=%s | due=%s | user=%s',
+                    existing.id, parent.id, due_date, user.username)
+        return api_ok({'scheduled': _scheduled_payload(existing),
+                       'created': False})
+
+    sched = ScheduledInspection(
+        facility_id          = parent.facility_id,
+        template_id          = parent.template_id,
+        # Assign to whoever performed the original — they are the one being
+        # asked to put it right. Falls back to the caller when the parent has
+        # no inspector (its account was deleted).
+        inspector_id         = parent.inspector_id or user.id,
+        frequency            = 'once',
+        next_due_date        = due_date,
+        active               = True,
+        notes                = notes,
+        parent_inspection_id = parent.id,
+        created_by           = user.id,
+    )
+    db.session.add(sched)
+    db.session.commit()
+
+    logger.info('API SCHEDULED | follow-up created | schedule=%s | parent=%s | '
+                'facility=%s | due=%s | user=%s',
+                sched.id, parent.id, parent.facility_id, due_date, user.username)
+
+    return api_ok({'scheduled': _scheduled_payload(sched), 'created': True}, 201)