feat: 二维码访问功能，统一端点管道增强，端点迁移至 Services 层

- 新增二维码生成端点，自动检测局域网 IP，前端扫一扫即可打开网站
  - 提取 IApiResponse 接口，ServiceRequestBinder 支持强类型请求 DTO 绑定
  - FileStream 端点迁移至 AppEndpoints 统一注册，管道支持 FileStreamResponse 原始文件返回
  - 文件库端点全面使用 MapGet<TService, TRequest> 泛型注册
  - 移除 Avalonia-API/Extensions 中的业务端点文件，统一由 Services 层管理

Avalonia-Services/Avalonia-Services.csproj

@@ -9,6 +9,7 @@
 
   <ItemGroup>
     <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.7" />
+    <PackageReference Include="QRCoder" Version="1.8.0" />
     <PackageReference Include="Serilog" Version="4.2.0" />
     <PackageReference Include="Serilog.Sinks.Console" Version="6.0.0" />
     <PackageReference Include="Serilog.Sinks.File" Version="6.0.0" />

Avalonia-Services/Core/FileStreamResponse.cs

@@ -0,0 +1,11 @@
+namespace Avalonia_Services.Core
+{
+    /// <summary>
+    /// 文件流响应 —— 管道检测到此类型时将返回原始文件而非 JSON。
+    /// </summary>
+    public sealed record FileStreamResponse(
+        string FilePath,
+        string FileName,
+        string ContentType,
+        DateTime LastModified);
+}

Avalonia-Services/Core/ServiceEndpointCollection.cs

@@ -1,3 +1,4 @@
+using Avalonia_Common.Core;
 using System;
 using System.Collections.Generic;
 using System.Threading.Tasks;
@@ -177,6 +178,14 @@ namespace Avalonia_Services.Core
             return AddEndpoint(pattern, "GET", handler);
         }
 
+        /// <summary>
+        /// 注册一个返回统一响应契约的 GET 端点。
+        /// </summary>
+        public ServiceEndpoint MapGet(string pattern, Func<ServiceEndpointContext, Task<IApiResponse>> handler)
+        {
+            return MapGet(pattern, CreateApiResponseHandler(handler));
+        }
+
         /// <summary>
         /// 注册一个带服务依赖注入的 GET 端点。
         /// </summary>
@@ -192,6 +201,33 @@ namespace Avalonia_Services.Core
             return MapGet(pattern, CreateServiceHandler(handler));
         }
 
+        /// <summary>
+        /// 注册一个带服务依赖注入且返回统一响应契约的 GET 端点。
+        /// </summary>
+        public ServiceEndpoint MapGet<TService>(
+            string pattern,
+            Func<TService, ServiceEndpointContext, Task<IApiResponse>> handler)
+            where TService : notnull
+        {
+            return MapGet(pattern, CreateServiceHandler(handler));
+        }
+
+        /// <summary>
+        /// 注册一个带查询请求 DTO 和服务依赖注入的 GET 端点。
+        /// </summary>
+        public ServiceEndpoint MapGet<TService, TRequest>(
+            string pattern,
+            Func<TService, TRequest, ServiceEndpointContext, Task<IApiResponse>> handler)
+            where TService : notnull
+        {
+            var endpoint = MapGet(
+                pattern,
+                CreateServiceHandler<TService>((service, ctx) =>
+                    handler(service, ServiceRequestBinder.BindQuery<TRequest>(ctx), ctx)));
+            endpoint.OpenApiRequestType ??= typeof(TRequest);
+            return endpoint;
+        }
+
         /// <summary>
         /// 注册一个 POST 端点。
         /// </summary>
@@ -200,6 +236,14 @@ namespace Avalonia_Services.Core
             return AddEndpoint(pattern, "POST", handler);
         }
 
+        /// <summary>
+        /// 注册一个返回统一响应契约的 POST 端点。
+        /// </summary>
+        public ServiceEndpoint MapPost(string pattern, Func<ServiceEndpointContext, Task<IApiResponse>> handler)
+        {
+            return MapPost(pattern, CreateApiResponseHandler(handler));
+        }
+
         /// <summary>
         /// 注册一个带服务依赖注入的 POST 端点。
         /// </summary>
@@ -215,6 +259,33 @@ namespace Avalonia_Services.Core
             return MapPost(pattern, CreateServiceHandler(handler));
         }
 
+        /// <summary>
+        /// 注册一个带服务依赖注入且返回统一响应契约的 POST 端点。
+        /// </summary>
+        public ServiceEndpoint MapPost<TService>(
+            string pattern,
+            Func<TService, ServiceEndpointContext, Task<IApiResponse>> handler)
+            where TService : notnull
+        {
+            return MapPost(pattern, CreateServiceHandler(handler));
+        }
+
+        /// <summary>
+        /// 注册一个带 JSON 请求 DTO 和服务依赖注入的 POST 端点。
+        /// </summary>
+        public ServiceEndpoint MapPost<TService, TRequest>(
+            string pattern,
+            Func<TService, TRequest, ServiceEndpointContext, Task<IApiResponse>> handler)
+            where TService : notnull
+        {
+            var endpoint = MapPost(
+                pattern,
+                CreateServiceHandler<TService>((service, ctx) =>
+                    handler(service, ServiceRequestBinder.BindBody<TRequest>(ctx), ctx)));
+            endpoint.OpenApiRequestType ??= typeof(TRequest);
+            return endpoint;
+        }
+
         /// <summary>
         /// 注册一个 PUT 端点。
         /// </summary>
@@ -223,6 +294,14 @@ namespace Avalonia_Services.Core
             return AddEndpoint(pattern, "PUT", handler);
         }
 
+        /// <summary>
+        /// 注册一个返回统一响应契约的 PUT 端点。
+        /// </summary>
+        public ServiceEndpoint MapPut(string pattern, Func<ServiceEndpointContext, Task<IApiResponse>> handler)
+        {
+            return MapPut(pattern, CreateApiResponseHandler(handler));
+        }
+
         /// <summary>
         /// 注册一个带服务依赖注入的 PUT 端点。
         /// </summary>
