Jul 30 - Internal handler files

app/api/issues.py

@@ -110,6 +110,10 @@ def _issue_payload(issue):
         'vendor_name':              issue.vendor_name or None,
         'vendor_contact':           issue.vendor_contact or None,
         'vendor_notes':             issue.vendor_notes or None,
+        # Janitorial staff handler — used when handler_type == 'internal'.
+        # Distinct from assigned_to: the crew member may not be a system user.
+        'internal_handler_name':    issue.internal_handler_name or None,
+        'internal_handler_contact': issue.internal_handler_contact or None,
     }
 
 
@@ -550,7 +554,9 @@ def update_issue_handler(issue_id):
         "facility_handler_notes":   "...",   // optional
         "vendor_name":              "...",   // optional (vendor handler)
         "vendor_contact":           "...",   // optional
-        "vendor_notes":             "..."    // optional
+        "vendor_notes":             "...",   // optional
+        "internal_handler_name":    "...",   // optional (janitorial staff handler)
+        "internal_handler_contact": "..."    // optional
     }
 
     Only keys present in the body are updated; empty strings clear a field.
@@ -591,6 +597,7 @@ def update_issue_handler(issue_id):
     _text_fields = (
         'facility_handler_name', 'facility_handler_contact', 'facility_handler_notes',
         'vendor_name', 'vendor_contact', 'vendor_notes',
+        'internal_handler_name', 'internal_handler_contact',
     )
     for field in _text_fields:
         if field in data:

app/models/issue.py

@@ -85,18 +85,24 @@ class Issue(db.Model):
     vendor_notes   = db.Column(db.Text, nullable=True)
 
     # Handler type — who is responsible for resolving the issue (phase39).
-    # NULL and 'internal' both mean janitorial staff (the default); 'facility'
+    # 'internal' means janitorial staff (the default); 'facility' unlocks the
-    # unlocks the facility_handler_* sub-fields; 'vendor' points to vendor_*.
+    # facility_handler_* sub-fields; 'vendor' points to vendor_*.
-    handler_type             = db.Column(db.Enum('internal', 'facility', 'vendor'), nullable=True)
+    # NOT NULL DEFAULT 'internal' since phase44 — previously nullable, with NULL
+    # treated as a synonym for 'internal'. Existing NULLs were backfilled by that
+    # migration, so the two representations are now one.
+    handler_type             = db.Column(
+        db.Enum('internal', 'facility', 'vendor'),
+        nullable=False, default='internal',
+    )
     facility_handler_name    = db.Column(db.String(100), nullable=True)
     facility_handler_contact = db.Column(db.String(200), nullable=True)
     facility_handler_notes   = db.Column(db.Text, nullable=True)
-
+    # Free-text name of the janitorial staff member who will handle the issue,
-    HANDLER_LABELS = {
+    # used when handler_type == 'internal'. Distinct from assigned_to (the JQC
-        'internal': 'Janitorial Staff',
+    # User who owns follow-up): the actual crew member may not be a system user.
-        'facility': 'Facility Staff',
+    # (phase44)
-        'vendor':   'External Vendor',
+    internal_handler_name    = db.Column(db.String(100), nullable=True)
-    }
+    internal_handler_contact = db.Column(db.String(200), nullable=True)  # phone or email
 
     # Relationships
     # NOTE: Issue.area is provided by the backref on Area.issues (facility.py).
@@ -124,6 +130,13 @@ class Issue(db.Model):
         'facility': 'Facility Staff',
         'vendor':   'External Vendor',
     }
+    # One-line explanation per handler type, shown under the radio options on the
+    # issue form so staff pick the right one. (phase44)
+    HANDLER_DESCRIPTIONS = {
+        'internal': 'Our janitorial crew handles it.',
+        'facility': "The facility's own on-site staff handle it.",
+        'vendor':   'An outside contractor handles it.',
+    }
 
     @property
     def handler_label(self):

