From 8e42d0c1b7ae36cff2e7c69999117911a4b6f300 Mon Sep 17 00:00:00 2001
From: wanshenmean <cathay_xy@163.com>
Date: 星期四, 26 三月 2026 17:31:06 +0800
Subject: [PATCH] feat(WCS): 完善 WIDESEAWCS_Tasks 模块代码注释
---
Code/WCS/WIDESEAWCS_Server/WIDESEAWCS_Tasks/RobotJob/RobotClientManager.cs | 137 +++++++++++++++++++++++++++++++++++++--------
1 files changed, 113 insertions(+), 24 deletions(-)
diff --git a/Code/WCS/WIDESEAWCS_Server/WIDESEAWCS_Tasks/RobotJob/RobotClientManager.cs b/Code/WCS/WIDESEAWCS_Server/WIDESEAWCS_Tasks/RobotJob/RobotClientManager.cs
index 2e372bf..75d098b 100644
--- a/Code/WCS/WIDESEAWCS_Server/WIDESEAWCS_Tasks/RobotJob/RobotClientManager.cs
+++ b/Code/WCS/WIDESEAWCS_Server/WIDESEAWCS_Tasks/RobotJob/RobotClientManager.cs
@@ -1,24 +1,64 @@
using System.Collections.Concurrent;
using System.Net.Sockets;
+using WIDESEAWCS_Core.LogHelper;
using WIDESEAWCS_QuartzJob;
using WIDESEAWCS_Tasks.SocketServer;
namespace WIDESEAWCS_Tasks
{
/// <summary>
- /// 鏈烘鎵嬪鎴风杩炴帴绠＄悊鍣� - 璐熻矗TCP瀹㈡埛绔繛鎺ョ鐞嗗拰浜嬩欢璁㈤槄
+ /// 鏈烘鎵嬪鎴风杩炴帴绠＄悊鍣� - 璐熻矗 TCP 瀹㈡埛绔繛鎺ョ鐞嗗拰浜嬩欢璁㈤槄
/// </summary>
+ /// <remarks>
+ /// 鏍稿績鑱岃矗锛�
+ /// 1. 缁存姢涓庢満姊版墜璁惧鐨� TCP 杩炴帴鐘舵��
+ /// 2. 纭繚姣忎釜瀹㈡埛绔彧鍚姩涓�娆℃秷鎭鐞嗗惊鐜�
+ /// 3. 绠＄悊瀹㈡埛绔繛鎺�/鏂紑鐨勭敓鍛藉懆鏈熶簨浠�
+ /// 4. 鎻愪緵鍙戦�佹秷鎭埌瀹㈡埛绔殑鎺ュ彛
+ /// </remarks>
public class RobotClientManager
{
+ /// <summary>
+ /// TCP Socket 鏈嶅姟鍣ㄥ疄渚嬶紝鐢ㄤ簬绠＄悊鎵�鏈夊鎴风杩炴帴
+ /// </summary>
private readonly TcpSocketServer _tcpSocket;
+
+ /// <summary>
+ /// 鏈烘鎵嬬姸鎬佺鐞嗗櫒锛岀敤浜庤鍐欒澶囩姸鎬�
+ /// </summary>
private readonly RobotStateManager _stateManager;
- // 璺熻釜宸茬粡鍚姩 HandleClientAsync 鐨勫鎴风
+ /// <summary>
+ /// 璺熻釜宸插惎鍔ㄦ秷鎭鐞嗙殑瀹㈡埛绔紝閬垮厤閲嶅鍚姩
+ /// </summary>
+ /// <remarks>
+ /// Key: 瀹㈡埛绔� IP 鍦板潃
+ /// Value: 鏄惁宸插惎鍔紙true 琛ㄧず宸插惎鍔級
+ /// 浣跨敤 ConcurrentDictionary 淇濊瘉绾跨▼瀹夊叏
+ /// </remarks>
private static readonly ConcurrentDictionary<string, bool> _handleClientStarted = new();
+
+ /// <summary>
+ /// 浜嬩欢璁㈤槄鏍囧織锛岀‘淇� RobotReceived 浜嬩欢鍙闃呬竴娆�
+ /// </summary>
+ /// <remarks>
+ /// 浣跨敤鍘熷瓙鎿嶄綔 Interlocked.CompareExchange 淇濊瘉鍏ㄥ眬鍙闃呬竴娆�
+ /// </remarks>
private static int _eventSubscribedFlag;
+ /// <summary>
+ /// 瀹㈡埛绔柇寮�杩炴帴鏃惰Е鍙戠殑浜嬩欢
+ /// </summary>
+ /// <remarks>
+ /// 浜嬩欢鍙傛暟鍖呭惈鏂紑杩炴帴鐨勬満姊版墜鐘舵�佷俊鎭�
+ /// </remarks>
public event EventHandler<RobotSocketState>? OnClientDisconnected;
+ /// <summary>
+ /// 鏋勯�犲嚱鏁�
+ /// </summary>
+ /// <param name="tcpSocket">TCP Socket 鏈嶅姟鍣ㄥ疄渚�</param>
+ /// <param name="stateManager">鐘舵�佺鐞嗗櫒瀹炰緥</param>
public RobotClientManager(TcpSocketServer tcpSocket, RobotStateManager stateManager)
{
_tcpSocket = tcpSocket;
@@ -28,66 +68,88 @@
/// <summary>
/// 纭繚瀹㈡埛绔凡杩炴帴骞惰闃呮秷鎭簨浠�
/// </summary>
- /// <param name="ipAddress">璁惧IP鍦板潃</param>
+ /// <remarks>
+ /// 杩欐槸 RobotJob Execute 鏂规硶涓殑鏍稿績妫�鏌ラ�昏緫锛�
+ /// 1. 楠岃瘉瀹㈡埛绔槸鍚﹀湪绾�
+ /// 2. 璁㈤槄鏂紑浜嬩欢锛堝叏灞�鍙墽琛屼竴娆★級
+ /// 3. 纭繚娑堟伅澶勭悊寰幆宸插惎鍔�
+ /// 4. 闃叉閲嶅鍚姩 HandleClientAsync
+ /// </remarks>
+ /// <param name="ipAddress">璁惧 IP 鍦板潃</param>
/// <param name="robotCrane">鏈哄櫒浜鸿澶囦俊鎭�</param>
/// <returns>瀹㈡埛绔槸鍚﹀彲鐢紙宸茶繛鎺ヤ笖娑堟伅澶勭悊宸插惎鍔級</returns>
public bool EnsureClientSubscribed(string ipAddress, RobotCraneDevice robotCrane)
{
- // 妫�鏌ユ槸鍚︽湁璇ュ鎴风杩炴帴
+ // 浠� TCP 鏈嶅姟鍣ㄨ幏鍙栨墍鏈夊凡杩炴帴瀹㈡埛绔殑 ID 鍒楄〃
var clientIds = _tcpSocket.GetClientIds();
+
+ // 妫�鏌ヨ IP 鍦板潃鐨勫鎴风鏄惁宸茶繛鎺�
bool isClientConnected = clientIds.Contains(ipAddress);
+ // 濡傛灉瀹㈡埛绔湭杩炴帴
if (!isClientConnected)
{
- // 瀹㈡埛绔湭杩炴帴锛屾竻鐞� HandleClientAsync 鐘舵��
+ // 娓呯悊璇ュ鎴风鐨� HandleClientAsync 鍚姩鏍囧織
+ // 浠ヤ究涓嬫閲嶈繛鏃跺彲浠ラ噸鏂板惎鍔ㄥ鐞�
_handleClientStarted.TryRemove(ipAddress, out _);
return false;
}
- // 璁㈤槄涓�娆� robot 浜嬩欢锛堝叏灞�涓�娆★級- message浜嬩欢鐢盧obotJob璁㈤槄
+ // 璁㈤槄涓�娆� RobotReceived 浜嬩欢锛堝叏灞�鍙闃呬竴娆★級
+ // 浣跨敤 Interlocked.CompareExchange 瀹炵幇鍘熷瓙鎿嶄綔锛岀‘淇濈嚎绋嬪畨鍏�
if (System.Threading.Interlocked.CompareExchange(ref _eventSubscribedFlag, 1, 0) == 0)
{
+ // 缁戝畾瀹㈡埛绔柇寮�杩炴帴鐨勪簨浠跺鐞�
_tcpSocket.RobotReceived += OnRobotReceived;
- Console.WriteLine($"[{DateTime.Now:yyyy-MM-dd HH:mm:ss}] 鏈哄櫒浜篢CP鏂紑浜嬩欢宸茶闃�");
+ // 璁板綍鏃ュ織锛堟敞鎰忥細鏃ュ織鍐呭涓�"瀹㈡埛绔凡鏂紑杩炴帴"锛屽彲鑳芥槸閬楃暀鐨勫崰浣嶆枃鏈級
+ QuartzLogger.Error($"瀹㈡埛绔凡鏂紑杩炴帴", robotCrane.DeviceName);
}
- // 鑾峰彇TcpClient
+ // 浠� TCP 鏈嶅姟鍣ㄧ殑瀹㈡埛绔瓧鍏镐腑鑾峰彇 TcpClient 瀵硅薄
TcpClient? tcpClient = null;
_tcpSocket._clients.TryGetValue(ipAddress, out tcpClient);
+ // 濡傛灉鑾峰彇澶辫触锛堣櫧鐒� isClientConnected 涓� true锛屼絾鍙兘瀛樺湪瀛楀吀涓嶅悓姝ョ殑鎯呭喌锛�
if (tcpClient == null)
{
- // isClientConnected涓簍rue浣嗘棤娉曡幏鍙杢cpClient锛屽垪琛ㄥ彲鑳戒笉鍚屾
+ // 绉婚櫎鍚姩鏍囧織锛岃繑鍥� false 琛ㄧず瀹㈡埛绔笉鍙敤
_handleClientStarted.TryRemove(ipAddress, out _);
return false;
}
- // 妫�鏌ユ槸鍚﹀凡缁忎负杩欎釜瀹㈡埛绔惎鍔ㄨ繃 HandleClientAsync
+ // 妫�鏌ユ槸鍚﹀凡缁忎负杩欎釜瀹㈡埛绔惎鍔ㄨ繃娑堟伅澶勭悊寰幆
bool alreadyStarted = _handleClientStarted.TryGetValue(ipAddress, out _);
+ // 濡傛灉灏氭湭鍚姩锛屽垯鍚姩娑堟伅澶勭悊寰幆
if (!alreadyStarted)
{
- Console.WriteLine($"[{DateTime.Now:yyyy-MM-dd HH:mm:ss}] 鍚姩瀹㈡埛绔秷鎭鐞�: {ipAddress}");
+ // 璁板綍鏃ュ織
+ QuartzLogger.Error($"鍚姩瀹㈡埛绔秷鎭鐞�", robotCrane.DeviceName);
- // 閲嶆柊鑾峰彇鏈�鏂扮殑 state 瀵硅薄
+ // 鑾峰彇鏈�鏂扮殑鐘舵�佸璞�
var latestStateForSubscribe = _stateManager.GetState(ipAddress);
if (latestStateForSubscribe != null)
{
- // 鏍囪涓哄凡鍚姩
+ // 鏍囪涓哄凡鍚姩锛岄槻姝㈤噸澶嶅惎鍔�
_handleClientStarted[ipAddress] = true;
+ // 寮傛鍚姩瀹㈡埛绔秷鎭鐞嗗惊鐜�
+ // 浣跨敤 TaskContinuationOptions.OnlyOnFaulted 鎹曡幏寮傚父鎯呭喌
_ = _tcpSocket.HandleClientAsync(tcpClient, robotCrane.IPAddress, _tcpSocket._cts.Token, latestStateForSubscribe)
.ContinueWith(t =>
{
+ // 濡傛灉澶勭悊鍑虹幇寮傚父
if (t.IsFaulted)
{
+ // 璁板綍閿欒鏃ュ織
+ QuartzLogger.Error($"鐩戝惉瀹㈡埛绔秷鎭簨浠跺紓甯�", robotCrane.DeviceName);
Console.WriteLine($"[{DateTime.Now:yyyy-MM-dd HH:mm:ss}] HandleClientAsync error: {t.Exception?.GetBaseException().Message}");
// 鍙戠敓閿欒鏃讹紝绉婚櫎鍚姩鏍囧織锛屽厑璁镐笅娆￠噸璇�
_handleClientStarted.TryRemove(ipAddress, out _);
}
}, TaskContinuationOptions.OnlyOnFaulted);
- // 鏇存柊 IsEventSubscribed 鐘舵��
+ // 瀹夊叏鏇存柊鐘舵�侊紝鏍囪涓哄凡璁㈤槄娑堟伅浜嬩欢
_stateManager.TryUpdateStateSafely(ipAddress, s =>
{
s.IsEventSubscribed = true;
@@ -96,54 +158,81 @@
}
}
+ // 杩斿洖 true 琛ㄧず瀹㈡埛绔彲鐢�
return true;
}
/// <summary>
- /// 浜嬩欢锛氬鎴风鏂紑杩炴帴鏃惰Е鍙�
+ /// 浜嬩欢澶勭悊锛氬鎴风鏂紑杩炴帴鏃惰皟鐢�
/// </summary>
+ /// <remarks>
+ /// 瑙﹀彂鏃舵満锛氬綋 TCP 鏈嶅姟鍣ㄦ娴嬪埌瀹㈡埛绔柇寮�杩炴帴鏃�
+ /// 澶勭悊閫昏緫锛�
+ /// 1. 娓呯悊 HandleClientAsync 鍚姩鏍囧織
+ /// 2. 閲嶇疆璁惧鐘舵�侊紙鍙栨秷璁㈤槄銆佹竻闄ゅ姩浣滃拰鐘舵�侊級
+ /// 3. 瑙﹀彂 OnClientDisconnected 浜嬩欢閫氱煡涓婂眰
+ /// </remarks>
+ /// <param name="clientId">鏂紑杩炴帴鐨勫鎴风 IP 鍦板潃</param>
+ /// <returns>鍥哄畾杩斿洖 null锛屽洜涓烘槸浜嬩欢澶勭悊鍣ㄨ�岄潪鐪熸鐨勬秷鎭鐞嗗櫒</returns>
private Task<string?> OnRobotReceived(string clientId)
{
- // 瀹㈡埛绔柇寮�杩炴帴锛屾竻鐞� HandleClientAsync 鍚姩鏍囧織
+ // 绉婚櫎璇ュ鎴风鐨� HandleClientAsync 鍚姩鏍囧織
_handleClientStarted.TryRemove(clientId, out _);
+ // 閲嶇疆璇ュ鎴风鐨勭姸鎬佷俊鎭�
_stateManager.TryUpdateStateSafely(clientId, state =>
{
- state.IsEventSubscribed = false;
- state.CurrentAction = "";
- state.OperStatus = "";
- state.RobotArmObject = 0;
- state.RobotControlMode = 0;
- state.RobotRunMode = 0;
+ state.IsEventSubscribed = false; // 鍙栨秷璁㈤槄鏍囧織
+ state.CurrentAction = ""; // 娓呴櫎褰撳墠鍔ㄤ綔
+ state.OperStatus = ""; // 娓呴櫎杩愯鐘舵��
+ state.RobotArmObject = 0; // 閲嶇疆鎵嬭噦瀵硅薄鐘舵��
+ state.RobotControlMode = 0; // 閲嶇疆鎺у埗妯″紡
+ state.RobotRunMode = 0; // 閲嶇疆杩愯妯″紡
return state;
});
- // 瑙﹀彂鏂紑杩炴帴浜嬩欢
+ // 瑙﹀彂瀹㈡埛绔柇寮�杩炴帴浜嬩欢锛岄�氱煡涓婂眰锛堝 RobotJob锛�
+ // 浣跨敤绌虹殑鐘舵�佸璞′綔涓哄悗澶囷紙濡傛灉鑾峰彇涓嶅埌锛�
OnClientDisconnected?.Invoke(this, _stateManager.GetState(clientId) ?? new RobotSocketState { IPAddress = clientId });
+ // 杩斿洖 null锛屽洜涓鸿繖鏄簨浠跺鐞嗚�岄潪鐪熸鐨勬秷鎭矾鐢�
return Task.FromResult<string?>(null);
}
/// <summary>
/// 妫�鏌ュ鎴风鏄惁宸茶繛鎺�
/// </summary>
+ /// <param name="ipAddress">璁惧 IP 鍦板潃</param>
+ /// <returns>濡傛灉宸茶繛鎺ュ垯杩斿洖 true</returns>
public bool IsClientConnected(string ipAddress)
{
+ // 鑾峰彇鎵�鏈夊凡杩炴帴瀹㈡埛绔殑 ID 鍒楄〃
var clientIds = _tcpSocket.GetClientIds();
+ // 妫�鏌ュ垪琛ㄤ腑鏄惁鍖呭惈鎸囧畾鐨� IP 鍦板潃
return clientIds.Contains(ipAddress);
}
/// <summary>
/// 鍙戦�佹秷鎭埌瀹㈡埛绔�
/// </summary>
+ /// <remarks>
+ /// 灏佽 TcpSocketServer 鐨勫彂閫佹柟娉曪紝鎻愪緵鏇寸畝娲佺殑鎺ュ彛缁欎笟鍔″眰
+ /// </remarks>
+ /// <param name="ipAddress">鐩爣瀹㈡埛绔� IP 鍦板潃</param>
+ /// <param name="message">瑕佸彂閫佺殑娑堟伅鍐呭</param>
+ /// <returns>鍙戦�佹槸鍚︽垚鍔�</returns>
public async Task<bool> SendToClientAsync(string ipAddress, string message)
{
return await _tcpSocket.SendToClientAsync(ipAddress, message);
}
/// <summary>
- /// 鑾峰彇TcpSocketServer寮曠敤锛堢敤浜嶳obotJob鐩存帴璁块棶锛�
+ /// 鑾峰彇 TcpSocketServer 寮曠敤
/// </summary>
+ /// <remarks>
+ /// RobotJob 鍙兘闇�瑕佺洿鎺ヨ闂� TcpSocketServer 杩涜閰嶇疆
+ /// 姝ゅ睘鎬ф彁渚涘彧璇昏闂�
+ /// </remarks>
public TcpSocketServer TcpSocket => _tcpSocket;
}
}
--
Gitblit v1.9.3