@@ -238,6 +317,33 @@ namespace Avalonia_Services.Core
             return MapPut(pattern, CreateServiceHandler(handler));
         }
 
+        /// <summary>
+        /// 注册一个带服务依赖注入且返回统一响应契约的 PUT 端点。
+        /// </summary>
+        public ServiceEndpoint MapPut<TService>(
+            string pattern,
+            Func<TService, ServiceEndpointContext, Task<IApiResponse>> handler)
+            where TService : notnull
+        {
+            return MapPut(pattern, CreateServiceHandler(handler));
+        }
+
+        /// <summary>
+        /// 注册一个带 JSON 请求 DTO 和服务依赖注入的 PUT 端点。
+        /// </summary>
+        public ServiceEndpoint MapPut<TService, TRequest>(
+            string pattern,
+            Func<TService, TRequest, ServiceEndpointContext, Task<IApiResponse>> handler)
+            where TService : notnull
+        {
+            var endpoint = MapPut(
+                pattern,
+                CreateServiceHandler<TService>((service, ctx) =>
+                    handler(service, ServiceRequestBinder.BindBody<TRequest>(ctx), ctx)));
+            endpoint.OpenApiRequestType ??= typeof(TRequest);
+            return endpoint;
+        }
+
         /// <summary>
         /// 注册一个 DELETE 端点。
         /// </summary>
@@ -246,6 +352,14 @@ namespace Avalonia_Services.Core
             return AddEndpoint(pattern, "DELETE", handler);
         }
 
+        /// <summary>
+        /// 注册一个返回统一响应契约的 DELETE 端点。
+        /// </summary>
+        public ServiceEndpoint MapDelete(string pattern, Func<ServiceEndpointContext, Task<IApiResponse>> handler)
+        {
+            return MapDelete(pattern, CreateApiResponseHandler(handler));
+        }
+
         /// <summary>
         /// 注册一个带服务依赖注入的 DELETE 端点。
         /// </summary>
@@ -261,6 +375,33 @@ namespace Avalonia_Services.Core
             return MapDelete(pattern, CreateServiceHandler(handler));
         }
 
+        /// <summary>
+        /// 注册一个带服务依赖注入且返回统一响应契约的 DELETE 端点。
+        /// </summary>
+        public ServiceEndpoint MapDelete<TService>(
+            string pattern,
+            Func<TService, ServiceEndpointContext, Task<IApiResponse>> handler)
+            where TService : notnull
+        {
+            return MapDelete(pattern, CreateServiceHandler(handler));
+        }
+
+        /// <summary>
+        /// 注册一个带查询请求 DTO 和服务依赖注入的 DELETE 端点。
+        /// </summary>
+        public ServiceEndpoint MapDelete<TService, TRequest>(
+            string pattern,
+            Func<TService, TRequest, ServiceEndpointContext, Task<IApiResponse>> handler)
+            where TService : notnull
+        {
+            var endpoint = MapDelete(
+                pattern,
+                CreateServiceHandler<TService>((service, ctx) =>
+                    handler(service, ServiceRequestBinder.BindQuery<TRequest>(ctx), ctx)));
+            endpoint.OpenApiRequestType ??= typeof(TRequest);
+            return endpoint;
+        }
+
         /// <summary>
         /// 添加全局过滤器（作用于所有端点）。
         /// </summary>
@@ -318,6 +459,33 @@ namespace Avalonia_Services.Core
                 return await handler(service, ctx);
             };
         }
+
+        /// <summary>
+        /// 将统一响应契约适配为端点集合内部使用的异构响应类型。
+        /// </summary>
+        private static Func<ServiceEndpointContext, Task<object?>> CreateApiResponseHandler(
+            Func<ServiceEndpointContext, Task<IApiResponse>> handler)
+        {
+            return async ctx => await handler(ctx);
+        }
+
+        /// <summary>
+        /// 为服务端点创建统一响应契约的 DI 包装。
+        /// </summary>
+        private static Func<ServiceEndpointContext, Task<IApiResponse>> CreateServiceHandler<TService>(
+            Func<TService, ServiceEndpointContext, Task<IApiResponse>> handler)
+            where TService : notnull
+        {
+            return async ctx =>
+            {
+                var serviceProvider = ctx.Items["ServiceProvider"] as IServiceProvider
+                    ?? throw new InvalidOperationException("ServiceProvider 未注入。");
+
+                await using var scope = serviceProvider.CreateAsyncScope();
+                var service = scope.ServiceProvider.GetRequiredService<TService>();
+                return await handler(service, ctx);
+            };
+        }
     }
 
     /// <summary>

Avalonia-Services/Core/ServiceEndpointContext.cs

@@ -32,6 +32,11 @@ namespace Avalonia_Services.Core
         /// </summary>
         public Dictionary<string, string> Query { get; init; } = new(StringComparer.OrdinalIgnoreCase);
 
+        /// <summary>
+        /// 路由路径参数。
+        /// </summary>
+        public Dictionary<string, string> RouteValues { get; init; } = new(StringComparer.OrdinalIgnoreCase);
+
         /// <summary>
         /// 响应状态码
         /// </summary>

Avalonia-Services/Core/ServiceEndpointPatternMatcher.cs