app/routes/issues.py

@@ -462,8 +462,19 @@ def view(issue_id):
             issue.vendor_contact = form.vendor_contact.data.strip() or None
             issue.vendor_notes   = form.vendor_notes.data.strip() or None
 
-            # Handler type (phase39)
+            # Handler type (phase39; NOT NULL since phase44)
-            ht = form.handler_type.data or None
+            # Coerce empty/unknown to 'internal' explicitly. This is NOT
+            # preventing a crash: handler_type carries a Python-side
+            # default='internal', and SQLAlchemy applies a column default when
+            # the attribute is None — so the previous `or None` would have been
+            # silently rescued to 'internal' rather than raising. The point is to
+            # not depend on that fairly obscure behaviour, and to state the
+            # intended value at the point of assignment. The membership check
+            # also backstops a crafted POST, though SelectField.pre_validate
+            # already rejects out-of-choice values.
+            ht = form.handler_type.data or 'internal'
+            if ht not in ('internal', 'facility', 'vendor'):
+                ht = 'internal'
             issue.handler_type = ht
             if ht == 'facility':
                 issue.facility_handler_name    = form.facility_handler_name.data.strip() or None
@@ -474,6 +485,13 @@ def view(issue_id):
                 issue.facility_handler_contact = None
                 issue.facility_handler_notes   = None
 
+            # Janitorial staff handler (phase44). Written unconditionally, the
+            # same way vendor_* above is: the work-order dispatch route also
+            # writes vendor_name, so clearing non-active handler fields here
+            # would discard data set elsewhere.
+            issue.internal_handler_name    = (form.internal_handler_name.data    or '').strip() or None
+            issue.internal_handler_contact = (form.internal_handler_contact.data or '').strip() or None
+
         from app.routes.inspections import _save_photo
         new_photos = []
         for file_obj in request.files.getlist('result_photos'):
@@ -752,6 +770,25 @@ def create():
             reported_at = now_eastern(),
             reported_by = current_user.id,
         )
+
+        # "Handled By" — staff only; customer-created issues stay internal.
+        # (phase44) Previously the create form carried no handler fields at all,
+        # so a handler chosen here was silently discarded and had to be re-entered
+        # on the update form.
+        if current_user.role != 'customer':
+            handler = form.handler_type.data or 'internal'
+            if handler not in ('internal', 'facility', 'vendor'):
+                handler = 'internal'
+            issue.handler_type = handler
+            issue.facility_handler_name    = (form.facility_handler_name.data    or '').strip() or None
+            issue.facility_handler_contact = (form.facility_handler_contact.data or '').strip() or None
+            issue.facility_handler_notes   = (form.facility_handler_notes.data   or '').strip() or None
+            issue.vendor_name    = (form.vendor_name.data    or '').strip() or None
+            issue.vendor_contact = (form.vendor_contact.data or '').strip() or None
+            issue.vendor_notes   = (form.vendor_notes.data   or '').strip() or None
+            issue.internal_handler_name    = (form.internal_handler_name.data    or '').strip() or None
+            issue.internal_handler_contact = (form.internal_handler_contact.data or '').strip() or None
+
         db.session.add(issue)
         db.session.commit()
         current_app.logger.info(
@@ -804,7 +841,8 @@ def create():
         return redirect(url_for('issues.index'))
 
     return render_template('issues/form.html', form=form, title='Log New Issue',
-                           projects=projects, selected_project_id=selected_project_id)
+                           projects=projects, selected_project_id=selected_project_id,
+                           issue_handler_descriptions=Issue.HANDLER_DESCRIPTIONS)
 
 
 # ── Supervisor verify resolved issue ─────────────────────────────────────────

app/templates/issues/form.html

@@ -46,6 +46,93 @@
           </div>
           {% endif %}
 
