using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;

namespace MoShiro.Backend.Api;

public static class EndpointConventions
{
    /// <summary>每个端点都必须有 operationId（snake_case，资源_动作）、summary 和 tag。</summary>
    public static RouteHandlerBuilder Api(this RouteHandlerBuilder builder, string operationId, string summary, string tag) =>
        builder.WithName(operationId).WithSummary(summary).WithTags(tag);

    /// <summary>声明端点需要的能力（授权的唯一依据）；OpenAPI 里带上 <c>x-moshiro-capability</c>。</summary>
    public static RouteHandlerBuilder Requires(this RouteHandlerBuilder builder, string capability) =>
        builder.WithMetadata(new CapabilityRequirement(capability)).AddOpenApiOperationTransformer((operation, _, _) =>
        {
            operation.Extensions ??= new Dictionary<string, Microsoft.OpenApi.IOpenApiExtension>();
            operation.Extensions["x-moshiro-capability"] = new Microsoft.OpenApi.JsonNodeExtension(System.Text.Json.Nodes.JsonValue.Create(capability));
            return Task.CompletedTask;
        });

    /// <summary>匿名可访问的管理端点（登录）：显式声明，对账测试才能区分「忘了声明」。</summary>
    public static RouteHandlerBuilder AllowsAnonymous(this RouteHandlerBuilder builder) =>
        builder.WithMetadata(new CapabilityRequirement(null));

    public static RouteHandlerBuilder Returns<T>(this RouteHandlerBuilder builder, int status = StatusCodes.Status200OK) =>
        builder.Produces<T>(status);

    /// <summary>登记该端点可能返回的错误状态（problem+json），让 OpenAPI 文档完整。</summary>
    public static RouteHandlerBuilder ProducesProblems(this RouteHandlerBuilder builder, params int[] statuses)
    {
        foreach (int status in statuses)
        {
            builder.Produces<ProblemDto>(status, Problems.ContentType);
        }

        return builder;
    }
}