@@ -0,0 +1,75 @@
+namespace Avalonia_Services.Core
+{
+    /// <summary>
+    /// Matches unified endpoint patterns and extracts simple route values.
+    /// </summary>
+    internal static class ServiceEndpointPatternMatcher
+    {
+        /// <summary>
+        /// Match literal segments and single-segment route parameters such as {id} or {id:int}.
+        /// </summary>
+        public static bool TryMatch(
+            string pattern,
+            string path,
+            out Dictionary<string, string> routeValues)
+        {
+            routeValues = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+
+            var patternSegments = SplitSegments(pattern);
+            var pathSegments = SplitSegments(path);
+            if (patternSegments.Length != pathSegments.Length)
+            {
+                return false;
+            }
+
+            for (var index = 0; index < patternSegments.Length; index++)
+            {
+                var patternSegment = patternSegments[index];
+                var pathSegment = pathSegments[index];
+
+                if (TryGetParameterName(patternSegment, out var parameterName))
+                {
+                    if (!MatchesConstraint(patternSegment, pathSegment))
+                    {
+                        return false;
+                    }
+
+                    routeValues[parameterName] = Uri.UnescapeDataString(pathSegment);
+                    continue;
+                }
+
+                if (!string.Equals(patternSegment, pathSegment, StringComparison.OrdinalIgnoreCase))
+                {
+                    return false;
+                }
+            }
+
+            return true;
+        }
+
+        private static string[] SplitSegments(string value)
+        {
+            return value.Split('/', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        }
+
+        private static bool TryGetParameterName(string segment, out string parameterName)
+        {
+            parameterName = string.Empty;
+            if (segment.Length < 3 || segment[0] != '{' || segment[^1] != '}')
+            {
+                return false;
+            }
+
+            var token = segment[1..^1];
+            var constraintIndex = token.IndexOf(':');
+            parameterName = constraintIndex >= 0 ? token[..constraintIndex] : token;
+            return !string.IsNullOrWhiteSpace(parameterName);
+        }
+
+        private static bool MatchesConstraint(string segment, string value)
+        {
+            return !segment.EndsWith(":int}", StringComparison.OrdinalIgnoreCase)
+                || int.TryParse(value, out _);
+        }
+    }
+}

Avalonia-Services/Core/ServiceRequestBinder.cs

@@ -0,0 +1,53 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Avalonia_Services.Core
+{
+    /// <summary>
+    /// Binds unified endpoint request models from JSON bodies or query parameters.
+    /// </summary>
+    internal static class ServiceRequestBinder
+    {
+        private static readonly JsonSerializerOptions JsonOptions = new(JsonSerializerDefaults.Web)
+        {
+            NumberHandling = JsonNumberHandling.AllowReadingFromString,
+        };
+
+        /// <summary>
+        /// Bind a JSON request body. Empty bodies are treated as an empty JSON object.
+        /// </summary>
+        public static T BindBody<T>(ServiceEndpointContext context)
+        {
+            var json = string.IsNullOrWhiteSpace(context.Body) ? "{}" : context.Body;
+            return Deserialize<T>(json, "body");
+        }
+
+        /// <summary>
+        /// Bind route and query parameters to a request DTO.
+        /// </summary>
+        public static T BindQuery<T>(ServiceEndpointContext context)
+        {
+            var values = new Dictionary<string, string>(context.Query, StringComparer.OrdinalIgnoreCase);
+            foreach (var routeValue in context.RouteValues)
+            {
+                values[routeValue.Key] = routeValue.Value;
+            }
+
+            var json = JsonSerializer.Serialize(values, JsonOptions);
+            return Deserialize<T>(json, "query");
+        }
+
+        private static T Deserialize<T>(string json, string source)
+        {
+            try
+            {
+                return JsonSerializer.Deserialize<T>(json, JsonOptions)
+                    ?? throw new ArgumentException($"Request {source} cannot be bound to {typeof(T).Name}.");
+            }
+            catch (JsonException ex)
+            {
+                throw new ArgumentException($"Request {source} cannot be bound to {typeof(T).Name}.", ex);
+            }
+        }
+    }
+}

Avalonia-Services/Endpoints/AppEndpoints.cs

@@ -1,10 +1,7 @@
 using Avalonia_Common.Core;
-using Avalonia_EFCore.Database;
-using Avalonia_EFCore.Models;
 using Avalonia_Services.Core;
-using Avalonia_Services.Services;
 using Avalonia_Services.Services.FileLibrary;
-using Microsoft.EntityFrameworkCore;
+using Avalonia_Services.Services.QrCode;
 
 namespace Avalonia_Services.Endpoints
 {
@@ -35,24 +32,12 @@ namespace Avalonia_Services.Endpoints
                 });
 
                 // ---- 业务端点注册 ----
-                // 天气预报（从数据库读取）
-                endpoints.MapGet("api/wData", GetWeatherForecastsAsync)
-                    .WithOpenApi("Weather", "获取天气预报信息。")
-                    .WithName("GetWeatherForecast");
-
-                // 获取用户（演示从数据库查询）
-                endpoints.MapGet("api/getUser", GetUserFromDatabaseAsync)
-                    .WithName("GetUser");
-
-                // 处理数据（POST — 演示参数处理）
-                endpoints.MapPost("api/processData", ProcessDataAsync)
-                    .WithName("ProcessData");
 
                 endpoints.MapGet<IFileLibraryEndpointService>("api/library/drives", (service, ctx) => service.GetDrivesAsync(ctx))
                     .WithOpenApi("FileLibrary", "查询服务器磁盘。")
                     .WithName("GetLibraryDrives");
 
-                endpoints.MapGet<IFileLibraryEndpointService>("api/library/directories", (service, ctx) => service.GetDirectoriesAsync(ctx))
+                endpoints.MapGet<IFileLibraryEndpointService, DirectoryQueryRequest>("api/library/directories", (service, request, _) => service.GetDirectoriesAsync(request))
                     .WithOpenApi("FileLibrary", "查询服务器目录。")
                     .WithName("GetLibraryDirectories");
 
@@ -60,34 +45,42 @@ namespace Avalonia_Services.Endpoints
                     .WithOpenApi("FileLibrary", "查询文件库目录。")
                     .WithName("GetLibraryRoots");
 
