From f8807dc371cb6f7c92aebb0a405dc4f77f9a55c0 Mon Sep 17 00:00:00 2001 From: NguyenND Date: Thu, 9 Jul 2026 10:49:55 -0400 Subject: [PATCH] Jul 9 - Update the 'Handled by' more clear and understandable --- CLAUDE.md | 4 +++- app/models/issue.py | 10 ++++++++-- app/templates/issues/form.html | 8 ++++++++ app/templates/issues/list.html | 2 +- app/templates/issues/view.html | 15 ++++++++++++--- app/utils/forms.py | 4 ++-- docs/manual_updates_customer.md | 6 +++--- docs/manual_updates_inspector_mobile.md | 2 +- docs/manual_updates_web_inspector.md | 4 ++-- 9 files changed, 40 insertions(+), 15 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index ec839b0..e15bffa 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -256,10 +256,12 @@ issues: id, inspection_id (nullable), area_id, facility_id (nullable), severity | Value | Meaning | Detail fields | `assigned_to` role | |---|---|---|---| -| `internal` (default) | Our staff | — (the assignee IS the handler) | the handler | +| `internal` (default) | Janitorial Staff (our crew) | — (the assignee IS the handler) | the handler | | `facility` | The facility's own staff | `facility_handler_name/contact/notes` (free text) | internal **follow-up owner** | | `vendor` | External contractor | `vendor_name/contact/notes` (Phase 26) | internal **follow-up owner** | +**Display labels are perspective-neutral** (they read the same for staff and customers) with a descriptor line under the selector and a tooltip on badges: `internal` → **"Janitorial Staff"** ("Our janitorial crew handles it."), `facility` → **"Facility Staff"** ("The facility's own on-site staff handle it."), `vendor` → **"External Vendor"** ("An outside contractor handles it."). Labels/descriptions live in `Issue.HANDLER_LABELS` / `HANDLER_DESCRIPTIONS`, the WTForms `handler_type` choices, and the `HANDLER_DESC` JS map in both issue templates — keep these in sync. Do **not** use viewer-relative words like "Our"/"Your" for the stored categories. + `assigned_to` (a JQC User) is **always** available: it is the handler for `internal`, and the internal follow-up owner (e.g. the inspector who verifies/updates) for `facility`/`vendor`. Settable in **two places**, both with a "Handled By" selector that reveals the facility or vendor sub-fields via JS: - **Log New Issue** form (`issues/form.html`) — at creation, for non-customer staff. Customer-created issues stay `internal` (the handler UI is hidden for them, same as `assigned_to`). - **Update Issue** panel on the issue detail page (`issues/view.html`) — triage after creation. diff --git a/app/models/issue.py b/app/models/issue.py index de1f113..ac638f9 100644 --- a/app/models/issue.py +++ b/app/models/issue.py @@ -115,15 +115,21 @@ class Issue(db.Model): return self.followers.filter_by(user_id=user.id).first() is not None # Human-readable label for the handler category (phase35). + # Perspective-neutral wording so it reads the same for staff and customers. HANDLER_LABELS = { - 'internal': 'Our Staff', + 'internal': 'Janitorial Staff', 'facility': 'Facility Staff', 'vendor': 'External Vendor', } + 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): - return self.HANDLER_LABELS.get(self.handler_type or 'internal', 'Our Staff') + return self.HANDLER_LABELS.get(self.handler_type or 'internal', 'Janitorial Staff') @property def resolved_facility(self): diff --git a/app/templates/issues/form.html b/app/templates/issues/form.html index 757dc01..486db35 100644 --- a/app/templates/issues/form.html +++ b/app/templates/issues/form.html @@ -41,6 +41,7 @@
{{ form.handler_type.label(class="form-label fw-semibold") }} {{ form.handler_type(class="form-select", id="handler_type_select") }} +
@@ -157,6 +158,11 @@ // ── "Handled By" — reveal the facility/vendor sub-block + relabel assignee ── var handlerSelect = document.getElementById('handler_type_select'); + var HANDLER_DESC = { + 'internal': 'Our janitorial crew handles it.', + 'facility': "The facility's own on-site staff handle it.", + 'vendor': 'An outside contractor handles it.' + }; function syncHandlerUI() { if (!handlerSelect) { return; } var v = handlerSelect.value; @@ -164,6 +170,8 @@ var venBlock = document.getElementById('vendor_block'); if (facBlock) { facBlock.style.display = (v === 'facility') ? '' : 'none'; } if (venBlock) { venBlock.style.display = (v === 'vendor') ? '' : 'none'; } + var desc = document.getElementById('handler_desc'); + if (desc) { desc.textContent = HANDLER_DESC[v] || ''; } var label = document.getElementById('assigned_to_label'); var help = document.getElementById('assigned_to_help'); if (label) { diff --git a/app/templates/issues/list.html b/app/templates/issues/list.html index 0671103..ce8da54 100644 --- a/app/templates/issues/list.html +++ b/app/templates/issues/list.html @@ -86,7 +86,7 @@ diff --git a/app/templates/issues/view.html b/app/templates/issues/view.html index 733161f..79ce957 100644 --- a/app/templates/issues/view.html +++ b/app/templates/issues/view.html @@ -76,11 +76,11 @@
Handled By
{% if issue.handler_type == 'facility' %} - Facility Staff + Facility Staff {% elif issue.handler_type == 'vendor' %} - External Vendor + External Vendor {% else %} - Our Staff + Janitorial Staff {% endif %}
@@ -373,6 +373,7 @@
{{ form.handler_type.label(class="form-label fw-semibold") }} {{ form.handler_type(class="form-select", id="handler_type_select") }} +
{% endif %} @@ -549,6 +550,11 @@ // ── "Handled By" — show the relevant sub-block (facility vs vendor) and // relabel the assignee as a follow-up owner for facility/vendor. ── var handlerSelect = document.getElementById('handler_type_select'); + var HANDLER_DESC = { + 'internal': 'Our janitorial crew handles it.', + 'facility': "The facility's own on-site staff handle it.", + 'vendor': 'An outside contractor handles it.' + }; function syncHandlerUI() { if (!handlerSelect) { return; } var v = handlerSelect.value; @@ -557,6 +563,9 @@ if (facBlock) { facBlock.style.display = (v === 'facility') ? '' : 'none'; } if (venBlock) { venBlock.style.display = (v === 'vendor') ? '' : 'none'; } + var desc = document.getElementById('handler_desc'); + if (desc) { desc.textContent = HANDLER_DESC[v] || ''; } + var label = document.getElementById('assigned_to_label'); var help = document.getElementById('assigned_to_help'); if (label) { diff --git a/app/utils/forms.py b/app/utils/forms.py index 6e74d7a..8a2eaaf 100644 --- a/app/utils/forms.py +++ b/app/utils/forms.py @@ -173,7 +173,7 @@ class IssueForm(FlaskForm): assigned_to = SelectField('Assign To', coerce=int, validators=[Optional()]) # Who handles the issue (phase35) — set at creation by staff handler_type = SelectField('Handled By', choices=[ - ('internal', 'Our Staff'), + ('internal', 'Janitorial Staff'), ('facility', 'Facility Staff'), ('vendor', 'External Vendor'), ], validators=[Optional()]) @@ -199,7 +199,7 @@ class IssueUpdateForm(FlaskForm): ]) # Who handles the issue (phase35) handler_type = SelectField('Handled By', choices=[ - ('internal', 'Our Staff'), + ('internal', 'Janitorial Staff'), ('facility', 'Facility Staff'), ('vendor', 'External Vendor'), ], validators=[Optional()]) diff --git a/docs/manual_updates_customer.md b/docs/manual_updates_customer.md index 95853b3..cd8cb94 100644 --- a/docs/manual_updates_customer.md +++ b/docs/manual_updates_customer.md @@ -68,9 +68,9 @@ notified immediately. You'll see a confirmation message when it's received. When you view an issue, it now shows **Handled By**, indicating who is responsible for resolving it: -- **Our Staff** — a member of the janitorial quality-control team. -- **Facility Staff** — the facility's own on-site staff are handling it. -- **External Vendor** — an outside contractor has been engaged. +- **Janitorial Staff** — our janitorial crew handles it. +- **Facility Staff** — the facility's own on-site staff handle it. +- **External Vendor** — an outside contractor handles it. In every case, one of our team members remains the **follow-up owner** who verifies the work and updates the issue. You do not set this field — it is diff --git a/docs/manual_updates_inspector_mobile.md b/docs/manual_updates_inspector_mobile.md index 3c94b4f..e11d6ac 100644 --- a/docs/manual_updates_inspector_mobile.md +++ b/docs/manual_updates_inspector_mobile.md @@ -10,7 +10,7 @@ unchanged: - **Scheduled inspections** — created and executed through the web app. The iPad app has no scheduled-inspection list or "Start from schedule" action. -- **Issue "Handled By" (Our Staff / Facility Staff / External Vendor)** — set and +- **Issue "Handled By" (Janitorial Staff / Facility Staff / External Vendor)** — set and displayed on the web only. The mobile issue screens are unchanged. - **Facility QR codes / occupant report-a-problem** — a public web page; not part of the inspector app. diff --git a/docs/manual_updates_web_inspector.md b/docs/manual_updates_web_inspector.md index 1b0bbb3..890e010 100644 --- a/docs/manual_updates_web_inspector.md +++ b/docs/manual_updates_web_inspector.md @@ -61,8 +61,8 @@ who follows up: | Handled By | Meaning | |---|---| -| **Our Staff** | A JQC team member resolves it. | -| **Facility Staff** | The facility's own staff handle it (their contact is recorded on the issue). | +| **Janitorial Staff** | Our janitorial crew resolves it. | +| **Facility Staff** | The facility's own on-site staff handle it (their contact is recorded on the issue). | | **External Vendor** | An outside contractor handles it (vendor details are recorded on the issue). | Regardless of who does the work, **one of our staff is always the follow-up