chore: [env] .env.example 업데이트 및 .gitignore 정리

- .env.example을 SAM 프로젝트 실제 키 구조로 업데이트
- .gitignore에 !.env.example 예외 추가
- GCS_* 중복 키 제거, Gemini/Claude/Vertex 키 섹션 추가

app/Swagger/v1/RoleApi.php

@@ -3,7 +3,7 @@
 namespace App\Swagger\v1;
 
 /**
- * @OA\Tag(name="Role", description="역할 관리(목록/조회/등록/수정/삭제/통계/활성)")
+ * @OA\Tag(name="Role", description="역할 관리(목록/조회/등록/수정/삭제)")
  */
 
 /**
@@ -18,9 +18,6 @@
  *   @OA\Property(property="name", type="string", example="menu-manager"),
  *   @OA\Property(property="description", type="string", nullable=true, example="메뉴 관리 역할"),
  *   @OA\Property(property="guard_name", type="string", example="api"),
- *   @OA\Property(property="is_hidden", type="boolean", example=false),
- *   @OA\Property(property="permissions_count", type="integer", example=12),
- *   @OA\Property(property="users_count", type="integer", example=3),
  *   @OA\Property(property="created_at", type="string", format="date-time", example="2025-08-16 10:00:00"),
  *   @OA\Property(property="updated_at", type="string", format="date-time", example="2025-08-16 10:00:00")
  * )
@@ -50,8 +47,7 @@
  *   required={"name"},
  *
  *   @OA\Property(property="name", type="string", example="menu-manager", description="역할명(테넌트+가드 내 고유)"),
- *   @OA\Property(property="description", type="string", nullable=true, example="메뉴 관리 역할"),
- *   @OA\Property(property="is_hidden", type="boolean", example=false, description="숨김 여부")
+ *   @OA\Property(property="description", type="string", nullable=true, example="메뉴 관리 역할")
  * )
  *
  * @OA\Schema(
@@ -59,19 +55,7 @@
  *   type="object",
  *
  *   @OA\Property(property="name", type="string", example="menu-admin"),
- *   @OA\Property(property="description", type="string", nullable=true, example="설명 변경"),
- *   @OA\Property(property="is_hidden", type="boolean", example=false)
- * )
- *
- * @OA\Schema(
- *   schema="RoleStats",
- *   type="object",
- *   description="역할 통계",
- *
- *   @OA\Property(property="total", type="integer", example=5),
- *   @OA\Property(property="visible", type="integer", example=3),
- *   @OA\Property(property="hidden", type="integer", example=2),
- *   @OA\Property(property="with_users", type="integer", example=4)
+ *   @OA\Property(property="description", type="string", nullable=true, example="설명 변경")
  * )
  */
 class RoleApi
@@ -80,14 +64,13 @@ class RoleApi
      * @OA\Get(
      *   path="/api/v1/roles",
      *   summary="역할 목록 조회",
-     *   description="테넌트 범위 내 역할 목록을 페이징으로 반환합니다. (q로 이름/설명 검색, is_hidden으로 필터)",
+     *   description="테넌트 범위 내 역할 목록을 페이징으로 반환합니다. (q로 이름/설명 검색)",
      *   tags={"Role"},
      *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
      *
      *   @OA\Parameter(name="page", in="query", required=false, @OA\Schema(type="integer", example=1)),
      *   @OA\Parameter(name="size", in="query", required=false, @OA\Schema(type="integer", example=10)),
      *   @OA\Parameter(name="q", in="query", required=false, @OA\Schema(type="string", example="read")),
-     *   @OA\Parameter(name="is_hidden", in="query", required=false, description="숨김 상태 필터", @OA\Schema(type="boolean", example=false)),
      *
      *   @OA\Response(response=200, description="목록 조회 성공",
      *
@@ -225,62 +208,4 @@ public function update() {}
      * )
      */
     public function destroy() {}
-
-    /**
-     * @OA\Get(
-     *   path="/api/v1/roles/stats",
-     *   summary="역할 통계 조회",
-     *   description="테넌트 범위 내 역할 통계(전체/공개/숨김/사용자 보유)를 반환합니다.",
-     *   tags={"Role"},
-     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
-     *
-     *   @OA\Response(response=200, description="통계 조회 성공",
-     *
-     *     @OA\JsonContent(
-     *       allOf={
-     *
-     *         @OA\Schema(ref="#/components/schemas/ApiResponse"),
-     *         @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/RoleStats"))
-     *       }
-     *     )
-     *   ),
-     *
-     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
-     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
-     * )
-     */
-    public function stats() {}
-
-    /**
-     * @OA\Get(
-     *   path="/api/v1/roles/active",
-     *   summary="활성 역할 목록 (드롭다운용)",
-     *   description="숨겨지지 않은 활성 역할 목록을 이름순으로 반환합니다. (id, name, description만 포함)",
-     *   tags={"Role"},
-     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
-     *
-     *   @OA\Response(response=200, description="목록 조회 성공",
-     *
-     *     @OA\JsonContent(
-     *       allOf={
-     *
-     *         @OA\Schema(ref="#/components/schemas/ApiResponse"),
-     *         @OA\Schema(@OA\Property(property="data", type="array",
-     *
-     *           @OA\Items(type="object",
-     *
-     *             @OA\Property(property="id", type="integer", example=1),
-     *             @OA\Property(property="name", type="string", example="admin"),
-     *             @OA\Property(property="description", type="string", nullable=true, example="관리자")
-     *           )
-     *         ))
-     *       }
-     *     )
-     *   ),
-     *
-     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
-     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
-     * )
-     */
-    public function active() {}
 }

