1414from dataclasses import dataclass , field
1515from typing import Any
1616
17+ from roborock .data import RoborockBase
1718from roborock .data .b01_q10 .b01_q10_code_mappings import (
1819 B01_Q10_DP ,
1920 YXCleaningResult ,
2223 YXStartMethod ,
2324)
2425from roborock .data .b01_q10 .b01_q10_containers import Q10CleanRecord
26+ from roborock .exceptions import RoborockException
27+ from roborock .map .b01_q10_map_parser import (
28+ Q10CleanRecordDetail ,
29+ Q10HistoricalTracePacket ,
30+ Q10MapPacket ,
31+ Q10MapPacketKind ,
32+ Q10Point ,
33+ )
2534
2635from .command import CommandTrait
2736from .common import UpdatableTrait
2837
2938__all__ = [
39+ "CleanHistory" ,
3040 "CleanHistoryTrait" ,
3141 "CleanRecordConverter" ,
3242 "CleanRecordPush" ,
@@ -107,40 +117,78 @@ def parse_record(raw: Any | None) -> Q10CleanRecord | None:
107117 return None
108118
109119
110- class CleanHistoryTrait (UpdatableTrait ):
111- """Access to the Q10 clean-record history (``dpCleanRecord``, DP 52).
112-
113- A read-model trait updated from the DPS stream like the others, but it overrides
114- :meth:`update_from_dps` because the payload is a structured push (a record list,
115- or a single ``op:"notify"`` record) rather than a flat data-point-to-field map.
116- """
120+ @dataclass
121+ class CleanHistory (RoborockBase ):
122+ """Received clean-history data, independent of request and transport state."""
117123
118- def __init__ ( self , command : CommandTrait ) -> None :
119- """Initialize the clean history trait ."""
120- UpdatableTrait . __init__ ( self , command , _LOGGER )
121- self . _converter = CleanRecordConverter ()
122- self . records : list [Q10CleanRecord ] = []
123- """Decoded clean records, most recent first ."""
124+ records : list [ Q10CleanRecord ] = field ( default_factory = list )
125+ """Decoded clean records, most recent first ."""
126+ detail : Q10CleanRecordDetail | None = None
127+ """Latest received archive. Its wire payload contains no record identifier."""
128+ detail_path : list [Q10Point ] = field ( default_factory = list )
129+ """Historical path points from the latest received archive, included in diagnostics ."""
124130
125131 @property
126132 def last_record (self ) -> Q10CleanRecord | None :
127133 """The most recent clean record, or ``None`` if there are none."""
128134 return self .records [0 ] if self .records else None
129135
136+ @property
137+ def detail_packet (self ) -> Q10MapPacket | None :
138+ """The map from the most recently received clean-record detail."""
139+ return self .detail .map if self .detail else None
140+
141+ @property
142+ def detail_trace (self ) -> Q10HistoricalTracePacket | None :
143+ """Historical path embedded in the latest received clean-record detail."""
144+ return self .detail .trace if self .detail else None
145+
146+ def as_dict (self , exclude : set [str ] | None = None ) -> dict [str , Any ]:
147+ """Serialize history metadata and path without binary map packets and grids."""
148+ return super ().as_dict (exclude = (exclude or set ()) | {"detail" })
149+
150+
151+ class CleanHistoryTrait (CleanHistory , UpdatableTrait ):
152+ """Browse past cleaning runs and retrieve their parsed maps and historical paths.
153+
154+ Subscribe with ``add_update_listener`` to receive requested or unsolicited
155+ archives. Archive pushes contain no record ID, so the latest detail cannot
156+ be attributed to a particular selection.
157+ """
158+
159+ _command : CommandTrait
160+
161+ def __init__ (self , command : CommandTrait ) -> None :
162+ CleanHistory .__init__ (self )
163+ UpdatableTrait .__init__ (self , command , _LOGGER )
164+ self ._command = command
165+ self ._converter = CleanRecordConverter ()
166+
130167 async def refresh (self ) -> None :
131168 """Request the clean-record list from the device.
132169
133170 This sends the query and returns immediately; the records arrive
134171 asynchronously on the device stream and populate :attr:`records` once
135172 :meth:`update_from_dps` processes the ``dpCleanRecord`` push.
136173 """
137- if self ._command is None :
138- raise ValueError ("Trait is read-only; no command channel was provided" )
139174 await self ._command .send (
140175 B01_Q10_DP .COMMON ,
141176 params = {str (B01_Q10_DP .CLEAN_RECORD .code ): {"op" : "list" }},
142177 )
143178
179+ async def refresh_detail (self , record : Q10CleanRecord ) -> None :
180+ """Request the saved map and path for a past cleaning run.
181+
182+ Returns after sending; listeners receive the archive separately. The
183+ push contains no record ID to correlate it with this selection.
184+ """
185+ if not record .raw or not record .map_len :
186+ raise RoborockException ("The Q10 clean record has no saved map detail" )
187+ await self ._command .send (
188+ B01_Q10_DP .COMMON ,
189+ {str (B01_Q10_DP .CLEAN_RECORD .code ): {"op" : "select" , "id" : record .raw }},
190+ )
191+
144192 def update_from_dps (self , decoded_dps : dict [B01_Q10_DP , Any ]) -> None :
145193 """Apply a ``dpCleanRecord`` push (a full list reply or a single notify)."""
146194 envelope = decoded_dps .get (B01_Q10_DP .CLEAN_RECORD )
@@ -151,6 +199,14 @@ def update_from_dps(self, decoded_dps: dict[B01_Q10_DP, Any]) -> None:
151199 return
152200 self ._apply (push )
153201
202+ def update_from_detail (self , detail : Q10CleanRecordDetail ) -> None :
203+ """Store a pushed clean-record map and path and notify listeners."""
204+ if detail .map .kind is not Q10MapPacketKind .CLEAN_RECORD_DETAIL :
205+ raise ValueError (f"Expected a Q10 clean-record detail packet, got { detail .map .kind .value } " )
206+ self .detail = detail
207+ self .detail_path = list (detail .trace .points ) if detail .trace else []
208+ self ._notify_update ()
209+
154210 def _apply (self , push : CleanRecordPush ) -> None :
155211 """Merge or replace the records from ``push``, then sort newest-first and notify."""
156212 if push .replace :
0 commit comments