+          {# ── Handled By (phase44) — staff only; customers stay internal ── #}
+          {% if current_user.role != 'customer' %}
+          <hr class="my-3">
+          <p class="fw-semibold mb-2">
+            <i class="bi bi-person-check me-1 text-secondary"></i>Handled By
+          </p>
+          <div class="mb-3">
+            {{ form.handler_type(class="form-select", id="handlerTypeSelect") }}
+            <div class="form-text" id="handlerTypeHelp"></div>
+          </div>
+
+          <div id="internalHandlerFields">
+            <div class="mb-2">
+              {{ form.internal_handler_name.label(class="form-label small fw-semibold mb-1") }}
+              {{ form.internal_handler_name(class="form-control form-control-sm",
+                 placeholder="Crew member handling this") }}
+            </div>
+            <div class="mb-3">
+              {{ form.internal_handler_contact.label(class="form-label small fw-semibold mb-1") }}
+              {{ form.internal_handler_contact(class="form-control form-control-sm",
+                 placeholder="Phone or email") }}
+            </div>
+          </div>
+
+          <div id="facilityHandlerFields" style="display:none;">
+            <div class="mb-2">
+              {{ form.facility_handler_name.label(class="form-label small fw-semibold mb-1") }}
+              {{ form.facility_handler_name(class="form-control form-control-sm",
+                 placeholder="Contact name at the facility") }}
+            </div>
+            <div class="mb-2">
+              {{ form.facility_handler_contact.label(class="form-label small fw-semibold mb-1") }}
+              {{ form.facility_handler_contact(class="form-control form-control-sm",
+                 placeholder="Phone or email") }}
+            </div>
+            <div class="mb-3">
+              {{ form.facility_handler_notes.label(class="form-label small fw-semibold mb-1") }}
+              {{ form.facility_handler_notes(class="form-control form-control-sm", rows=2,
+                 placeholder="Notes about what they are handling…") }}
+            </div>
+          </div>
+
+          <div id="vendorHandlerFields" style="display:none;">
+            <div class="mb-2">
+              {{ form.vendor_name.label(class="form-label small fw-semibold mb-1") }}
+              {{ form.vendor_name(class="form-control form-control-sm",
+                 placeholder="Contractor or vendor name") }}
+            </div>
+            <div class="mb-2">
+              {{ form.vendor_contact.label(class="form-label small fw-semibold mb-1") }}
+              {{ form.vendor_contact(class="form-control form-control-sm",
+                 placeholder="Phone or email") }}
+            </div>
+            <div class="mb-3">
+              {{ form.vendor_notes.label(class="form-label small fw-semibold mb-1") }}
+              {{ form.vendor_notes(class="form-control form-control-sm", rows=2,
+                 placeholder="Scope, quote reference, etc.") }}
+            </div>
+          </div>
+
+          <script>
+          (function(){
+            var sel   = document.getElementById('handlerTypeSelect');
+            var help  = document.getElementById('handlerTypeHelp');
+            var boxes = {
+              internal: document.getElementById('internalHandlerFields'),
+              facility: document.getElementById('facilityHandlerFields'),
+              vendor:   document.getElementById('vendorHandlerFields')
+            };
+            var notes = {
+              internal: {{ (issue_handler_descriptions or {}).get('internal', '')|tojson }},
+              facility: {{ (issue_handler_descriptions or {}).get('facility', '')|tojson }},
+              vendor:   {{ (issue_handler_descriptions or {}).get('vendor',   '')|tojson }}
+            };
+            function sync(){
+              var v = sel ? sel.value : 'internal';
+              for (var k in boxes){
+                if (boxes[k]) { boxes[k].style.display = (k === v) ? '' : 'none'; }
+              }
+              if (help) { help.textContent = notes[v] || ''; }
+            }
+            if (sel){ sel.addEventListener('change', sync); }
+            sync();
+          })();
+          </script>
+          {% endif %}
+
           <div class="d-flex gap-2">
             <button type="submit" class="btn btn-danger">Log Issue</button>
             <a href="{{ url_for('issues.index') }}" class="btn btn-outline-secondary">Cancel</a>

app/templates/issues/view.html

@@ -76,10 +76,11 @@
           <dt class="col-sm-3">Assigned To</dt>
           <dd class="col-sm-9">{{ issue.assigned_user.display_name if issue.assigned_user else '— Unassigned —' }}</dd>
 
-          {% if issue.handler_type and issue.handler_type != 'internal' %}
+          {% set _ht = issue.handler_type or 'internal' %}
+          {% if _ht != 'internal' or issue.internal_handler_name or issue.internal_handler_contact %}
           <dt class="col-sm-3">Handled By</dt>
           <dd class="col-sm-9">
-            {% if issue.handler_type == 'facility' %}
+            {% if _ht == 'facility' %}
             <span class="badge bg-secondary">
               <i class="bi bi-building me-1"></i>Facility Staff
             </span>
@@ -92,8 +93,18 @@
             {% if issue.facility_handler_notes %}
             <div class="text-muted small mt-1" style="white-space:pre-wrap;">{{ issue.facility_handler_notes }}</div>
             {% endif %}
-            {% elif issue.handler_type == 'vendor' %}
+            {% elif _ht == 'vendor' %}
             <span class="badge bg-dark"><i class="bi bi-person-gear me-1"></i>External Vendor</span>
+            {% else %}
+            <span class="badge bg-light text-dark border">
+              <i class="bi bi-people me-1"></i>Janitorial Staff
+            </span>
+            {% if issue.internal_handler_name %}
+            <span class="ms-2 fw-semibold">{{ issue.internal_handler_name }}</span>
+            {% endif %}
+            {% if issue.internal_handler_contact %}
+            <span class="text-muted ms-2">{{ issue.internal_handler_contact }}</span>
+            {% endif %}
             {% endif %}
           </dd>
           {% endif %}
@@ -416,13 +427,30 @@
                  placeholder="Notes about what they are handling…") }}
             </div>
           </div>
