ScadaBridge/src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Repositories/ITemplateEngineRepository.cs

using ZB.MOM.WW.ScadaBridge.Commons.Entities.Instances;
using ZB.MOM.WW.ScadaBridge.Commons.Entities.Scripts;
using ZB.MOM.WW.ScadaBridge.Commons.Entities.Templates;

namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;

public interface ITemplateEngineRepository
{
    // Template
    /// <summary>Retrieves a template by ID.</summary>
    /// <param name="id">The template ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<Template?> GetTemplateByIdAsync(int id, CancellationToken cancellationToken = default);
    /// <summary>Retrieves a template with its child entities by ID.</summary>
    /// <param name="id">The template ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<Template?> GetTemplateWithChildrenAsync(int id, CancellationToken cancellationToken = default);
    /// <summary>
    /// Bulk variant of <see cref="GetTemplateWithChildrenAsync(int, CancellationToken)"/>
    /// that fetches every template whose <see cref="Template.Name"/> matches one of
    /// <paramref name="names"/> in a single SQL/EF query, eager-loading
    /// Attributes / Alarms / Scripts / Compositions. Resolves the Transport-008
    /// N+1 in <c>BundleImporter.PreviewAsync</c> — names that don't match an
    /// existing template are omitted from the result rather than producing a
    /// null entry, so callers should look up by name into the returned list.
    /// </summary>
    /// <param name="names">Template names to load. Duplicate / null / empty names are filtered out.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<IReadOnlyList<Template>> GetTemplatesWithChildrenAsync(IEnumerable<string> names, CancellationToken cancellationToken = default);
    /// <summary>Retrieves all templates.</summary>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<IReadOnlyList<Template>> GetAllTemplatesAsync(CancellationToken cancellationToken = default);
    /// <summary>
    /// Returns every template that contains a composition referencing
    /// <paramref name="composedTemplateId"/>. Each result is eager-loaded with
    /// its Attributes / Scripts / Compositions so the caller can build a
    /// CompositionContext without a follow-up round-trip per parent.
    /// </summary>
    /// <param name="composedTemplateId">The composed template ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<IReadOnlyList<Template>> GetTemplatesComposingAsync(int composedTemplateId, CancellationToken cancellationToken = default);
    /// <summary>Adds a new template.</summary>
    /// <param name="template">The template to add.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task AddTemplateAsync(Template template, CancellationToken cancellationToken = default);
    /// <summary>Updates an existing template.</summary>
    /// <param name="template">The template to update.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task UpdateTemplateAsync(Template template, CancellationToken cancellationToken = default);
    /// <summary>Deletes a template by ID.</summary>
    /// <param name="id">The template ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task DeleteTemplateAsync(int id, CancellationToken cancellationToken = default);

    // TemplateAttribute
    /// <summary>Retrieves a template attribute by ID.</summary>
    /// <param name="id">The attribute ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<TemplateAttribute?> GetTemplateAttributeByIdAsync(int id, CancellationToken cancellationToken = default);
    /// <summary>Retrieves attributes for a template.</summary>
    /// <param name="templateId">The template ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<IReadOnlyList<TemplateAttribute>> GetAttributesByTemplateIdAsync(int templateId, CancellationToken cancellationToken = default);
    /// <summary>Adds a new template attribute.</summary>
    /// <param name="attribute">The attribute to add.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task AddTemplateAttributeAsync(TemplateAttribute attribute, CancellationToken cancellationToken = default);
    /// <summary>Updates an existing template attribute.</summary>
    /// <param name="attribute">The attribute to update.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task UpdateTemplateAttributeAsync(TemplateAttribute attribute, CancellationToken cancellationToken = default);
    /// <summary>Deletes a template attribute by ID.</summary>
    /// <param name="id">The attribute ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task DeleteTemplateAttributeAsync(int id, CancellationToken cancellationToken = default);

