From 3101c532520cfd7d7475f280d9a069c7b6b49f6a Mon Sep 17 00:00:00 2001 From: n8n IEC 62304 Bot Date: Mon, 6 Jul 2026 17:08:55 +0200 Subject: [PATCH] docs(iec62304): [REL-1.0.2] apply curated XML doc review updates --- .../Repositories/MasterListRepository.cs | 212 +++++++----------- adas-core.LdapLogin/LdapLoginService.cs | 63 +++--- 2 files changed, 116 insertions(+), 159 deletions(-) diff --git a/adas-core.Infrastructure/Repositories/MasterListRepository.cs b/adas-core.Infrastructure/Repositories/MasterListRepository.cs index f5415a29..b379b003 100644 --- a/adas-core.Infrastructure/Repositories/MasterListRepository.cs +++ b/adas-core.Infrastructure/Repositories/MasterListRepository.cs @@ -113,12 +113,10 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Updates an existing master list entity with full replacement. + /// Replaces the document in the collection matching the entity's identifier, or inserts it when no match exists (upsert behavior). Failures are logged and rethrown to the caller. /// - /// The entity with updated values. - /// Throws and re-throws exceptions after logging. - /// + /// The entity to upsert; its identifier is used as the filter and 's current state replaces the matched document. + /// public async Task Update(T entity) { try @@ -168,17 +166,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 T matching the specified , projecting the "options" array to at most 100 elements. Returns null when no matching document is found or when an exception is caught, with the error logged. /// - /// 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 locate. + /// A that yields the matching entity, or null when the entity is not found or an error occurs. + /// public async Task FindById(ObjectId id) { try @@ -202,16 +194,15 @@ 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. + /// Finds a specific option item within a master document using MongoDB aggregation, returning the localized or null if not found. + /// Uses the provided to resolve translations: when the locale is or matches the document's default locale, the option's main name is returned; otherwise, the matching entry in the option's localeItems is used, falling back to the main name when no translation exists. + /// Any exception raised during the aggregation or deserialization is logged and surfaced as a null result. /// - /// 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 that contains the options array. + /// The of the specific option to retrieve. + /// The value used to select the appropriate translation. + /// A that resolves to the matching , or null when the option is not found or an error occurs. + /// public async Task FindOptionItemById(ObjectId masterId, ObjectId optionId, LocaleEnum locale) { try @@ -568,17 +559,11 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Finds a master list entity by its name. + /// Asynchronously retrieves the first entity whose Name matches the supplied , applying a projection that caps the options array at 100 elements. If no document is found, or the query fails, the task resolves to null. /// - /// 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 property to build the equality filter. + /// A producing the first matching entity, or null when no match exists or the operation is aborted by a caught exception. + /// public async Task FindByName(string name) { try @@ -614,12 +599,11 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Retrieves paginated master lists with optional text filtering. + /// Builds a paginated query against the master collection of , applying a case-insensitive substring match on the text against the Name property when provided. Sorts results ascending by name and returns a fluent find interface so callers can continue chaining pagination or projection operations. /// - /// The pagination and filtering parameters. - /// A fluent queryable for MasterList results. - /// + /// The containing pagination options and the optional used to match against Name. + /// An representing the sorted (and optionally text-filtered) query, ready for further pagination configuration. + /// public IFindFluent GetPaginatedMasterList(PaginationFilter filter) { var filterBuilder = Builders.Filter; @@ -666,14 +650,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Adds a new option to a master list. + /// Adds a new entry to the master list identified by , returning null when an equivalent option already exists, the database update does not modify any document, or the operation fails. /// - /// 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 of the master list (document of type T) that will receive the new option. + /// The describing the option to add, including its name, optional visual properties, and locale information. + /// A that yields the newly created when the push update succeeds, or null when a duplicate is detected, no document is modified, or an exception is logged and swallowed. + /// public async Task AddOptionToMasterList(ObjectId id, FilterOptionListElement opt) { var exist = await GetMasterListByIdAndSearchOptions(id, opt); @@ -713,16 +695,11 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Retrieves all master list entities. + /// Asynchronously retrieves all entities of type T from the underlying collection. + /// If an exception occurs during retrieval, the error 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 represents the asynchronous operation. The task result contains an of all entities, or an empty collection if an error was encountered. + /// public async Task> GetAll() { try @@ -738,12 +715,13 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Retrieves all master list entities without options, returning only metadata. + /// Retrieves all master lists from the underlying collection and projects each entity into a , + /// where the field holds the count of associated options instead of the full options collection. + /// If the operation fails, 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 task that represents the asynchronous operation, yielding an of all + /// projected master lists, or an empty collection if an error occurs. + /// public async Task> GetAllWithoutOptions() { try @@ -768,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 collection by invoking CountDocumentsAsync with a filter that matches every document. If the operation fails, the exception 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 yields the total number of entities, or 0 if an error occurs. + /// public async Task Count() { try @@ -789,15 +765,13 @@ 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 options of a master list identified by , applying the supplied and resolving localized names and descriptions for the requested locale. + /// When is null, or when the aggregation yields no document, an empty list is returned; any exception is logged and also results in an empty list. /// - /// 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 to retrieve. + /// The optional that defines the search criteria (option type, text, name, and description) and the target locale used to translate each option. + /// A of entries matching the filters, ordered by name, or an empty list when no results are found. + /// public async Task> GetMasterListByIdAndSearchOptions(ObjectId id, FilterOptionListElement? filters) { try @@ -1169,14 +1143,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Updates the metadata details for a master list. + /// Updates the option details of an existing master list entry identified by , applying only the fields from that are not (currently and ). /// - /// 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 of the document to update in the collection. + /// The carrying the new values; properties are left unchanged. + /// The instance if the document was found and modified; otherwise, when the document was not found, no fields were modified, or the operation failed. + /// public async Task UpdateOptionDetailsToMasterList(ObjectId id, UpdateMasterListDetailsDto opt) { @@ -1206,14 +1178,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Updates the name of a master list. + /// Updates the name of a master list entry identified by in the underlying collection. Returns true when the document was modified, or false if no document matched the identifier or an exception was 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 master list document to update. + /// The new name to assign to the master list entry. + /// true if a document was modified; otherwise, false. + /// public async Task UpdateMasterListName(ObjectId id, string name) { var filter = Builders.Filter.And( @@ -1234,14 +1204,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Updates the description of a master list. + /// Updates the description of a master list entry identified by in the MongoDB collection, returning when a document was modified and when no document matched or a caught was logged. /// - /// 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 set on the entry. + /// A that resolves to if the update modified a document; otherwise, when the entry was not found or an error was logged. + /// public async Task UpdateMasterListDescription(ObjectId id, string description) { var filter = Builders.Filter.And( @@ -1262,14 +1230,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Removes an option from a master list by matching all its properties. + /// Removes the specified option from the master list document identified by by issuing a pull filter against the MongoDB collection that matches all of the option's properties (name, option type, icons, colors, default flag, and description). Returns true when the document is modified, or false if no match is found or if an exception is caught and logged. /// - /// 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 property values define the filter used to locate and remove the matching element. + /// A that resolves to true if the document was modified; otherwise, false. + /// public async Task RemoveMasterListOption(ObjectId id, OptionList oldOpt) { var filter = Builders.Filter.Eq("_id", id); @@ -1298,11 +1264,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. + /// Overrides the base index creation to build non-unique, background MongoDB indexes on the options.name, options.description, and options._id fields of the collection, configuring Spanish as the default and override language for text tokenization. The logic only runs when is ; for any other type the method is a no-op. /// - /// + /// public override async Task CreateIndexes() { if (typeof(T) == typeof(DiagnosisList)) @@ -1414,13 +1378,12 @@ public class MasterListRepository : MongoRepository, IMasterListRepository } /// - /// Creates a fluent query for paginated results with combined filters. + /// Creates a find fluent query that applies the provided combined with a logical AND, falling back to an empty filter (matching all documents) when no filters are supplied, and orders the results by the specified . /// - /// List of filter definitions to apply. - /// Sort definition for the query results. - /// A fluent queryable for T results. - /// + /// A list of criteria to combine. When empty, an empty filter is used so that all documents match. + /// The that defines the ordering of the returned documents. + /// An configured with the combined filter and the given sort. + /// private IFindFluent CreateFindFluent(List> filters, SortDefinition sort) { var combinedFilter = filters.Any() @@ -1430,14 +1393,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. + /// Creates a new instance populated with entries for every value except and the locale specified by . Each property of matching an included enum name is dynamically assigned a new whose is set to the value of . /// - /// 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 locale to exclude from the generated object. + /// The name assigned to every created in the resulting . + /// A new object containing the corresponding entries. + /// private Locale GetNewItemLocale(LocaleEnum localeList, string opt) { var newLocale = new Locale(); @@ -1511,16 +1472,13 @@ 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 , filtering them by the option name resolved against the specified . When the requested locale differs from the document's default locale, the method attempts to use the translated name; if no translation exists, it falls back to the original name. Returns an empty list when no document is found, when no options match, or when an error is logged. /// - /// 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. - /// + /// The of the master list document to match in the aggregation pipeline. + /// The option name to filter by after the locale-based name resolution. + /// The value used to select the translated name; the matching translation key is derived from its lowercased string representation. + /// A of of containing the matching options ordered by name, or an empty list when nothing is found or an exception occurs. + /// private async Task> GetMasterListByIdAndTextSearch( ObjectId id, string newOptName, LocaleEnum locale) { diff --git a/adas-core.LdapLogin/LdapLoginService.cs b/adas-core.LdapLogin/LdapLoginService.cs index 51a3628a..0ef2d517 100644 --- a/adas-core.LdapLogin/LdapLoginService.cs +++ b/adas-core.LdapLogin/LdapLoginService.cs @@ -78,15 +78,14 @@ public class LdapLoginService : ILoginService public UserEnum.LoginMethod Method => UserEnum.LoginMethod.Ldap; /// - /// Authenticates a user against the LDAP server using the provided username and password. + /// Authenticates a user against the configured LDAP server using and , and resolves the matching entry. When an LDAP service account is configured it is used for the bind; otherwise the username is optionally prefixed with the configured domain and bound with the supplied password. Searches the directory for the user entry and creates or retrieves the local record. /// - /// The username of the user to authenticate. - /// The password of the user to authenticate. - /// The authenticated user. - /// Thrown when there is an error during the login process. - /// Thrown when the user is not found in the LDAP directory. - /// + /// The username used to bind to LDAP and to locate the user entry in the directory. + /// The password used for the LDAP bind when no service account is configured. + /// The resolved from the LDAP directory entry. + /// Thrown when the LDAP server is not configured, when the directory entry is not found, or when the resolved user is null. + /// Thrown when the LDAP bind fails for the supplied credentials. + /// public async Task Login(string username, string password) { if (_ldapConfig.Server == null) @@ -158,25 +157,25 @@ public class LdapLoginService : ILoginService } /// - /// This method is not implemented in the LdapLoginService, as the login process is handled through the Login(string username, string password) method. + /// Authenticates a user based on the current . + /// This method is not yet implemented and always throws a . /// - /// The HTTP context of the request. - /// A task representing the asynchronous operation. - /// Thrown when the method is not implemented. - /// + /// The of the incoming HTTP request used to extract authentication information. + /// A that resolves to the authenticated user. + /// Always thrown because the method is not implemented. + /// public Task Login(HttpContext context) => throw new LoginServicesException("Not implemented"); /// - /// This method is not implemented in the LdapLoginService, as the authentication process is handled through the Login(string username, string password) method. + /// Authenticates a user with the provided and and returns the corresponding . + /// This method is not implemented and always throws a when invoked. /// /// The username of the user to authenticate. /// The password of the user to authenticate. - /// A task representing the asynchronous operation. - /// Thrown when the method is not implemented. - /// + /// A that yields the authenticated . + /// Thrown because authentication is not implemented. + /// public Task Authenticate(string username, string password) => throw new LoginServicesException("Not implemented"); @@ -247,13 +246,14 @@ public class LdapLoginService : ILoginService /// - /// This method checks the authorities of a user based on the LDAP entry and the application's configuration. + /// Synchronizes the authorities of a with the authorities defined in the supplied , updating existing records or inserting new ones as appropriate. + /// Authorities appearing in the whitelist are preserved and excluded from the LDAP map, while remaining LDAP authorities are compared against the current persisted list; entries with set to true have their refreshed via , otherwise they are inserted with . + /// On any failure, the error is logged and an empty list is returned. /// - /// The user whose authorities are being checked. - /// The LDAP entry containing the user's information. - /// A list of updated authorities for the user. - /// + /// The user whose authorities are being reconciled. + /// The providing the source authorities map and whitelist. + /// The updated list retrieved from the authority service. + /// private async Task> CheckAuthorities(User user, LdapEntry entry) { @@ -343,14 +343,13 @@ public class LdapLoginService : ILoginService /// - /// This method retrieves a list of authorities for a user based on the LDAP entry and the application's configuration for mapping LDAP groups to authorities. + /// Maps the supplied to a instance by reading attributes whose names are configured in the LDAP settings. + /// The is taken from the configured user name property, falling back to an empty string when the attribute is absent. + /// When the first name and/or last name properties are configured, their attribute values are used to build the ; otherwise the name is left unset, and the last name is appended to the first name when both are present. /// - /// The LDAP entry containing the user's information. - /// The existing or newly created user with updated authorities. - /// - /// + /// The whose attributes are read to populate the resulting . + /// A populated from the attributes exposed by according to the current LDAP configuration. + /// private User GetUser(LdapEntry ldapEntry) {