+          <div id="internalHandlerFields"
+               style="{{ '' if (issue.handler_type or 'internal') == 'internal' else 'display:none;' }}">
+            <div class="mb-2">
+              {{ form.internal_handler_name.label(class="form-label small fw-semibold mb-1") }}
+              {{ form.internal_handler_name(class="form-control form-control-sm",
+                 placeholder="Crew member handling this",
+                 value=issue.internal_handler_name or '') }}
+            </div>
+            <div class="mb-3">
+              {{ form.internal_handler_contact.label(class="form-label small fw-semibold mb-1") }}
+              {{ form.internal_handler_contact(class="form-control form-control-sm",
+                 placeholder="Phone or email",
+                 value=issue.internal_handler_contact or '') }}
+            </div>
+          </div>
           <script>
           (function(){
             var sel = document.getElementById('handlerTypeSelect');
             var box = document.getElementById('facilityHandlerFields');
-            if(sel && box){
+            var inv = document.getElementById('internalHandlerFields');
+            if(sel){
               sel.addEventListener('change', function(){
-                box.style.display = (this.value === 'facility') ? '' : 'none';
+                if(box){ box.style.display = (this.value === 'facility') ? '' : 'none'; }
+                if(inv){ inv.style.display = (this.value === 'internal') ? '' : 'none'; }
               });
             }
           })();

app/utils/forms.py

@@ -206,6 +206,23 @@ class IssueForm(FlaskForm):
         FileAllowed(['jpg','jpeg','png','gif'], 'Images only.')
     ])
     assigned_to = SelectField('Assign To', coerce=int, validators=[Optional()])