-                endpoints.MapPost<IFileLibraryEndpointService>("api/library/roots", (service, ctx) => service.AddRootAsync(ctx))
+                endpoints.MapPost<IFileLibraryEndpointService, AddLibraryRootRequest>("api/library/roots", (service, request, _) => service.AddRootAsync(request))
                     .WithOpenApi("FileLibrary", "添加文件库目录。")
                     .WithName("AddLibraryRoot");
 
-                endpoints.MapPost<IFileLibraryEndpointService>("api/library/roots/enabled", (service, ctx) => service.SetRootEnabledAsync(ctx))
+                endpoints.MapPost<IFileLibraryEndpointService, UpdateLibraryRootRequest>("api/library/roots/enabled", (service, request, _) => service.SetRootEnabledAsync(request))
                     .WithOpenApi("FileLibrary", "启用或禁用文件库目录。")
                     .WithName("SetLibraryRootEnabled");
 
-                endpoints.MapPost<IFileLibraryEndpointService>("api/library/roots/delete", (service, ctx) => service.DeleteRootAsync(ctx))
+                endpoints.MapPost<IFileLibraryEndpointService, DeleteLibraryRootRequest>("api/library/roots/delete", (service, request, _) => service.DeleteRootAsync(request))
                     .WithOpenApi("FileLibrary", "删除文件库目录。")
                     .WithName("DeleteLibraryRoot");
 
-                endpoints.MapPost<IFileLibraryEndpointService>("api/library/roots/scan", (service, ctx) => service.ScanRootAsync(ctx))
+                endpoints.MapPost<IFileLibraryEndpointService, ScanLibraryRootRequest>("api/library/roots/scan", (service, request, _) => service.ScanRootAsync(request))
                     .WithOpenApi("FileLibrary", "立即扫描文件库目录。")
                     .WithName("ScanLibraryRoot");
 
-                endpoints.MapGet<IFileLibraryEndpointService>("api/files", (service, ctx) => service.SearchFilesAsync(ctx))
+                endpoints.MapGet<IFileLibraryEndpointService, SearchFilesRequest>("api/files", (service, request, _) => service.SearchFilesAsync(request))
                     .WithOpenApi("FileLibrary", "分页查询已扫描文件。")
                     .WithName("SearchFiles");
 
-                endpoints.MapGet<IFileLibraryEndpointService>("api/files/detail", (service, ctx) => service.GetFileAsync(ctx))
+                endpoints.MapGet<IFileLibraryEndpointService, FileQueryRequest>("api/files/detail", (service, request, _) => service.GetFileAsync(request))
                     .WithOpenApi("FileLibrary", "查询文件详情。")
                     .WithName("GetFileDetail");
 
-                endpoints.MapGet<IFileLibraryEndpointService>("api/files/text", (service, ctx) => service.GetTextPreviewAsync(ctx))
+                endpoints.MapGet<IFileLibraryEndpointService, FileQueryRequest>("api/files/text", (service, request, _) => service.GetTextPreviewAsync(request))
                     .WithOpenApi("FileLibrary", "预览文本文件。")
                     .WithName("GetTextPreview");
 
+                endpoints.MapGet("api/files/stream", GetFileStreamAsync)
+                    .WithOpenApi("FileLibrary", "流式传输文件（支持 Range 请求）。")
+                    .WithName("StreamManagedFile");
+
+                endpoints.MapGet<IQrCodeService>("api/qrcode", (service, ctx) => service.GenerateQrCodeAsync(ctx))
+                    .WithOpenApi("Utility", "生成局域网访问二维码。")
+                    .WithName("GetQrCode");
+
                 // ---- 需要鉴权的端点示例 ----
                 // endpoints.MapGet("api/admin/dashboard", AdminDashboardAsync)
                 //     .WithName("AdminDashboard")
@@ -101,86 +94,16 @@ namespace Avalonia_Services.Endpoints
 
         #region 业务处理方法
 
-        /// <summary>
-        /// 从数据库查询天气预报（优先数据库，回退到内存生成）。
-        /// </summary>
-        private static async Task<object?> GetWeatherForecastsAsync(ServiceEndpointContext ctx)
+        private static async Task<object?> GetFileStreamAsync(ServiceEndpointContext ctx)
         {
             var sp = ctx.Items["ServiceProvider"] as IServiceProvider;
+            var service = sp?.GetService(typeof(IFileStreamService)) as IFileStreamService;
+            if (service is null) return null;
 
-            // 尝试从数据库读取
-            if (sp?.GetService(typeof(AppDataContext)) is AppDataContext db)
-            {
-                var dbForecasts = await db.WeatherForecasts
-                    .OrderByDescending(f => f.Date)
-                    .Take(5)
-                    .ToListAsync();
+            if (!int.TryParse(ctx.Query.GetValueOrDefault("id"), out var id) || id <= 0)
+                return null;
 
-                if (dbForecasts.Count > 0)
-                {
-                    return ResponseHelper.Ok(dbForecasts, "获取天气预报成功（来自数据库）");
-                }
-            }
-
-            // 回退：内存生成（数据库为空时）
-            var service = sp?.GetService(typeof(WeatherForecastService)) as WeatherForecastService
-                ?? new WeatherForecastService();
-
-            var forecasts = service.GetWeatherForecasts();
-            return ResponseHelper.Ok(forecasts, "获取天气预报成功（内存生成）");
-        }
-
-        /// <summary>
-        /// 从数据库获取用户信息（演示数据库查询），若无数据则返回演示用户。
-        /// </summary>
-        /// <param name="ctx">服务端点上下文。</param>
-        /// <returns>用户信息。</returns>
-        private static async Task<object?> GetUserFromDatabaseAsync(ServiceEndpointContext ctx)
-        {
-            var sp = ctx.Items["ServiceProvider"] as IServiceProvider;
-
-            // 尝试从数据库读取用户
-            if (sp?.GetService(typeof(AppDataContext)) is AppDataContext db)
-            {
-                var users = await db.Set<UserEntity>().Take(1).ToListAsync();
-                if (users.Count > 0)
-                {
-                    return ResponseHelper.Ok(users[0], "获取用户成功（来自数据库）");
-                }
-            }
-
-            // 回退：演示数据
-            await Task.Delay(100);
-            var user = new { id = 1, name = "张三", email = "zhangsan@example.com" };
-            return ResponseHelper.Ok(user);
-        }
-
-        /// <summary>
-        /// 处理前端发送的数据（POST 演示），将数据存入数据库或转为大写返回。
-        /// </summary>
-        /// <param name="ctx">服务端点上下文。</param>
-        /// <returns>处理结果。</returns>
-        private static async Task<object?> ProcessDataAsync(ServiceEndpointContext ctx)
-        {
-            var sp = ctx.Items["ServiceProvider"] as IServiceProvider;
-
-            // 演示：将收到的数据存入数据库
-            var input = ctx.Body ?? string.Empty;
-            if (sp?.GetService(typeof(AppDataContext)) is AppDataContext db && !string.IsNullOrWhiteSpace(input))
-            {
-                var forecast = new WeatherForecastEntity
-                {
-                    Date = DateOnly.FromDateTime(DateTime.Now),
-                    TemperatureC = 20,
-                    Summary = input,
-                };
-                db.WeatherForecasts.Add(forecast);
-                await db.SaveChangesAsync();
-                return ResponseHelper.Ok(forecast, "数据已存入数据库");
-            }
-
-            await Task.Delay(200);
-            return ResponseHelper.Ok(new { input, processed = input.ToUpperInvariant() });
+            return await service.GetFileStreamAsync(id);
         }
 
         #endregion

