From 165d9665316da78056a85a12da8ae56e7fe51b0a Mon Sep 17 00:00:00 2001
From: wanshenmean <cathay_xy@163.com>
Date: 星期日, 19 四月 2026 19:17:37 +0800
Subject: [PATCH] docs: 添加 RobotState Redis→数据库迁移设计文档

---
 Code/docs/superpowers/specs/2026-04-19-robot-state-redis-to-db-design.md |  195 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 195 insertions(+), 0 deletions(-)

diff --git a/Code/docs/superpowers/specs/2026-04-19-robot-state-redis-to-db-design.md b/Code/docs/superpowers/specs/2026-04-19-robot-state-redis-to-db-design.md
new file mode 100644
index 0000000..799c381
--- /dev/null
+++ b/Code/docs/superpowers/specs/2026-04-19-robot-state-redis-to-db-design.md
@@ -0,0 +1,195 @@
+# RobotState Redis 鈫� 鏁版嵁搴撹縼绉昏璁�
+
+**鏃ユ湡**锛�2026-04-19
+**鐘舵��**锛氬凡鎵瑰噯
+
+## 1. 鑳屾櫙涓庣洰鏍�
+
+灏� `RobotSocketState` 鐨勫瓨鍌ㄤ粠 Redis 鍒囨崲鍒� SQL Server 鏁版嵁搴擄紝鍒╃敤 SqlSugar 鐨� `RowVersion` 瀹炵幇涔愯骞跺彂鎺у埗銆�
+
+### 娑夊強鑼冨洿
+
+- `RobotJob/` 鏂囦欢澶逛笅鎵�鏈変娇鐢� Redis 璇诲啓 `RobotSocketState` 鐨勪唬鐮�
+- 鏂板缓 `Dt_RobotState` 鏁版嵁搴撳疄浣撳拰 `IRobotStateRepository` 浠撳偍灞�
+
+### 涓嶆秹鍙婂彉鏇�
+
+- `RobotWorkflowOrchestrator`銆乣RobotTaskProcessor`銆乣RobotSimpleCommandHandler` 绛変笟鍔￠�昏緫涓嶅彉
+- 渚濊禆 `RobotStateManager` 鐨勮皟鐢ㄦ柟浠ｇ爜涓嶅彉锛屽彧鏀瑰瓨鍌ㄥ悗绔�
+
+---
+
+## 2. 鏁版嵁搴撳疄浣撹璁�
+
+**琛ㄥ悕**锛歚Dt_RobotState`
+
+**瀹炰綋璺緞**锛歚WIDESEAWCS_Model/Models/RobotState/Dt_RobotState.cs`
+
+| 瀛楁鍚� | 绫诲瀷 | 璇存槑 |
+|--------|------|------|
+| `Id` | int | 涓婚敭锛岃嚜澧� |
+| `IPAddress` | string(50) | 璁惧IP锛屽敮涓�绱㈠紩 |
+| `RowVersion` | byte[] | SqlSugar 琛岀増鏈紝骞跺彂鎺у埗 |
+| `IsEventSubscribed` | bool | 鏄惁宸茶闃呮秷鎭� |
+| `RobotRunMode` | int? | 杩愯妯″紡锛�1鎵嬪姩 2鑷姩锛� |
+| `RobotControlMode` | int? | 鎺у埗妯″紡锛�1瀹㈡埛绔帶鍒� 2鍏朵粬锛� |
+| `RobotArmObject` | int? | 鎵嬭噦鎶撳彇鐘舵�侊紙0鏃犵墿鏂� 1鏈夌墿鏂欙級 |
+| `RobotCraneJson` | string(max) | 璁惧淇℃伅搴忓垪鍖� JSON |
+| `Homed` | string(50) | 鍥為浂鐘舵�侊紙Homed/Homing锛� |
+| `CurrentAction` | string(50) | 褰撳墠鍔ㄤ綔锛圥icking/Putting/PickFinished 绛夛級 |
+| `OperStatus` | string(50) | 杩愯鐘舵�侊紙Running/Pausing/Emstoping 绛夛級 |
+| `LastPickPositionsJson` | string(max) | 鍙栬揣浣嶇疆鏁扮粍 JSON |
+| `LastPutPositionsJson` | string(max) | 鏀捐揣浣嶇疆鏁扮粍 JSON |
+| `CellBarcodeJson` | string(max) | 鐢佃姱鏉＄爜鍒楄〃 JSON |
+| `CurrentTaskJson` | string(max) | 褰撳墠浠诲姟 Dt_RobotTask 搴忓垪鍖� JSON |
+| `IsSplitPallet` | bool | 鏄惁鎷嗙洏浠诲姟 |
+| `IsGroupPallet` | bool | 鏄惁缁勭洏/鎹㈢洏浠诲姟 |
+| `RobotTaskTotalNum` | int | 宸插鐞嗕换鍔℃�绘暟 |
+| `IsInFakeBatteryMode` | bool | 鏄惁鍋囩數鑺ˉ鍏呮ā寮� |
+| `CurrentBatchIndex` | int | 褰撳墠鎵规璧峰缂栧彿 |
+| `ChangePalletPhase` | int | 鎹㈢洏浠诲姟闃舵锛�0-5锛� |
+| `IsScanNG` | bool | 鏄惁鎵爜NG |
+| `BatteryArrived` | bool | 鐢佃姱鏄惁鍒颁綅 |
+| `CreateTime` | datetime | 鍒涘缓鏃堕棿 |
+| `UpdateTime` | datetime | 鏈�鍚庢洿鏂版椂闂� |
+
+**绱㈠紩**锛歚IPAddress` 鍞竴绱㈠紩锛岀敤浜庡揩閫熷畾浣嶈澶囩姸鎬�
+
+**骞跺彂鎺у埗**锛歋qlSugar `RowVersion`锛屾暟鎹簱鑷姩閫掑锛屾洿鏂版椂 `WHERE RowVersion = @expected`
+
+---
+
+## 3. JSON 搴忓垪鍖栧瓧娈�
+
+浠ヤ笅澶嶆潅瀵硅薄浠� JSON 瀛楃涓插瓨鍌紝鍙嶅簭鍒楀寲鏃朵繚鎸佷笌鍘� `RobotSocketState` 灞炴�у畬鍏ㄥ吋瀹癸細
+
+| JSON 瀛楁 | 瀵瑰簲鍘熷睘鎬� | 鍙嶅簭鍒楀寲绫诲瀷 |
+|-----------|-----------|-------------|
+| `RobotCraneJson` | `RobotCrane` | `RobotCraneDevice` |
+| `CurrentTaskJson` | `CurrentTask` | `Dt_RobotTask` |
+| `LastPickPositionsJson` | `LastPickPositions` | `int[]` |
+| `LastPutPositionsJson` | `LastPutPositions` | `int[]` |
+| `CellBarcodeJson` | `CellBarcode` | `List<string>` |
+
+搴忓垪鍖栧伐鍏凤細`Newtonsoft.Json`锛堜笌椤圭洰鐜版湁淇濇寔涓�鑷达級
+
+---
+
+## 4. 鏋舵瀯鍒嗗眰
+
+```
+璋冪敤鏂癸紙RobotJob / Workflow / Processor锛�
+        鈫� 渚濊禆
+RobotStateManager
+        鈫� 渚濊禆
+IRobotStateRepository锛堟帴鍙ｏ級
+        鈫� 瀹炵幇
+RobotStateRepository锛圫qlSugar 瀹炵幇锛�
+        鈫� 鎿嶄綔
+SQL Server (Dt_RobotState 琛�)
+```
+
+### 4.1 IRobotStateRepository 鎺ュ彛
+
+```csharp
+public interface IRobotStateRepository
+{
+    /// <summary>鏍规嵁 IP 鑾峰彇鐘舵�侊紝涓嶅瓨鍦ㄨ繑鍥� null</summary>
+    Dt_RobotState? GetByIp(string ipAddress);
+
+    /// <summary>鑾峰彇鎴栧垱寤虹姸鎬侊紙鏁版嵁搴撴棤璁板綍鏃跺垱寤猴級</summary>
+    Dt_RobotState GetOrCreate(string ipAddress, RobotCraneDevice robotCrane);
+
+    /// <summary>瀹夊叏鏇存柊锛堜箰瑙傞攣锛夛紝杩斿洖鏄惁鎴愬姛</summary>
+    bool TryUpdate(string ipAddress, Dt_RobotState newState, byte[] expectedRowVersion);
+}
+```
+
+### 4.2 RobotStateRepository 瀹炵幇瑕佺偣
+
+- 娉ㄥ叆 `ISqlSugarClient`
+- `GetOrCreate`锛氬厛鏌ワ紝鏃犺褰曞垯 INSERT
+- `TryUpdate`锛氭墽琛� `UPDATE ... WHERE RowVersion = @expected`锛屾鏌ュ奖鍝嶈鏁�
+- 鏁扮粍/澶嶆潅瀵硅薄锛氬湪 Repository 灞傚簭鍒楀寲/鍙嶅簭鍒楀寲锛屽澶栨毚闇插己绫诲瀷灞炴��
+
+---
+
+## 5. RobotStateManager 鏀归��
+
+**鏂囦欢**锛歚WIDESEAWCS_Tasks/RobotJob/RobotStateManager.cs`
+
+### 鏀归�犲唴瀹�
+
+| 鍘熸潵锛圧edis锛� | 鏀归�犲悗锛圖B锛� |
+|-------------|-------------|
+| `ICacheService _cache` | `IRobotStateRepository _repository` |
+| `GetState(ipAddress)` | `_repository.GetByIp(ipAddress)` |
+| `GetOrCreateState(ipAddress, robotCrane)` | `_repository.GetOrCreate(ipAddress, robotCrane)` |
+| `TryUpdateStateSafely(ipAddress, func)` | 鍐呴儴璋冪敤 `_repository.TryUpdate`锛屼娇鐢� `RowVersion` 浣滀负鏈熸湜鐗堟湰 |
+| `CloneState` | 淇濈暀锛圝SON 搴忓垪鍖栨繁鎷疯礉锛� |
+| `GetCacheKey(ipAddress)` | 绉婚櫎锛堜笉鍐嶉渶瑕� Redis Key锛� |
+
+### 鏋勯�犲嚱鏁板彉鏇�
+
+```csharp
+// 鍘熸潵
+public RobotStateManager(ICacheService cache, ILogger logger)
+
+// 鏀归�犲悗
+public RobotStateManager(IRobotStateRepository repository, ILogger logger)
+```
+
+---
+
+## 6. RobotJob 鏋勯�犲嚱鏁版敼閫�
+
+**鏂囦欢**锛歚WIDESEAWCS_Tasks/RobotJob/RobotJob.cs`
+
+```csharp
+// 鍘熸潵
+_stateManager = new RobotStateManager(cache, _logger);
+
+// 鏀归�犲悗锛氶渶瑕侀�氳繃 DI 娉ㄥ叆 IRobotStateRepository
+_stateManager = new RobotStateManager(
+    ResolvedInstances.FirstOrDefault(typeof(IRobotStateRepository)) as IRobotStateRepository,
+    _logger);
+```
+
+**澶囬�夋柟妗�**锛氬鏋� DI 瀹瑰櫒鍦� Job 鏋勯�犳椂涓嶄究瑙ｆ瀽锛屽彲閫氳繃鏂规硶鍙傛暟娉ㄥ叆 `IRobotStateRepository`銆�
+
+---
+
+## 7. 鏂囦欢鍙樻洿娓呭崟
+
+| 鎿嶄綔 | 鏂囦欢璺緞 |
+|------|---------|
+| 鏂板 | `WIDESEAWCS_Model/Models/RobotState/Dt_RobotState.cs` |
+| 鏂板 | `WIDESEAWCS_ITaskInfoRepository/IRobotStateRepository.cs` |
+| 鏂板 | `WIDESEAWCS_ITaskInfoRepository/RobotStateRepository.cs` |
+| 鏀归�� | `WIDESEAWCS_Tasks/RobotJob/RobotStateManager.cs` |
+| 鏀归�� | `WIDESEAWCS_Tasks/RobotJob/RobotJob.cs` |
+| 鏀归�� | `WIDESEAWCS_Tasks/RobotJob/RobotSocketState.cs`锛堢Щ闄ゆ垨淇濈暀涓� DTO锛燂級 |
+
+**璇存槑**锛歚RobotSocketState.cs` 寤鸿淇濈暀浣滀负鍐呭瓨涓殑鐘舵�佸璞★紙DTO锛夛紝鍦� Repository 灞傚仛瀹炰綋杞崲銆備笟鍔″眰缁х画浣跨敤 `RobotSocketState`锛孯epository 灞傝礋璐ｄ笌 `Dt_RobotState` 浜掕浆銆�
+
+---
+
+## 8. 渚濊禆娉ㄥ叆娉ㄥ唽
+
+鍦� `AutofacModuleRegister` 鎴栧搴� DI 閰嶇疆涓敞鍐岋細
+
+```csharp
+builder.RegisterType<RobotStateRepository>().As<IRobotStateRepository>().InstancePerDependency();
+```
+
+---
+
+## 9. 杩佺Щ姝ラ锛堝疄鏂借鍒掞級
+
+1. **鏂板缓 `Dt_RobotState` 瀹炰綋绫�**
+2. **鏂板缓 `IRobotStateRepository` 鎺ュ彛鍜� `RobotStateRepository` 瀹炵幇**
+3. **鏀归�� `RobotStateManager`**锛氫緷璧� Repository锛屾浛鎹� Redis 璋冪敤
+4. **鏀归�� `RobotJob`**锛氭敞鍏� Repository 鍒� StateManager
+5. **鏇存柊 `RobotSocketState`**锛氫綔涓哄唴瀛� DTO 淇濈暀锛屾垨涓庡疄浣撳悎骞讹紙寰呭畾锛�
+6. **閰嶇疆 DI 娉ㄥ唽**
+7. **娴嬭瘯楠岃瘉**锛氱‘淇濆苟鍙戞洿鏂般�佺姸鎬佹祦杞�昏緫涓庡師鏉ヤ竴鑷�

--
Gitblit v1.9.3