补充注释

2026-08-24 15:32:50 +08:00
parent b8b2d7e3fa
commit 22a7df5bec
84 changed files with 5913 additions and 45 deletions
@@ -1,27 +1,73 @@
 namespace SimpleAdmin.Application;

+/// <summary>
+/// 合同适用范围分页查询参数。
+/// </summary>
 public class OnboardingContractScopePageInput : BasePageInput
 {
+    /// <summary>
+    /// 入职业务公司 Id。
+    /// </summary>
    public long? CompanyId { get; set; }
+
+    /// <summary>
+    /// 岗位 Id；为空时表示公司级配置。
+    /// </summary>
    public long? PositionId { get; set; }
+
+    /// <summary>
+    /// 合同模板 Id。
+    /// </summary>
    public long? TemplateId { get; set; }
 }

+/// <summary>
+/// 新增合同适用范围参数。
+/// </summary>
 public class OnboardingContractScopeAddInput
 {
+    /// <summary>
+    /// 入职业务公司 Id。
+    /// </summary>
    [IdNotNull(ErrorMessage = "公司Id不能为空")]
    public long CompanyId { get; set; }
+
+    /// <summary>
+    /// 岗位 Id；为空时表示公司级配置。
+    /// </summary>
    public long? PositionId { get; set; }
+
+    /// <summary>
+    /// 合同模板 Id。
+    /// </summary>
    [IdNotNull(ErrorMessage = "模板Id不能为空")]
    public long TemplateId { get; set; }
+
+    /// <summary>
+    /// 合同模板版本 Id。
+    /// </summary>
    [IdNotNull(ErrorMessage = "模板版本Id不能为空")]
    public long TemplateVersionId { get; set; }
+
+    /// <summary>
+    /// 是否必填、必传或必签。
+    /// </summary>
    public bool Required { get; set; } = true;
+
+    /// <summary>
+    /// 显示排序码。
+    /// </summary>
    public int? SortCode { get; set; }
 }

+/// <summary>
+/// 编辑合同适用范围参数。
+/// </summary>
 public class OnboardingContractScopeEditInput : OnboardingContractScopeAddInput
 {
+    /// <summary>
+    /// 业务数据 Id。
+    /// </summary>
    [IdNotNull(ErrorMessage = "适用范围Id不能为空")]
    public long Id { get; set; }
 }
@@ -1,26 +1,68 @@
 namespace SimpleAdmin.Application;

+/// <summary>
+/// 合同模板分页查询参数。
+/// </summary>
 public class OnboardingContractTemplatePageInput : BasePageInput
 {
+    /// <summary>
+    /// 合同模板名称。
+    /// </summary>
    public string TemplateName { get; set; }
+
+    /// <summary>
+    /// 合同类型。
+    /// </summary>
    public string ContractType { get; set; }
+
+    /// <summary>
+    /// 启用状态或状态筛选条件。
+    /// </summary>
    public string Status { get; set; }
 }

+/// <summary>
+/// 新增合同模板参数。
+/// </summary>
 public class OnboardingContractTemplateAddInput
 {
+    /// <summary>
+    /// 合同模板业务编码。
+    /// </summary>
    [global::System.ComponentModel.DataAnnotations.Required(ErrorMessage = "模板编码不能为空")]
    public string TemplateCode { get; set; }
+
+    /// <summary>
+    /// 合同模板名称。
+    /// </summary>
    [global::System.ComponentModel.DataAnnotations.Required(ErrorMessage = "模板名称不能为空")]
    public string TemplateName { get; set; }
+
+    /// <summary>
+    /// 合同类型。
+    /// </summary>
    [global::System.ComponentModel.DataAnnotations.Required(ErrorMessage = "合同类型不能为空")]
    public string ContractType { get; set; }
+
+    /// <summary>
+    /// 业务说明。
+    /// </summary>
    public string Description { get; set; }
+
+    /// <summary>
+    /// 启用状态或状态筛选条件。
+    /// </summary>
    public string Status { get; set; } = "enable";
 }

