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 21:21:05 +02:00
parent 64da453152
commit ad518abd07
2 changed files with 109 additions and 161 deletions
Download Patch File Download Diff File Expand all files Collapse all files
adas-core.Infrastructure/Repositories/MasterListRepository.cs
+96 -143
View File
@@ -113,12 +113,11 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Updates an existing master list entity with full replacement.
/// Persists the supplied <typeparamref name="T"/> entity in the collection by replacing the document identified by <see cref="T.Id"/>, or inserting a new document when no match is found (upsert). Logs and rethrows any exception raised during the operation.
/// </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=low kind=wrong_summary
/// "Summary says 'Updates an existing' entity, but ReplaceOptions { IsUpsert = true } allows the operation to also insert a new entity if none matches the filter, so 'existing' is not strictly accurate." -->
/// <typeparam name="T">The document type stored in the collection.</typeparam>
/// <param name="entity">The entity whose <see cref="T.Id"/> locates the target document and whose state is written to the collection.</param>
/// <!-- aidoc:v1 sig=019b691 body=863650a -->
public async Task Update(T entity)
{
try
@@ -168,17 +167,12 @@ 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 <typeparamref name="T"/> from the collection by its <see cref="ObjectId"/>, applying a projection that truncates the <c>options</c> field to 100 elements. Returns <see langword="null"/> when no matching document is found, or when an exception is caught and logged by <see cref="Log"/>.
/// </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 on T, not specific to 'master list' entities" -->
/// <!-- aidoc-review:v1 severity=high kind=wrong_returns
/// "Returns T? (generic), not specifically a 'MasterList entity'" -->
/// <!-- aidoc-review:v1 severity=high kind=extra_exception
/// "<exception cref='Exception'> is misleading: the catch block swallows all exceptions and returns null; the method does not propagate an Exception to callers" -->
/// <typeparam name="T">The document type stored in the collection, expected to expose an <see cref="ObjectId"/> identifier.</typeparam>
/// <param name="id">The <see cref="ObjectId"/> of the entity to locate.</param>
/// <returns>A <see cref="Task{T}"/> that resolves to the matching entity, or <see langword="null"/> if the document is not found or the operation fails.</returns>
/// <!-- aidoc:v1 sig=81ac96a body=1519944 -->
public async Task<T?> FindById(ObjectId id)
{
try
@@ -202,16 +196,13 @@ 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.
/// Retrieves a single <see cref="OptionList"/> item from a master document identified by <paramref name="masterId"/> and <paramref name="optionId"/>, applying locale-aware name resolution. When <paramref name="locale"/> is <see cref="LocaleEnum.Default"/> or matches the document's default locale, the base name is returned; otherwise, the matching entry from the <c>localeItems</c> map is used, falling back to the base name when no translation is found. Returns <see langword="null"/> when the option is not found or if an error occurs during aggregation.
/// </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's try/catch catches all Exception instances and returns null, so it does not propagate any exception to the caller; the <exception cref=\"Exception\"/> tag is therefore misleading." -->
/// <param name="masterId">The <see cref="ObjectId"/> of the master document that contains the option collection to search.</param>
/// <param name="optionId">The <see cref="ObjectId"/> of the specific option within the master document's options array.</param>
/// <param name="locale">The <see cref="LocaleEnum"/> value that drives translation selection; <see cref="LocaleEnum.Default"/> resolves to the document's default locale, while any other value attempts a locale-specific lookup.</param>
/// <returns>A <see cref="Task{TResult}"/> that yields the matched <see cref="OptionList"/>, or <see langword="null"/> if no document/option is found or the operation fails.</returns>
/// <!-- aidoc:v1 sig=fdb2628 body=0e4983e -->
public async Task<OptionList?> FindOptionItemById(ObjectId masterId, ObjectId optionId, LocaleEnum locale)
{
try
@@ -383,17 +374,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Finds a master list entity by its ID with optional locale translation for options.
/// Uses MongoDB aggregation to unwind options and apply translations.
/// Asynchronously finds an entity of type <typeparamref name="T"/> by its MongoDB <see cref="ObjectId"/>, executing an aggregation pipeline that unwinds the <c>options</c> array and resolves localized option names. When <paramref name="locale"/> is <c>null</c> or <see cref="LocaleEnum.Default"/>, the original option name is returned; otherwise, the option name is translated using the supplied locale, falling back to the original name when no matching <c>localeItems</c> entry exists. Returns <c>null</c> when no document is found or when an exception is caught and logged.
/// </summary>
/// <param name="id">The ObjectId of the entity to retrieve.</param>
/// <param name="locale">Optional locale for translated option names.</param>
/// <returns>The MasterList entity with translated options if found; otherwise, null.</returns>
/// <exception cref="Exception">Logs errors and returns null on failure.</exception>
/// <!-- aidoc-review:v1 severity=medium kind=wrong_exception
/// "Method catches all exceptions and returns null; it never throws Exception, so the <exception cref=\"Exception\"/> tag is misleading." -->
/// <!-- aidoc-review:v1 severity=medium kind=wrong_returns
/// "Returns is documented as 'MasterList entity' but the method signature is generic Task<T?> and does not indicate T is MasterList." -->
/// <param name="id">The MongoDB <see cref="ObjectId"/> that uniquely identifies the document to retrieve.</param>
/// <param name="locale">The optional <see cref="LocaleEnum"/> used to resolve translated option names; pass <c>null</c> or <see cref="LocaleEnum.Default"/> to use the default (non-translated) names.</param>
/// <returns>A <see cref="Task{T}"/> that yields the matched entity of type <typeparamref name="T"/>, or <c>null</c> if no document matches <paramref name="id"/> or if an error occurs during aggregation.</returns>
/// <!-- aidoc:v1 sig=cb4a658 body=f2e88d8 -->
public async Task<T?> FindById(ObjectId id, LocaleEnum? locale)
{
try
@@ -571,17 +557,11 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Finds a master list entity by its name.
/// Asynchronously finds a single <typeparamref name="T"/> entity by its <see cref="T.Name"/> using a MongoDB query, projecting only the first 100 elements of the <c>options</c> field to limit payload size. Returns <c>null</c> if no matching document is found or if an error occurs during the search.
/// </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_summary
/// "Method is generic on T, not specific to a 'master list entity'." -->
/// <!-- aidoc-review:v1 severity=high kind=wrong_returns
/// "Documents return of 'The MasterList entity', but the method returns generic Task<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 never propagates one to the caller." -->
/// <param name="name">The name value used to build the equality filter against the entity's <c>Name</c> field.</param>
/// <returns>A <see cref="Task{T}"/> that yields the matching <typeparamref name="T"/> instance, or <c>null</c> when no document matches or the operation fails.</returns>
/// <!-- aidoc:v1 sig=80a1541 body=8b5b558 -->
public async Task<T?> FindByName(string name)
{
try
@@ -644,15 +624,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Retrieves paginated options within a master list with optional text filtering.
/// Retrieves the options belonging to the master list identified by <paramref name="listId"/>, optionally narrowed down by the text contained in <paramref name="filter"/>. Returns an empty collection when no master list exists for the given identifier, and when a non-empty filter text is supplied, applies a case-insensitive match against each option's name, description, or option type.
/// </summary>
/// <param name="filter">The pagination and filtering parameters.</param>
/// <param name="listId">The ObjectId of the master list.</param>
/// <returns>A list of filtered OptionList items.</returns>
/// <!-- aidoc-review:v1 severity=high kind=wrong_summary
/// "Summary states the method retrieves 'paginated options', but the code contains no pagination logic (no Skip/Take, page index, or page size handling). The method only applies an optional text filter and returns all matching options via ToList()." -->
/// <!-- aidoc-review:v1 severity=high kind=wrong_param_role
/// "filter is documented as 'The pagination and filtering parameters', but the code only reads filter.FilteredRequest.Text; no pagination fields of the filter are consumed." -->
/// <param name="filter">The <see cref="PaginationFilter"/> that provides the optional text used to filter the returned options.</param>
/// <param name="listId">The <see cref="ObjectId"/> of the master list whose options should be retrieved.</param>
/// <returns>A <see cref="Task"/> that resolves to a <see cref="List{OptionList}"/> of options matching the filter, or an empty list when the master list cannot be found.</returns>
/// <!-- aidoc:v1 sig=2ac8d75 body=b25fb18 -->
public async Task<List<OptionList>> GetPaginatedOptions(PaginationFilter filter, ObjectId listId)
{
//TODO: LOCALE
@@ -672,14 +649,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"/>. Returns the created option on success, or <c>null</c> if a matching option already exists, the master list cannot be retrieved, the update does not modify any document, or the operation throws an exception that is logged.
/// </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
/// "The method catches all exceptions internally and returns null; it never throws Exception to the caller, so the <exception cref=\"Exception\"> tag is misleading." -->
/// <param name="id">The <see cref="ObjectId"/> of the master list to update.</param>
/// <param name="opt">The <see cref="FilterOptionListElement"/> describing the option to add; its locale items are reused when <see cref="FilterOptionListElement.IsFromAdmPanel"/> is <c>true</c>, otherwise new locale entries are generated from the master list's <see cref="LocaleEnum"/> default.</param>
/// <returns>A <see cref="Task{OptionList}"/> that resolves to the newly created <see cref="OptionList"/> when the push update succeeds, or <c>null</c> when the operation is skipped, no document is modified, or the update fails.</returns>
/// <!-- aidoc:v1 sig=1602f0d body=e7fd138 -->
public async Task<OptionList?> AddOptionToMasterList(ObjectId id, FilterOptionListElement opt)
{
var exist = await GetMasterListByIdAndSearchOptions(id, opt);
@@ -719,16 +694,11 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Retrieves all master list entities.
/// Asynchronously retrieves all entities from the underlying collection.
/// If an exception occurs during retrieval, the error is logged and an empty collection is returned rather than propagating the failure.
/// </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
/// "Summary references 'master list entities' but the method is generic (IEnumerable<T>) and does not specifically operate on MasterList." -->
/// <!-- aidoc-review:v1 severity=high kind=wrong_returns
/// "Returns tag describes 'MasterList entities' but the method returns IEnumerable<T>, a generic type." -->
/// <!-- aidoc-review:v1 severity=high kind=wrong_exception
/// "Exception tag documents Exception, but the method catches all exceptions and never re-throws; it returns an empty list on failure instead of throwing." -->
/// <returns>A <see cref="Task"/> that yields an <see cref="IEnumerable{T}"/> containing all retrieved entities, or an empty collection if the operation fails.</returns>
/// <!-- aidoc:v1 sig=3a61c61 body=40d7129 -->
public async Task<IEnumerable<T>> GetAll()
{
try
@@ -744,12 +714,10 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Retrieves all master list entities without options, returning only metadata.
/// Retrieves all master list entries from the underlying collection without applying any filter and projects each result into a <see cref="MasterListDto"/>, where the <see cref="MasterListDto.Options"/> property is set to the count of associated options rather than the option list itself.
/// </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=medium kind=extra_exception
/// "The method catches all exceptions, logs them, and returns an empty list; no exception propagates to the caller, so the <exception> tag is misleading" -->
/// <returns>A <see cref="Task"/> that resolves to an <see cref="IEnumerable{T}"/> containing the projected <see cref="MasterListDto"/> instances, or an empty collection if an error is encountered while querying the data store.</returns>
/// <!-- aidoc:v1 sig=e493435 body=1c299ba -->
public async Task<IEnumerable<MasterListDto>> GetAllWithoutOptions()
{
try
@@ -774,12 +742,13 @@ 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 underlying <see cref="Collection"/> by invoking
/// <c>CountDocumentsAsync</c> with a filter that matches every document. If the operation fails,
/// the exception is logged via <c>Log.Error</c> 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=medium kind=wrong_exception
/// "The method catches all exceptions internally and never throws to the caller, so documenting <exception cref=\"Exception\"> is misleading. The catch block logs and returns 0 instead of propagating the exception." -->
/// <returns>A <see cref="Task{Int32}"/> that represents the asynchronous count operation. The result
/// is the total number of entities, or <c>0</c> if an error occurred while querying the collection.</returns>
/// <!-- aidoc:v1 sig=f1f0a98 body=01cd3d1 -->
public async Task<int> Count()
{
try
@@ -795,17 +764,12 @@ 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 optional <paramref name="filters"/> to restrict the results by option type, text, name, or description, and resolving the localized <c>name</c> and <c>description</c> fields for each option based on the requested locale. When <paramref name="filters"/> is <c>null</c>, no options are returned. Text searches are performed case-insensitively against both the name and description of each option using a normalized pattern, and the final result is ordered alphabetically by name. Any exception during execution is logged and an empty list is returned.
/// </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=high kind=extra_exception
/// "The method catches all exceptions internally and never propagates one to the caller, so documenting <exception cref=\"Exception\"> is misleading; the method always returns a list (possibly empty)." -->
/// <!-- aidoc-review:v1 severity=high kind=missing_param
/// "The filters parameter also contains a 'Locale' property used to drive translation selection, which is not mentioned in the <param> description." -->
/// <param name="id">The <see cref="ObjectId"/> of the master list whose options will be queried.</param>
/// <param name="filters">Optional <see cref="FilterOptionListElement"/> containing the search criteria (option type, text, name, description, and locale). When <c>null</c>, the method returns an empty list.</param>
/// <returns>A <see cref="Task{List{OptionList}}"/> containing the filtered, localized, and alphabetically ordered options; an empty list is returned when no filters are provided, no options match, or an error occurs.</returns>
/// <!-- aidoc:v1 sig=f6ee5be body=17d6a96 -->
public async Task<List<OptionList>> GetMasterListByIdAndSearchOptions(ObjectId id, FilterOptionListElement? filters)
{
try
@@ -1014,15 +978,13 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Updates a specific option within a master list with locale-aware field updates.
/// Updates an option within a master list, handling duplicate detection, locale-specific translations, and conditional field updates based on the master list's required field rules.
/// </summary>
/// <param name="id">The ObjectId of the master list.</param>
/// <param name="newOpt">The OptionList with updated values.</param>
/// <param name="locale">The locale for translation updates.</param>
/// <returns>The updated OptionList 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 method catches all exceptions internally and never throws to the caller, so the <exception> tag is misleading; the catch block logs and returns null, but no exception propagates." -->
/// <param name="id">The <see cref="MongoDB.Bson.ObjectId"/> of the master list that contains the option to update.</param>
/// <param name="newOpt">The <see cref="OptionList"/> containing the new values to apply to the existing option.</param>
/// <param name="locale">The <see cref="LocaleEnum"/> indicating which locale the <paramref name="newOpt"/> applies to; when it matches the master's default locale, the main field is updated, otherwise the translation stored in <c>localeItems</c> is updated.</param>
/// <returns>A <see cref="Task{T}"/> containing the updated <see cref="OptionList"/>, the existing option when a duplicate is detected, or <c>null</c> when the option is not found, no fields qualify for update, or the update operation fails.</returns>
/// <!-- aidoc:v1 sig=e771f23 body=5520a4a -->
public async Task<OptionList?> UpdateMasterListOption(ObjectId id, OptionList newOpt, LocaleEnum locale)
{
// 1. Evitar duplicados
@@ -1117,14 +1079,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Updates a specific option within a master list with full replacement.
/// Updates an existing option inside the master list identified by <paramref name="id"/> with the data from <paramref name="newOpt"/>. Returns <see langword="null"/> when the master list is not found, when no document is modified, or when an exception is caught and logged.
/// </summary>
/// <param name="id">The ObjectId of the master list.</param>
/// <param name="newOpt">The OptionList with updated values.</param>
/// <returns>The updated OptionList if successful; otherwise, null.</returns>
/// <exception cref="Exception">Logs errors and returns null on failure.</exception>
/// <!-- aidoc-review:v1 severity=high kind=wrong_exception
/// "The <exception cref=\"Exception\"> tag implies the method throws Exception to the caller, but the code catches all exceptions internally and returns null instead of throwing." -->
/// <param name="id">The <see cref="ObjectId"/> of the master list that owns the option to update.</param>
/// <param name="newOpt">The <see cref="OptionList"/> whose <see cref="ObjectId"/> targets the option to replace and whose values are persisted to the document.</param>
/// <returns>A task containing the updated <see cref="OptionList"/> when the update succeeds, or <see langword="null"/> when the master list is missing, nothing was modified, or the update failed.</returns>
/// <!-- aidoc:v1 sig=6def54c body=9554543 -->
public async Task<OptionList?> UpdateMasterListOption(ObjectId id, OptionList newOpt)
{
var master = await FindById(id);
@@ -1179,14 +1139,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Updates the metadata details for a master list.
/// Updates the option details of a master list document identified by <paramref name="id"/>, persisting only the non-null fields supplied in <paramref name="opt"/>.
/// </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=high kind=wrong_exception
/// "The <exception cref=\"Exception\"> tag is incorrect: the method catches all exceptions in a try/catch and returns null, rather than throwing Exception. The detail text 'Logs errors and returns null on failure' describes the catch block, not a thrown exception." -->
/// <param name="id">The <see cref="ObjectId"/> of the master list entry to update.</param>
/// <param name="opt">The <see cref="UpdateMasterListDetailsDto"/> whose non-null <see cref="UpdateMasterListDetailsDto.CanAddElement"/> and <see cref="UpdateMasterListDetailsDto.OptionListDetails"/> values are written to the document.</param>
/// <returns>The supplied <see cref="UpdateMasterListDetailsDto"/> when at least one field is modified, or <see langword="null"/> when the document is not found, no changes are applied, or the operation fails.</returns>
/// <!-- aidoc:v1 sig=53d4179 body=49f50ca -->
public async Task<UpdateMasterListDetailsDto?> UpdateOptionDetailsToMasterList(ObjectId id,
UpdateMasterListDetailsDto opt)
{
@@ -1216,14 +1174,13 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Updates the name of a master list.
/// Updates the name of the master list document identified by <paramref name="id"/>.
/// Returns <c>true</c> if a document was modified, <c>false</c> if no document matched the id or if 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=medium kind=wrong_exception
/// "The method catches all exceptions in its try/catch block and returns false; it never propagates an Exception to callers, so the <exception cref=\"Exception\"> tag is misleading." -->
/// <param name="id">The <see cref="MongoDB.Bson.ObjectId"/> of the master list entry to update.</param>
/// <param name="name">The new name to assign to the entry.</param>
/// <returns>A <see cref="Task{Boolean}"/> that resolves to <c>true</c> when the update modified a document; 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(
@@ -1244,14 +1201,13 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Updates the description of a master list.
/// Updates the <see cref="T.Description"/> field of the master list entry identified by <paramref name="id"/>.
/// Returns <c>true</c> when the matched document is modified, and <c>false</c> when no document matches the filter or the underlying update operation throws, in which case the exception is logged and the call resolves to <c>false</c>.
/// </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 <exception cref=\"Exception\"> tag is misused. The method catches all exceptions internally and returns false, so no exception ever propagates to the caller. The tag incorrectly implies the method may throw an exception to its caller." -->
/// <param name="id">The <see cref="ObjectId"/> of the master list entry to update.</param>
/// <param name="description">The new description value to set on the entry.</param>
/// <returns>A <see cref="Task{Boolean}"/> that yields <c>true</c> if the update modified a document; otherwise, <c>false</c>.</returns>
/// <!-- aidoc:v1 sig=5a27a55 body=3552f46 -->
public async Task<bool> UpdateMasterListDescription(ObjectId id, string description)
{
var filter = Builders<T>.Filter.And(
@@ -1307,11 +1263,12 @@ 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.
/// Creates background MongoDB indexes on the <see cref="DiagnosisList"/> collection to optimize queries against the nested <c>options</c> document fields, configuring the indexes with <c>spanish</c> as both the default and override language for text indexing.
/// </summary>
/// <!-- aidoc-review:v1 severity=high kind=wrong_summary
/// "Documentation states the method creates 'text indexes' but the code uses Builders<T>.IndexKeys.Ascending(...), which creates single-field ascending indexes, not text indexes." -->
/// <remarks>
/// When the generic type parameter is not <see cref="DiagnosisList"/>, the method performs no actions and returns without creating any indexes.
/// </remarks>
/// <!-- aidoc:v1 sig=4955da2 body=2c8d1f7 -->
public override async Task CreateIndexes()
{
if (typeof(T) == typeof(DiagnosisList))
@@ -1423,13 +1380,12 @@ public class MasterListRepository<T> : MongoRepository<T>, IMasterListRepository
}
/// <summary>
/// Creates a fluent query for paginated results with combined filters.
/// Creates a find query against the underlying collection by combining the provided <paramref name="filters"/> with a logical AND and applying the specified <paramref name="sort"/>. When the filter list is empty, an empty filter is used so that the query matches every document.
/// </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
/// "Summary claims 'paginated results' but the method does not perform pagination; it only builds a find query with combined filters and a sort, with no Skip or Limit calls." -->
/// <param name="filters">The list of <see cref="FilterDefinition{T}"/> predicates to combine; an empty list causes no filtering to be applied.</param>
/// <param name="sort">The <see cref="SortDefinition{T}"/> used to order the returned documents.</param>
/// <returns>An <see cref="IFindFluent{T,T}"/> configured with the combined filter and sort, ready for further chaining.</returns>
/// <!-- aidoc:v1 sig=704d715 body=2a35652 -->
private IFindFluent<T, T> CreateFindFluent(List<FilterDefinition<T>> filters, SortDefinition<T> sort)
{
var combinedFilter = filters.Any()
@@ -1519,16 +1475,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.
/// Asynchronously retrieves a filtered list of <see cref="OptionList"/> entries from the master collection by matching the document with the specified <paramref name="id"/> and filtering options whose resolved name equals <paramref name="newOptName"/> for the given <paramref name="locale"/>. When the requested locale differs from the document's default, the pipeline uses the translated name from <c>localeItems</c>, falling back to the original name if no translation is available. Returns an empty list if no matching options are found or if an exception is logged during execution.
/// </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=medium kind=extra_exception
/// "The method wraps all logic in a try/catch that catches Exception and returns an empty list; no exception is propagated out of the method, so the <exception cref=\"Exception\"> tag is incorrect." -->
/// <param name="id">The <see cref="ObjectId"/> identifying the master document to aggregate.</param>
/// <param name="newOptName">The option name used to filter the options after locale-based name resolution.</param>
/// <param name="locale">The <see cref="LocaleEnum"/> value used to select the translated name for each option.</param>
/// <returns>A <see cref="Task"/> containing a <see cref="List{T}"/> of <see cref="OptionList"/> entries ordered by name, or an empty list when no match exists or an error is caught.</returns>
/// <!-- aidoc:v1 sig=342dc63 body=21f31fc -->
private async Task<List<OptionList>> GetMasterListByIdAndTextSearch(
ObjectId id, string newOptName, LocaleEnum locale)
{