app/Swagger/v1/RolePermissionApi.php

@@ -5,7 +5,7 @@
 /**
  * @OA\Tag(
  *   name="RolePermission",
- *   description="역할-퍼미션 매핑(조회/부여/회수/동기화/매트릭스/토글)"
+ *   description="역할-퍼미션 매핑(조회/부여/회수/동기화)"
  * )
  */
 
@@ -96,64 +96,6 @@
  *     )
  *   }
  * )
- *
- * @OA\Schema(
- *   schema="PermissionMenuTree",
- *   type="object",
- *   description="권한 매트릭스용 메뉴 트리",
- *
- *   @OA\Property(property="menus", type="array",
- *
- *     @OA\Items(type="object",
- *
- *       @OA\Property(property="id", type="integer", example=1),
- *       @OA\Property(property="parent_id", type="integer", nullable=true, example=null),
- *       @OA\Property(property="name", type="string", example="대시보드"),
- *       @OA\Property(property="url", type="string", nullable=true, example="/dashboard"),
- *       @OA\Property(property="icon", type="string", nullable=true, example="dashboard"),
- *       @OA\Property(property="sort_order", type="integer", example=1),
- *       @OA\Property(property="is_active", type="boolean", example=true),
- *       @OA\Property(property="depth", type="integer", example=0),
- *       @OA\Property(property="has_children", type="boolean", example=true)
- *     )
- *   ),
- *   @OA\Property(property="permission_types", type="array", @OA\Items(type="string"), example={"view","create","update","delete","approve","export","manage"})
- * )
- *
- * @OA\Schema(
- *   schema="RolePermissionMatrix",
- *   type="object",
- *   description="역할의 권한 매트릭스",
- *
- *   @OA\Property(property="role", type="object",
- *     @OA\Property(property="id", type="integer", example=1),
- *     @OA\Property(property="name", type="string", example="admin"),
- *     @OA\Property(property="description", type="string", nullable=true, example="관리자")
- *   ),
- *   @OA\Property(property="permission_types", type="array", @OA\Items(type="string"), example={"view","create","update","delete","approve","export","manage"}),
- *   @OA\Property(property="permissions", type="object", description="메뉴ID를 키로 한 권한 맵",
- *     example={"101": {"view": true, "create": true}, "102": {"view": true}},
- *     additionalProperties=true
- *   )
- * )
- *
- * @OA\Schema(
- *   schema="RolePermissionToggleRequest",
- *   type="object",
- *   required={"menu_id","permission_type"},
- *
- *   @OA\Property(property="menu_id", type="integer", example=101, description="메뉴 ID"),
- *   @OA\Property(property="permission_type", type="string", example="view", description="권한 유형 (view, create, update, delete, approve, export, manage)")
- * )
- *
- * @OA\Schema(
- *   schema="RolePermissionToggleResponse",
- *   type="object",
- *
- *   @OA\Property(property="menu_id", type="integer", example=101),
- *   @OA\Property(property="permission_type", type="string", example="view"),
- *   @OA\Property(property="granted", type="boolean", example=true, description="토글 후 권한 부여 상태")
- * )
  */
 class RolePermissionApi
 {
@@ -251,142 +193,4 @@ public function revoke() {}
      * )
      */
     public function sync() {}