+    # Who handles the issue (phase44) — set at creation by staff. MT previously
+    # exposed these only on the update form, so a handler chosen at creation had
+    # to be re-entered afterwards.
+    handler_type = SelectField('Handled By', choices=[
+        ('internal', 'Janitorial Staff'),
+        ('facility', 'Facility Staff'),
+        ('vendor',   'External Vendor'),
+    ], validators=[Optional()])
+    facility_handler_name    = StringField('Facility Contact Name', validators=[Optional(), Length(max=100)])
+    facility_handler_contact = StringField('Facility Contact', validators=[Optional(), Length(max=200)])
+    facility_handler_notes   = TextAreaField('Facility Handling Notes', validators=[Optional(), Length(max=1000)])
+    vendor_name    = StringField('Contractor Name', validators=[Optional(), Length(max=100)])
+    vendor_contact = StringField('Contractor Contact', validators=[Optional(), Length(max=200)])
+    vendor_notes   = TextAreaField('Contractor Notes', validators=[Optional(), Length(max=1000)])
+    # Janitorial staff member's name + contact — used when handler_type == 'internal'
+    internal_handler_name    = StringField('Staff Name', validators=[Optional(), Length(max=100)])
+    internal_handler_contact = StringField('Staff Contact', validators=[Optional(), Length(max=200)])
 
 
 class IssueUpdateForm(FlaskForm):
@@ -224,9 +241,9 @@ class IssueUpdateForm(FlaskForm):
     vendor_name    = StringField('Contractor Name', validators=[Optional(), Length(max=100)])
     vendor_contact = StringField('Contractor Contact', validators=[Optional(), Length(max=200)])
     vendor_notes   = TextAreaField('Contractor Notes', validators=[Optional(), Length(max=1000)])
