补充注释

SimpleAdmin.Application/Services/Onboarding/Audit/Dto/OnboardingAuditInput.cs

@@ -1,9 +1,18 @@
 namespace SimpleAdmin.Application;
 
+/// <summary>
+/// 入职审核、退回、撤销或归档操作参数。
+/// </summary>
 public class OnboardingAuditActionInput
 {
+    /// <summary>
+    /// 入职任务 Id。
+    /// </summary>
     [IdNotNull(ErrorMessage = "任务Id不能为空")]
     public long TaskId { get; set; }
 
+    /// <summary>
+    /// 审核意见或流程操作说明。
+    /// </summary>
     public string AuditOpinion { get; set; }
 }

SimpleAdmin.Application/Services/Onboarding/Audit/IOnboardingAuditService.cs

@@ -1,7 +1,16 @@
 namespace SimpleAdmin.Application;
 
+/// <summary>
+/// 定义入职审核业务能力。
+/// </summary>
 public interface IOnboardingAuditService : ITransient
 {
+    /// <summary>
+    /// 审核通过入职任务，并在同一事务中创建正式员工档案。
+    /// </summary>
     Task Approve(OnboardingAuditActionInput input);
+    /// <summary>
+    /// 退回入职任务，保存审核意见并允许候选人补充资料。
+    /// </summary>
     Task Reject(OnboardingAuditActionInput input);
 }

SimpleAdmin.Application/Services/Onboarding/Audit/OnboardingAuditService.cs

@@ -1,5 +1,8 @@
 namespace SimpleAdmin.Application;
 
+/// <summary>
+/// 实现入职审核业务能力。
+/// </summary>
 public class OnboardingAuditService : IOnboardingAuditService
 {
     private readonly SqlSugarScope _db;
@@ -15,6 +18,9 @@ public class OnboardingAuditService : IOnboardingAuditService
         _snapshotService = snapshotService;
     }
 
+    /// <summary>
+    /// 审核通过入职任务，并在同一事务中创建正式员工档案。
+    /// </summary>
     public async Task Approve(OnboardingAuditActionInput input)
     {
         var task = await GetAuditableTask(input.TaskId);
@@ -30,6 +36,7 @@ public class OnboardingAuditService : IOnboardingAuditService
             throw Oops.Bah("仍有资料需要补充，不能审核通过");
         }
 
+        // 审核通过是创建正式员工的唯一入口，因此必须在入库前拦截身份证号或手机号重复。
         var hasExistingEmployee = await _db.Queryable<ObEmployee>()
             .AnyAsync(item => item.IdCardNumber == employeeInfo.IdCardNumber || item.Phone == employeeInfo.Phone);
         if (hasExistingEmployee)
@@ -46,6 +53,7 @@ public class OnboardingAuditService : IOnboardingAuditService
         employee.PositionId = task.PositionId;
         employee.ExtraInfoJson = global::System.Text.Json.JsonSerializer.Serialize(extraValues);
 
+        // 员工档案、任务状态和审核记录必须同时成功，避免出现“已通过但没有员工档案”的中间状态。
         await _db.Ado.BeginTranAsync();
         try
         {
@@ -66,6 +74,9 @@ public class OnboardingAuditService : IOnboardingAuditService
         }
     }
 
+    /// <summary>
+    /// 退回入职任务，保存审核意见并允许候选人补充资料。
+    /// </summary>
     public async Task Reject(OnboardingAuditActionInput input)
     {
         if (string.IsNullOrWhiteSpace(input.AuditOpinion))
@@ -92,6 +103,7 @@ public class OnboardingAuditService : IOnboardingAuditService
         var config = await _config.GetByConfigKey(CateGoryConst.CONFIG_BIZ_DEFINE, "onboard.reviewer.userIds")
             ?? throw Oops.Bah("请配置入职审核人");
         using var configJson = global::System.Text.Json.JsonDocument.Parse(config.ConfigValue);
+        // 审核人由全局配置与公司专属配置合并得出，不依赖独立业务表。
         var reviewerIds = new List<long>();
         if (configJson.RootElement.TryGetProperty("all", out var allReviewers))
         {
@@ -126,5 +138,3 @@ public class OnboardingAuditService : IOnboardingAuditService
         }).ExecuteCommandAsync();
     }
 }
-
-