+/// <summary>
+/// 编辑合同模板参数。
+/// </summary>
 public class OnboardingContractTemplateEditInput : OnboardingContractTemplateAddInput
 {
+    /// <summary>
+    /// 业务数据 Id。
+    /// </summary>
    [IdNotNull(ErrorMessage = "模板Id不能为空")]
    public long Id { get; set; }
 }
@@ -1,30 +1,80 @@
 namespace SimpleAdmin.Application;

+/// <summary>
+/// 合同模板版本分页查询参数。
+/// </summary>
 public class OnboardingContractVersionPageInput : BasePageInput
 {
+    /// <summary>
+    /// 合同模板 Id。
+    /// </summary>
    [IdNotNull(ErrorMessage = "模板Id不能为空")]
    public long TemplateId { get; set; }
+
+    /// <summary>
+    /// 模板版本状态。
+    /// </summary>
    public string VersionStatus { get; set; }
 }

+/// <summary>
+/// 新增合同模板版本参数。
+/// </summary>
 public class OnboardingContractVersionAddInput
 {
+    /// <summary>
+    /// 合同模板 Id。
+    /// </summary>
    [IdNotNull(ErrorMessage = "模板Id不能为空")]
    public long TemplateId { get; set; }
+
+    /// <summary>
+    /// 模板版本号。
+    /// </summary>
    [global::System.ComponentModel.DataAnnotations.Required(ErrorMessage = "版本号不能为空")]
    public string VersionNo { get; set; }
+
+    /// <summary>
+    /// 模板 DOCX 源文件 Id。
+    /// </summary>
    [IdNotNull(ErrorMessage = "DOCX源文件不能为空")]
    public long SourceDocxFileId { get; set; }
+
+    /// <summary>
+    /// 源文件内容哈希。
+    /// </summary>
    public string FileHash { get; set; }
+
+    /// <summary>
+    /// 生效日期。
+    /// </summary>
    public DateTime? EffectiveDate { get; set; }
+
+    /// <summary>
+    /// 失效日期。
+    /// </summary>
    public DateTime? ExpiryDate { get; set; }
+
+    /// <summary>
+    /// 业务备注。
+    /// </summary>
    public string Remark { get; set; }
 }

+/// <summary>
+/// 设置合同模板版本状态参数。
+/// </summary>
 public class OnboardingContractVersionStatusInput
 {
+    /// <summary>
+    /// 业务数据 Id。
+    /// </summary>
    [IdNotNull(ErrorMessage = "版本Id不能为空")]
    public long Id { get; set; }
+
+    /// <summary>
+    /// 模板版本状态。
+    /// </summary>
    [global::System.ComponentModel.DataAnnotations.Required(ErrorMessage = "版本状态不能为空")]
    public string VersionStatus { get; set; }
 }
@@ -1,35 +1,101 @@
 namespace SimpleAdmin.Application;

+/// <summary>
+/// 模板变量分页查询参数。
+/// </summary>
 public class OnboardingTemplateVariablePageInput : BasePageInput
 {
+    /// <summary>
+    /// 合同模板版本 Id。
+    /// </summary>
    [IdNotNull(ErrorMessage = "模板版本Id不能为空")]
    public long TemplateVersionId { get; set; }
 }

