using Microsoft.AspNetCore.Builder;

namespace MAX.Framework.Interfaces
{
	/// <summary>
	/// 业务模块：把「服务注册」和「管道装配」两件事都交给模块自己，
	/// 由宿主的两行代码统一驱动（模块不需要出现在 Program.cs 里）：
	/// <list type="number">
	/// <item><c>builder.AddStoreHub()</c> → 自动发现所有模块并执行 <see cref="AddModule"/>（服务注册阶段，<c>Build()</c> 之前）；</item>
	/// <item><c>app.UseStoreHubModules()</c> → 自动执行 <see cref="UseModule"/>（管道阶段，<c>Build()</c> 之后、<c>Run()</c> 之前）。</item>
	/// </list>
	/// 模块实例由反射创建，因此实现类必须有无参构造函数。
	/// </summary>
	public interface IModule
	{
		/// <summary>
		/// 模块执行顺序（数值越大越先执行），默认 <see cref="MAX.Core.Interfaces.IntPriority.Normal"/>。
		/// 两个阶段都按这个顺序执行。
		/// </summary>
		int Priority => MAX.Core.Interfaces.IntPriority.Normal;

		/// <summary>
		/// 模块自己的配置文件（相对宿主输出目录 <see cref="AppContext.BaseDirectory"/>），
		/// 例如 "appsettings.CloudProduct.json"；默认 null 表示该模块没有独立配置文件。
		/// 该文件由 <c>builder.AddStoreHub()</c> 自动并入宿主配置树（插在 appsettings*.json 之后、环境变量/命令行之前），
		/// 因此模块内的服务照常注入 <c>IConfiguration</c> 就能读到自己的配置节，模块之间互不干扰。
		/// 注意：只有 <c>builder.AddStoreHub()</c> 入口能加载模块配置文件，
		/// 直接用 <c>builder.Services.AddStoreHub()</c> 时拿不到 IConfigurationBuilder，模块配置不会生效。
		/// </summary>
		string? ConfigurationFile => null;

		/// <summary>
		/// 服务注册阶段（<c>builder.Build()</c> 之前）：注册本模块的服务、选项、后台任务类型。
		/// 需要读配置时用 <see cref="ModuleContext.Configuration"/>，不要再去碰 <c>builder</c>。
		/// </summary>
		void AddModule(ModuleContext context);

		/// <summary>
		/// 管道装配阶段（<c>builder.Build()</c> 之后、<c>app.Run()</c> 之前）：
		/// 注册中间件（如 Hangfire 看板）、Map 端点、读取 <see cref="WebApplication.Services"/> 解析服务、注册启动任务等。
		/// 不需要管道装配的模块可以不实现（默认空实现）。
		/// </summary>
		void UseModule(WebApplication app)
		{
		}
	}
}