feat(upserver): 接入认证与KV存档并完成限定钓鱼闭环

Client/Assets/Scripts/Services/PlayerData/PlayerKVKeyReadResult.cs

@@ -0,0 +1,35 @@
+using System;
+
+namespace game.PlayerDataStorage
+{
+    internal enum PlayerKVKeyReadError { None, InvalidInput, LoadGuardActive, StaleOrClosing, NotReady }
+
+    /// <summary>
+    /// A detached key observation, not authority for a later gameplay mutation.
+    /// Found=null means failure; Found=false means a valid snapshot lacked the key;
+    /// Found=true means a value exists, including the empty string.
+    /// </summary>
+    internal sealed class PlayerKVKeyReadResult
+    {
+        internal PlayerKVKeyReadError Error { get; }
+        internal bool Success => Error == PlayerKVKeyReadError.None;
+        internal bool? Found { get; }
+        internal string Value { get; }
+        internal string OwnerInstanceId { get; }
+        internal string PlayerId { get; }
+        internal long? Epoch { get; }
+
+        internal PlayerKVKeyReadResult(PlayerKVKeyReadError error, PlayerKVGameSessionHandle handle,
+            bool? found = null, string value = null)
+        {
+            if (error == PlayerKVKeyReadError.None && (!found.HasValue || (found.Value && value == null)))
+                throw new ArgumentException("A successful key observation requires an existence verdict.");
+            Error = error;
+            OwnerInstanceId = handle?.OwnerInstanceId;
+            PlayerId = handle?.PlayerId;
+            Epoch = handle?.Epoch;
+            Found = Success ? found : null;
+            Value = Success && found == true ? value : null;
+        }
+    }
+}