+/// <summary>
+/// 新增模板变量参数。
+/// </summary>
 public class OnboardingTemplateVariableAddInput
 {
+    /// <summary>
+    /// 合同模板版本 Id。
+    /// </summary>
    [IdNotNull(ErrorMessage = "模板版本Id不能为空")]
    public long TemplateVersionId { get; set; }
+
+    /// <summary>
+    /// 合同变量编码。
+    /// </summary>
    [global::System.ComponentModel.DataAnnotations.Required(ErrorMessage = "变量编码不能为空")]
    public string VariableCode { get; set; }
+
+    /// <summary>
+    /// 合同变量名称。
+    /// </summary>
    [global::System.ComponentModel.DataAnnotations.Required(ErrorMessage = "变量名称不能为空")]
    public string VariableName { get; set; }
+
+    /// <summary>
+    /// 合同变量来源类型。
+    /// </summary>
    [global::System.ComponentModel.DataAnnotations.Required(ErrorMessage = "变量类型不能为空")]
    public string VariableType { get; set; }
+
+    /// <summary>
+    /// 字段或变量数据类型。
+    /// </summary>
    [global::System.ComponentModel.DataAnnotations.Required(ErrorMessage = "数据类型不能为空")]
    public string DataType { get; set; }
+
+    /// <summary>
+    /// 关联的候选人基础信息字段。
+    /// </summary>
    public string EmployeeField { get; set; }
+
+    /// <summary>
+    /// 默认值。
+    /// </summary>
    public string DefaultValue { get; set; }
+
+    /// <summary>
+    /// 可选项 JSON。
+    /// </summary>
    public string OptionsJson { get; set; }
+
+    /// <summary>
+    /// 格式化规则。
+    /// </summary>
    public string FormatRule { get; set; }
+
+    /// <summary>
+    /// 是否必填、必传或必签。
+    /// </summary>
    public bool Required { get; set; }
+
+    /// <summary>
+    /// 人事是否可以编辑。
+    /// </summary>
    public bool HrEditable { get; set; }
+
+    /// <summary>
+    /// 显示排序码。
+    /// </summary>
    public int? SortCode { get; set; }
+
+    /// <summary>
+    /// 业务备注。
+    /// </summary>
    public string Remark { get; set; }
 }

+/// <summary>
+/// 编辑模板变量参数。
+/// </summary>
 public class OnboardingTemplateVariableEditInput : OnboardingTemplateVariableAddInput
 {
+    /// <summary>
+    /// 业务数据 Id。
+    /// </summary>
    [IdNotNull(ErrorMessage = "变量Id不能为空")]
    public long Id { get; set; }
 }
@@ -1,19 +1,67 @@
 namespace SimpleAdmin.Application;

+/// <summary>
+/// 定义合同模板、版本、变量和适用范围业务能力。
+/// </summary>
 public interface IOnboardingContractTemplateService : ITransient
 {
+    /// <summary>
+    /// 分页查询合同模板主档案。
+    /// </summary>
    Task<SqlSugarPagedList<ObContractTemplate>> Page(OnboardingContractTemplatePageInput input);
+    /// <summary>
+    /// 查询合同模板详情。
+    /// </summary>
    Task<ObContractTemplate> Detail(BaseIdInput input);
+    /// <summary>
+    /// 新增合同模板主档案。
+    /// </summary>
    Task Add(OnboardingContractTemplateAddInput input);
+    /// <summary>
+    /// 编辑合同模板主档案。
+    /// </summary>
    Task Edit(OnboardingContractTemplateEditInput input);
+    /// <summary>
+    /// 删除未被版本、适用范围或任务合同引用的模板。
+    /// </summary>
    Task Delete(BaseIdListInput input);
+    /// <summary>
+    /// 分页查询指定合同模板的版本。
+    /// </summary>
    Task<SqlSugarPagedList<ObContractTemplateVersion>> VersionPage(OnboardingContractVersionPageInput input);
+    /// <summary>
+    /// 新增合同模板 DOCX 版本。
+    /// </summary>
    Task AddVersion(OnboardingContractVersionAddInput input);
+    /// <summary>
+    /// 启用或停用合同模板版本。
+    /// </summary>
    Task SetVersionStatus(OnboardingContractVersionStatusInput input);
+    /// <summary>
+    /// 分页查询指定模板版本的变量定义。
+    /// </summary>
    Task<SqlSugarPagedList<ObTemplateVariable>> VariablePage(OnboardingTemplateVariablePageInput input);
+    /// <summary>
+    /// 为草稿模板版本新增变量。
+    /// </summary>
    Task AddVariable(OnboardingTemplateVariableAddInput input);
+    /// <summary>
+    /// 编辑草稿模板版本中的变量。
+    /// </summary>
    Task EditVariable(OnboardingTemplateVariableEditInput input);
+    /// <summary>
+    /// 删除草稿模板版本中的变量。
+    /// </summary>
    Task DeleteVariable(BaseIdListInput input);    Task<SqlSugarPagedList<ObContractScope>> ScopePage(OnboardingContractScopePageInput input);
+    /// <summary>
+    /// 新增公司或岗位的合同适用范围。
+    /// </summary>
    Task AddScope(OnboardingContractScopeAddInput input);
+    /// <summary>
+    /// 编辑合同适用范围。
+    /// </summary>
    Task EditScope(OnboardingContractScopeEditInput input);
+    /// <summary>
+    /// 删除合同适用范围。
+    /// </summary>
    Task DeleteScope(BaseIdListInput input);}
