sam-api/app/Swagger/v1/TriggerAuditLogApi.php

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *   name="Trigger Audit",
 *   description="DB 트리거 기반 데이터 변경 추적 로그"
 * )
 *
 * @OA\Schema(
 *   schema="TriggerAuditLog",
 *   type="object",
 *
 *   @OA\Property(property="id", type="integer", example=1),
 *   @OA\Property(property="table_name", type="string", example="products"),
 *   @OA\Property(property="row_id", type="string", example="42"),
 *   @OA\Property(property="dml_type", type="string", enum={"INSERT","UPDATE","DELETE"}),
 *   @OA\Property(property="old_values", type="object", nullable=true),
 *   @OA\Property(property="new_values", type="object", nullable=true),
 *   @OA\Property(property="changed_columns", type="array", nullable=true, @OA\Items(type="string")),
 *   @OA\Property(property="tenant_id", type="integer", nullable=true),
 *   @OA\Property(property="actor_id", type="integer", nullable=true),
 *   @OA\Property(property="session_info", type="object", nullable=true,
 *     @OA\Property(property="ip", type="string"),
 *     @OA\Property(property="ua", type="string"),
 *     @OA\Property(property="route", type="string")
 *   ),
 *   @OA\Property(property="db_user", type="string", nullable=true, example="samuser@%"),
 *   @OA\Property(property="created_at", type="string", format="date-time")
 * )
 */
class TriggerAuditLogApi
{
    /**
     * @OA\Get(
     *   path="/api/v1/trigger-audit-logs",
     *   tags={"Trigger Audit"},
     *   summary="감사 로그 목록 조회",
     *   description="DB 트리거 기반 변경 로그를 페이지네이션으로 조회합니다.",
     *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *   @OA\Parameter(name="page", in="query", @OA\Schema(type="integer", minimum=1)),
     *   @OA\Parameter(name="size", in="query", @OA\Schema(type="integer", minimum=1, maximum=200)),
     *   @OA\Parameter(name="table_name", in="query", description="테이블명 필터", @OA\Schema(type="string")),
     *   @OA\Parameter(name="row_id", in="query", description="레코드 PK 필터", @OA\Schema(type="string")),
     *   @OA\Parameter(name="dml_type", in="query", description="DML 유형 필터", @OA\Schema(type="string", enum={"INSERT","UPDATE","DELETE"})),
     *   @OA\Parameter(name="tenant_id", in="query", @OA\Schema(type="integer")),
     *   @OA\Parameter(name="actor_id", in="query", @OA\Schema(type="integer")),
     *   @OA\Parameter(name="db_user", in="query", @OA\Schema(type="string")),
     *   @OA\Parameter(name="from", in="query", description="시작일", @OA\Schema(type="string", format="date")),
     *   @OA\Parameter(name="to", in="query", description="종료일", @OA\Schema(type="string", format="date")),
     *   @OA\Parameter(name="sort", in="query", @OA\Schema(type="string", enum={"created_at","id"})),
     *   @OA\Parameter(name="order", in="query", @OA\Schema(type="string", enum={"asc","desc"})),
     *
     *   @OA\Response(
     *     response=200,
     *     description="목록 조회 성공",
     *
     *     @OA\JsonContent(type="object",
     *
     *       @OA\Property(property="success", type="boolean"),
     *       @OA\Property(property="message", type="string"),
     *       @OA\Property(property="data", type="object",
     *         @OA\Property(property="current_page", type="integer"),
     *         @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/TriggerAuditLog")),
     *         @OA\Property(property="last_page", type="integer"),
     *         @OA\Property(property="per_page", type="integer"),
     *         @OA\Property(property="total", type="integer")
     *       )
     *     )
     *   )
     * )
     */
    public function index() {}

    /**
     * @OA\Get(
     *   path="/api/v1/trigger-audit-logs/stats",
     *   tags={"Trigger Audit"},
     *   summary="감사 로그 통계",
     *   description="전체/오늘/DML별 건수, 상위 테이블, 저장소 크기 통계를 반환합니다.",
     *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *   @OA\Parameter(name="tenant_id", in="query", @OA\Schema(type="integer")),
     *
     *   @OA\Response(
     *     response=200,
     *     description="통계 조회 성공",
     *
     *     @OA\JsonContent(type="object",
     *
     *       @OA\Property(property="success", type="boolean"),
     *       @OA\Property(property="message", type="string"),
     *       @OA\Property(property="data", type="object",
     *         @OA\Property(property="total", type="integer"),
     *         @OA\Property(property="today", type="integer"),
     *         @OA\Property(property="by_dml_type", type="object",
     *           @OA\Property(property="INSERT", type="integer"),
     *           @OA\Property(property="UPDATE", type="integer"),
     *           @OA\Property(property="DELETE", type="integer")
     *         ),
     *         @OA\Property(property="top_tables", type="object"),
     *         @OA\Property(property="storage_mb", type="number")
     *       )
     *     )
     *   )
     * )
     */
    public function stats() {}

