Fix airflow fan power-href preference and unique_id collision risk

Opus review of the previous commit caught two real bugs. The airflow fan's
power writes preferred /power/vs/0, copied from the TP1X fan class -- but
that order is only harmless there because TP1X never reports /power/0 at
all. This family's dumps carry both hrefs, and the power_switch entity is
unconditionally bound to /power/0 when present, so the fan was writing to
a different resource than power_switch reads/writes, leaving the two
entities disagreeing until the next poll. Flipped to prefer /power/0,
matching the range hood's fan and common.POWER_GENERIC.

Also renamed the new FanDesc's key from 'fan' to 'airflow_fan': BoundEntity
unique_ids are derived from key alone, not href, so it collided with
air_purifier.FAN's own 'fan' key on the (currently unobserved, but
unenforced) possibility of a board reporting both.

Added a platform-level test file covering the power-href preference and
percentage<->speed-code mapping, mirroring test_range_hood_fan.py's harness.

tests/fixtures/golden/air_purifier.json

@@ -1,5 +1,6 @@
 {
   "state_keys": [
+    "airflow_fan",
     "alarm_code",
     "clean_level",
     "device_active",
@@ -10,7 +11,6 @@
     "energy_last_month_kwh",
     "energy_saved_kwh",
     "energy_this_month_kwh",
-    "fan",
     "fan_direction",
     "filter_progress",
     "fine_dust",

tests/test_air_purifier_airflow_fan.py

@@ -0,0 +1,105 @@
+"""HA fan-entity mapping tests for the ARTIK051_TVTL air purifier (issue #56)."""
+
+from custom_components.localthings.fan import LocalThingsAirflowFan
+from custom_components.localthings.registry.by_type import air_purifier
+from custom_components.localthings.registry.capabilities.air_purifier import HREF_AIRFLOW
+from custom_components.localthings.registry.discovery import discover
+from custom_components.localthings.registry.entities import FanDesc
+from tests.conftest import _load_device
+
+
+class _FakeCoordinator:
+    device_serial = 'TEST-AIRFLOW-SERIAL'
+    device_info = {}
+    data = {}
+
+    def __init__(self, resources):
+        self.last_resources = resources
+        self.commands = []
+
+    def resource(self, href):
+        return self.last_resources.get(href, {})
+
+    async def async_send_command(self, bound, payload):
+        self.commands.append((bound, payload))
+
+
+def _entity(resources, coordinator=None):
+    bound = discover(
+        resources,
+        air_purifier.REGISTRY.capabilities,
+        air_purifier.REGISTRY.pattern_capabilities,
+    )
+    fan_bound = next(
+        item for item in bound
+        if isinstance(item.desc, FanDesc) and item.href == HREF_AIRFLOW
+    )
+    return LocalThingsAirflowFan(
+        coordinator or _FakeCoordinator(resources), fan_bound,
+    )
+
+
+def test_power_off_maps_to_zero_percent_and_five_retained_speeds():
+    entity = _entity(_load_device('air_purifier'))
+    assert entity.is_on is False
+    assert entity.speed_count == 5
+    assert entity.percentage == 0
+
+
+def test_active_codes_map_to_ordered_percentages():
+    """Confirmed via issue #56's second, properly-spaced diagnostics round:
+    /airflow/0's speed is a clean 0-4 code across Auto/Sleep/Low/Medium/High."""
+    resources = _load_device('air_purifier')
+    resources['/power/0']['value'] = True
+
+    for code, expected_percentage in ((0, 20), (1, 40), (2, 60), (3, 80), (4, 100)):
+        resources['/airflow/0']['speed'] = code
+        assert _entity(resources).percentage == expected_percentage
+
+
+async def test_power_write_prefers_standard_resource_when_both_exist():
+    """Both /power/0 and /power/vs/0 are present on this family's dumps --
+    /power/0 must win, matching common.POWER_GENERIC's own preference (the
+    power_switch entity is unconditionally bound to /power/0 whenever it's
+    present, so writing here to /power/vs/0 first would leave the two
+    entities disagreeing until the next poll)."""
+    resources = _load_device('air_purifier')
+    coordinator = _FakeCoordinator(resources)
+    entity = _entity(resources, coordinator)
+
+    await entity.async_turn_on()
+
+    assert coordinator.commands[-1][1] == ('power', True, '/power/0')
+
+
+async def test_power_write_falls_back_to_vendor_resource():
+    resources = _load_device('air_purifier')
+    resources.pop('/power/0')
+    coordinator = _FakeCoordinator(resources)
+    entity = _entity(resources, coordinator)
+
+    await entity.async_turn_off()
+
+    assert coordinator.commands[-1][1] == ('power', False, '/power/vs/0')
+
+
+async def test_set_percentage_writes_raw_speed_code():
+    resources = _load_device('air_purifier')
+    resources['/power/0']['value'] = True
+    coordinator = _FakeCoordinator(resources)
+    entity = _entity(resources, coordinator)
+
+    await entity.async_set_percentage(60)
+
+    assert coordinator.commands[-1][1] == ('speed', 2)
+
+
+async def test_set_percentage_zero_turns_off():
+    resources = _load_device('air_purifier')
+    resources['/power/0']['value'] = True
+    coordinator = _FakeCoordinator(resources)
+    entity = _entity(resources, coordinator)
+
+    await entity.async_set_percentage(0)
+
+    assert coordinator.commands[-1][1] == ('power', False, '/power/0')

tests/test_air_purifier_capabilities.py

@@ -41,7 +41,7 @@ def test_expected_entities_present():
     for key in (
         'power_switch', 'alarm_code', 'dust', 'fine_dust', 'super_fine_dust',
         'odor', 'clean_level', 'filter_progress', 'device_active',
-        'diagnosis_status', 'fan', 'fan_direction',
+        'diagnosis_status', 'airflow_fan', 'fan_direction',
         'display_light', 'operating_mode',
     ):
         assert key in state, key
@@ -121,7 +121,7 @@ def test_airflow_fan_write_contract():
     (two independent units, 60-90s apart per setting): /airflow/0's `speed`
     is a clean, monotonic 0-4 code, so the write is a plain int passthrough
     -- no named-preset table needed (see fan.py's LocalThingsAirflowFan)."""
-    fan_desc = next(e for e in air_purifier.AIRFLOW_GENERIC.entities if e.key == 'fan')
+    fan_desc = next(e for e in air_purifier.AIRFLOW_GENERIC.entities if e.key == 'airflow_fan')
     assert fan_desc.write_fn(('speed', 3), {}) == (['airflow', '0'], {'speed': 3})
     assert fan_desc.write_fn(('power', True, '/power/vs/0'), {}) == (
         ['power', 'vs', '0'], {'x.com.samsung.da.power': 'On'},
@@ -136,5 +136,5 @@ def test_airflow_speed_reads_from_dump():
     fan_direction stays a plain diagnostic (every dump seen reads 'Off'
     regardless of fan setting)."""
     state = _state()
-    assert state['fan'] == 0
+    assert state['airflow_fan'] == 0
     assert state['fan_direction'] == 'Off'

tests/test_translations.py

@@ -126,8 +126,10 @@ def test_no_catalog_carries_unresolved_core_references():
 
 
 # The hood fan is its device's primary feature: fan.py sets _attr_name = None
-# so it presents as the device itself, and never reads a catalog name.
-UNNAMED_DESCRIPTORS = {("fan", "fan")}
+# so it presents as the device itself, and never reads a catalog name. Same
+# for the ARTIK051 air-purifier's airflow_fan (issue #56) -- ordered speed
+# levels, no presets, same _attr_name = None treatment.
+UNNAMED_DESCRIPTORS = {("fan", "fan"), ("fan", "airflow_fan")}
 
 
 def test_every_descriptor_has_an_entity_catalog_entry():