464 lines
20 KiB
Python
464 lines
20 KiB
Python
"""
|
|
app/routes/scheduled_inspections.py
|
|
------------------------------------
|
|
Planned / recurring inspection assignments (phase36).
|
|
|
|
Management (list/new/edit/delete) : admin, director, project_manager
|
|
Start (execute the planned inspection): the assigned inspector ONLY (the person
|
|
who must do it) — not managers. A manager
|
|
who needs to run it assigns it to themselves.
|
|
Cron reminders : POST /run?token=DIGEST_SECRET (no login)
|
|
|
|
Fulfillment (marking a schedule done and rolling recurring ones forward) happens
|
|
in the inspection execute route when the linked inspection is completed —
|
|
see app/routes/inspections.py.
|
|
"""
|
|
|
|
import logging
|
|
from datetime import timedelta
|
|
|
|
from flask import (Blueprint, render_template, redirect, url_for, flash,
|
|
request, abort, current_app)
|
|
from flask_login import login_required, current_user
|
|
|
|
from app import db
|
|
from app.models.scheduled_inspection import (ScheduledInspection,
|
|
MONTH_MODE_DAY, MONTH_MODE_NTH)
|
|
from app.models.facility import Facility
|
|
from app.models.inspection import Inspection, InspectionTemplate
|
|
from app.models.project import Project
|
|
from app.models.user import User
|
|
from app.utils.forms import ScheduledInspectionForm
|
|
from app.utils.decorators import project_manager_required
|
|
from app.utils.audit import log_action, ACTION_CREATE, ACTION_UPDATE, ACTION_DELETE
|
|
from app.utils.time_utils import now_eastern
|
|
from app.utils.notifications import notify
|
|
from app.models.notification import EVENT_SCHEDULED_INSPECTION
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
bp = Blueprint('scheduled_inspections', __name__, url_prefix='/scheduled-inspections')
|
|
|
|
|
|
def _populate_choices(form):
|
|
# facility_id choices are ALL active facilities so POST validation passes
|
|
# regardless of which contract the UI-only contract selector had chosen
|
|
# (CLAUDE.md rule 61). The contract selector narrows the list client-side.
|
|
facilities = Facility.query.filter_by(active=True).order_by(Facility.name).all()
|
|
templates = (InspectionTemplate.query
|
|
.filter_by(active=True).order_by(InspectionTemplate.name).all())
|
|
inspectors = (User.query.filter_by(role='inspector', active=True)
|
|
.order_by(User.username).all())
|
|
form.facility_id.choices = [(f.id, f.name) for f in facilities]
|
|
form.template_id.choices = [(t.id, t.name) for t in templates]
|
|
form.inspector_id.choices = [(u.id, u.display_name) for u in inspectors]
|
|
|
|
|
|
def _active_contracts():
|
|
return Project.query.filter_by(active=True).order_by(Project.name).all()
|
|
|
|
|
|
def _notify_assignee(sched, reassigned=False):
|
|
"""Send an immediate in-app + email notification to the assigned inspector
|
|
that a scheduled inspection was assigned (or reassigned) to them.
|
|
No-op when there is no active inspector. Caller commits."""
|
|
inspector = sched.inspector
|
|
if not inspector or not inspector.active:
|
|
return
|
|
fac = sched.facility.name if sched.facility else '—'
|
|
tpl = sched.template.name if sched.template else '—'
|
|
verb = 'reassigned to you' if reassigned else 'assigned to you'
|
|
notify(
|
|
recipient = inspector,
|
|
title = f'Scheduled inspection {verb} — {fac}',
|
|
body = (f'A "{tpl}" inspection at {fac} has been {verb} '
|
|
f'({sched.frequency_label.lower()}), due '
|
|
f'{sched.next_due_date:%b %d, %Y}.'),
|
|
link = url_for('scheduled_inspections.index'),
|
|
event_type = EVENT_SCHEDULED_INSPECTION,
|
|
send_email = True,
|
|
)
|
|
|
|
|
|
def _apply_recurrence(sched, form):
|
|
"""Copy the recurrence block for the chosen frequency onto *sched* and
|
|
clear the blocks that no longer apply, then snap next_due_date onto the
|
|
rule. Keeping the unused columns NULL means `recurrence_label` and the
|
|
date math never read stale settings after a frequency change."""
|
|
sched.frequency = form.frequency.data
|
|
|
|
if sched.frequency == 'weekly':
|
|
sched.set_weekdays(form.weekdays.data)
|
|
else:
|
|
sched.weekdays = None
|
|
|
|
if sched.frequency == 'monthly':
|
|
sched.month_mode = form.month_mode.data or MONTH_MODE_DAY
|
|
if sched.month_mode == MONTH_MODE_NTH:
|
|
sched.day_of_month = None
|
|
sched.nth_week = form.nth_week.data
|
|
sched.nth_weekday = form.nth_weekday.data
|
|
else:
|
|
sched.day_of_month = form.day_of_month.data
|
|
sched.nth_week = None
|
|
sched.nth_weekday = None
|
|
else:
|
|
sched.month_mode = sched.day_of_month = None
|
|
sched.nth_week = sched.nth_weekday = None
|
|
|
|
# End date (phase44) — a boundary, not a cadence setting. A one-time
|
|
# schedule has none: it ends by deactivating when it is completed.
|
|
sched.end_date = form.end_date.data if sched.frequency != 'once' else None
|
|
|
|
# Snap the picked date forward onto the first matching occurrence.
|
|
sched.next_due_date = sched.align_due_date(form.next_due_date.data)
|
|
|
|
|
|
def _reject_if_past_end_date(sched, form):
|
|
"""True (and a form error set) if the aligned first occurrence falls past
|
|
the end date.
|
|
|
|
The form already rejects an end date earlier than the *picked* due date, but
|
|
align_due_date() can push that date forward onto the recurrence rule — pick
|
|
a Tuesday for a Mon/Wed/Fri schedule and the first occurrence is Wednesday.
|
|
Without this check that combination would save as active with no occurrence
|
|
it is ever allowed to run.
|
|
"""
|
|
if sched.is_within_end_date(sched.next_due_date):
|
|
return False
|
|
form.end_date.errors.append(
|
|
f'With this recurrence the first occurrence falls on '
|
|
f'{sched.next_due_date:%b %d, %Y}, after the end date.')
|
|
return True
|
|
|
|
|
|
def _open_inspection_ids(schedules):
|
|
"""{schedule_id: inspection_id} for schedules with an inspection already
|
|
in progress, so the UI offers Continue instead of a duplicate Start."""
|
|
ids = [s.id for s in schedules if s.id]
|
|
if not ids:
|
|
return {}
|
|
rows = (Inspection.query
|
|
.filter(Inspection.scheduled_inspection_id.in_(ids),
|
|
Inspection.status == 'in_progress')
|
|
.order_by(Inspection.id.desc())
|
|
.all())
|
|
return {r.scheduled_inspection_id: r.id for r in rows}
|
|
|
|
|
|
def _selected_project_id(form):
|
|
"""Contract of the submitted facility (for restoring the selector on
|
|
re-render), or None."""
|
|
if form.facility_id.data:
|
|
fac = db.session.get(Facility, form.facility_id.data)
|
|
if fac:
|
|
return fac.project_id
|
|
return None
|
|
|
|
|
|
# ── List ──────────────────────────────────────────────────────────────────────
|
|
|
|
@bp.route('/')
|
|
@login_required
|
|
def index():
|
|
if current_user.role == 'customer':
|
|
abort(403)
|
|
|
|
today = now_eastern().date()
|
|
q = ScheduledInspection.query
|
|
|
|
# Inspectors see only their own assignments; managers see everything.
|
|
if current_user.role == 'inspector':
|
|
q = q.filter(ScheduledInspection.inspector_id == current_user.id)
|
|
|
|
schedules = q.order_by(
|
|
ScheduledInspection.active.desc(),
|
|
ScheduledInspection.next_due_date.asc(),
|
|
).all()
|
|
|
|
return render_template('scheduled_inspections/list.html',
|
|
schedules=schedules, today=today,
|
|
open_inspections=_open_inspection_ids(schedules))
|
|
|
|
|
|
# ── Create ──────────────────────────────────────────────────────────────────
|
|
|
|
@bp.route('/new', methods=['GET', 'POST'])
|
|
@login_required
|
|
@project_manager_required
|
|
def create():
|
|
form = ScheduledInspectionForm()
|
|
_populate_choices(form)
|
|
# On a new schedule this date IS the start; on edit it is whatever the next
|
|
# occurrence happens to be. One field, two meanings — so the label follows
|
|
# the context instead of saying both at once.
|
|
form.next_due_date.label.text = 'Start Date'
|
|
if not form.next_due_date.data:
|
|
form.next_due_date.data = now_eastern().date()
|
|
|
|
if form.validate_on_submit():
|
|
sched = ScheduledInspection(
|
|
facility_id = form.facility_id.data,
|
|
template_id = form.template_id.data,
|
|
inspector_id = form.inspector_id.data,
|
|
next_due_date = form.next_due_date.data,
|
|
notes = (form.notes.data or '').strip() or None,
|
|
active = form.active.data,
|
|
created_by = current_user.id,
|
|
)
|
|
_apply_recurrence(sched, form)
|
|
if _reject_if_past_end_date(sched, form):
|
|
# sched was never added to the session — nothing to roll back.
|
|
return render_template('scheduled_inspections/form.html',
|
|
form=form, title='New Scheduled Inspection',
|
|
projects=_active_contracts(),
|
|
selected_project_id=_selected_project_id(form))
|
|
db.session.add(sched)
|
|
db.session.commit()
|
|
log_action(ACTION_CREATE, 'ScheduledInspection', sched.id,
|
|
f'{sched.template.name} @ {sched.facility.name}',
|
|
f'freq={sched.recurrence_label}; due={sched.next_due_date}; '
|
|
f'end={sched.end_date or "—"}; '
|
|
f'inspector={sched.inspector_id}')
|
|
logger.info('SCHED INSP | create | by=%s | id=%s', current_user.username, sched.id)
|
|
|
|
# Notify the assigned inspector immediately.
|
|
_notify_assignee(sched, reassigned=False)
|
|
db.session.commit()
|
|
|
|
flash('Scheduled inspection created.', 'success')
|
|
return redirect(url_for('scheduled_inspections.index'))
|
|
|
|
return render_template('scheduled_inspections/form.html',
|
|
form=form, title='New Scheduled Inspection',
|
|
projects=_active_contracts(),
|
|
selected_project_id=_selected_project_id(form))
|
|
|
|
|
|
# ── Edit ──────────────────────────────────────────────────────────────────────
|
|
|
|
@bp.route('/<int:schedule_id>/edit', methods=['GET', 'POST'])
|
|
@login_required
|
|
@project_manager_required
|
|
def edit(schedule_id):
|
|
sched = db.session.get(ScheduledInspection, schedule_id)
|
|
if sched is None:
|
|
abort(404)
|
|
form = ScheduledInspectionForm(obj=sched)
|
|
_populate_choices(form)
|
|
form.next_due_date.label.text = 'Next Due Date'
|
|
if request.method == 'GET':
|
|
# obj= copies the raw CSV column into a multi-select field; hand it the
|
|
# parsed int list instead so the checkboxes pre-tick correctly.
|
|
form.weekdays.data = sched.weekday_list
|
|
form.month_mode.data = sched.month_mode or MONTH_MODE_DAY
|
|
|
|
if form.validate_on_submit():
|
|
old_inspector_id = sched.inspector_id
|
|
sched.facility_id = form.facility_id.data
|
|
sched.template_id = form.template_id.data
|
|
sched.inspector_id = form.inspector_id.data
|
|
sched.notes = (form.notes.data or '').strip() or None
|
|
sched.active = form.active.data
|
|
_apply_recurrence(sched, form)
|
|
if _reject_if_past_end_date(sched, form):
|
|
# sched is a persistent object and has already been mutated — discard
|
|
# those pending changes before re-rendering so nothing leaks out on
|
|
# the next flush.
|
|
db.session.rollback()
|
|
return render_template('scheduled_inspections/form.html',
|
|
form=form, title='Edit Scheduled Inspection',
|
|
schedule=sched, projects=_active_contracts(),
|
|
selected_project_id=_selected_project_id(form))
|
|
db.session.commit()
|
|
log_action(ACTION_UPDATE, 'ScheduledInspection', sched.id,
|
|
f'{sched.template.name} @ {sched.facility.name}',
|
|
f'freq={sched.recurrence_label}; due={sched.next_due_date}; '
|
|
f'end={sched.end_date or "—"}; '
|
|
f'active={sched.active}')
|
|
|
|
# Notify the inspector if the assignment changed to them.
|
|
if sched.active and sched.inspector_id and sched.inspector_id != old_inspector_id:
|
|
_notify_assignee(sched, reassigned=True)
|
|
db.session.commit()
|
|
|
|
flash('Scheduled inspection updated.', 'success')
|
|
return redirect(url_for('scheduled_inspections.index'))
|
|
|
|
# Restore the contract selector: submitted facility's contract on error,
|
|
# otherwise the schedule's current facility's contract.
|
|
sel_pid = _selected_project_id(form)
|
|
if sel_pid is None and sched.facility:
|
|
sel_pid = sched.facility.project_id
|
|
return render_template('scheduled_inspections/form.html',
|
|
form=form, title='Edit Scheduled Inspection', schedule=sched,
|
|
projects=_active_contracts(),
|
|
selected_project_id=sel_pid)
|
|
|
|
|
|
# ── Delete ────────────────────────────────────────────────────────────────────
|
|
|
|
@bp.route('/<int:schedule_id>/delete', methods=['POST'])
|
|
@login_required
|
|
@project_manager_required
|
|
def delete(schedule_id):
|
|
sched = db.session.get(ScheduledInspection, schedule_id)
|
|
if sched is None:
|
|
abort(404)
|
|
label = f'{sched.template.name if sched.template else "?"} @ {sched.facility.name if sched.facility else "?"}'
|
|
sid = sched.id
|
|
db.session.delete(sched)
|
|
db.session.commit()
|
|
log_action(ACTION_DELETE, 'ScheduledInspection', sid, label)
|
|
flash('Scheduled inspection deleted.', 'success')
|
|
return redirect(url_for('scheduled_inspections.index'))
|
|
|
|
|
|
# ── Start (create the planned inspection and open the execute flow) ───────────
|
|
|
|
@bp.route('/<int:schedule_id>/start')
|
|
@login_required
|
|
def start(schedule_id):
|
|
sched = db.session.get(ScheduledInspection, schedule_id)
|
|
if sched is None:
|
|
abort(404)
|
|
|
|
# Only the assigned inspector may start it — this inspection is theirs to do.
|
|
# Managers (admin/director/pm) manage the schedule but do not start it for
|
|
# someone else; if a manager needs to do the inspection, assign it to them.
|
|
if not sched.inspector_id or sched.inspector_id != current_user.id:
|
|
abort(403)
|
|
|
|
if not sched.active:
|
|
flash('This scheduled inspection is no longer active.', 'warning')
|
|
return redirect(url_for('scheduled_inspections.index'))
|
|
|
|
template = sched.template
|
|
if template is None or not template.get_form_schema():
|
|
flash('The template for this schedule has no form fields yet.', 'warning')
|
|
return redirect(url_for('scheduled_inspections.index'))
|
|
|
|
# Already started but not submitted? Resume it rather than opening a second
|
|
# inspection against the same occurrence.
|
|
existing = (Inspection.query
|
|
.filter_by(scheduled_inspection_id=sched.id, status='in_progress')
|
|
.order_by(Inspection.id.desc())
|
|
.first())
|
|
if existing is not None:
|
|
flash('Resuming the inspection you already started for this schedule.', 'info')
|
|
return redirect(url_for('inspections.execute', inspection_id=existing.id))
|
|
|
|
inspection = Inspection(
|
|
template_id = sched.template_id,
|
|
facility_id = sched.facility_id,
|
|
area_id = None,
|
|
inspector_id = current_user.id,
|
|
inspection_date = now_eastern(),
|
|
status = 'in_progress',
|
|
scheduled_inspection_id = sched.id,
|
|
# phase45 — a schedule created by "Schedule Follow-up" carries the
|
|
# inspection it is a follow-up of. Inheriting it here is what makes the
|
|
# run a real linked re-inspection: execute() pre-fills from the parent
|
|
# and submit clears the parent's follow_up_required. NULL for ordinary
|
|
# schedules, which is every pre-phase45 row.
|
|
parent_inspection_id = sched.parent_inspection_id,
|
|
)
|
|
db.session.add(inspection)
|
|
db.session.commit()
|
|
log_action(ACTION_CREATE, 'Inspection', inspection.id,
|
|
f'{inspection.template.name} @ {inspection.facility.name}',
|
|
f'from scheduled_inspection_id={sched.id}')
|
|
logger.info('SCHED INSP | start | schedule=%s | inspection=%s | by=%s',
|
|
sched.id, inspection.id, current_user.username)
|
|
flash('Inspection started from schedule. Complete and submit the form below.', 'info')
|
|
return redirect(url_for('inspections.execute', inspection_id=inspection.id))
|
|
|
|
|
|
# ── Cron: reminders (advance / due / overdue) ─────────────────────────────────
|
|
|
|
@bp.route('/run', methods=['POST'])
|
|
def run_reminders():
|
|
token = request.form.get('token') or request.args.get('token')
|
|
if not token or token != current_app.config.get('DIGEST_SECRET'):
|
|
abort(403)
|
|
|
|
today = now_eastern().date()
|
|
sent = {'advance': 0, 'due': 0, 'overdue': 0, 'expired': 0}
|
|
|
|
schedules = ScheduledInspection.query.filter_by(active=True).all()
|
|
|
|
# Expire schedules past their end date BEFORE any reminder work (phase44).
|
|
# fulfill() closes out a schedule that reaches its boundary by being
|
|
# completed; this covers the one that reaches it without ever being done —
|
|
# otherwise it stays active and re-alerts as overdue indefinitely.
|
|
live = []
|
|
for s in schedules:
|
|
if s.expire_if_past_end_date(today):
|
|
sent['expired'] += 1
|
|
logger.info('SCHED INSP | expired | id=%s | end=%s', s.id, s.end_date)
|
|
else:
|
|
live.append(s)
|
|
schedules = live
|
|
|
|
# Cache admin/director recipients for overdue alerts
|
|
managers = User.query.filter(
|
|
User.role.in_(['admin', 'director']), User.active == True # noqa: E712
|
|
).all()
|
|
|
|
for s in schedules:
|
|
inspector = s.inspector
|
|
link = url_for('scheduled_inspections.index')
|
|
fac_name = s.facility.name if s.facility else '—'
|
|
tpl_name = s.template.name if s.template else '—'
|
|
|
|
# Advance reminder — 1 day before due
|
|
if (not s.advance_notified and inspector and inspector.active
|
|
and s.next_due_date == today + timedelta(days=1)):
|
|
notify(
|
|
recipient = inspector,
|
|
title = f'Inspection due tomorrow — {fac_name}',
|
|
body = (f'Reminder: a "{tpl_name}" inspection at {fac_name} '
|
|
f'is scheduled for tomorrow ({s.next_due_date:%b %d, %Y}).'),
|
|
link = link,
|
|
event_type = EVENT_SCHEDULED_INSPECTION,
|
|
send_email = True,
|
|
)
|
|
s.advance_notified = True
|
|
sent['advance'] += 1
|
|
|
|
# Due reminder — on/after due date
|
|
if (not s.due_notified and inspector and inspector.active
|
|
and s.next_due_date <= today):
|
|
notify(
|
|
recipient = inspector,
|
|
title = f'Inspection due today — {fac_name}',
|
|
body = (f'A "{tpl_name}" inspection at {fac_name} is due '
|
|
f'({s.next_due_date:%b %d, %Y}). Please complete it.'),
|
|
link = link,
|
|
event_type = EVENT_SCHEDULED_INSPECTION,
|
|
send_email = True,
|
|
)
|
|
s.due_notified = True
|
|
sent['due'] += 1
|
|
|
|
# Overdue alert — due date has passed, still not fulfilled
|
|
if not s.overdue_notified and s.next_due_date < today:
|
|
for m in managers:
|
|
notify(
|
|
recipient = m,
|
|
title = f'Overdue scheduled inspection — {fac_name}',
|
|
body = (f'The "{tpl_name}" inspection at {fac_name} assigned to '
|
|
f'{inspector.display_name if inspector else "—"} was due '
|
|
f'{s.next_due_date:%b %d, %Y} and has not been completed.'),
|
|
link = link,
|
|
event_type = EVENT_SCHEDULED_INSPECTION,
|
|
send_email = True,
|
|
)
|
|
s.overdue_notified = True
|
|
sent['overdue'] += 1
|
|
|
|
db.session.commit()
|
|
logger.info('SCHED INSP | reminders | advance=%s due=%s overdue=%s expired=%s',
|
|
sent['advance'], sent['due'], sent['overdue'], sent['expired'])
|
|
return {'ok': True, 'sent': sent}, 200
|