<?php

declare(strict_types=1);

namespace App\Http\Controllers;

/**
 * Centralised OpenAPI annotations for the core 30 endpoints.
 *
 * The annotations live in a separate, never-instantiated class so they
 * are picked up by `l5-swagger:generate` without polluting per-action
 * controllers.  Each block reflects the same path that is wired in
 * routes/api.php.
 *
 * NOTE: Auth controllers (LoginController, RegisterController, OAuthController),
 * the catalog endpoint (BlocksController), the install status probe
 * (InstallStatusController) and the privacy endpoints (PrivacyController) hold
 * their own annotations; this file covers only the remaining surface.
 *
 * @OA\Tag(name="Community", description="Boards, posts, comments, reactions, reports")
 * @OA\Tag(name="Payment",   description="Payment methods, authorize, refund, webhooks")
 * @OA\Tag(name="Resources", description="Downloadable resources and ratings")
 * @OA\Tag(name="Manuals",   description="Operational manuals and versions")
 * @OA\Tag(name="Marketplace", description="Themes / skins marketplace")
 * @OA\Tag(name="Shop",      description="Products, cart, checkout, orders")
 *
 * ──────────────────────── Community ────────────────────────
 *
 * @OA\Get(
 *   path="/api/v1/community/boards",
 *   tags={"Community"},
 *   summary="List public boards",
 *   @OA\Response(response=200, description="OK")
 * )
 * @OA\Get(
 *   path="/api/v1/community/boards/{slug}",
 *   tags={"Community"},
 *   summary="Show a board with categories",
 *   @OA\Parameter(name="slug", in="path", required=true, @OA\Schema(type="string")),
 *   @OA\Response(response=200, description="OK"),
 *   @OA\Response(response=404, description="Not found")
 * )
 * @OA\Get(
 *   path="/api/v1/community/boards/{slug}/posts",
 *   tags={"Community"},
 *   summary="List posts on a board (paginated)",
 *   @OA\Parameter(name="slug", in="path", required=true, @OA\Schema(type="string")),
 *   @OA\Parameter(name="page", in="query", @OA\Schema(type="integer")),
 *   @OA\Response(response=200, description="OK")
 * )
 * @OA\Post(
 *   path="/api/v1/community/boards/{slug}/posts",
 *   tags={"Community"},
 *   summary="Create a post",
 *   security={{"sanctum":{}}},
 *   @OA\Parameter(name="slug", in="path", required=true, @OA\Schema(type="string")),
 *   @OA\RequestBody(required=true, @OA\JsonContent(
 *     required={"title","content"},
 *     @OA\Property(property="title",   type="string"),
 *     @OA\Property(property="content", type="string"),
 *     @OA\Property(property="category_id", type="string", nullable=true),
 *   )),
 *   @OA\Response(response=201, description="Created")
 * )
 * @OA\Get(
 *   path="/api/v1/community/posts/{id}",
 *   tags={"Community"},
 *   summary="Show a post",
 *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="string")),
 *   @OA\Response(response=200, description="OK")
 * )
 * @OA\Patch(
 *   path="/api/v1/community/posts/{id}",
 *   tags={"Community"},
 *   summary="Edit own post",
 *   security={{"sanctum":{}}},
 *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="string")),
 *   @OA\Response(response=200, description="OK")
 * )
 * @OA\Delete(
 *   path="/api/v1/community/posts/{id}",
 *   tags={"Community"},
 *   summary="Delete own post",
 *   security={{"sanctum":{}}},
 *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="string")),
 *   @OA\Response(response=204, description="Deleted")
 * )
 * @OA\Post(
 *   path="/api/v1/community/posts/{id}/comments",
 *   tags={"Community"},
 *   summary="Comment on a post",
 *   security={{"sanctum":{}}},
 *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="string")),
 *   @OA\RequestBody(required=true, @OA\JsonContent(
 *     required={"body"},
 *     @OA\Property(property="body", type="string"),
 *     @OA\Property(property="parent_id", type="string", nullable=true),
 *   )),
 *   @OA\Response(response=201, description="Created")
 * )
 * @OA\Post(
 *   path="/api/v1/community/posts/{id}/reactions",
 *   tags={"Community"},
 *   summary="Toggle a reaction on a post",
 *   security={{"sanctum":{}}},
 *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="string")),
 *   @OA\RequestBody(@OA\JsonContent(@OA\Property(property="type", type="string", example="like"))),
 *   @OA\Response(response=200, description="Toggled")
 * )
 * @OA\Post(
 *   path="/api/v1/community/posts/{id}/reports",
 *   tags={"Community"},
 *   summary="Report a post",
 *   security={{"sanctum":{}}},
 *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="string")),
 *   @OA\RequestBody(required=true, @OA\JsonContent(
 *     @OA\Property(property="reason", type="string"),
 *   )),
 *   @OA\Response(response=201, description="Created")
 * )
 *
 * ──────────────────────── Payment ────────────────────────
 *
 * @OA\Get(
 *   path="/api/v1/payment-methods",
 *   tags={"Payment"},
 *   summary="List active payment methods",
 *   @OA\Response(response=200, description="OK")
 * )
 * @OA\Post(
 *   path="/api/v1/payments",
 *   tags={"Payment"},
 *   summary="Authorize a new payment",
 *   security={{"sanctum":{}}},
 *   @OA\RequestBody(required=true, @OA\JsonContent(
 *     required={"payment_method_id","order_ref","amount"},
 *     @OA\Property(property="payment_method_id", type="string", format="uuid"),
 *     @OA\Property(property="order_ref",         type="string"),
 *     @OA\Property(property="amount",            type="integer", minimum=100),
 *     @OA\Property(property="currency",          type="string",  example="KRW"),
 *   )),
 *   @OA\Response(response=201, description="Created")
 * )
 * @OA\Get(
 *   path="/api/v1/payments/{id}",
 *   tags={"Payment"},
 *   summary="Get payment status",
 *   security={{"sanctum":{}}},
 *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="string")),
 *   @OA\Response(response=200, description="OK")
 * )
 * @OA\Post(
 *   path="/api/v1/payments/{id}/refund",
 *   tags={"Payment"},
 *   summary="Refund a payment",
 *   security={{"sanctum":{}}},
 *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="string")),
 *   @OA\Response(response=200, description="Refunded")
 * )
 * @OA\Post(
 *   path="/api/v1/webhooks/payment/{provider}",
 *   tags={"Payment"},
 *   summary="Provider webhook (signature verified)",
 *   @OA\Parameter(name="provider", in="path", required=true, @OA\Schema(type="string")),
 *   @OA\Response(response=200, description="Acknowledged")
 * )
 *
 * ──────────────────────── Resources & Manuals ────────────────────────
 *
 * @OA\Get(
 *   path="/api/v1/resources",
 *   tags={"Resources"},
 *   summary="List resources",
 *   @OA\Response(response=200, description="OK")
 * )
 * @OA\Get(
 *   path="/api/v1/resources/{slug}",
 *   tags={"Resources"},
 *   summary="Show a resource",
 *   @OA\Parameter(name="slug", in="path", required=true, @OA\Schema(type="string")),
 *   @OA\Response(response=200, description="OK")
 * )
 * @OA\Post(
 *   path="/api/v1/resources/{id}/download",
 *   tags={"Resources"},
 *   summary="Initiate a resource download (audited)",
 *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="string")),
 *   @OA\Response(response=200, description="Signed URL")
 * )
 * @OA\Post(
 *   path="/api/v1/resources/{id}/rate",
 *   tags={"Resources"},
 *   summary="Rate a resource (1–5)",
 *   security={{"sanctum":{}}},
 *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="string")),
 *   @OA\Response(response=200, description="Saved")
 * )
 * @OA\Get(
 *   path="/api/v1/manuals",
 *   tags={"Manuals"},
 *   summary="List manuals",
 *   @OA\Response(response=200, description="OK")
 * )
 * @OA\Get(
 *   path="/api/v1/manuals/{version}/{slug}",
 *   tags={"Manuals"},
 *   summary="Show a manual page",
 *   @OA\Parameter(name="version", in="path", required=true, @OA\Schema(type="string")),
 *   @OA\Parameter(name="slug",    in="path", required=true, @OA\Schema(type="string")),
 *   @OA\Response(response=200, description="OK")
 * )
 *
 * ──────────────────────── Marketplace ────────────────────────
 *
 * @OA\Get(
 *   path="/api/v1/marketplace/items",
 *   tags={"Marketplace"},
 *   summary="List marketplace items",
 *   @OA\Response(response=200, description="OK")
 * )
 * @OA\Get(
 *   path="/api/v1/marketplace/items/{slug}",
 *   tags={"Marketplace"},
 *   summary="Show a marketplace item",
 *   @OA\Parameter(name="slug", in="path", required=true, @OA\Schema(type="string")),
 *   @OA\Response(response=200, description="OK")
 * )
 * @OA\Post(
 *   path="/api/v1/marketplace/items/{id}/purchase",
 *   tags={"Marketplace"},
 *   summary="Purchase a marketplace item",
 *   security={{"sanctum":{}}},
 *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="string")),
 *   @OA\Response(response=201, description="Purchased")
 * )
 *
 * ──────────────────────── Shop ────────────────────────
 *
 * @OA\Get(
 *   path="/api/v1/shop/products",
 *   tags={"Shop"},
 *   summary="List products",
 *   @OA\Response(response=200, description="OK")
 * )
 * @OA\Get(
 *   path="/api/v1/shop/products/{slug}",
 *   tags={"Shop"},
 *   summary="Show a product",
 *   @OA\Parameter(name="slug", in="path", required=true, @OA\Schema(type="string")),
 *   @OA\Response(response=200, description="OK")
 * )
 * @OA\Get(
 *   path="/api/v1/shop/categories",
 *   tags={"Shop"},
 *   summary="List categories",
 *   @OA\Response(response=200, description="OK")
 * )
 * @OA\Post(
 *   path="/api/v1/shop/checkout",
 *   tags={"Shop"},
 *   summary="Place an order",
 *   @OA\RequestBody(required=true, @OA\JsonContent(
 *     @OA\Property(property="customer", type="object"),
 *     @OA\Property(property="items",    type="array", @OA\Items()),
 *   )),
 *   @OA\Response(response=201, description="Created")
 * )
 * @OA\Get(
 *   path="/api/v1/shop/orders",
 *   tags={"Shop"},
 *   summary="List my orders",
 *   security={{"sanctum":{}}},
 *   @OA\Response(response=200, description="OK")
 * )
 * @OA\Get(
 *   path="/api/v1/shop/orders/{id}",
 *   tags={"Shop"},
 *   summary="Show one of my orders",
 *   security={{"sanctum":{}}},
 *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="string")),
 *   @OA\Response(response=200, description="OK")
 * )
 */
final class OpenApiAnnotations
{
    // Intentionally empty — annotation host only.
}