Avalonia-Services/Endpoints/AuthEndpoints.cs

@@ -16,17 +16,17 @@ namespace Avalonia_Services.Endpoints
         {
             builder.ConfigureEndpoints(endpoints =>
             {
-                endpoints.MapPost<IApiAuthEndpointService>("api/auth/login", (service, ctx) => service.LoginAsync(ctx))
+                endpoints.MapPost<IApiAuthEndpointService, ApiLoginRequest>("api/auth/login", (service, request, ctx) => service.LoginAsync(request, ctx))
                     .WithName("ApiLogin")
                     .WithOpenApi("Auth", "API 登录，返回 access token 和 refresh token。", "", typeof(ApiLoginRequest), typeof(AuthTokenResponse))
                     .ApiOnly();
 
-                endpoints.MapPost<IApiAuthEndpointService>("api/auth/refresh", (service, ctx) => service.RefreshAsync(ctx))
+                endpoints.MapPost<IApiAuthEndpointService, ApiRefreshTokenRequest>("api/auth/refresh", (service, request, ctx) => service.RefreshAsync(request, ctx))
                     .WithName("ApiRefresh")
                     .WithOpenApi("Auth", "API refresh token 轮换。", "", typeof(ApiRefreshTokenRequest), typeof(AuthTokenResponse))
                     .ApiOnly();
 
-                endpoints.MapPost<IApiAuthEndpointService>("api/auth/logout", (service, ctx) => service.LogoutAsync(ctx))
+                endpoints.MapPost<IApiAuthEndpointService, ApiLogoutRequest>("api/auth/logout", (service, request, ctx) => service.LogoutAsync(request, ctx))
                     .WithName("ApiLogout")
                     .WithOpenApi("Auth", "API 退出登录并吊销 refresh token。", "", typeof(ApiLogoutRequest))
                     .ApiOnly();
@@ -41,17 +41,17 @@ namespace Avalonia_Services.Endpoints
         {
             builder.ConfigureEndpoints(endpoints =>
             {
-                endpoints.MapPost<IPcAuthEndpointService>("api/pc/auth/authorize", (service, ctx) => service.AuthorizeAsync(ctx))
+                endpoints.MapPost<IPcAuthEndpointService, PcAuthorizeRequest>("api/pc/auth/authorize", (service, request, ctx) => service.AuthorizeAsync(request, ctx))
                     .WithName("PcAuthorize")
                     .WithOpenApi("Auth", "PC 授权码登录，生成本地全局 token。", "", typeof(PcAuthorizeRequest), typeof(PcTokenResponse))
                     .PcOnly();
 
-                endpoints.MapPost<IPcAuthEndpointService>("api/pc/auth/refresh", (service, ctx) => service.RefreshAsync(ctx))
+                endpoints.MapPost<IPcAuthEndpointService, PcRefreshRequest>("api/pc/auth/refresh", (service, request, ctx) => service.RefreshAsync(request, ctx))
                     .WithName("PcRefresh")
                     .WithOpenApi("Auth", "PC 全局 token 刷新。", "", typeof(PcRefreshRequest), typeof(PcTokenResponse))
                     .PcOnly();
 
-                endpoints.MapPost<IPcAuthEndpointService>("api/pc/auth/logout", (service, ctx) => service.LogoutAsync(ctx))
+                endpoints.MapPost<IPcAuthEndpointService, PcLogoutRequest>("api/pc/auth/logout", (service, request, ctx) => service.LogoutAsync(request, ctx))
                     .WithName("PcLogout")
                     .WithOpenApi("Auth", "PC 退出登录。", "", typeof(PcLogoutRequest))
                     .PcOnly();

Avalonia-Services/Extensions/DesktopEndpointAdapter.cs

@@ -109,10 +109,19 @@ namespace Avalonia_Services.Extensions
             Dictionary<string, string>? query = null)
         {
             // 查找匹配的端点（忽略大小写 + 方法匹配）
-            var endpoint = _endpoints.Endpoints.FirstOrDefault(e =>
-                e.SupportsHost(EndpointHostTarget.Pc) &&
-                string.Equals(e.Pattern, path, StringComparison.OrdinalIgnoreCase) &&
-                string.Equals(e.HttpMethod, method, StringComparison.OrdinalIgnoreCase));
+            var match = _endpoints.Endpoints
+                .Where(e =>
+                    e.SupportsHost(EndpointHostTarget.Pc) &&
+                    string.Equals(e.HttpMethod, method, StringComparison.OrdinalIgnoreCase))
+                .Select(e => new
+                {
+                    Endpoint = e,
+                    IsMatched = ServiceEndpointPatternMatcher.TryMatch(e.Pattern, path, out var routeValues),
+                    RouteValues = routeValues,
+                })
+                .FirstOrDefault(candidate => candidate.IsMatched);
+
+            var endpoint = match?.Endpoint;
 
             if (endpoint is null)
             {
@@ -127,6 +136,7 @@ namespace Avalonia_Services.Extensions
                 Body = body,
                 Headers = headers ?? new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase),
                 Query = query ?? new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase),
+                RouteValues = match!.RouteValues,
                 Items = { ["ServiceProvider"] = _serviceProvider },
             };
 

Avalonia-Services/Services/AuthService/AuthEndpointServices.cs

@@ -1,3 +1,4 @@
+using Avalonia_Common.Core;
 using Avalonia_Services.Core;
 using System.Threading.Tasks;
 
@@ -13,21 +14,21 @@ namespace Avalonia_Services.Services.AuthService
         /// </summary>
         /// <param name="ctx">服务端点上下文。</param>
         /// <returns>包含 Token 的认证响应。</returns>
-        Task<object?> LoginAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> LoginAsync(ApiLoginRequest request, ServiceEndpointContext ctx);
 
         /// <summary>
         /// 使用 Refresh Token 刷新 Access Token。
         /// </summary>
         /// <param name="ctx">服务端点上下文。</param>
         /// <returns>新的 Token 对。</returns>
-        Task<object?> RefreshAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> RefreshAsync(ApiRefreshTokenRequest request, ServiceEndpointContext ctx);
 
         /// <summary>
         /// 处理用户登出请求。
         /// </summary>
         /// <param name="ctx">服务端点上下文。</param>
         /// <returns>登出结果。</returns>
-        Task<object?> LogoutAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> LogoutAsync(ApiLogoutRequest request, ServiceEndpointContext ctx);
     }
 
     /// <summary>
@@ -40,20 +41,20 @@ namespace Avalonia_Services.Services.AuthService
         /// </summary>
         /// <param name="ctx">服务端点上下文。</param>
         /// <returns>包含 Token 的认证响应。</returns>
-        Task<object?> AuthorizeAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> AuthorizeAsync(PcAuthorizeRequest request, ServiceEndpointContext ctx);
 
         /// <summary>
         /// 刷新当前 Token。
         /// </summary>
         /// <param name="ctx">服务端点上下文。</param>
         /// <returns>新的 Token 响应。</returns>
-        Task<object?> RefreshAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> RefreshAsync(PcRefreshRequest request, ServiceEndpointContext ctx);
 
         /// <summary>
         /// 处理用户登出请求。
         /// </summary>
         /// <param name="ctx">服务端点上下文。</param>
         /// <returns>登出结果。</returns>
-        Task<object?> LogoutAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> LogoutAsync(PcLogoutRequest request, ServiceEndpointContext ctx);
     }
 }

Avalonia-Services/Services/FileLibrary/FileLibraryContracts.cs

@@ -17,6 +17,19 @@ namespace Avalonia_Services.Services.FileLibrary
     public sealed record DeleteLibraryRootRequest(
         [property: JsonPropertyName("id")] int Id);
 
+    public sealed record DirectoryQueryRequest(
+        [property: JsonPropertyName("path")] string? Path);
+
+    public sealed record FileQueryRequest(
+        [property: JsonPropertyName("id")] int Id);
+
+    public sealed record SearchFilesRequest(
+        [property: JsonPropertyName("page")] int Page = 1,
+        [property: JsonPropertyName("pageSize")] int PageSize = 24,
+        [property: JsonPropertyName("mediaType")] string? MediaType = null,
+        [property: JsonPropertyName("keyword")] string? Keyword = null,
+        [property: JsonPropertyName("rootId")] int RootId = 0);
+
     public sealed record DriveDto(
         string Name,
         string DisplayName,

Avalonia-Services/Services/FileLibrary/FileLibraryEndpointService.cs

@@ -1,99 +1,77 @@
 using Avalonia_Common.Core;
 using Avalonia_Services.Core;
-using System.Text.Json;
 
 namespace Avalonia_Services.Services.FileLibrary
 {
     public sealed class FileLibraryEndpointService(IFileLibraryService fileLibrary) : IFileLibraryEndpointService
     {
-        private static readonly JsonSerializerOptions JsonOptions = new()
-        {
-            PropertyNameCaseInsensitive = true,
-        };
-
-        public async Task<object?> GetDrivesAsync(ServiceEndpointContext ctx)
+        public async Task<IApiResponse> GetDrivesAsync(ServiceEndpointContext ctx)
         {
             return ResponseHelper.Ok(await fileLibrary.GetDrivesAsync());
         }
 
-        public async Task<object?> GetDirectoriesAsync(ServiceEndpointContext ctx)
+        public async Task<IApiResponse> GetDirectoriesAsync(DirectoryQueryRequest request)
         {
-            var path = ctx.Query.GetValueOrDefault("path");
-            return ResponseHelper.Ok(await fileLibrary.GetDirectoriesAsync(path));
+            return ResponseHelper.Ok(await fileLibrary.GetDirectoriesAsync(request.Path));
         }
 
-        public async Task<object?> GetRootsAsync(ServiceEndpointContext ctx)
+        public async Task<IApiResponse> GetRootsAsync(ServiceEndpointContext ctx)
         {
             return ResponseHelper.Ok(await fileLibrary.GetRootsAsync());
         }
 
-        public async Task<object?> AddRootAsync(ServiceEndpointContext ctx)
+        public async Task<IApiResponse> AddRootAsync(AddLibraryRootRequest request)
         {
-            var request = ReadBody<AddLibraryRootRequest>(ctx);
             return ResponseHelper.Ok(await fileLibrary.AddRootAsync(request), "文件库目录已添加并完成扫描。");
         }
 
-        public async Task<object?> SetRootEnabledAsync(ServiceEndpointContext ctx)
+        public async Task<IApiResponse> SetRootEnabledAsync(UpdateLibraryRootRequest request)
         {
-            var request = ReadBody<UpdateLibraryRootRequest>(ctx);
             return ResponseHelper.Ok(await fileLibrary.SetRootEnabledAsync(request), "文件库目录状态已更新。");
         }
 
-        public async Task<object?> DeleteRootAsync(ServiceEndpointContext ctx)
+        public async Task<IApiResponse> DeleteRootAsync(DeleteLibraryRootRequest request)
         {
-            var request = ReadBody<DeleteLibraryRootRequest>(ctx);
             await fileLibrary.DeleteRootAsync(request);
             return ResponseHelper.Succeed("文件库目录已删除。");
         }
 
-        public async Task<object?> ScanRootAsync(ServiceEndpointContext ctx)
+        public async Task<IApiResponse> ScanRootAsync(ScanLibraryRootRequest request)
         {
-            var request = ReadBody<ScanLibraryRootRequest>(ctx);
             return ResponseHelper.Ok(await fileLibrary.ScanRootAsync(request.Id), "文件库目录扫描完成。");
         }
 
-        public async Task<object?> SearchFilesAsync(ServiceEndpointContext ctx)
+        public async Task<IApiResponse> SearchFilesAsync(SearchFilesRequest request)
         {
-            return await fileLibrary.SearchFilesAsync(ctx);
+            return await fileLibrary.SearchFilesAsync(request);
         }
 
-        public async Task<object?> GetFileAsync(ServiceEndpointContext ctx)
+        public async Task<IApiResponse> GetFileAsync(FileQueryRequest request)
         {
-            var id = ReadId(ctx);
-            var file = await fileLibrary.GetFileAsync(id);
+            ValidateFileId(request.Id);
+            var file = await fileLibrary.GetFileAsync(request.Id);
             return file is null
                 ? ResponseHelper.Failure(404, "文件不存在或尚未扫描入库。")
                 : ResponseHelper.Ok(file);
         }
 
-        public async Task<object?> GetTextPreviewAsync(ServiceEndpointContext ctx)
+        public async Task<IApiResponse> GetTextPreviewAsync(FileQueryRequest request)
         {
-            var id = ReadId(ctx);
-            var preview = await fileLibrary.GetTextPreviewAsync(id);
+            ValidateFileId(request.Id);
+            var preview = await fileLibrary.GetTextPreviewAsync(request.Id);
             return preview is null
                 ? ResponseHelper.Failure(404, "文本文件不存在或无法预览。")
                 : ResponseHelper.Ok(preview);
         }
 
-        private static T ReadBody<T>(ServiceEndpointContext ctx)
+        private static void ValidateFileId(int id)
         {
-            if (string.IsNullOrWhiteSpace(ctx.Body))
+            if (id > 0)
             {
-                throw new InvalidOperationException("请求体不能为空。");
+                return;
             }
 
-            var body = JsonSerializer.Deserialize<T>(ctx.Body, JsonOptions);
-            return body ?? throw new InvalidOperationException("请求体格式错误。");
-        }
-
-        private static int ReadId(ServiceEndpointContext ctx)
-        {
-            if (int.TryParse(ctx.Query.GetValueOrDefault("id"), out var id) && id > 0)
-            {
-                return id;
-            }
-
-            throw new InvalidOperationException("id 参数无效。");
+            throw new ArgumentException("id 参数无效。");
         }
     }
 }

Avalonia-Services/Services/FileLibrary/FileLibraryService.cs

@@ -213,13 +213,13 @@ namespace Avalonia_Services.Services.FileLibrary
             }
         }
 