    /**
     * @OA\Get(
     *   path="/api/v1/trigger-audit-logs/{id}",
     *   tags={"Trigger Audit"},
     *   summary="감사 로그 상세 조회",
     *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
     *
     *   @OA\Response(
     *     response=200,
     *     description="상세 조회 성공",
     *
     *     @OA\JsonContent(type="object",
     *
     *       @OA\Property(property="success", type="boolean"),
     *       @OA\Property(property="message", type="string"),
     *       @OA\Property(property="data", ref="#/components/schemas/TriggerAuditLog")
     *     )
     *   ),
     *
     *   @OA\Response(response=404, description="Not Found")
     * )
     */
    public function show() {}

    /**
     * @OA\Get(
     *   path="/api/v1/trigger-audit-logs/{tableName}/{rowId}/history",
     *   tags={"Trigger Audit"},
     *   summary="레코드 변경 이력 조회",
     *   description="특정 테이블의 특정 레코드에 대한 전체 변경 이력을 조회합니다.",
     *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *   @OA\Parameter(name="tableName", in="path", required=true, description="테이블명", @OA\Schema(type="string")),
     *   @OA\Parameter(name="rowId", in="path", required=true, description="레코드 PK", @OA\Schema(type="string")),
     *
     *   @OA\Response(
     *     response=200,
     *     description="이력 조회 성공",
     *
     *     @OA\JsonContent(type="object",
     *
     *       @OA\Property(property="success", type="boolean"),
     *       @OA\Property(property="message", type="string"),
     *       @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/TriggerAuditLog"))
     *     )
     *   )
     * )
     */
    public function recordHistory() {}

    /**
     * @OA\Get(
     *   path="/api/v1/trigger-audit-logs/{id}/rollback-preview",
     *   tags={"Trigger Audit"},
     *   summary="롤백 SQL 미리보기",
     *   description="해당 변경을 되돌리기 위한 SQL문을 미리 확인합니다.",
     *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
     *
     *   @OA\Response(
     *     response=200,
     *     description="롤백 SQL 반환",
     *
     *     @OA\JsonContent(type="object",
     *
     *       @OA\Property(property="success", type="boolean"),
     *       @OA\Property(property="message", type="string"),
     *       @OA\Property(property="data", type="object",
     *         @OA\Property(property="audit_id", type="integer"),
     *         @OA\Property(property="rollback_sql", type="string")
     *       )
     *     )
     *   ),
     *
     *   @OA\Response(response=404, description="Not Found")
     * )
     */
    public function rollbackPreview() {}

    /**
     * @OA\Post(
     *   path="/api/v1/trigger-audit-logs/{id}/rollback",
     *   tags={"Trigger Audit"},
     *   summary="롤백 실행",
     *   description="해당 변경을 실제로 되돌립니다. confirm=true 필수.",
     *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
     *
     *   @OA\RequestBody(
     *     required=true,
     *
     *     @OA\JsonContent(
     *       required={"confirm"},
     *
     *       @OA\Property(property="confirm", type="boolean", example=true, description="롤백 확인 (true 필수)")
     *     )
     *   ),
     *
     *   @OA\Response(
     *     response=200,
     *     description="롤백 성공",
     *
     *     @OA\JsonContent(type="object",
     *
     *       @OA\Property(property="success", type="boolean"),
     *       @OA\Property(property="message", type="string"),
     *       @OA\Property(property="data", type="object",
     *         @OA\Property(property="rolled_back", type="boolean"),
     *         @OA\Property(property="sql_executed", type="string")
     *       )
     *     )
     *   ),
     *
     *   @OA\Response(response=404, description="Not Found"),
     *   @OA\Response(response=422, description="Validation Error")
     * )
     */
    public function rollbackExecute() {}
}