chore: add documentation comments and stylecop rules

src/Api/TakeoutSaaS.AdminApi/Program.cs

@@ -26,13 +26,16 @@ using TakeoutSaaS.Module.Tenancy.Extensions;
 using TakeoutSaaS.Shared.Web.Extensions;
 using TakeoutSaaS.Shared.Web.Swagger;
 
+// 1. 创建构建器与日志模板
 var builder = WebApplication.CreateBuilder(args);
 const string logTemplate = "[{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} {Level:u3}] [TraceId:{TraceId}] [SpanId:{SpanId}] [Service:{Service}] {SourceContext} {Message:lj}{NewLine}{Exception}";
 
+// 2. 加载种子配置文件
 builder.Configuration
     .AddJsonFile("appsettings.Seed.json", optional: true, reloadOnChange: true)
     .AddJsonFile($"appsettings.Seed.{builder.Environment.EnvironmentName}.json", optional: true, reloadOnChange: true);
 
+// 3. 配置 Serilog 输出
 builder.Host.UseSerilog((context, _, configuration) =>
 {
     configuration
@@ -47,6 +50,7 @@ builder.Host.UseSerilog((context, _, configuration) =>
             outputTemplate: logTemplate);
 });
 
+// 4. 注册通用 Web 能力与 Swagger
 builder.Services.AddSharedWebCore();
 builder.Services.AddSharedSwagger(options =>
 {
@@ -54,6 +58,8 @@ builder.Services.AddSharedSwagger(options =>
     options.Description = "管理后台 API 文档";
     options.EnableAuthorization = true;
 });
+
+// 5. 注册领域与基础设施模块
 builder.Services.AddIdentityApplication();
 builder.Services.AddIdentityInfrastructure(builder.Configuration, enableAdminSeed: true);
 builder.Services.AddAppInfrastructure(builder.Configuration);
@@ -71,6 +77,8 @@ builder.Services.AddMessagingModule(builder.Configuration);
 builder.Services.AddMessagingApplication();
 builder.Services.AddSchedulerModule(builder.Configuration);
 builder.Services.AddHealthChecks();
+
+// 6. 配置 OpenTelemetry 采集
 var otelSection = builder.Configuration.GetSection("Otel");
 var otelEndpoint = otelSection.GetValue<string>("Endpoint");
 var useConsoleExporter = otelSection.GetValue<bool?>("UseConsoleExporter") ?? builder.Environment.IsDevelopment();
@@ -86,7 +94,6 @@ builder.Services.AddOpenTelemetry()
             .AddAspNetCoreInstrumentation()
             .AddHttpClientInstrumentation()
             .AddEntityFrameworkCoreInstrumentation();
-
         if (!string.IsNullOrWhiteSpace(otelEndpoint))
         {
             tracing.AddOtlpExporter(exporter =>
@@ -94,7 +101,6 @@ builder.Services.AddOpenTelemetry()
                 exporter.Endpoint = new Uri(otelEndpoint);
             });
         }
-
         if (useConsoleExporter)
         {
             tracing.AddConsoleExporter();
@@ -107,7 +113,6 @@ builder.Services.AddOpenTelemetry()
             .AddHttpClientInstrumentation()
             .AddRuntimeInstrumentation()
             .AddPrometheusExporter();
-
         if (!string.IsNullOrWhiteSpace(otelEndpoint))
         {
             metrics.AddOtlpExporter(exporter =>
@@ -115,13 +120,13 @@ builder.Services.AddOpenTelemetry()
                 exporter.Endpoint = new Uri(otelEndpoint);
             });
         }
-
         if (useConsoleExporter)
         {
             metrics.AddConsoleExporter();
         }
     });
 
+// 7. 解析并配置 CORS
 var adminOrigins = ResolveCorsOrigins(builder.Configuration, "Cors:Admin");
 builder.Services.AddCors(options =>
 {
@@ -131,8 +136,8 @@ builder.Services.AddCors(options =>
     });
 });
 
+// 8. 构建应用并配置中间件管道
 var app = builder.Build();
-
 app.UseCors("AdminApiCors");
 app.UseTenantResolution();
 app.UseSharedWebCore();
@@ -140,12 +145,12 @@ app.UseAuthentication();
 app.UseAuthorization();
 app.UseSharedSwagger();
 app.UseSchedulerDashboard(builder.Configuration);
-
 app.MapHealthChecks("/healthz");
 app.MapPrometheusScrapingEndpoint();
 app.MapControllers();
 app.Run();
 
+// 9. 解析配置中的 CORS 域名
 static string[] ResolveCorsOrigins(IConfiguration configuration, string sectionKey)
 {
     var origins = configuration.GetSection(sectionKey).Get<string[]>();
@@ -155,6 +160,7 @@ static string[] ResolveCorsOrigins(IConfiguration configuration, string sectionK
         .ToArray() ?? [];
 }
 
+// 10. 构建 CORS 策略
 static void ConfigureCorsPolicy(CorsPolicyBuilder policy, string[] origins)
 {
     if (origins.Length == 0)
@@ -166,7 +172,6 @@ static void ConfigureCorsPolicy(CorsPolicyBuilder policy, string[] origins)
         policy.WithOrigins(origins)
             .AllowCredentials();
     }
-
     policy
         .AllowAnyHeader()
         .AllowAnyMethod();