    // TemplateAlarm
    /// <summary>Retrieves a template alarm by ID.</summary>
    /// <param name="id">The alarm ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<TemplateAlarm?> GetTemplateAlarmByIdAsync(int id, CancellationToken cancellationToken = default);
    /// <summary>Retrieves alarms for a template.</summary>
    /// <param name="templateId">The template ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<IReadOnlyList<TemplateAlarm>> GetAlarmsByTemplateIdAsync(int templateId, CancellationToken cancellationToken = default);
    /// <summary>Adds a new template alarm.</summary>
    /// <param name="alarm">The alarm to add.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task AddTemplateAlarmAsync(TemplateAlarm alarm, CancellationToken cancellationToken = default);
    /// <summary>Updates an existing template alarm.</summary>
    /// <param name="alarm">The alarm to update.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task UpdateTemplateAlarmAsync(TemplateAlarm alarm, CancellationToken cancellationToken = default);
    /// <summary>Deletes a template alarm by ID.</summary>
    /// <param name="id">The alarm ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task DeleteTemplateAlarmAsync(int id, CancellationToken cancellationToken = default);

    // TemplateNativeAlarmSource
    /// <summary>Retrieves a template native alarm source by ID.</summary>
    Task<TemplateNativeAlarmSource?> GetTemplateNativeAlarmSourceByIdAsync(int id, CancellationToken cancellationToken = default);
    /// <summary>Retrieves native alarm sources for a template.</summary>
    Task<IReadOnlyList<TemplateNativeAlarmSource>> GetNativeAlarmSourcesByTemplateIdAsync(int templateId, CancellationToken cancellationToken = default);
    /// <summary>Adds a new template native alarm source.</summary>
    Task AddTemplateNativeAlarmSourceAsync(TemplateNativeAlarmSource source, CancellationToken cancellationToken = default);
    /// <summary>Updates an existing template native alarm source.</summary>
    Task UpdateTemplateNativeAlarmSourceAsync(TemplateNativeAlarmSource source, CancellationToken cancellationToken = default);
    /// <summary>Deletes a template native alarm source by ID.</summary>
    Task DeleteTemplateNativeAlarmSourceAsync(int id, CancellationToken cancellationToken = default);

    // TemplateScript
    /// <summary>Retrieves a template script by ID.</summary>
    /// <param name="id">The script ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<TemplateScript?> GetTemplateScriptByIdAsync(int id, CancellationToken cancellationToken = default);
    /// <summary>Retrieves scripts for a template.</summary>
    /// <param name="templateId">The template ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<IReadOnlyList<TemplateScript>> GetScriptsByTemplateIdAsync(int templateId, CancellationToken cancellationToken = default);
    /// <summary>Adds a new template script.</summary>
    /// <param name="script">The script to add.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task AddTemplateScriptAsync(TemplateScript script, CancellationToken cancellationToken = default);
    /// <summary>Updates an existing template script.</summary>
    /// <param name="script">The script to update.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task UpdateTemplateScriptAsync(TemplateScript script, CancellationToken cancellationToken = default);
    /// <summary>Deletes a template script by ID.</summary>
    /// <param name="id">The script ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task DeleteTemplateScriptAsync(int id, CancellationToken cancellationToken = default);

    // TemplateComposition
    /// <summary>Retrieves a template composition by ID.</summary>
    /// <param name="id">The composition ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<TemplateComposition?> GetTemplateCompositionByIdAsync(int id, CancellationToken cancellationToken = default);
    /// <summary>Retrieves compositions for a template.</summary>
    /// <param name="templateId">The template ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<IReadOnlyList<TemplateComposition>> GetCompositionsByTemplateIdAsync(int templateId, CancellationToken cancellationToken = default);
    /// <summary>Adds a new template composition.</summary>
    /// <param name="composition">The composition to add.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task AddTemplateCompositionAsync(TemplateComposition composition, CancellationToken cancellationToken = default);
    /// <summary>Updates an existing template composition.</summary>
    /// <param name="composition">The composition to update.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task UpdateTemplateCompositionAsync(TemplateComposition composition, CancellationToken cancellationToken = default);
    /// <summary>Deletes a template composition by ID.</summary>
    /// <param name="id">The composition ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task DeleteTemplateCompositionAsync(int id, CancellationToken cancellationToken = default);