-        public async Task<PagedResponse<FileRecordDto>> SearchFilesAsync(ServiceEndpointContext ctx, CancellationToken cancellationToken = default)
+        public async Task<PagedResponse<FileRecordDto>> SearchFilesAsync(SearchFilesRequest request, CancellationToken cancellationToken = default)
         {
-            var page = ParseInt(ctx.Query.GetValueOrDefault("page"), 1, 1, 100000);
-            var pageSize = ParseInt(ctx.Query.GetValueOrDefault("pageSize"), 24, 1, 100);
-            var mediaType = ctx.Query.GetValueOrDefault("mediaType")?.Trim();
-            var keyword = ctx.Query.GetValueOrDefault("keyword")?.Trim();
-            var rootId = ParseInt(ctx.Query.GetValueOrDefault("rootId"), 0, 0, int.MaxValue);
+            var page = Math.Clamp(request.Page, 1, 100000);
+            var pageSize = Math.Clamp(request.PageSize, 1, 100);
+            var mediaType = request.MediaType?.Trim();
+            var keyword = request.Keyword?.Trim();
+            var rootId = Math.Clamp(request.RootId, 0, int.MaxValue);
 
             var query = db.ManagedFileRecords
                 .AsNoTracking()
@@ -399,11 +399,5 @@ namespace Avalonia_Services.Services.FileLibrary
                 MediaFileTypes.IsBrowserPlayable(file.Extension));
         }
 
