ljrojas91/adas-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(iec62304): [REL-1.0.2] apply curated XML doc review updates

Browse Source
This commit is contained in:
n8n IEC 62304 Bot
2026-07-06 17:08:55 +02:00
parent 481d768ebd
commit 3101c53252
2 changed files with 116 additions and 159 deletions
Download Patch File Download Diff File Expand all files Collapse all files
adas-core.Infrastructure/Repositories/MasterListRepository.cs
+85 -127
View File
@@ -113,12 +113,10 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// 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.
/// </summary>
/// <param name="entity">The entity with updated values.</param>
/// <exception cref="Exception">Throws and re-throws exceptions after logging.</exception>
/// <!-- aidoc-review:v1 severity=medium kind=wrong_summary
/// "Summary says 'Updates an existing' entity, but the code uses IsUpsert = true, so the method can also insert a new entity when one does not exist." -->
/// <param name="entity">The entity to upsert; its identifier is used as the filter and <paramref name="entity"/>'s current state replaces the matched document.</param>
/// <!-- aidoc:v1 sig=019b691 body=863650a -->
public async Task Update(T entity)
{
try
@@ -168,17 +166,11 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Finds a master list entity by its ID with options projection limited to 100 items.
/// Asynchronously retrieves an entity of type <c>T</c> matching the specified <paramref name="id"/>, projecting the "options" array to at most 100 elements. Returns <c>null</c> when no matching document is found or when an exception is caught, with the error logged.
/// </summary>
/// <param name="id">The ObjectId of the entity to retrieve.</param>
/// <returns>The MasterList entity if found; otherwise, null.</returns>
/// <exception cref="Exception">Logs errors and returns null on failure.</exception>
/// <!-- aidoc-review:v1 severity=high kind=wrong_summary
/// "Method is generic (FindById<T>) and not specific to a 'master list entity'; summary incorrectly scopes it to master list." -->
/// <!-- aidoc-review:v1 severity=high kind=wrong_returns
/// "Documentation says 'The MasterList entity' but the method's return type is the generic T?, not a MasterList." -->
/// <!-- aidoc-review:v1 severity=high kind=wrong_exception
/// "Documents <exception cref=\"Exception\">, but the method catches all exceptions internally and never propagates them to the caller." -->
/// <param name="id">The <see cref="ObjectId"/> identifier of the entity to locate.</param>
/// <returns>A <see cref="Task{T}"/> that yields the matching entity, or <c>null</c> when the entity is not found or an error occurs.</returns>
/// <!-- aidoc:v1 sig=81ac96a body=1519944 -->
public async Task<T?> FindById(ObjectId id)
{
try
@@ -202,16 +194,15 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// 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 <see cref="OptionList"/> or <c>null</c> if not found.
/// Uses the provided <paramref name="locale"/> to resolve translations: when the locale is <see cref="LocaleEnum.Default"/> or matches the document's default locale, the option's main name is returned; otherwise, the matching entry in the option's <c>localeItems</c> 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 <c>null</c> result.
/// </summary>
/// <param name="masterId">The ObjectId of the master list.</param>
/// <param name="optionId">The ObjectId of the option to retrieve.</param>
/// <param name="locale">The locale for translation.</param>
/// <returns>The OptionList with translated fields if found; otherwise, null.</returns>
/// <exception cref="Exception">Logs errors and returns null on failure.</exception>
/// <!-- aidoc-review:v1 severity=medium kind=extra_exception
/// "The method wraps its entire body in a try/catch that catches Exception, logs it, and returns null; it never propagates Exception to the caller, so the <exception cref=\"Exception\"/> tag is misleading. The behavior described (log and return null) belongs in the <remarks> or summary, not as a thrown exception." -->
/// <param name="masterId">The <see cref="ObjectId"/> of the master document that contains the options array.</param>
/// <param name="optionId">The <see cref="ObjectId"/> of the specific option to retrieve.</param>
/// <param name="locale">The <see cref="LocaleEnum"/> value used to select the appropriate translation.</param>
/// <returns>A <see cref="Task{OptionList}"/> that resolves to the matching <see cref="OptionList"/>, or <c>null</c> when the option is not found or an error occurs.</returns>
/// <!-- aidoc:v1 sig=fdb2628 body=0e4983e -->
public async Task<OptionList?> FindOptionItemById(ObjectId masterId, ObjectId optionId, LocaleEnum locale)
{
try
@@ -568,17 +559,11 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Finds a master list entity by its name.
/// Asynchronously retrieves the first entity whose <c>Name</c> matches the supplied <paramref name="name"/>, applying a projection that caps the <c>options</c> array at 100 elements. If no document is found, or the query fails, the task resolves to <c>null</c>.
/// </summary>
/// <param name="name">The name of the master list to retrieve.</param>
/// <returns>The MasterList entity if found; otherwise, null.</returns>
/// <exception cref="Exception">Logs errors and returns null on failure.</exception>
/// <!-- aidoc-review:v1 severity=high kind=wrong_returns
/// "The method returns Task<T?> (generic), not MasterList; the return type description should reference T, not MasterList." -->
/// <!-- aidoc-review:v1 severity=high kind=wrong_summary
/// "Summary says 'Finds a master list entity' but the method is generic (T) and is not specific to master lists." -->
/// <!-- aidoc-review:v1 severity=high kind=wrong_exception
/// "The method catches all exceptions internally and returns null; it does not propagate any exception, so the <exception> tag is misleading." -->
/// <param name="name">The value compared against the entity's <c>Name</c> property to build the equality filter.</param>
/// <returns>A <see cref="Task{T}"/> producing the first matching entity, or <c>null</c> when no match exists or the operation is aborted by a caught exception.</returns>
/// <!-- aidoc:v1 sig=80a1541 body=8b5b558 -->
public async Task<T?> FindByName(string name)
{
try
@@ -614,12 +599,11 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Retrieves paginated master lists with optional text filtering.
/// Builds a paginated query against the master collection of <typeparamref name="T"/>, applying a case-insensitive substring match on the <see cref="PaginationFilter.FilteredRequest"/> text against the <c>Name</c> property when provided. Sorts results ascending by <c>name</c> and returns a fluent find interface so callers can continue chaining pagination or projection operations.
/// </summary>
/// <param name="filter">The pagination and filtering parameters.</param>
/// <returns>A fluent queryable for MasterList results.</returns>
/// <!-- aidoc-review:v1 severity=high kind=wrong_returns
/// "Documentation states the method returns 'A fluent queryable for MasterList results', but the method returns IFindFluent<T, T> where T is a generic type parameter, not specifically MasterList." -->
/// <param name="filter">The <see cref="PaginationFilter"/> containing pagination options and the optional <see cref="FilteredRequest.Text"/> used to match against <c>Name</c>.</param>
/// <returns>An <see cref="IFindFluent{TDocument, TProjection}"/> representing the sorted (and optionally text-filtered) query, ready for further pagination configuration.</returns>
/// <!-- aidoc:v1 sig=bbb39c7 body=f42ebaa -->
public IFindFluent<T, T> GetPaginatedMasterList(PaginationFilter filter)
{
var filterBuilder = Builders<T>.Filter;
@@ -666,14 +650,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Adds a new option to a master list.
/// Adds a new <see cref="OptionList"/> entry to the master list identified by <paramref name="id"/>, returning <c>null</c> when an equivalent option already exists, the database update does not modify any document, or the operation fails.
/// </summary>
/// <param name="id">The ObjectId of the master list.</param>
/// <param name="opt">The option element to add.</param>
/// <returns>The newly created OptionList if successful; otherwise, null if duplicate exists.</returns>
/// <exception cref="Exception">Logs errors and returns null on failure.</exception>
/// <!-- aidoc-review:v1 severity=high kind=wrong_exception
/// "<exception cref=\"Exception\"> documents an exception that is caught and handled inside the method (try/catch returns null) rather than thrown out to the caller." -->
/// <param name="id">The <see cref="ObjectId"/> of the master list (document of type <c>T</c>) that will receive the new option.</param>
/// <param name="opt">The <see cref="FilterOptionListElement"/> describing the option to add, including its name, optional visual properties, and locale information.</param>
/// <returns>A <see cref="Task{T}"/> that yields the newly created <see cref="OptionList"/> when the push update succeeds, or <c>null</c> when a duplicate is detected, no document is modified, or an exception is logged and swallowed.</returns>
/// <!-- aidoc:v1 sig=1602f0d body=e7fd138 -->
public async Task<OptionList?> AddOptionToMasterList(ObjectId id, FilterOptionListElement opt)
{
var exist = await GetMasterListByIdAndSearchOptions(id, opt);
@@ -713,16 +695,11 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// 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.
/// </summary>
/// <returns>An enumerable of all MasterList entities.</returns>
/// <exception cref="Exception">Logs errors and returns empty list on failure.</exception>
/// <!-- aidoc-review:v1 severity=high kind=wrong_summary
/// "Method is generic (IEnumerable<T>), not specific to 'master list entities'; the name 'master list' does not appear in the code." -->
/// <!-- aidoc-review:v1 severity=high kind=wrong_returns
/// "Documents 'An enumerable of all MasterList entities' but the method is generic and returns IEnumerable<T>, not a concrete MasterList type." -->
/// <!-- aidoc-review:v1 severity=high kind=wrong_exception
/// "Documents <exception cref='Exception'> but the method catches all exceptions internally and returns an empty list; it does not throw Exception." -->
/// <returns>A task that represents the asynchronous operation. The task result contains an <see cref="IEnumerable{T}"/> of all entities, or an empty collection if an error was encountered.</returns>
/// <!-- aidoc:v1 sig=3a61c61 body=40d7129 -->
public async Task<IEnumerable<T>> GetAll()
{
try
@@ -738,12 +715,13 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Retrieves all master list entities without options, returning only metadata.
/// Retrieves all master lists from the underlying collection and projects each entity into a <see cref="MasterListDto"/>,
/// where the <see cref="MasterListDto.Options"/> 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.
/// </summary>
/// <returns>An enumerable of MasterListDto containing id, name, description, listType, and options count.</returns>
/// <exception cref="Exception">Logs errors and returns empty list on failure.</exception>
/// <!-- aidoc-review:v1 severity=high kind=wrong_exception
/// "The method catches all exceptions in a try/catch and returns an empty list without rethrowing, so it does not throw Exception. The <exception> tag misleads readers into expecting an exception to propagate." -->
/// <returns>A task that represents the asynchronous operation, yielding an <see cref="IEnumerable{MasterListDto}"/> of all
/// projected master lists, or an empty collection if an error occurs.</returns>
/// <!-- aidoc:v1 sig=e493435 body=1c299ba -->
public async Task<IEnumerable<MasterListDto>> GetAllWithoutOptions()
{
try
@@ -768,12 +746,10 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Counts the total number of master list entities in the collection.
/// Asynchronously counts all entities in the collection by invoking <c>CountDocumentsAsync</c> with a filter that matches every document. If the operation fails, the exception is logged and the method returns <c>0</c> as a safe fallback.
/// </summary>
/// <returns>The total count of entities.</returns>
/// <exception cref="Exception">Logs errors and returns 0 on failure.</exception>
/// <!-- aidoc-review:v1 severity=high kind=wrong_exception
/// "The method catches all exceptions and returns 0, so it never throws Exception. The <exception cref=\"Exception\"> tag misleads readers into thinking the method can throw." -->
/// <returns>A <see cref="Task{Int32}"/> that yields the total number of entities, or <c>0</c> if an error occurs.</returns>
/// <!-- aidoc:v1 sig=f1f0a98 body=01cd3d1 -->
public async Task<int> Count()
{
try
@@ -789,15 +765,13 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// 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 <paramref name="id"/>, applying the supplied <paramref name="filters"/> and resolving localized names and descriptions for the requested locale.
/// When <paramref name="filters"/> is <c>null</c>, or when the aggregation yields no document, an empty list is returned; any exception is logged and also results in an empty list.
/// </summary>
/// <param name="id">The ObjectId of the master list.</param>
/// <param name="filters">The filter criteria including text, name, description, and optionType.</param>
/// <returns>A list of matching OptionList items ordered by name.</returns>
/// <exception cref="Exception">Logs errors and returns empty list on failure.</exception>
/// <!-- aidoc-review:v1 severity=medium kind=extra_exception
/// "The method has a catch (Exception ex) block that logs and returns an empty list; it does not propagate any exception to callers, making the <exception cref='Exception'> tag misleading." -->
/// <param name="id">The <see cref="ObjectId"/> of the master list to retrieve.</param>
/// <param name="filters">The optional <see cref="FilterOptionListElement"/> that defines the search criteria (option type, text, name, and description) and the target locale used to translate each option.</param>
/// <returns>A <see cref="Task{List{OptionList}}"/> of <see cref="OptionList"/> entries matching the filters, ordered by name, or an empty list when no results are found.</returns>
/// <!-- aidoc:v1 sig=f6ee5be body=17d6a96 -->
public async Task<List<OptionList>> GetMasterListByIdAndSearchOptions(ObjectId id, FilterOptionListElement? filters)
{
try
@@ -1169,14 +1143,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Updates the metadata details for a master list.
/// Updates the option details of an existing master list entry identified by <paramref name="id"/>, applying only the fields from <paramref name="opt"/> that are not <see langword="null"/> (currently <see cref="UpdateMasterListDetailsDto.CanAddElement"/> and <see cref="UpdateMasterListDetailsDto.OptionListDetails"/>).
/// </summary>
/// <param name="id">The ObjectId of the master list.</param>
/// <param name="opt">The UpdateMasterListDetailsDto with updated values.</param>
/// <returns>The updated UpdateMasterListDetailsDto if successful; otherwise, null.</returns>
/// <exception cref="Exception">Logs errors and returns null on failure.</exception>
/// <!-- aidoc-review:v1 severity=medium kind=extra_exception
/// "The <exception cref=\"Exception\"> tag suggests the method may throw Exception, but the body catches all exceptions internally, logs them, and returns null without rethrowing." -->
/// <param name="id">The <see cref="ObjectId"/> of the document to update in the collection.</param>
/// <param name="opt">The <see cref="UpdateMasterListDetailsDto"/> carrying the new values; <see langword="null"/> properties are left unchanged.</param>
/// <returns>The <paramref name="opt"/> instance if the document was found and modified; otherwise, <see langword="null"/> when the document was not found, no fields were modified, or the operation failed.</returns>
/// <!-- aidoc:v1 sig=53d4179 body=49f50ca -->
public async Task<UpdateMasterListDetailsDto?> UpdateOptionDetailsToMasterList(ObjectId id,
UpdateMasterListDetailsDto opt)
{
@@ -1206,14 +1178,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Updates the name of a master list.
/// Updates the name of a master list entry identified by <paramref name="id"/> in the underlying collection. Returns <c>true</c> when the document was modified, or <c>false</c> if no document matched the identifier or an exception was caught and logged.
/// </summary>
/// <param name="id">The ObjectId of the master list.</param>
/// <param name="name">The new name.</param>
/// <returns>True if the update was successful; otherwise, false.</returns>
/// <exception cref="Exception">Logs errors and returns false on failure.</exception>
/// <!-- aidoc-review:v1 severity=high kind=wrong_exception
/// "The <exception cref=\"Exception\"> tag documents an exception that is never thrown. The method's try/catch block catches all Exception types and returns false, so callers do not need to handle any exception thrown by this method." -->
/// <param name="id">The <see cref="ObjectId"/> of the master list document to update.</param>
/// <param name="name">The new name to assign to the master list entry.</param>
/// <returns><c>true</c> if a document was modified; otherwise, <c>false</c>.</returns>
/// <!-- aidoc:v1 sig=5b79a51 body=36dfe99 -->
public async Task<bool> UpdateMasterListName(ObjectId id, string name)
{
var filter = Builders<T>.Filter.And(
@@ -1234,14 +1204,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Updates the description of a master list.
/// Updates the description of a master list entry identified by <paramref name="id"/> in the MongoDB collection, returning <see langword="true"/> when a document was modified and <see langword="false"/> when no document matched or a caught <see cref="Exception"/> was logged.
/// </summary>
/// <param name="id">The ObjectId of the master list.</param>
/// <param name="description">The new description.</param>
/// <returns>True if the update was successful; otherwise, false.</returns>
/// <exception cref="Exception">Logs errors and returns false on failure.</exception>
/// <!-- aidoc-review:v1 severity=high kind=wrong_exception
/// "The method catches all exceptions and returns false rather than throwing them, so an <exception> tag documenting that exceptions are thrown is misleading." -->
/// <param name="id">The <see cref="ObjectId"/> of the master list entry to update.</param>
/// <param name="description">The new description to set on the entry.</param>
/// <returns>A <see cref="Task{Boolean}"/> that resolves to <see langword="true"/> if the update modified a document; otherwise, <see langword="false"/> when the entry was not found or an error was logged.</returns>
/// <!-- aidoc:v1 sig=5a27a55 body=3552f46 -->
public async Task<bool> UpdateMasterListDescription(ObjectId id, string description)
{
var filter = Builders<T>.Filter.And(
@@ -1262,14 +1230,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Removes an option from a master list by matching all its properties.
/// Removes the specified option from the master list document identified by <paramref name="id"/> 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.
/// </summary>
/// <param name="id">The ObjectId of the master list.</param>
/// <param name="oldOpt">The OptionList to remove.</param>
/// <returns>True if the option was removed; otherwise, false.</returns>
/// <exception cref="Exception">Logs errors and returns false on failure.</exception>
/// <!-- aidoc-review:v1 severity=medium kind=extra_exception
/// "The method catches all exceptions internally and returns false rather than propagating them, so an <exception> tag is misleading." -->
/// <param name="id">The <see cref="ObjectId"/> of the master list document to update.</param>
/// <param name="oldOpt">The <see cref="OptionList"/> whose property values define the filter used to locate and remove the matching element.</param>
/// <returns>A <see cref="Task{Boolean}"/> that resolves to true if the document was modified; otherwise, false.</returns>
/// <!-- aidoc:v1 sig=8de50cd body=d974b9b -->
public async Task<bool> RemoveMasterListOption(ObjectId id, OptionList oldOpt)
{
var filter = Builders<T>.Filter.Eq("_id", id);
@@ -1298,11 +1264,9 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// 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 <c>options.name</c>, <c>options.description</c>, and <c>options._id</c> fields of the <see cref="DiagnosisList"/> collection, configuring Spanish as the default and override language for text tokenization. The logic only runs when <typeparamref name="T"/> is <see cref="DiagnosisList"/>; for any other type the method is a no-op.
/// </summary>
/// <!-- aidoc-review:v1 severity=high kind=wrong_summary
/// "Documentation states the method 'creates text indexes', but the code uses Builders<T>.IndexKeys.Ascending(...) to create ascending indexes, not text indexes. The language options (LanguageOverride/DefaultLanguage) are configured, but no Text index keys are used." -->
/// <!-- aidoc:v1 sig=4955da2 body=2c8d1f7 -->
public override async Task CreateIndexes()
{
if (typeof(T) == typeof(DiagnosisList))
@@ -1414,13 +1378,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Creates a fluent query for paginated results with combined filters.
/// Creates a find fluent query that applies the provided <paramref name="filters"/> 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 <paramref name="sort"/>.
/// </summary>
/// <param name="filters">List of filter definitions to apply.</param>
/// <param name="sort">Sort definition for the query results.</param>
/// <returns>A fluent queryable for T results.</returns>
/// <!-- aidoc-review:v1 severity=high kind=wrong_summary
/// "The method does not perform pagination (no Skip/Limit applied). It only combines filters and applies a sort, so 'paginated results' in the summary is incorrect." -->
/// <param name="filters">A list of <see cref="FilterDefinition{T}"/> criteria to combine. When empty, an empty filter is used so that all documents match.</param>
/// <param name="sort">The <see cref="SortDefinition{T}"/> that defines the ordering of the returned documents.</param>
/// <returns>An <see cref="IFindFluent{T,T}"/> configured with the combined filter and the given sort.</returns>
/// <!-- aidoc:v1 sig=704d715 body=2a35652 -->
private IFindFluent<T, T> CreateFindFluent(List<FilterDefinition<T>> filters, SortDefinition<T> sort)
{
var combinedFilter = filters.Any()
@@ -1430,14 +1393,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// 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 <see cref="Locale"/> instance populated with <see cref="LocaleItem"/> entries for every <see cref="LocaleEnum"/> value except <see cref="LocaleEnum.Default"/> and the locale specified by <paramref name="localeList"/>. Each property of <see cref="Locale"/> matching an included enum name is dynamically assigned a new <see cref="LocaleItem"/> whose <see cref="LocaleItem.Name"/> is set to the value of <paramref name="opt"/>.
/// </summary>
/// <param name="localeList">The default locale to exclude from translations.</param>
/// <param name="opt">The option name to use as default translation.</param>
/// <returns>A Locale object with translations for all other locales.</returns>
/// <!-- aidoc-review:v1 severity=medium kind=wrong_summary
/// "The summary says entries are created for 'all locales except the specified default', but the code also always excludes LocaleEnum.Default (hardcoded skip) in addition to the localeList parameter, which is not mentioned." -->
/// <param name="localeList">The locale to exclude from the generated <see cref="Locale"/> object.</param>
/// <param name="opt">The name assigned to every <see cref="LocaleItem"/> created in the resulting <see cref="Locale"/>.</param>
/// <returns>A new <see cref="Locale"/> object containing the corresponding <see cref="LocaleItem"/> entries.</returns>
/// <!-- aidoc:v1 sig=147db59 body=9b63847 -->
private Locale GetNewItemLocale(LocaleEnum localeList, string opt)
{
var newLocale = new Locale();
@@ -1511,16 +1472,13 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// 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 <paramref name="id"/>, filtering them by the option name <paramref name="newOptName"/> resolved against the specified <paramref name="locale"/>. 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.
/// </summary>
/// <param name="id">The ObjectId of the master list.</param>
/// <param name="newOptName">The option name to search for.</param>
/// <param name="locale">The locale for translation.</param>
/// <returns>A list of matching OptionList items ordered by name.</returns>
/// <exception cref="Exception">Logs errors and returns empty list on failure.</exception>
/// <!-- aidoc-review:v1 severity=low kind=extra_exception
/// "The method catches all exceptions internally and returns an empty list; the <exception cref=\"Exception\"> tag is misleading because the method does not actually throw any exception to the caller." -->
/// <param name="id">The <see cref="ObjectId"/> of the master list document to match in the aggregation pipeline.</param>
/// <param name="newOptName">The option name to filter by after the locale-based name resolution.</param>
/// <param name="locale">The <see cref="LocaleEnum"/> value used to select the translated name; the matching translation key is derived from its lowercased string representation.</param>
/// <returns>A <see cref="Task{T}"/> of <see cref="List{T}"/> of <see cref="OptionList"/> containing the matching options ordered by name, or an empty list when nothing is found or an exception occurs.</returns>
/// <!-- aidoc:v1 sig=342dc63 body=21f31fc -->
private async Task<List<OptionList>> GetMasterListByIdAndTextSearch(
ObjectId id, string newOptName, LocaleEnum locale)
{