HRM-10/HRM.BO/Salary/SalaryMasterBulkUploadTemplate.cs
Mohaimen Hasan 838b8d4480 first commit
2026-11-03 13:06:00 +06:00

326 lines
14 KiB
C#

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
namespace HRM.BO
{
#region Template layout
/// <summary>One column of the Salary Master Data sheet.</summary>
public class SalaryMasterBulkUploadColumn
{
public SalaryMasterBulkUploadColumn(string key, string label, bool isMandatory, string itemSide, double width)
{
Key = key;
Label = label;
IsMandatory = isMandatory;
ItemSide = itemSide;
Width = width;
}
/// <summary>Field name of the column in an uploaded row, e.g. "basicSalary".</summary>
public string Key { get; set; }
/// <summary>
/// What the column is called. For an amount column this is also the ItemName saved in
/// HistorySalaryMonthlyDetail.
/// </summary>
public string Label { get; set; }
public bool IsMandatory { get; set; }
/// <summary>
/// Amount columns only: Gross, Deduction or Others (<see cref="HistorySalaryItemSide"/>).
/// Null for a text column.
/// </summary>
public string ItemSide { get; set; }
/// <summary>Excel column width (characters).</summary>
public double Width { get; set; }
/// <summary>An amount column — saved as a HistorySalaryMonthlyDetail row, not on the header.</summary>
public bool IsAmount
{
get { return !string.IsNullOrEmpty(ItemSide); }
}
/// <summary>The heading row text: the label, with " *" for a mandatory column.</summary>
public string Heading
{
get { return IsMandatory ? Label + " *" : Label; }
}
}
/// <summary>
/// The single source of truth for the Salary Master Data Bulk Upload: the columns, in
/// sheet order, and the sheet's fixed rows. The downloadable workbook is generated from this
/// and the uploaded one is checked against it, so the two cannot drift apart. Add a column by
/// appending it in its place — the uploader matches columns by position and heading.
/// </summary>
public static class SalaryMasterBulkUploadTemplate
{
public const string SheetName = "Salary Master Data";
public const string ContentType =
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
/// <summary>Row 1: "Salary Month" in A1 and the month itself in B1.</summary>
public const int MonthRow = 1;
public const int HeadingRow = 2;
public const int FirstDataRow = 3;
/// <summary>Rows of the data area given a number format in the downloaded template.</summary>
public const int FormattedDataRows = 2000;
public const int MaxRows = 5000;
public const int MaxUploadMegabytes = 10;
/// <summary>Totals that differ from the sum of their items by more than this are reported.</summary>
public const double TotalTolerance = 1;
public const string MonthLabel = "Salary Month";
public const string MonthFormat = "MMMM yyyy";
public const string AmountFormat = "#,##0.00";
// Heading fill per kind of column, and the border.
public const string EmployeeHeaderColor = "#D9E1F2";
public const string GrossHeaderColor = "#E2EFDA";
public const string DeductionHeaderColor = "#FCE4D6";
public const string OthersHeaderColor = "#EDEDED";
public const string MandatoryTextColor = "#C00000";
public const string OptionalTextColor = "#1F2937";
public const string BorderColor = "#8EA9C1";
public const string EmployeeNoKey = "employeeNo";
public const string NameKey = "name";
public const string DepartmentKey = "department";
public const string DesignationKey = "designation";
public const string LocationKey = "location";
public const string CostCenterKey = "costCenter";
public const string GradeKey = "grade";
public const string IsConfirmKey = "isConfirm";
public const string TotalGrossKey = "totalGross";
public const string TotalDeductionKey = "totalDeduction";
public const string NetPayKey = "netPay";
/// <summary>The only values "Is Confirm" takes (or blank); saved exactly so.</summary>
public const string ConfirmYes = "Yes";
public const string ConfirmNo = "No";
private static readonly List<SalaryMasterBulkUploadColumn> _columns = new List<SalaryMasterBulkUploadColumn>
{
new SalaryMasterBulkUploadColumn(EmployeeNoKey, "Employee ID", true, null, 16),
new SalaryMasterBulkUploadColumn(NameKey, "Name", true, null, 28),
new SalaryMasterBulkUploadColumn(DepartmentKey, "Department", true, null, 22),
new SalaryMasterBulkUploadColumn(DesignationKey, "Designation", true, null, 22),
new SalaryMasterBulkUploadColumn(LocationKey, "Location", true, null, 18),
new SalaryMasterBulkUploadColumn(CostCenterKey, "Cost-Center", true, null, 18),
new SalaryMasterBulkUploadColumn(GradeKey, "Grade", true, null, 12),
new SalaryMasterBulkUploadColumn(IsConfirmKey, "Is Confirm", true, null, 12),
new SalaryMasterBulkUploadColumn("basicSalary", "Basic Salary", false, HistorySalaryItemSide.Gross, 15),
new SalaryMasterBulkUploadColumn("houseRent", "House Rent", false, HistorySalaryItemSide.Gross, 15),
new SalaryMasterBulkUploadColumn("convince", "Convince", false, HistorySalaryItemSide.Gross, 15),
new SalaryMasterBulkUploadColumn(TotalGrossKey, "Total Gross", false, HistorySalaryItemSide.Others, 15),
new SalaryMasterBulkUploadColumn("pf", "PF", false, HistorySalaryItemSide.Deduction, 13),
new SalaryMasterBulkUploadColumn("tax", "Tax", false, HistorySalaryItemSide.Deduction, 13),
new SalaryMasterBulkUploadColumn(TotalDeductionKey, "Total Deduction", false, HistorySalaryItemSide.Others, 15),
new SalaryMasterBulkUploadColumn(NetPayKey, "Net Pay", false, HistorySalaryItemSide.Others, 15),
};
/// <summary>Every column, in sheet order (a copy — the declaration itself cannot be changed).</summary>
public static List<SalaryMasterBulkUploadColumn> GetColumns()
{
return _columns.ToList();
}
/// <summary>The downloaded file's name, e.g. "Salary-Master-Data-Oct-2026.xlsx".</summary>
public static string FileName(DateTime salaryMonth)
{
return "Salary-Master-Data-" + salaryMonth.ToString("MMM-yyyy") + ".xlsx";
}
/// <summary>"October 2026".</summary>
public static string MonthText(DateTime salaryMonth)
{
return salaryMonth.ToString(MonthFormat);
}
public static bool IsExcelFile(string fileName)
{
return string.Equals(Path.GetExtension(fileName ?? string.Empty), ".xlsx", StringComparison.OrdinalIgnoreCase);
}
}
#endregion
#region Upload read result
/// <summary>One problem in one cell (or row) of the uploaded sheet. Severity is "error" or "warning".</summary>
public class SalaryMasterBulkUploadIssue
{
public const string Error = "error";
public const string Warning = "warning";
public string Severity { get; set; }
/// <summary>The Excel row number; 0 for a problem with the file as a whole.</summary>
public int RowNo { get; set; }
/// <summary>The Excel cell, e.g. "J12"; empty for a problem with the file as a whole.</summary>
public string Cell { get; set; }
public string EmployeeNo { get; set; }
public string EmployeeName { get; set; }
public string Column { get; set; }
/// <summary>What the cell held; empty for a missing value.</summary>
public string Value { get; set; }
/// <summary>What is wrong and how to put it right.</summary>
public string Message { get; set; }
}
/// <summary>One employee row of the uploaded sheet.</summary>
public class SalaryMasterBulkUploadRow
{
public SalaryMasterBulkUploadRow()
{
Values = new Dictionary<string, string>();
Amounts = new Dictionary<string, double>();
}
/// <summary>The Excel row number, so a problem can be traced back to the sheet.</summary>
public int RowNo { get; set; }
/// <summary>Every cell as text, keyed by <see cref="SalaryMasterBulkUploadColumn.Key"/>.</summary>
public Dictionary<string, string> Values { get; set; }
/// <summary>
/// The amount of each amount column whose cell holds a number (a blank cell is 0), keyed
/// like <see cref="Values"/>. A cell that is not a number has no entry.
/// </summary>
public Dictionary<string, double> Amounts { get; set; }
/// <summary>The employee already has a row for this salary month: saving replaces it.</summary>
public bool IsReplace { get; set; }
public bool HasError { get; set; }
public bool HasWarning { get; set; }
}
/// <summary>
/// What was read from an uploaded file: the validation layers in the order they ran (the
/// check classes are shared with Employee Bulk Upload), every problem, and — whenever the
/// columns could be matched — the employee rows, problems or not.
/// </summary>
public class SalaryMasterBulkUploadReadResult
{
public SalaryMasterBulkUploadReadResult()
{
Columns = SalaryMasterBulkUploadTemplate.GetColumns();
Rows = new List<SalaryMasterBulkUploadRow>();
Layers = new List<EmployeeBulkUploadLayer>();
Issues = new List<SalaryMasterBulkUploadIssue>();
}
public string FileName { get; set; }
/// <summary>The salary month picked on the page — the last date of that month.</summary>
public DateTime SalaryMonth { get; set; }
public List<SalaryMasterBulkUploadColumn> Columns { get; set; }
public List<SalaryMasterBulkUploadRow> Rows { get; set; }
public List<EmployeeBulkUploadLayer> Layers { get; set; }
public List<SalaryMasterBulkUploadIssue> Issues { get; set; }
/// <summary>Rows whose employee has no row for the salary month yet — saved as new.</summary>
public int NewCount { get; set; }
/// <summary>Rows whose employee already has a row for the salary month — saving replaces it.</summary>
public int ReplaceCount { get; set; }
public int ErrorCount
{
get { return Issues.Count(x => x.Severity == SalaryMasterBulkUploadIssue.Error); }
}
public int WarningCount
{
get { return Issues.Count(x => x.Severity == SalaryMasterBulkUploadIssue.Warning); }
}
/// <summary>The first layer that failed; 0 when every layer passed.</summary>
public int FailedLayerNo
{
get
{
EmployeeBulkUploadLayer failed = Layers
.FirstOrDefault(x => x.Status == EnumBulkUploadCheckStatus.Failed);
return failed == null ? 0 : failed.LayerNo;
}
}
/// <summary>Every layer passed and there is at least one row: the file may be saved.</summary>
public bool CanSave
{
get
{
return Layers.Count > 0
&& Layers.All(x => x.Status == EnumBulkUploadCheckStatus.Passed)
&& Rows.Count > 0;
}
}
public EmployeeBulkUploadLayer AddLayer(int layerNo, string name, string description)
{
EmployeeBulkUploadLayer layer = new EmployeeBulkUploadLayer(layerNo, name, description);
Layers.Add(layer);
return layer;
}
}
/// <summary>What a save did — or, when nothing was saved, why.</summary>
public class SalaryMasterBulkUploadSaveResult
{
public bool Saved { get; set; }
public string Message { get; set; }
/// <summary>Employees saved for the first time for the salary month.</summary>
public int InsertedCount { get; set; }
/// <summary>Employees whose earlier row for the salary month was replaced.</summary>
public int ReplacedCount { get; set; }
/// <summary>The validation the save ran first; set when the file no longer passes it.</summary>
public SalaryMasterBulkUploadReadResult Validation { get; set; }
}
#endregion
#region ISalaryMasterBulkUpload Service
public interface ISalaryMasterBulkUploadService
{
/// <summary>The empty workbook for one salary month, generated from <see cref="SalaryMasterBulkUploadTemplate"/>.</summary>
byte[] GetTemplate(DateTime salaryMonth);
/// <summary>
/// Validates an uploaded workbook layer by layer and returns every layer, every problem
/// and the rows. Nothing is saved; a failed check is part of the result, not an exception.
/// </summary>
SalaryMasterBulkUploadReadResult ReadUpload(Stream stream, string fileName, long fileLength,
DateTime salaryMonth, int payrollTypeID);
/// <summary>
/// Validates the workbook again and, only when every layer passes, saves every row in one
/// transaction — all or nothing.
/// </summary>
SalaryMasterBulkUploadSaveResult SaveUpload(Stream stream, string fileName, long fileLength,
DateTime salaryMonth, int payrollTypeID, int userID);
}
#endregion
}