Improve user experience for person entity configuration.

Author: ronnnnnnnnnnnnn

custom_components/renpho_fitness_scale_ble/config_flow.py

@@ -16,7 +16,12 @@
     async_discovered_service_info,
 )
 from homeassistant.config_entries import ConfigEntry, ConfigFlow, OptionsFlow
-from homeassistant.const import CONF_ADDRESS, UnitOfLength, UnitOfMass
+from homeassistant.const import (
+    CONF_ADDRESS,
+    STATE_UNKNOWN,
+    UnitOfLength,
+    UnitOfMass,
+)
 from homeassistant.data_entry_flow import FlowResult
 from homeassistant.helpers import (
     config_validation as cv,
@@ -166,6 +171,26 @@ def _validate_person_entity_unique(
     return True
 
 
+def _validate_person_entity_has_tracker(hass, person_entity: str | None) -> bool:
+    """A person entity is only useful here if it can report a location.
+
+    A ``person.X`` with no device trackers assigned sits in state
+    ``unknown``; linking it would do nothing (location-based matching only
+    skips a user when their person is ``not_home``). Reject that so users
+    don't configure an inert link. ``unavailable`` is treated as
+    acceptable — it's typically transient (HA restart, brief tracker
+    outage), and blocking on it would be a flaky validation. A missing
+    state is also accepted (the entity selector only offers existing
+    entities, so this is purely defensive).
+    """
+    if not person_entity:
+        return True
+    state = hass.states.get(person_entity)
+    if state is None:
+        return True
+    return state.state != STATE_UNKNOWN
+
+
 def _get_mobile_notify_services(hass) -> dict[str, str]:
     services: dict[str, str] = {}
     for service_name in hass.services.async_services().get("notify", {}):
@@ -435,9 +460,14 @@ async def async_step_add_first_user(
     ) -> FlowResult:
         if user_input is not None:
             user_name = user_input[CONF_USER_NAME]
+            person_entity = user_input.get(CONF_PERSON_ENTITY)
             errors: dict[str, str] = {}
             if not _validate_user_name_not_empty(user_name):
                 errors["base"] = "empty_user_name"
+            if person_entity and not _validate_person_entity_has_tracker(
+                self.hass, person_entity
+            ):
+                errors["person_entity"] = "person_entity_no_tracker"
             if errors:
                 return self.async_show_form(
                     step_id="add_first_user",
@@ -447,14 +477,14 @@ async def async_step_add_first_user(
             body_metrics = user_input.get(CONF_BODY_METRICS_ENABLED, False)
             if body_metrics:
                 self.context[CONF_USER_NAME] = user_name
-                self.context[CONF_PERSON_ENTITY] = user_input.get(CONF_PERSON_ENTITY)
+                self.context[CONF_PERSON_ENTITY] = person_entity
                 self.context[CONF_MOBILE_NOTIFY_SERVICES] = user_input.get(
                     CONF_MOBILE_NOTIFY_SERVICES, []
                 )
                 return await self.async_step_add_first_user_body_metrics()
             return self._create_entry_with_first_user(
                 user_name=user_name,
-                person_entity=user_input.get(CONF_PERSON_ENTITY),
+                person_entity=person_entity,
                 mobile_services=user_input.get(CONF_MOBILE_NOTIFY_SERVICES, []),
                 body_metrics_enabled=False,
                 body_metrics_fields=None,
@@ -568,6 +598,10 @@ async def async_step_add_user(
                 person_entity, self.user_profiles
             ):
                 errors["person_entity"] = "duplicate_person_entity"
+            elif person_entity and not _validate_person_entity_has_tracker(
+                self.hass, person_entity
+            ):
+                errors["person_entity"] = "person_entity_no_tracker"
             if errors:
                 return self.async_show_form(
                     step_id="add_user",
@@ -679,6 +713,10 @@ async def async_step_edit_user_details(
                 exclude_user_id=selected_user_id,
             ):
                 errors["person_entity"] = "duplicate_person_entity"
+            elif person_entity and not _validate_person_entity_has_tracker(
+                self.hass, person_entity
+            ):
+                errors["person_entity"] = "person_entity_no_tracker"
             if errors:
                 return self.async_show_form(
                     step_id="edit_user_details",

custom_components/renpho_fitness_scale_ble/repairs.py

@@ -12,12 +12,18 @@
 mean the location signal the user *configured* isn't doing anything,
 and the integration falls back to weight-only matching for that user.
 
-``mobile_service_missing`` and ``person_entity_missing`` are fixable
-in-place — the right one-click action is unambiguous (drop the stale
-entry / clear the broken link). ``person_entity_unknown`` is left
-non-fixable because the right remediation usually isn't clearing the
-link, it's assigning a tracker to the existing person; that's a
-decision the user has to make.
+``mobile_service_missing``, ``person_entity_missing``, and
+``person_entity_unknown`` are all fixable in-place with a one-click
+"clear the link / drop the stale entry" action. For the two person
+cases, clearing isn't the *only* remediation (relinking, or assigning a
+device tracker, also resolves them), but it's a safe unambiguous default
+we can offer directly — the fix-flow text points at the alternatives.
+
+The person-entity issues are only raised when the integration has 2+
+users configured. The location filter that consumes the link only runs
+in the multi-user resolver path (see ``_select_library_mode_argument``),
+so with a single user a linked person is inert and warning about it
+would be pure noise.
 
 Issue types:
 
@@ -30,16 +36,17 @@
     Configure remains available for users who want to point at a new
     entity instead.
 
-- ``person_entity_unknown_<entry_id>_<user_id>`` *(non-fixable)*
+- ``person_entity_unknown_<entry_id>_<user_id>`` *(fixable)*
     The linked ``person.X`` exists but its state is ``unknown`` — the
     person was created in HA but no device trackers have been assigned
     to it. Same runtime impact as the missing case (not excluded, just
     no useful location signal). Surfaced as a warning so the user knows
-    their configuration is degraded. Left non-fixable because the right
-    remediation is usually "assign a tracker", not "clear the link".
-    ``unavailable`` is deliberately *not* flagged because it's typically
-    transient (HA restart, brief tracker outage); raising a flapping
-    issue every reload would just be noise.
+    their configuration is degraded. The fix flow clears the link (the
+    right move for a household that doesn't use location-based matching);
+    the fix-flow text also points at the alternative of assigning a
+    device tracker instead. ``unavailable`` is deliberately *not* flagged
+    because it's typically transient (HA restart, brief tracker outage);
+    raising a flapping issue every reload would just be noise.
 
 - ``mobile_service_missing_<entry_id>_<user_id>_<service_slug>`` *(fixable)*
     A configured ``notify.mobile_app_*`` service no longer exists.
@@ -78,6 +85,7 @@
 
 _REPAIR_KIND_MOBILE_SERVICE_MISSING = "mobile_service_missing"
 _REPAIR_KIND_PERSON_ENTITY_MISSING = "person_entity_missing"
+_REPAIR_KIND_PERSON_ENTITY_UNKNOWN = "person_entity_unknown"
 
 
 def _person_entity_missing_issue_id(entry_id: str, user_id: str) -> str:
@@ -118,6 +126,12 @@ def async_scan_repair_issues(hass: HomeAssistant, entry: ConfigEntry) -> None:
     # currently in the registry to figure out what to add/remove.
     desired: dict[str, dict[str, Any]] = {}
 
+    # The location filter that consumes a linked person entity only runs in
+    # the multi-user resolver path. With a single user the link is inert, so
+    # the person-entity issues below would be pure noise — only raise them
+    # when 2+ users are configured.
+    multi_user = sum(1 for p in profiles if p.get(CONF_USER_ID)) >= 2
+
     for profile in profiles:
         user_id = profile.get(CONF_USER_ID, "")
         user_name = profile.get(CONF_USER_NAME, user_id)
@@ -129,7 +143,7 @@ def async_scan_repair_issues(hass: HomeAssistant, entry: ConfigEntry) -> None:
         #    exact "not_home"), but the configured link isn't providing the
         #    location signal the user expected.
         person_entity = profile.get(CONF_PERSON_ENTITY)
-        if person_entity:
+        if multi_user and person_entity:
             person_state = hass.states.get(person_entity)
             if person_state is None:
                 # Entity gone (deleted in Settings → People). Fixable:
@@ -153,7 +167,10 @@ def async_scan_repair_issues(hass: HomeAssistant, entry: ConfigEntry) -> None:
             elif person_state.state == STATE_UNKNOWN:
                 # Entity exists but has no working tracker — almost
                 # always permanent. (We don't flag STATE_UNAVAILABLE
-                # because that's typically transient.)
+                # because that's typically transient.) Fixable: clearing
+                # the inert link is the right move for a household that
+                # doesn't use location-based matching; the fix-flow text
+                # points at assigning a tracker as the alternative.
                 issue_id = _person_entity_unknown_issue_id(entry.entry_id, user_id)
                 desired[issue_id] = {
                     "translation_key": "person_entity_unknown",
@@ -162,6 +179,12 @@ def async_scan_repair_issues(hass: HomeAssistant, entry: ConfigEntry) -> None:
                         "person_entity": person_entity,
                     },
                     "severity": ir.IssueSeverity.WARNING,
+                    "is_fixable": True,
+                    "data": {
+                        "kind": _REPAIR_KIND_PERSON_ENTITY_UNKNOWN,
+                        "entry_id": entry.entry_id,
+                        "user_id": user_id,
+                    },
                 }
 
         # 2. Mobile notify services that no longer exist. Fixable in-place:
@@ -237,12 +260,15 @@ def async_clear_repair_issues_for_entry(
 
 
 class _ClearPersonEntityRepairFlow(RepairsFlow):
-    """Clear a broken person_entity link from a user profile.
+    """Clear a person_entity link from a user profile.
 
     Called from the Repairs UI when the user clicks **Submit** on a
-    ``person_entity_missing`` issue. Clearing is unambiguous; users who
-    want to point at a different person entity instead can do that via
-    Configure → Edit User.
+    ``person_entity_missing`` issue (entity deleted) or a
+    ``person_entity_unknown`` issue (entity exists but has no working
+    tracker). In both cases the link is inert, so clearing it is a safe
+    unambiguous action; users who want to point at a different person
+    entity, or to assign a tracker instead, can do that via
+    Configure → Edit User / Settings → People.
     """
 
     def __init__(self, entry_id: str, user_id: str) -> None:
@@ -372,7 +398,10 @@ async def async_create_fix_flow(
                 user_id=data["user_id"],
                 service=data["service"],
             )
-        if kind == _REPAIR_KIND_PERSON_ENTITY_MISSING:
+        if kind in (
+            _REPAIR_KIND_PERSON_ENTITY_MISSING,
+            _REPAIR_KIND_PERSON_ENTITY_UNKNOWN,
+        ):
             return _ClearPersonEntityRepairFlow(
                 entry_id=data["entry_id"],
                 user_id=data["user_id"],

custom_components/renpho_fitness_scale_ble/strings.json

@@ -25,6 +25,9 @@
           "person_entity": "Person entity (optional)",
           "mobile_notify_services": "Mobile devices for notifications",
           "body_metrics_enabled": "Calculate body composition metrics"
+        },
+        "data_description": {
+          "person_entity": "Only used when this scale has multiple users, to skip this user when their linked person is away from home at weigh-in time. Requires the person to have a working device tracker (e.g. their phone via the Home Assistant companion app). Leave blank to match by weight only."
         }
       },
       "add_first_user_body_metrics": {
@@ -52,6 +55,7 @@
     "error": {
       "empty_user_name": "User name cannot be empty.",
       "duplicate_person_entity": "Another user is already linked to this person entity.",
+      "person_entity_no_tracker": "This person has no device tracker, so location-based matching can't use it. Assign a device tracker in Settings → People first (typically their phone via the Home Assistant companion app), or leave this field blank.",
       "user_id_generation_failed": "Could not generate a unique user ID. Try a different name.",
       "invalid_user_name": "Invalid user name."
     }
@@ -76,6 +80,9 @@
           "person_entity": "Person entity (optional)",
           "mobile_notify_services": "Mobile devices for notifications",
           "body_metrics_enabled": "Calculate body composition metrics"
+        },
+        "data_description": {
+          "person_entity": "Only used when this scale has multiple users, to skip this user when their linked person is away from home at weigh-in time. Requires the person to have a working device tracker (e.g. their phone via the Home Assistant companion app). Leave blank to match by weight only."
         }
       },
       "add_user_body_metrics": {
@@ -107,6 +114,9 @@
           "person_entity": "Person entity (optional)",
           "mobile_notify_services": "Mobile devices for notifications",
           "body_metrics_enabled": "Calculate body composition metrics"
+        },
+        "data_description": {
+          "person_entity": "Only used when this scale has multiple users, to skip this user when their linked person is away from home at weigh-in time. Requires the person to have a working device tracker (e.g. their phone via the Home Assistant companion app). Leave blank to match by weight only."
         }
       },
       "edit_user_body_metrics": {
@@ -149,7 +159,8 @@
     },
     "error": {
       "empty_user_name": "User name cannot be empty.",
-      "duplicate_person_entity": "Another user is already linked to this person entity."
+      "duplicate_person_entity": "Another user is already linked to this person entity.",
+      "person_entity_no_tracker": "This person has no device tracker, so location-based matching can't use it. Assign a device tracker in Settings → People first (typically their phone via the Home Assistant companion app), or leave this field blank."
     }
   },
   "selector": {
@@ -175,7 +186,15 @@
     },
     "person_entity_unknown": {
       "title": "{user_name}: linked person has no location",
-      "description": "User **{user_name}** is linked to person entity `{person_entity}`, but that person has no working device trackers, so its state is `unknown`. Auto-assignment continues using weight matching — the link doesn't actively cause a problem — but location-based filtering for this user is effectively disabled until a tracker is assigned.\n\nFix it by either:\n\n- Going to **Settings → People**, opening `{person_entity}`, and assigning a device tracker to it (typically the user's phone via the Home Assistant companion app), **or**\n- Going to **Settings → Devices & Services → Renpho Fitness Scale BLE → Configure** and clearing the **Person Entity** field on this user's profile if you don't plan to set up a tracker."
+      "fix_flow": {
+        "step": {
+          "confirm": {
+            "title": "Clear the person entity link?",
+            "description": "User **{user_name}** is linked to person entity `{person_entity}`, but that person has no working device trackers, so its state is `unknown`. Location-based matching only skips a user when their person is `not_home`, so with no tracker this link does nothing — auto-assignment is already using weight-only matching for this user.\n\nIf you don't use location-based matching (for example, everyone is usually home at weigh-in time), clearing this link is safe and removes this warning.\n\nPrefer to keep it? Assign a device tracker to `{person_entity}` in **Settings → People** instead (typically the user's phone via the Home Assistant companion app), and this warning will clear on its own.\n\nThis will clear the link from the profile.",
+            "submit": "Clear"
+          }
+        }
+      }
     },
     "mobile_service_missing": {
       "title": "{user_name}: mobile notify service `{service}` not found",