-        private static int ParseInt(string? value, int fallback, int min, int max)
-        {
-            return int.TryParse(value, out var parsed)
-                ? Math.Clamp(parsed, min, max)
-                : fallback;
-        }
     }
 }

Avalonia-Services/Services/FileLibrary/FileStreamService.cs

@@ -0,0 +1,37 @@
+using Avalonia_EFCore.Database;
+using Avalonia_EFCore.Models;
+using Avalonia_Services.Core;
+using Microsoft.EntityFrameworkCore;
+
+namespace Avalonia_Services.Services.FileLibrary
+{
+    public interface IFileStreamService
+    {
+        Task<FileStreamResponse?> GetFileStreamAsync(int id, CancellationToken cancellationToken = default);
+    }
+
+    public sealed class FileStreamService(AppDataContext db) : IFileStreamService
+    {
+        public async Task<FileStreamResponse?> GetFileStreamAsync(int id, CancellationToken cancellationToken = default)
+        {
+            var file = await db.ManagedFileRecords
+                .AsNoTracking()
+                .Include(item => item.LibraryRoot)
+                .FirstOrDefaultAsync(item =>
+                    item.Id == id
+                    && item.Exists
+                    && item.LibraryRoot != null
+                    && item.LibraryRoot.IsAvailable,
+                    cancellationToken);
+
+            if (file is null || !System.IO.File.Exists(file.AbsolutePath))
+                return null;
+
+            return new FileStreamResponse(
+                file.AbsolutePath,
+                file.FileName,
+                file.ContentType,
+                file.LastWriteTimeUtc);
+        }
+    }
+}

