defmodule Mv.Authorization.PolicyHelpers do
  @moduledoc """
  Policy helpers for consistent bypass vs HasPermission patterns.

  ## Pattern: READ Bypass + UPDATE HasPermission

  For resources with scope :own/:linked permissions:
  - READ: Use bypass with expr() for auto_filter
  - UPDATE/CREATE/DESTROY: Use HasPermission for scope evaluation

  ## Usage

      use Mv.Authorization.PolicyHelpers

      policies do
        # Standard pattern for User resource
        standard_user_policies()
      end

  ## Why This Pattern?

  See `docs/policy-bypass-vs-haspermission.md` for detailed explanation.
  """

  defmacro standard_user_policies do
    quote do
      # READ: Bypass for auto_filter
      bypass action_type(:read) do
        description "Users can read their own records"
        authorize_if expr(id == ^actor(:id))
      end

      # UPDATE/CREATE/DESTROY: HasPermission
      policy action_type([:update, :create, :destroy]) do
        description "Check permissions from role"
        authorize_if Mv.Authorization.Checks.HasPermission
      end
    end
  end
end