-    # Handler type (phase39)
+    # Handler type (phase39; empty option removed phase44 — handler_type is now
+    # NOT NULL DEFAULT 'internal', so "unset" is not a representable state)
     handler_type             = SelectField('Handled By', choices=[
-        ('', '— Select —'),
         ('internal', 'Janitorial Staff'),
         ('facility', 'Facility Staff'),
         ('vendor',   'External Vendor'),
@@ -234,6 +251,9 @@ class IssueUpdateForm(FlaskForm):
     facility_handler_name    = StringField('Facility Contact Name',       validators=[Optional(), Length(max=100)])
     facility_handler_contact = StringField('Facility Contact Phone/Email', validators=[Optional(), Length(max=200)])
     facility_handler_notes   = TextAreaField('Facility Handler Notes',    validators=[Optional(), Length(max=1000)])
+    # Janitorial staff member's name + contact — used when handler_type == 'internal' (phase44)
+    internal_handler_name    = StringField('Staff Name',    validators=[Optional(), Length(max=100)])
+    internal_handler_contact = StringField('Staff Contact', validators=[Optional(), Length(max=200)])
 
 # ── Projects ─────────────────────────────────────────────────────────────────
 

migrations/versions/phase44_internal_handler.py

@@ -0,0 +1,110 @@
+"""phase44 — issue internal_handler_name / internal_handler_contact,
+and convergence of handler_type to NOT NULL DEFAULT 'internal'
+
+Ports single-tenant phase41 + phase42 into the multi-tenant chain, and closes the
+last divergence in the handler model.
+
+1. Adds `internal_handler_name` and `internal_handler_contact` to `issues`,
+   capturing the janitorial staff member who will handle an issue when
+   handler_type == 'internal'. Distinct from `assigned_to` (the JQC User who owns
+   follow-up) — the actual crew member may not be a system user. Parallels the
+   existing facility_handler_* and vendor_* contact pairs.
+
+2. Converges `handler_type` from MT's `NULL`-able column onto the single-tenant
+   definition, `NOT NULL DEFAULT 'internal'`. MT's application code already
+   treats NULL and 'internal' as the same thing (`handler_type or 'internal'`
+   appears in the model property, the API payload and the templates), so this
+   only removes a redundant second representation of "internal". Existing NULL
+   rows are backfilled to 'internal' BEFORE the MODIFY, otherwise the ALTER
+   fails on a table containing NULLs.
+
+RE-RUNNABLE. Step 1 uses an INFORMATION_SCHEMA column-existence check. Step 2
+cannot use one — the column already exists; what changes is its nullability — so
+it checks IS_NULLABLE instead and skips when the column is already NOT NULL.
+Checking only for existence there would silently make this migration a no-op on
+re-run against a half-applied schema.
+
+No batch_alter_table (MySQL).
+"""
+
+revision      = 'phase44_internal_handler'
+down_revision = 'phase43_schedule_plan_fields'
+branch_labels = None
+depends_on    = None
+
+from alembic import op
+import sqlalchemy as sa
+
+
+def _column_exists(conn, table, column):
+    result = conn.execute(sa.text(
+        "SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS "
+        "WHERE TABLE_SCHEMA = DATABASE() "
+        "AND TABLE_NAME = :t AND COLUMN_NAME = :c"
+    ), {"t": table, "c": column})
+    return result.scalar() > 0
+
+
+def _column_is_nullable(conn, table, column):
+    """True when the column exists AND is declared NULL-able.
+
+    Returns False for a missing column so callers never attempt to MODIFY
+    something that isn't there.
+    """
+    result = conn.execute(sa.text(
+        "SELECT IS_NULLABLE FROM INFORMATION_SCHEMA.COLUMNS "
+        "WHERE TABLE_SCHEMA = DATABASE() "
+        "AND TABLE_NAME = :t AND COLUMN_NAME = :c"
+    ), {"t": table, "c": column})
+    row = result.first()
+    return bool(row) and row[0] == 'YES'
+
+
+def upgrade():
+    bind = op.get_bind()
+
+    # ── 1. internal_handler_name ──────────────────────────────────────────
+    if not _column_exists(bind, 'issues', 'internal_handler_name'):
+        op.execute(sa.text(
+            "ALTER TABLE issues ADD COLUMN internal_handler_name VARCHAR(100) NULL"
+        ))
+
+    # ── 2. internal_handler_contact ───────────────────────────────────────
+    if not _column_exists(bind, 'issues', 'internal_handler_contact'):
+        op.execute(sa.text(
+            "ALTER TABLE issues ADD COLUMN internal_handler_contact VARCHAR(200) NULL"
+        ))
+
+    # ── 3. handler_type -> NOT NULL DEFAULT 'internal' ────────────────────
+    # Backfill first: MODIFY ... NOT NULL fails outright if any row holds NULL.
+    # This runs unconditionally (it is itself idempotent — a second run matches
+    # zero rows) so the data is correct even if a previous attempt aborted
+    # between the UPDATE and the ALTER.
+    if _column_is_nullable(bind, 'issues', 'handler_type'):
+        op.execute(sa.text(
+            "UPDATE issues SET handler_type = 'internal' WHERE handler_type IS NULL"
+        ))
+        op.execute(sa.text(
+            "ALTER TABLE issues MODIFY COLUMN handler_type "
+            "ENUM('internal','facility','vendor') NOT NULL DEFAULT 'internal'"
+        ))
+
+
+def downgrade():
+    bind = op.get_bind()
+
+    # Revert handler_type to nullable with no default. Stored values are left
+    # as-is: rows that were NULL before the upgrade are now 'internal', which is
+    # semantically identical under the application's `handler_type or 'internal'`
+    # reads, so there is nothing to undo in the data.
+    if not _column_is_nullable(bind, 'issues', 'handler_type'):
+        op.execute(sa.text(
+            "ALTER TABLE issues MODIFY COLUMN handler_type "
+            "ENUM('internal','facility','vendor') NULL"
+        ))
+
+    if _column_exists(bind, 'issues', 'internal_handler_contact'):
+        op.execute(sa.text("ALTER TABLE issues DROP COLUMN internal_handler_contact"))
+
+    if _column_exists(bind, 'issues', 'internal_handler_name'):
+        op.execute(sa.text("ALTER TABLE issues DROP COLUMN internal_handler_name"))