Avalonia-Services/Services/FileLibrary/IFileLibraryEndpointService.cs

@@ -1,27 +1,28 @@
+using Avalonia_Common.Core;
 using Avalonia_Services.Core;
 
 namespace Avalonia_Services.Services.FileLibrary
 {
     public interface IFileLibraryEndpointService
     {
-        Task<object?> GetDrivesAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> GetDrivesAsync(ServiceEndpointContext ctx);
 
-        Task<object?> GetDirectoriesAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> GetDirectoriesAsync(DirectoryQueryRequest request);
 
-        Task<object?> GetRootsAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> GetRootsAsync(ServiceEndpointContext ctx);
 
-        Task<object?> AddRootAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> AddRootAsync(AddLibraryRootRequest request);
 
-        Task<object?> SetRootEnabledAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> SetRootEnabledAsync(UpdateLibraryRootRequest request);
 
-        Task<object?> DeleteRootAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> DeleteRootAsync(DeleteLibraryRootRequest request);
 
-        Task<object?> ScanRootAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> ScanRootAsync(ScanLibraryRootRequest request);
 
-        Task<object?> SearchFilesAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> SearchFilesAsync(SearchFilesRequest request);
 
-        Task<object?> GetFileAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> GetFileAsync(FileQueryRequest request);
 
-        Task<object?> GetTextPreviewAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> GetTextPreviewAsync(FileQueryRequest request);
     }
 }

Avalonia-Services/Services/FileLibrary/IFileLibraryService.cs

@@ -1,5 +1,4 @@
 using Avalonia_Common.Core;
-using Avalonia_Services.Core;
 
 namespace Avalonia_Services.Services.FileLibrary
 {
@@ -21,7 +20,7 @@ namespace Avalonia_Services.Services.FileLibrary
 
         Task ScanDueRootsAsync(CancellationToken cancellationToken = default);
 
-        Task<PagedResponse<FileRecordDto>> SearchFilesAsync(ServiceEndpointContext ctx, CancellationToken cancellationToken = default);
+        Task<PagedResponse<FileRecordDto>> SearchFilesAsync(SearchFilesRequest request, CancellationToken cancellationToken = default);
 
         Task<FileRecordDto?> GetFileAsync(int id, CancellationToken cancellationToken = default);
 

Avalonia-Services/Services/QrCode/IQrCodeService.cs

@@ -0,0 +1,9 @@
+using Avalonia_Services.Core;
+
+namespace Avalonia_Services.Services.QrCode
+{
+    public interface IQrCodeService
+    {
+        Task<object?> GenerateQrCodeAsync(ServiceEndpointContext ctx);
+    }
+}

Avalonia-Services/Services/QrCode/QrCodeContracts.cs

@@ -0,0 +1,4 @@
+namespace Avalonia_Services.Services.QrCode
+{
+    public sealed record QrCodeResponse(string Url, string QrCodeBase64);
+}

Avalonia-Services/Services/QrCode/QrCodeService.cs

@@ -0,0 +1,46 @@
+using Avalonia_Common.Core;
+using Avalonia_Services.Core;
+using QRCoder;
+using System.Net;
+using System.Net.NetworkInformation;
+using System.Net.Sockets;
+
+namespace Avalonia_Services.Services.QrCode
+{
+    public sealed class QrCodeService : IQrCodeService
+    {
+        public Task<object?> GenerateQrCodeAsync(ServiceEndpointContext ctx)
+        {
+            var ip = GetLanIpAddress();
+            if (ip is null)
+                throw new InvalidOperationException("无法获取局域网IP地址");
+
+            var url = $"http://{ip}:5206";
+            var base64 = GeneratePngBase64(url);
+            return Task.FromResult<object?>(ResponseHelper.Ok(new QrCodeResponse(url, base64)));
+        }
+
+        private static string GeneratePngBase64(string content)
+        {
+            using var generator = new QRCodeGenerator();
+            using var data = generator.CreateQrCode(content, QRCodeGenerator.ECCLevel.Q);
+            using var png = new PngByteQRCode(data);
+            var bytes = png.GetGraphic(20);
+            return $"data:image/png;base64,{Convert.ToBase64String(bytes)}";
+        }
+
+        private static string? GetLanIpAddress()
+        {
+            return NetworkInterface.GetAllNetworkInterfaces()
+                .Where(ni => ni.OperationalStatus == OperationalStatus.Up
+                             && ni.NetworkInterfaceType != NetworkInterfaceType.Loopback)
+                .SelectMany(ni => ni.GetIPProperties().UnicastAddresses)
+                .Select(ua => ua.Address)
+                .FirstOrDefault(ip =>
+                    ip.AddressFamily == AddressFamily.InterNetwork
+                    && !IPAddress.IsLoopback(ip)
+                    && !ip.ToString().StartsWith("169.254"))
+                ?.ToString();
+        }
+    }
+}