@@ -5,6 +5,9 @@ namespace SimpleAdmin.Application;
 /// </summary>
 public class OnboardingContractTemplateService : DbRepository<ObContractTemplate>, IOnboardingContractTemplateService
 {
+    /// <summary>
+    /// 分页查询合同模板主档案。
+    /// </summary>
    public async Task<SqlSugarPagedList<ObContractTemplate>> Page(OnboardingContractTemplatePageInput input)
    {
        return await Context.Queryable<ObContractTemplate>()
@@ -18,17 +21,26 @@ public class OnboardingContractTemplateService : DbRepository<ObContractTemplate
            .ToPagedListAsync(input.PageNum, input.PageSize);
    }

+    /// <summary>
+    /// 查询合同模板详情。
+    /// </summary>
    public async Task<ObContractTemplate> Detail(BaseIdInput input)
    {
        return await GetByIdAsync(input.Id) ?? throw Oops.Bah("合同模板不存在");
    }

+    /// <summary>
+    /// 新增合同模板主档案。
+    /// </summary>
    public async Task Add(OnboardingContractTemplateAddInput input)
    {
        await EnsureCodeUnique(input.TemplateCode, 0);
        await InsertAsync(input.Adapt<ObContractTemplate>());
    }

+    /// <summary>
+    /// 编辑合同模板主档案。
+    /// </summary>
    public async Task Edit(OnboardingContractTemplateEditInput input)
    {
        await Detail(new BaseIdInput { Id = input.Id });
@@ -36,6 +48,9 @@ public class OnboardingContractTemplateService : DbRepository<ObContractTemplate
        await UpdateAsync(input.Adapt<ObContractTemplate>());
    }

+    /// <summary>
+    /// 删除未被版本、适用范围或任务合同引用的模板。
+    /// </summary>
    public async Task Delete(BaseIdListInput input)
    {
        if (input.Ids.Count == 0)
@@ -59,6 +74,9 @@ public class OnboardingContractTemplateService : DbRepository<ObContractTemplate
        await DeleteByIdsAsync(input.Ids.Cast<object>().ToArray());
    }

+    /// <summary>
+    /// 分页查询指定合同模板的版本。
+    /// </summary>
    public async Task<SqlSugarPagedList<ObContractTemplateVersion>> VersionPage(OnboardingContractVersionPageInput input)
    {
        return await Context.Queryable<ObContractTemplateVersion>()
@@ -68,6 +86,9 @@ public class OnboardingContractTemplateService : DbRepository<ObContractTemplate
            .ToPagedListAsync(input.PageNum, input.PageSize);
    }

+    /// <summary>
+    /// 新增合同模板 DOCX 版本。
+    /// </summary>
    public async Task AddVersion(OnboardingContractVersionAddInput input)
    {
        await Detail(new BaseIdInput { Id = input.TemplateId });
@@ -85,6 +106,9 @@ public class OnboardingContractTemplateService : DbRepository<ObContractTemplate
        await Context.Insertable(input.Adapt<ObContractTemplateVersion>()).ExecuteCommandAsync();
    }

+    /// <summary>
+    /// 启用或停用合同模板版本。
+    /// </summary>
    public async Task SetVersionStatus(OnboardingContractVersionStatusInput input)
    {
        if (input.VersionStatus != ContractTemplateVersionStatus.Enabled
@@ -108,6 +132,9 @@ public class OnboardingContractTemplateService : DbRepository<ObContractTemplate
        await Context.Updateable(version).ExecuteCommandAsync();
    }

+    /// <summary>
+    /// 分页查询指定模板版本的变量定义。
+    /// </summary>
    public async Task<SqlSugarPagedList<ObTemplateVariable>> VariablePage(OnboardingTemplateVariablePageInput input)
    {
        return await Context.Queryable<ObTemplateVariable>()
@@ -117,6 +144,9 @@ public class OnboardingContractTemplateService : DbRepository<ObContractTemplate
            .ToPagedListAsync(input.PageNum, input.PageSize);
    }

+    /// <summary>
+    /// 为草稿模板版本新增变量。
+    /// </summary>
    public async Task AddVariable(OnboardingTemplateVariableAddInput input)
    {
        await EnsureVersionDraft(input.TemplateVersionId);
@@ -124,6 +154,9 @@ public class OnboardingContractTemplateService : DbRepository<ObContractTemplate
        await Context.Insertable(input.Adapt<ObTemplateVariable>()).ExecuteCommandAsync();
    }

+    /// <summary>
+    /// 编辑草稿模板版本中的变量。
+    /// </summary>
    public async Task EditVariable(OnboardingTemplateVariableEditInput input)
    {
        var variable = await Context.Queryable<ObTemplateVariable>().InSingleAsync(input.Id)
@@ -136,6 +169,9 @@ public class OnboardingContractTemplateService : DbRepository<ObContractTemplate
        await Context.Updateable(input.Adapt<ObTemplateVariable>()).ExecuteCommandAsync();
    }

+    /// <summary>
+    /// 删除草稿模板版本中的变量。
+    /// </summary>
    public async Task DeleteVariable(BaseIdListInput input)
    {
        if (input.Ids.Count == 0)
@@ -152,6 +188,9 @@ public class OnboardingContractTemplateService : DbRepository<ObContractTemplate
        await Context.Deleteable<ObTemplateVariable>().In(input.Ids).ExecuteCommandAsync();
    }

+    /// <summary>
+    /// 分页查询合同适用范围。
+    /// </summary>
    public async Task<SqlSugarPagedList<ObContractScope>> ScopePage(OnboardingContractScopePageInput input)
    {
        return await Context.Queryable<ObContractScope>()
@@ -162,6 +201,9 @@ public class OnboardingContractTemplateService : DbRepository<ObContractTemplate
            .ToPagedListAsync(input.PageNum, input.PageSize);
    }

+    /// <summary>
+    /// 新增公司或岗位的合同适用范围。
+    /// </summary>
    public async Task AddScope(OnboardingContractScopeAddInput input)
    {
        await EnsureScopeValid(input.CompanyId, input.PositionId, input.TemplateId, input.TemplateVersionId);
@@ -169,6 +211,9 @@ public class OnboardingContractTemplateService : DbRepository<ObContractTemplate
        await Context.Insertable(input.Adapt<ObContractScope>()).ExecuteCommandAsync();
    }

+    /// <summary>
+    /// 编辑合同适用范围。
+    /// </summary>
    public async Task EditScope(OnboardingContractScopeEditInput input)
    {
        var scopeExists = await Context.Queryable<ObContractScope>().AnyAsync(it => it.Id == input.Id);
@@ -180,6 +225,9 @@ public class OnboardingContractTemplateService : DbRepository<ObContractTemplate
        await Context.Updateable(input.Adapt<ObContractScope>()).ExecuteCommandAsync();
    }

+    /// <summary>
+    /// 删除合同适用范围。
+    /// </summary>
    public async Task DeleteScope(BaseIdListInput input)
    {
        if (input.Ids.Count == 0)