    // Instance
    /// <summary>Retrieves an instance by ID.</summary>
    /// <param name="id">The instance ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<Instance?> GetInstanceByIdAsync(int id, CancellationToken cancellationToken = default);
    /// <summary>Retrieves all instances.</summary>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<IReadOnlyList<Instance>> GetAllInstancesAsync(CancellationToken cancellationToken = default);
    /// <summary>Retrieves instances for a template.</summary>
    /// <param name="templateId">The template ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<IReadOnlyList<Instance>> GetInstancesByTemplateIdAsync(int templateId, CancellationToken cancellationToken = default);
    /// <summary>Retrieves instances for a site.</summary>
    /// <param name="siteId">The site ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<IReadOnlyList<Instance>> GetInstancesBySiteIdAsync(int siteId, CancellationToken cancellationToken = default);
    /// <summary>Retrieves an instance by unique name.</summary>
    /// <param name="uniqueName">The unique instance name.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<Instance?> GetInstanceByUniqueNameAsync(string uniqueName, CancellationToken cancellationToken = default);
    /// <summary>Adds a new instance.</summary>
    /// <param name="instance">The instance to add.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task AddInstanceAsync(Instance instance, CancellationToken cancellationToken = default);
    /// <summary>Updates an existing instance.</summary>
    /// <param name="instance">The instance to update.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task UpdateInstanceAsync(Instance instance, CancellationToken cancellationToken = default);
    /// <summary>Deletes an instance by ID.</summary>
    /// <param name="id">The instance ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task DeleteInstanceAsync(int id, CancellationToken cancellationToken = default);

    // InstanceAttributeOverride
    /// <summary>Retrieves attribute overrides for an instance.</summary>
    /// <param name="instanceId">The instance ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<IReadOnlyList<InstanceAttributeOverride>> GetOverridesByInstanceIdAsync(int instanceId, CancellationToken cancellationToken = default);
    /// <summary>Adds a new instance attribute override.</summary>
    /// <param name="attributeOverride">The override to add.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task AddInstanceAttributeOverrideAsync(InstanceAttributeOverride attributeOverride, CancellationToken cancellationToken = default);
    /// <summary>Updates an existing instance attribute override.</summary>
    /// <param name="attributeOverride">The override to update.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task UpdateInstanceAttributeOverrideAsync(InstanceAttributeOverride attributeOverride, CancellationToken cancellationToken = default);
    /// <summary>Deletes an instance attribute override by ID.</summary>
    /// <param name="id">The override ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task DeleteInstanceAttributeOverrideAsync(int id, CancellationToken cancellationToken = default);

    // InstanceAlarmOverride
    /// <summary>Retrieves alarm overrides for an instance.</summary>
    /// <param name="instanceId">The instance ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<IReadOnlyList<InstanceAlarmOverride>> GetAlarmOverridesByInstanceIdAsync(int instanceId, CancellationToken cancellationToken = default);
    /// <summary>Retrieves an alarm override by instance and alarm name.</summary>
    /// <param name="instanceId">The instance ID.</param>
    /// <param name="alarmCanonicalName">The alarm canonical name.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<InstanceAlarmOverride?> GetAlarmOverrideAsync(int instanceId, string alarmCanonicalName, CancellationToken cancellationToken = default);
    /// <summary>Adds a new instance alarm override.</summary>
    /// <param name="alarmOverride">The override to add.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task AddInstanceAlarmOverrideAsync(InstanceAlarmOverride alarmOverride, CancellationToken cancellationToken = default);
    /// <summary>Updates an existing instance alarm override.</summary>
    /// <param name="alarmOverride">The override to update.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task UpdateInstanceAlarmOverrideAsync(InstanceAlarmOverride alarmOverride, CancellationToken cancellationToken = default);
    /// <summary>Deletes an instance alarm override by ID.</summary>
    /// <param name="id">The override ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task DeleteInstanceAlarmOverrideAsync(int id, CancellationToken cancellationToken = default);

    // InstanceNativeAlarmSourceOverride
    /// <summary>Retrieves native alarm source overrides for an instance.</summary>
    Task<IReadOnlyList<InstanceNativeAlarmSourceOverride>> GetNativeAlarmSourceOverridesByInstanceIdAsync(int instanceId, CancellationToken cancellationToken = default);
    /// <summary>Retrieves a single native alarm source override by instance + source canonical name.</summary>
    Task<InstanceNativeAlarmSourceOverride?> GetNativeAlarmSourceOverrideAsync(int instanceId, string sourceCanonicalName, CancellationToken cancellationToken = default);
    /// <summary>Adds a new instance native alarm source override.</summary>
    Task AddInstanceNativeAlarmSourceOverrideAsync(InstanceNativeAlarmSourceOverride ovr, CancellationToken cancellationToken = default);
    /// <summary>Updates an existing instance native alarm source override.</summary>
    Task UpdateInstanceNativeAlarmSourceOverrideAsync(InstanceNativeAlarmSourceOverride ovr, CancellationToken cancellationToken = default);
    /// <summary>Deletes an instance native alarm source override by ID.</summary>
    Task DeleteInstanceNativeAlarmSourceOverrideAsync(int id, CancellationToken cancellationToken = default);

