docs: 完善身份模块文档注释与字段说明

src/Core/TakeoutSaaS.Shared.Web/Middleware/CorrelationIdMiddleware.cs

@@ -15,8 +15,13 @@ public sealed class CorrelationIdMiddleware(RequestDelegate next, ILogger<Correl
     private const string SpanHeader = "X-Span-Id";
     private const string RequestHeader = "X-Request-Id";
 
+    /// <summary>
+    /// 管道入口，确保 TraceId/SpanId 贯穿请求。
+    /// </summary>
+    /// <param name="context">HTTP 上下文。</param>
     public async Task InvokeAsync(HttpContext context)
     {
+        // 1. 确保活动存在并启动
         var ownsActivity = Activity.Current is null;
         var activity = Activity.Current ?? new Activity("TakeoutSaaS.Request");
 
@@ -26,6 +31,7 @@ public sealed class CorrelationIdMiddleware(RequestDelegate next, ILogger<Correl
             activity.Start();
         }
 
+        // 2. 生成/解析 TraceId、SpanId
         var traceId = activity.TraceId.ToString();
         var spanId = activity.SpanId.ToString();
 
@@ -34,6 +40,7 @@ public sealed class CorrelationIdMiddleware(RequestDelegate next, ILogger<Correl
             traceId = ResolveTraceId(context);
         }
 
+        // 3. 写入上下文与响应头
         context.TraceIdentifier = traceId;
         TraceContext.TraceId = traceId;
         TraceContext.SpanId = spanId;
@@ -45,6 +52,7 @@ public sealed class CorrelationIdMiddleware(RequestDelegate next, ILogger<Correl
             return Task.CompletedTask;
         });
 
+        // 4. 带 Scope 调用后续中间件
         using (logger.BeginScope(new Dictionary<string, object>
         {
             ["TraceId"] = traceId,
@@ -57,6 +65,7 @@ public sealed class CorrelationIdMiddleware(RequestDelegate next, ILogger<Correl
             }
             finally
             {
+                // 5. 清理上下文与活动
                 TraceContext.Clear();
                 if (ownsActivity)
                 {