docs: 补全全部缺失的 XML 文档注释（中文）

- 为全部 5 个项目（Avalonia-API、Avalonia-Common、Avalonia-EFCore、 Avalonia-PC、Avalonia-Services）中缺失注释的类、方法、属性、字段、接口成员等补全中文 XML 文档注释 - 共修改约 37 个文件，补全约 220+ 处注释 - 修复 ServiceEndpointCollection.cs 中 MapDelete<TService> 语法错误 - 修复 PcAuthService.cs 中 const prefix 位置错乱导致编译失败的问题 - 扫描结果：缺失项 0 - 构建结果：4/4 项目编译通过
2026-05-18 11:35:13 +08:00
parent 446502b0e9
commit fc6f9f6bc3
43 changed files with 884 additions and 233 deletions
@@ -1,11 +1,33 @@
 namespace Avalonia_Services.Services.AuthService
 {
+    /// <summary>
+    /// API 登录请求。
+    /// </summary>
+    /// <param name="Account">账号（邮箱或用户名）。</param>
+    /// <param name="Password">密码。</param>
+    /// <param name="Roles">请求的角色列表。</param>
    public sealed record ApiLoginRequest(string? Account, string? Password, string[]? Roles = null);

+    /// <summary>
+    /// API Refresh Token 请求。
+    /// </summary>
+    /// <param name="RefreshToken">刷新令牌。</param>
    public sealed record ApiRefreshTokenRequest(string? RefreshToken);

+    /// <summary>
+    /// API 登出请求。
+    /// </summary>
+    /// <param name="RefreshToken">要撤销的刷新令牌。</param>
    public sealed record ApiLogoutRequest(string? RefreshToken);

+    /// <summary>
+    /// 认证 Token 响应，包含 Access Token 和 Refresh Token 及其过期时间。
+    /// </summary>
+    /// <param name="AccessToken">访问令牌。</param>
+    /// <param name="RefreshToken">刷新令牌。</param>
+    /// <param name="AccessTokenExpiresAt">访问令牌过期时间。</param>
+    /// <param name="RefreshTokenExpiresAt">刷新令牌过期时间。</param>
+    /// <param name="Roles">用户角色列表。</param>
    public sealed record AuthTokenResponse(
        string AccessToken,
        string RefreshToken,
@@ -13,25 +35,64 @@ namespace Avalonia_Services.Services.AuthService
        DateTime RefreshTokenExpiresAt,
        string[] Roles);

+    /// <summary>
+    /// PC 端授权码登录请求。
+    /// </summary>
+    /// <param name="AuthorizationCode">第三方授权码。</param>
    public sealed record PcAuthorizeRequest(string? AuthorizationCode);

+    /// <summary>
+    /// PC 端 Token 刷新请求。
+    /// </summary>
+    /// <param name="Token">当前 Token。</param>
    public sealed record PcRefreshRequest(string? Token);

+    /// <summary>
+    /// PC 端登出请求。
+    /// </summary>
+    /// <param name="Token">要清除的 Token。</param>
    public sealed record PcLogoutRequest(string? Token);

+    /// <summary>
+    /// PC 端 Token 响应。
+    /// </summary>
+    /// <param name="Token">访问令牌。</param>
+    /// <param name="ExpiresAt">过期时间。</param>
+    /// <param name="Roles">用户角色列表。</param>
    public sealed record PcTokenResponse(string Token, DateTime ExpiresAt, string[] Roles);

+    /// <summary>
+    /// 第三方授权检查结果。
+    /// </summary>
    public enum ThirdPartyAuthCheckResult
    {
+        /// <summary>授权有效。</summary>
        Valid,
+        /// <summary>授权已丢失。</summary>
        AuthorizationLost,
+        /// <summary>暂时性失败。</summary>
        TemporaryFailure,
    }

+    /// <summary>
+    /// 第三方授权客户端接口，用于验证和刷新第三方授权。
+    /// </summary>
    public interface IPcThirdPartyAuthorizationClient
    {
+        /// <summary>
+        /// 验证第三方授权码是否有效。
+        /// </summary>
+        /// <param name="authorizationCode">第三方授权码。</param>
+        /// <param name="cancellationToken">取消令牌。</param>
+        /// <returns>授权检查结果。</returns>
        Task<ThirdPartyAuthCheckResult> ValidateAuthorizationCodeAsync(string authorizationCode, CancellationToken cancellationToken = default);

+        /// <summary>
+        /// 刷新第三方授权。
+        /// </summary>
+        /// <param name="authorizationReference">授权引用标识。</param>
+        /// <param name="cancellationToken">取消令牌。</param>
+        /// <returns>授权检查结果。</returns>
        Task<ThirdPartyAuthCheckResult> RefreshAuthorizationAsync(string authorizationReference, CancellationToken cancellationToken = default);
    }
 }
@@ -3,21 +3,57 @@ using System.Threading.Tasks;

 namespace Avalonia_Services.Services.AuthService
 {
+    /// <summary>
+    /// API 鉴权端点服务接口，定义登录、刷新 Token 和登出操作。
+    /// </summary>
    public interface IApiAuthEndpointService
    {
+        /// <summary>
+        /// 处理用户登录请求。
+        /// </summary>
+        /// <param name="ctx">服务端点上下文。</param>
+        /// <returns>包含 Token 的认证响应。</returns>
        Task<object?> LoginAsync(ServiceEndpointContext ctx);

+        /// <summary>
+        /// 使用 Refresh Token 刷新 Access Token。
+        /// </summary>
+        /// <param name="ctx">服务端点上下文。</param>
+        /// <returns>新的 Token 对。</returns>
        Task<object?> RefreshAsync(ServiceEndpointContext ctx);

+        /// <summary>
+        /// 处理用户登出请求。
+        /// </summary>
+        /// <param name="ctx">服务端点上下文。</param>
+        /// <returns>登出结果。</returns>
        Task<object?> LogoutAsync(ServiceEndpointContext ctx);
    }

+    /// <summary>
+    /// PC 端鉴权端点服务接口，定义授权码登录、Token 刷新和登出操作。
+    /// </summary>
    public interface IPcAuthEndpointService
    {
+        /// <summary>
+        /// 使用授权码进行登录授权。
+        /// </summary>
+        /// <param name="ctx">服务端点上下文。</param>
+        /// <returns>包含 Token 的认证响应。</returns>
        Task<object?> AuthorizeAsync(ServiceEndpointContext ctx);

+        /// <summary>
+        /// 刷新当前 Token。
+        /// </summary>
+        /// <param name="ctx">服务端点上下文。</param>
+        /// <returns>新的 Token 响应。</returns>
        Task<object?> RefreshAsync(ServiceEndpointContext ctx);

+        /// <summary>
+        /// 处理用户登出请求。
+        /// </summary>
+        /// <param name="ctx">服务端点上下文。</param>
+        /// <returns>登出结果。</returns>
        Task<object?> LogoutAsync(ServiceEndpointContext ctx);
    }
 }
@@ -2,6 +2,9 @@ using Avalonia_EFCore.Models;

 namespace Avalonia_Services.Services
 {
+    /// <summary>
+    /// 天气预报服务，随机生成未来 5 天的天气预报数据。
+    /// </summary>
    public class WeatherForecastService
    {
        private static readonly string[] Summaries =
@@ -9,6 +12,10 @@ namespace Avalonia_Services.Services
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        ];

+        /// <summary>
+        /// 生成未来 5 天的随机天气预报数据。
+        /// </summary>
+        /// <returns>天气预报数据集合。</returns>
        public IEnumerable<WeatherForecast> GetWeatherForecasts()
        {
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast