diff --git a/adas-core.Infrastructure/Repositories/MasterListRepository.cs b/adas-core.Infrastructure/Repositories/MasterListRepository.cs index e3de52aa..1f175ea3 100644 --- a/adas-core.Infrastructure/Repositories/MasterListRepository.cs +++ b/adas-core.Infrastructure/Repositories/MasterListRepository.cs @@ -114,12 +114,10 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Updates an existing master list entity with full replacement. + /// Upserts the specified in the collection, replacing the document matched by its identifier or inserting it when no match is found. Exceptions are logged and rethrown to the caller. /// - /// The entity with updated values. - /// Throws and re-throws exceptions after logging. - /// + /// The entity to persist; its identifier is used as the filter and its state replaces the existing document or creates a new one when absent. + /// public async Task Update(T entity) { try @@ -169,17 +167,11 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Finds a master list entity by its ID with options projection limited to 100 items. + /// Asynchronously retrieves an entity of type from the collection using its , applying a projection that truncates the "options" field to a maximum of 100 elements. Returns null when no document matches the identifier or when an exception is thrown, in which case the exception is logged and swallowed. /// - /// The ObjectId of the entity to retrieve. - /// The MasterList entity if found; otherwise, null. - /// Logs errors and returns null on failure. - /// - /// - /// + /// The identifier of the entity to look up. + /// A that resolves to the matching entity of type , or null if the entity is not found or an error occurs during retrieval. + /// public async Task FindById(ObjectId id) { try @@ -203,16 +195,13 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Finds a specific option within a master list by master and option IDs with locale translation. - /// Uses MongoDB aggregation to apply translations and return the translated option. + /// Retrieves a single item by its parent master identifier and option identifier, resolving the display name according to the requested using the aggregation translation logic embedded in the pipeline. /// - /// The ObjectId of the master list. - /// The ObjectId of the option to retrieve. - /// The locale for translation. - /// The OptionList with translated fields if found; otherwise, null. - /// Logs errors and returns null on failure. - /// + /// The of the master document whose embedded options collection will be searched. + /// The of the specific to retrieve from the unwound options array. + /// The used to select the localized name; when equal to or matching the document's default locale, the base name is returned, otherwise the matching localeItems entry is used with a fallback to the base name. + /// A that yields the matching deserialized from the aggregation result, or null if no document is found or the operation fails. + /// public async Task FindOptionItemById(ObjectId masterId, ObjectId optionId, LocaleEnum locale) { try @@ -352,14 +341,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Finds a specific option within a master list by master and option IDs without locale translation. + /// Asynchronously retrieves the option that matches the supplied and from the parent document's options array, returning the first match or when no option is found or when an error is logged. /// - /// The ObjectId of the master list. - /// The ObjectId of the option to retrieve. - /// The OptionList if found; otherwise, null. - /// Logs errors and returns null on failure. - /// + /// The identifier of the master document that owns the options array. + /// The identifier of the specific option to locate within that array. + /// A that yields the matching , or if the lookup yields no result or the operation fails. + /// public async Task FindOptionItemById(ObjectId masterId, ObjectId optionId) { try @@ -385,17 +372,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Finds a master list entity by its ID with optional locale translation for options. - /// Uses MongoDB aggregation to unwind options and apply translations. + /// Retrieves an entity by its , applying locale-aware name resolution to the nested options. When is or matches the document's default locale, the original option name is used; otherwise the translated name is looked up in localeItems with a fallback to the original name. Returns null when the entity is not found or an error occurs. /// - /// The ObjectId of the entity to retrieve. - /// Optional locale for translated option names. - /// The MasterList entity with translated options if found; otherwise, null. - /// Logs errors and returns null on failure. - /// - /// + /// The of the document to retrieve. + /// The optional used to resolve translated option names. When null or , the default locale is applied. + /// A containing the localized entity, or null when the entity cannot be found or the aggregation fails. + /// public async Task FindById(ObjectId id, LocaleEnum? locale) { try @@ -573,17 +555,13 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Finds a master list entity by its name. + /// Asynchronously finds the first entity matching the specified in the underlying collection, + /// applying a projection that limits the options array to 100 elements. Returns null when no matching document is found, + /// and logs the error and returns null if the lookup throws an exception. /// - /// The name of the master list to retrieve. - /// The MasterList entity if found; otherwise, null. - /// Logs errors and returns null on failure. - /// - /// - /// + /// The value compared against the entity's Name field to locate the document. + /// A task that yields the first matching entity of type T, or null if no match is found or the operation fails. + /// public async Task FindByName(string name) { try @@ -619,14 +597,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Retrieves paginated master lists with optional text filtering. + /// Builds a query for the master list of documents, sorted ascending by the name field. + /// When carries non-empty search text, a case-insensitive regex match is applied to the Name property; otherwise the query is returned without additional filtering. /// - /// The pagination and filtering parameters. - /// A fluent queryable for MasterList results. - /// - /// + /// The providing pagination settings and the optional search text. + /// An representing the prepared query, ready for further pagination and execution. + /// public IFindFluent GetPaginatedMasterList(PaginationFilter filter) { var filterBuilder = Builders.Filter; @@ -649,13 +625,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Retrieves paginated options within a master list with optional text filtering. + /// Retrieves the options belonging to the master list identified by , optionally applying a case-insensitive text filter on the option name, description, or type. Returns an empty list when the master list cannot be found. /// - /// The pagination and filtering parameters. - /// The ObjectId of the master list. - /// A list of filtered OptionList items. - /// + /// A whose FilteredRequest.Text is used to match option fields when provided. + /// The identifier of the master whose options are returned. + /// A task that yields a of options matching the filter, or an empty list if the master list does not exist. + /// public async Task> GetPaginatedOptions(PaginationFilter filter, ObjectId listId) { //TODO: LOCALE @@ -675,14 +650,14 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Adds a new option to a master list. + /// Adds a new entry to the master list identified by , rejecting duplicates that match the search criteria in . + /// When is set, the provided locale items are reused; otherwise new locale entries are derived from the current default locale (falling back to ) through GetNewItemLocale. + /// Returns when the option already exists, the update modifies no documents, or an exception is caught and logged. /// - /// The ObjectId of the master list. - /// The option element to add. - /// The newly created OptionList if successful; otherwise, null if duplicate exists. - /// Logs errors and returns null on failure. - /// + /// The identifier of the master list to which the option will be appended. + /// The option payload, including name, type, visual properties, and locale items used to seed translations. + /// The persisted on success; otherwise, if a duplicate is found, no document is modified, or an error occurs. + /// public async Task AddOptionToMasterList(ObjectId id, FilterOptionListElement opt) { var exist = await GetMasterListByIdAndSearchOptions(id, opt); @@ -722,16 +697,11 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Retrieves all master list entities. + /// Asynchronously retrieves all entities from the underlying collection by matching every document. + /// If the retrieval fails, the exception is logged and an empty collection is returned as a fallback. /// - /// An enumerable of all MasterList entities. - /// Logs errors and returns empty list on failure. - /// - /// - /// + /// A task that yields an of all entities, or an empty collection when an error occurs. + /// public async Task> GetAll() { try @@ -747,12 +717,11 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Retrieves all master list entities without options, returning only metadata. + /// Asynchronously retrieves all entries from the collection, mapping each result to include its identifier, name, description, list type, and the count of associated options. + /// If an error occurs while accessing the underlying store, the exception is logged and an empty collection is returned. /// - /// An enumerable of MasterListDto containing id, name, description, listType, and options count. - /// Logs errors and returns empty list on failure. - /// + /// A that yields an containing the projected master list entries, or an empty collection when the operation fails. + /// public async Task> GetAllWithoutOptions() { try @@ -777,12 +746,10 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Counts the total number of master list entities in the collection. + /// Asynchronously counts all entities in the underlying collection by invoking CountDocumentsAsync with a filter that matches every document. If an exception occurs during the count operation, the error is logged and the method returns 0 as a safe fallback. /// - /// The total count of entities. - /// Logs errors and returns 0 on failure. - /// + /// A that resolves to the total number of entities in the collection, or 0 if the operation fails. + /// public async Task Count() { try @@ -798,15 +765,14 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Searches for options within a master list using multiple filter criteria. - /// Uses MongoDB aggregation pipeline to apply filters and locale translations. + /// Retrieves the master list of entries associated with the supplied , applying the optional search and locale filters. + /// When is null the method short-circuits and returns an empty list; if the is provided it takes precedence over and and is matched as a case-insensitive regex across name and description. + /// The pipeline resolves per-option translations for the requested locale, falling back to the original values when no translation exists, then filters, sorts by name, and returns the result — or an empty list if an exception is encountered. /// - /// The ObjectId of the master list. - /// The filter criteria including text, name, description, and optionType. - /// A list of matching OptionList items ordered by name. - /// Logs errors and returns empty list on failure. - /// + /// The of the master list document to match in the aggregation pipeline. + /// The optional carrying the search criteria and locale to apply; when null no lookup is performed. + /// A containing the filtered and locale-resolved options ordered by name, or an empty list when is null or the aggregation fails. + /// public async Task> GetMasterListByIdAndSearchOptions(ObjectId id, FilterOptionListElement? filters) { try @@ -1015,15 +981,13 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Updates a specific option within a master list with locale-aware field updates. + /// Updates an existing option within a master list identified by , applying the changes from in the specified . Prevents duplicates by short-circuiting when an option with the same name already exists, routes name changes to either the main field or the locale-specific translation entry depending on whether the supplied locale matches the master's default locale, and respects the per-field required flags defined on the master. /// - /// The ObjectId of the master list. - /// The OptionList with updated values. - /// The locale for translation updates. - /// The updated OptionList if successful; otherwise, null. - /// Logs errors and returns null on failure. - /// + /// The of the master list that contains the option to update. + /// The carrying the new values to be applied to the matching option. + /// The that determines whether the name is written to the main field or stored as a translation under localeItems. + /// A that yields the updated when the operation succeeds, an existing duplicate when one is detected, or when there is nothing to update, no document was modified, or an error is logged and swallowed. + /// public async Task UpdateMasterListOption(ObjectId id, OptionList newOpt, LocaleEnum locale) { // 1. Evitar duplicados @@ -1118,14 +1082,13 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Updates a specific option within a master list with full replacement. + /// Updates an existing option within the master list identified by with the values supplied in . + /// Returns when the master list cannot be found, when no document is modified, or when the operation fails. /// - /// The ObjectId of the master list. - /// The OptionList with updated values. - /// The updated OptionList if successful; otherwise, null. - /// Logs errors and returns null on failure. - /// + /// The identifier of the master list that contains the option to update. + /// The new option values to persist; its is used to match the existing element. + /// The updated item, or if the master list is not found, the option was not updated, or an error occurred. + /// public async Task UpdateMasterListOption(ObjectId id, OptionList newOpt) { var master = await FindById(id); @@ -1180,16 +1143,14 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Updates the metadata details for a master list. + /// Asynchronously updates the option details of a master list document identified by , + /// applying only the non-null fields supplied in (such as and ). + /// Returns the updated when the document is modified, or when no document matches the identifier, no fields were changed, or an error occurs while updating. /// - /// The ObjectId of the master list. - /// The UpdateMasterListDetailsDto with updated values. - /// The updated UpdateMasterListDetailsDto if successful; otherwise, null. - /// Logs errors and returns null on failure. - /// - /// + /// The identifying the master list document to update. + /// The containing the new values to apply; only non-null properties are included in the update. + /// A that resolves to the updated on success, or when the document is not found, not modified, or the operation fails. + /// public async Task UpdateOptionDetailsToMasterList(ObjectId id, UpdateMasterListDetailsDto opt) { @@ -1219,14 +1180,13 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Updates the name of a master list. + /// Updates the name of a master list entry identified by . + /// Returns true when a document was modified, or false when no document matched the filter or an exception is caught and logged. /// - /// The ObjectId of the master list. - /// The new name. - /// True if the update was successful; otherwise, false. - /// Logs errors and returns false on failure. - /// + /// The of the document to update. + /// The new name to assign to the document. + /// true if the update modified a document; otherwise, false. + /// public async Task UpdateMasterListName(ObjectId id, string name) { var filter = Builders.Filter.And( @@ -1247,14 +1207,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Updates the description of a master list. + /// Updates the description of the master list entry identified by . /// - /// The ObjectId of the master list. - /// The new description. - /// True if the update was successful; otherwise, false. - /// Logs errors and returns false on failure. - /// + /// The of the master list entry to update. + /// The new description to apply to the entry. + /// when the document was modified; when no document matched the filter or the update operation failed. + /// public async Task UpdateMasterListDescription(ObjectId id, string description) { var filter = Builders.Filter.And( @@ -1275,14 +1233,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Removes an option from a master list by matching all its properties. + /// Removes the specified entry from the options array of a master list document identified by . The option is matched by all of its defining properties (name, optionType, iconDefault, iconCategory, iconColor, color, bgColor, isDefault, and description) using a pull filter, and the method returns only when at least one document was modified; if no matching document is found, or if an exception is caught, it is logged and the method returns . /// - /// The ObjectId of the master list. - /// The OptionList to remove. - /// True if the option was removed; otherwise, false. - /// Logs errors and returns false on failure. - /// + /// The of the master list document to update. + /// The whose properties are used to identify which element to pull from the options array. + /// A that resolves to if the document was modified (i.e., the option was removed), or if no document was updated or an error occurred. + /// public async Task RemoveMasterListOption(ObjectId id, OptionList oldOpt) { var filter = Builders.Filter.Eq("_id", id); @@ -1311,11 +1267,9 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Creates necessary indexes for the MasterList collection. - /// Currently creates text indexes for DiagnosisList on options.name, options.description, and options._id. + /// Creates MongoDB indexes for the entity type, adding non-unique background indexes on the options.name, options.description, and options._id fields with Spanish configured as both the default and override language. If the generic type is not , no indexes are created. /// - /// + /// public override async Task CreateIndexes() { if (typeof(T) == typeof(DiagnosisList)) @@ -1348,14 +1302,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Searches for options within a master list using text search with accent-aware regex. + /// Retrieves the options of a referenced entity whose name or description match the supplied , building a case-insensitive regex pattern (via BuildRegexPattern) and filtering through a MongoDB aggregation pipeline against . Returns an empty list when is null, empty, or whitespace, when the entity identified by cannot be found, or when no options match; any error is logged and an empty list is returned. /// - /// Optional text to search within options. - /// Optional master list ObjectId to filter results. - /// A list of matching OptionList items ordered by name. - /// Logs errors and returns empty list on failure. - /// + /// The free-text query used to match option names and descriptions. A null, empty, or whitespace value short-circuits the search and yields no results. + /// The of the parent entity whose options will be searched. When null, the aggregation matches a literal null identifier. + /// A containing the matching entries ordered by name, or an empty list when nothing matches or the operation fails. + /// private async Task> GetOptionsByTextSearch(string? textSearch, ObjectId? id = null) { try @@ -1428,14 +1380,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Creates a fluent query for paginated results with combined filters. + /// Creates an query by combining the provided with a logical AND and applying the given . When is empty, is used so that all documents are matched. /// - /// List of filter definitions to apply. - /// Sort definition for the query results. - /// A fluent queryable for T results. + /// The list of instances to combine. When the list is empty, no filtering is applied. + /// The to apply to the resulting query. + /// An configured with the combined filter and sort. /// - /// private IFindFluent CreateFindFluent(List> filters, SortDefinition sort) { var combinedFilter = filters.Any() @@ -1445,14 +1395,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Generates new locale items for a master list option based on a default locale. - /// Creates LocaleItem entries for all locales except the specified default. + /// Builds a new by assigning a fresh (with set to ) to every property of whose name matches a value, skipping and the value supplied through . /// - /// The default locale to exclude from translations. - /// The option name to use as default translation. - /// A Locale object with translations for all other locales. - /// + /// The value identifying the locale to omit when populating the resulting . + /// The name assigned to each created . + /// A with a new for every locale other than and ; properties without a matching enum name are left unset. + /// private Locale GetNewItemLocale(LocaleEnum localeList, string opt) { var newLocale = new Locale(); @@ -1487,14 +1435,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository // Método auxiliar para construir patrones regex con soporte de acentos - /// Builds a regex pattern that matches accented and non-accented versions of vowels. - /// Supports Spanish accent handling (á, é, í, ó, ú) and digits. + /// + /// Builds a case-insensitive regex pattern from , expanding each vowel into a character class that includes its common accented variants (e.g. a → [aáàäâ]). Digits are wrapped in a character class as literal matches, and any other character is appended as-is to be treated literally by the regex engine. /// - /// The input string to build the pattern from. - /// A regex-compatible pattern string. + /// The source text whose characters are translated into the resulting regex pattern. + /// A containing the constructed regular expression pattern. /// - /// private static string BuildRegexPattern(string input) { var regexPattern = new StringBuilder(); @@ -1528,16 +1474,17 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Searches for options within a master list by name with locale translation. - /// Uses MongoDB aggregation pipeline to apply locale-aware filtering. + /// Retrieves the options of a master list document identified by , rebuilding each option's + /// Name by selecting the translation matching (or falling back to the original name + /// when the locale is the default or no translation exists), and filters the resulting options by exact match against + /// . Returns the matched options ordered by name, or an empty list if no document is + /// found, no option matches, or an error occurs. /// - /// The ObjectId of the master list. - /// The option name to search for. - /// The locale for translation. - /// A list of matching OptionList items ordered by name. - /// Logs errors and returns empty list on failure. - /// + /// MongoDB of the master list document to search. + /// Option name (already resolved against the requested locale) used to filter the options. + /// Target used to pick the translated name; the lowercased enum value is matched against the stored locale code. + /// A of of containing the matching options sorted by name, or an empty list when there is no match or an error is logged. + /// private async Task> GetMasterListByIdAndTextSearch( ObjectId id, string newOptName, LocaleEnum locale) {