    // InstanceConnectionBinding
    /// <summary>Retrieves connection bindings for an instance.</summary>
    /// <param name="instanceId">The instance ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<IReadOnlyList<InstanceConnectionBinding>> GetBindingsByInstanceIdAsync(int instanceId, CancellationToken cancellationToken = default);
    /// <summary>Adds a new instance connection binding.</summary>
    /// <param name="binding">The binding to add.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task AddInstanceConnectionBindingAsync(InstanceConnectionBinding binding, CancellationToken cancellationToken = default);
    /// <summary>Updates an existing instance connection binding.</summary>
    /// <param name="binding">The binding to update.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task UpdateInstanceConnectionBindingAsync(InstanceConnectionBinding binding, CancellationToken cancellationToken = default);
    /// <summary>Deletes an instance connection binding by ID.</summary>
    /// <param name="id">The binding ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task DeleteInstanceConnectionBindingAsync(int id, CancellationToken cancellationToken = default);

    // Area
    /// <summary>Retrieves an area by ID.</summary>
    /// <param name="id">The area ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<Area?> GetAreaByIdAsync(int id, CancellationToken cancellationToken = default);
    /// <summary>Retrieves areas for a site.</summary>
    /// <param name="siteId">The site ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<IReadOnlyList<Area>> GetAreasBySiteIdAsync(int siteId, CancellationToken cancellationToken = default);
    /// <summary>Adds a new area.</summary>
    /// <param name="area">The area to add.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task AddAreaAsync(Area area, CancellationToken cancellationToken = default);
    /// <summary>Updates an existing area.</summary>
    /// <param name="area">The area to update.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task UpdateAreaAsync(Area area, CancellationToken cancellationToken = default);
    /// <summary>Deletes an area by ID.</summary>
    /// <param name="id">The area ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task DeleteAreaAsync(int id, CancellationToken cancellationToken = default);

    // SharedScript
    /// <summary>Retrieves a shared script by ID.</summary>
    /// <param name="id">The script ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<SharedScript?> GetSharedScriptByIdAsync(int id, CancellationToken cancellationToken = default);
    /// <summary>Retrieves a shared script by name.</summary>
    /// <param name="name">The script name.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<SharedScript?> GetSharedScriptByNameAsync(string name, CancellationToken cancellationToken = default);
    /// <summary>Retrieves all shared scripts.</summary>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<IReadOnlyList<SharedScript>> GetAllSharedScriptsAsync(CancellationToken cancellationToken = default);
    /// <summary>Adds a new shared script.</summary>
    /// <param name="sharedScript">The script to add.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task AddSharedScriptAsync(SharedScript sharedScript, CancellationToken cancellationToken = default);
    /// <summary>Updates an existing shared script.</summary>
    /// <param name="sharedScript">The script to update.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task UpdateSharedScriptAsync(SharedScript sharedScript, CancellationToken cancellationToken = default);
    /// <summary>Deletes a shared script by ID.</summary>
    /// <param name="id">The script ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task DeleteSharedScriptAsync(int id, CancellationToken cancellationToken = default);

    // TemplateFolder
    /// <summary>Retrieves a template folder by ID.</summary>
    /// <param name="id">The folder ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<TemplateFolder?> GetFolderByIdAsync(int id, CancellationToken cancellationToken = default);
    /// <summary>Retrieves all template folders.</summary>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<IReadOnlyList<TemplateFolder>> GetAllFoldersAsync(CancellationToken cancellationToken = default);
    /// <summary>Adds a new template folder.</summary>
    /// <param name="folder">The folder to add.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task AddFolderAsync(TemplateFolder folder, CancellationToken cancellationToken = default);
    /// <summary>Updates an existing template folder.</summary>
    /// <param name="folder">The folder to update.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task UpdateFolderAsync(TemplateFolder folder, CancellationToken cancellationToken = default);
    /// <summary>Deletes a template folder by ID.</summary>
    /// <param name="id">The folder ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task DeleteFolderAsync(int id, CancellationToken cancellationToken = default);

    /// <summary>Saves pending changes to the database.</summary>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<int> SaveChangesAsync(CancellationToken cancellationToken = default);
}