补充注释

SimpleAdmin.Application/Services/Onboarding/ContractDocument/Dto/OnboardingContractDocumentInput.cs

@@ -1,7 +1,13 @@
 namespace SimpleAdmin.Application;
 
+/// <summary>
+/// 生成任务合同文件参数。
+/// </summary>
 public class OnboardingGenerateContractInput
 {
+    /// <summary>
+    /// 任务合同 Id。
+    /// </summary>
     [IdNotNull(ErrorMessage = "任务合同Id不能为空")]
     public long TaskContractId { get; set; }
 }

SimpleAdmin.Application/Services/Onboarding/ContractDocument/IOnboardingContractDocumentService.cs

@@ -1,2 +1,12 @@
 namespace SimpleAdmin.Application;
-public interface IOnboardingContractDocumentService : ITransient { Task<long> Generate(OnboardingGenerateContractInput input); }
+
+/// <summary>
+/// 定义入职合同文件生成能力。
+/// </summary>
+public interface IOnboardingContractDocumentService : ITransient
+{
+    /// <summary>
+    /// 根据已审核通过的任务合同生成并保存 DOCX 文件。
+    /// </summary>
+    Task<long> Generate(OnboardingGenerateContractInput input);
+}

SimpleAdmin.Application/Services/Onboarding/ContractDocument/OnboardingContractDocumentService.cs

@@ -1,5 +1,8 @@
 namespace SimpleAdmin.Application;
 
+/// <summary>
+/// 实现入职合同文件生成业务能力。
+/// </summary>
 public class OnboardingContractDocumentService : IOnboardingContractDocumentService
 {
     private readonly SqlSugarScope _db;
@@ -11,6 +14,9 @@ public class OnboardingContractDocumentService : IOnboardingContractDocumentServ
         _fileService = fileService;
     }
 
+    /// <summary>
+    /// 根据已锁定的模板版本和变量快照生成任务合同 DOCX 文件。
+    /// </summary>
     public async Task<long> Generate(OnboardingGenerateContractInput input)
     {
         var contract = await _db.Queryable<ObTaskContract>().InSingleAsync(input.TaskContractId)
@@ -38,6 +44,7 @@ public class OnboardingContractDocumentService : IOnboardingContractDocumentServ
         using var sourceBytes = new MemoryStream();
         await sourceStream.CopyToAsync(sourceBytes);
 
+        // 合同只读取任务变量快照，确保模板或员工档案后续修改不会影响已生成文件。
         var rendered = ReplaceDocxText(
             sourceBytes.ToArray(),
             variables.ToDictionary(x => x.VariableCode, x => x.VariableValue ?? string.Empty));
@@ -63,6 +70,7 @@ public class OnboardingContractDocumentService : IOnboardingContractDocumentServ
             global::System.IO.Compression.ZipArchiveMode.Create,
             true);
 
+        // DOCX 本质是 ZIP 包，仅替换正文、页眉和页脚 XML 中的文本节点，其他资源原样复制。
         foreach (var entry in archive.Entries)
         {
             var next = target.CreateEntry(entry.FullName, global::System.IO.Compression.CompressionLevel.Optimal);
@@ -95,5 +103,3 @@ public class OnboardingContractDocumentService : IOnboardingContractDocumentServ
         return output.ToArray();
     }
 }
-
-