-
-    /**
-     * @OA\Get(
-     *   path="/api/v1/role-permissions/menus",
-     *   summary="권한 매트릭스용 메뉴 트리 조회",
-     *   description="활성 메뉴를 플랫 배열(depth 포함)로 반환하고, 사용 가능한 권한 유형 목록을 함께 반환합니다.",
-     *   tags={"RolePermission"},
-     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
-     *
-     *   @OA\Response(response=200, description="조회 성공",
-     *
-     *     @OA\JsonContent(
-     *       allOf={
-     *
-     *         @OA\Schema(ref="#/components/schemas/ApiResponse"),
-     *         @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/PermissionMenuTree"))
-     *       }
-     *     )
-     *   ),
-     *
-     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
-     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
-     * )
-     */
-    public function menus() {}
-
-    /**
-     * @OA\Get(
-     *   path="/api/v1/roles/{id}/permissions/matrix",
-     *   summary="역할의 권한 매트릭스 조회",
-     *   description="해당 역할에 부여된 메뉴별 권한 매트릭스를 반환합니다.",
-     *   tags={"RolePermission"},
-     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
-     *
-     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=1),
-     *
-     *   @OA\Response(response=200, description="조회 성공",
-     *
-     *     @OA\JsonContent(
-     *       allOf={
-     *
-     *         @OA\Schema(ref="#/components/schemas/ApiResponse"),
-     *         @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/RolePermissionMatrix"))
-     *       }
-     *     )
-     *   ),
-     *
-     *   @OA\Response(response=404, description="역할 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
-     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
-     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
-     * )
-     */
-    public function matrix() {}
-
-    /**
-     * @OA\Post(
-     *   path="/api/v1/roles/{id}/permissions/toggle",
-     *   summary="특정 메뉴의 특정 권한 토글",
-     *   description="지정한 메뉴+권한 유형의 부여 상태를 반전합니다. 하위 메뉴에 재귀적으로 전파합니다.",
-     *   tags={"RolePermission"},
-     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
-     *
-     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=1),
-     *
-     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/RolePermissionToggleRequest")),
-     *
-     *   @OA\Response(response=200, description="토글 성공",
-     *
-     *     @OA\JsonContent(
-     *       allOf={
-     *
-     *         @OA\Schema(ref="#/components/schemas/ApiResponse"),
-     *         @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/RolePermissionToggleResponse"))
-     *       }
-     *     )
-     *   ),
-     *
-     *   @OA\Response(response=404, description="역할 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
-     *   @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
-     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
-     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
-     * )
-     */
-    public function toggle() {}
-
-    /**
-     * @OA\Post(
-     *   path="/api/v1/roles/{id}/permissions/allow-all",
-     *   summary="모든 권한 허용",
-     *   description="해당 역할에 모든 활성 메뉴의 모든 권한 유형을 일괄 부여합니다.",
-     *   tags={"RolePermission"},
-     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
-     *
-     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=1),
-     *
-     *   @OA\Response(response=200, description="성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse")),
-     *   @OA\Response(response=404, description="역할 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
-     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
-     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
-     * )
-     */
-    public function allowAll() {}
-
-    /**
-     * @OA\Post(
-     *   path="/api/v1/roles/{id}/permissions/deny-all",
-     *   summary="모든 권한 거부",
-     *   description="해당 역할의 모든 메뉴 권한을 일괄 제거합니다.",
-     *   tags={"RolePermission"},
-     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
-     *
-     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=1),
-     *
-     *   @OA\Response(response=200, description="성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse")),
-     *   @OA\Response(response=404, description="역할 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
-     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
-     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
-     * )
-     */
-    public function denyAll() {}
-
-    /**
-     * @OA\Post(
-     *   path="/api/v1/roles/{id}/permissions/reset",
-     *   summary="기본 권한으로 초기화 (view만 허용)",
-     *   description="해당 역할의 모든 권한을 제거한 후, 모든 활성 메뉴에 view 권한만 부여합니다.",
-     *   tags={"RolePermission"},
-     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
-     *
-     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=1),
-     *
-     *   @OA\Response(response=200, description="성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse")),
-     *   @OA\Response(response=404, description="역할 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
-     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
-     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
-     * )
-     */
-    public function reset() {}
 }