fix : 회원 관리 API 수정 및 ApiResponse 타입 수정

app/Helpers/ApiResponse.php

@@ -110,8 +110,7 @@ public static function response($type = '', $query = '', $key = ''): array
 
     public static function handle(
         callable $callback,
-        string $successMessage = '요청 성공',
-        string $errorMessage = '요청 실패'
+        string $responseTitle = '요청'
     ): JsonResponse {
         try {
             $result = $callback();
@@ -121,10 +120,10 @@ public static function handle(
             }
 
             return self::success(
-                $result['data'] ?? null, $successMessage, $result['query'] ?? []
+                $result['data'] ?? null, $responseTitle." 성공", $result['query'] ?? []
             );
         } catch (\Throwable $e) {
-            return self::error($errorMessage, 500, [
+            return self::error($responseTitle." 실패", 500, [
                 'details' => $e->getMessage(),
             ]);
         }

app/Http/Controllers/Api/V1/BomController.php

@@ -11,46 +11,41 @@ class BomController
 {
     public function index(Request $request)
     {
-        $title = 'BOM 목록 조회';
         return ApiResponse::handle(function () use ($request) {
             return BomService::getBoms($request);
-        }, $title, $title.' 실패');
+        }, 'BOM 목록 조회');
     }
 
 
     public function store(Request $request)
     {
-        $title = 'BOM 등록';
         return ApiResponse::handle(function () use ($request) {
             return BomService::setBom($request);
-        }, $title, $title.' 실패');
+        }, 'BOM 등록');
     }
 
 
     public function show(Request $request, int $id)
     {
-        $title = '특정BOM 상세 조회';
         return ApiResponse::handle(function () use ($request) {
             return BomService::getBom($request);
-        }, $title, $title.' 실패');
+        }, '특정BOM 상세 조회');
     }
 
 
     public function update(Request $request, int $id)
     {
-        $title = 'BOM 수정';
         return ApiResponse::handle(function () use ($request) {
             return BomService::updateBom($request);
-        }, $title, $title.' 실패');
+        }, 'BOM 수정');
     }
 
 
     public function destroy(Request $request, int $id)
     {
-        $title = 'BOM 삭제';
         return ApiResponse::handle(function () use ($request) {
             return BomService::destoryBom($request);
-        }, $title, $title.' 실패');
+        }, 'BOM 삭제');
     }
 
 }

app/Http/Controllers/Api/V1/FileController.php

@@ -14,7 +14,7 @@ public function upload(Request $request)
     {
         return ApiResponse::handle(function () use ($request) {
             return FileService::uploadFiles($request->all());
-        }, '파일 업로드 성공', '파일 업로드 실패');
+        }, '파일 업로드');
     }
 
     // 파일 목록 조회
@@ -22,7 +22,7 @@ public function list(Request $request)
     {
         return ApiResponse::handle(function () use ($request) {
             return FileService::getFiles($request->all());
-        }, '파일 목록조회 성공', '파일 목록조회 실패');
+        }, '파일 목록조회');
     }
 
     // 파일 삭제
@@ -30,7 +30,7 @@ public function delete(Request $request)
     {
         return ApiResponse::handle(function () use ($request) {
             return FileService::deleteFiles($request->all());
-        }, '파일 삭제 성공', '파일 삭제 실패');
+        }, '파일 삭제');
     }
 
     // 파일 정보 조회 (단건)
@@ -38,6 +38,6 @@ public function findFile(Request $request)
     {
         return ApiResponse::handle(function () use ($request) {
             return FileService::findFile($request->all());
-        }, '파일 정보 조회 성공', '파일 정보 조회 실패');
+        }, '파일 정보 조회');
     }
 }

app/Http/Controllers/Api/V1/MaterialController.php

@@ -11,45 +11,40 @@ class MaterialController
 {
     public function index(Request $request)
     {
-        $title = '제품 목록 조회';
         return ApiResponse::handle(function () use ($request) {
             return MeterialService::getMeterials($request);
-        }, $title, $title.' 실패');
+        }, '제품 목록 조회');
     }
 
 
     public function store(Request $request)
     {
-        $title = '제품 등록';
         return ApiResponse::handle(function () use ($request) {
             return MeterialService::setMeterial($request);
-        }, $title, $title.' 실패');
+        }, '제품 등록');
     }
 
 
     public function show(Request $request, int $id)
     {
-        $title = '특정제품 상세 조회';
         return ApiResponse::handle(function () use ($id) {
             return MeterialService::getMeterial($id);
-        }, $title, $title.' 실패');
+        }, '특정제품 상세 조회');
     }
 
 
     public function update(Request $request, int $id)
     {
-        $title = '제품 수정';
         return ApiResponse::handle(function () use ($id) {
             return MeterialService::updateMeterial($id);
-        }, $title, $title.' 실패');
+        }, '제품 수정');
     }
 
 
     public function destroy(Request $request, int $id)
     {
-        $title = '제품 삭제';
         return ApiResponse::handle(function () use ($id) {
             return MeterialService::destoryMeterial($id);
-        }, $title, $title.' 실패');
+        }, '제품 삭제');
     }
 }

app/Http/Controllers/Api/V1/ModelController.php

@@ -11,46 +11,41 @@ class ModelController
 {
     public function index(Request $request)
     {
-        $title = '모델 목록 조회';
         return ApiResponse::handle(function () use ($request) {
             return ModelService::getModels($request);
-        }, $title, $title.' 실패');
+        }, '모델 목록 조회');
     }
 
 
     public function store(Request $request)
     {
-        $title = '모델 등록';
         return ApiResponse::handle(function () use ($request) {
             return ModelService::setModel($request);
-        }, $title, $title.' 실패');
+        }, '모델 등록');
     }
 
 
     public function show(Request $request, int $id)
     {
-        $title = '특정모델 상세 조회';
         return ApiResponse::handle(function () use ($id) {
             return ModelService::getModel($id);
-        }, $title, $title.' 실패');
+        }, '특정모델 상세 조회');
     }
 
 
     public function update(Request $request, int $id)
     {
-        $title = '모델 수정';
         return ApiResponse::handle(function () use ($id) {
             return ModelService::updateModel($id);
-        }, $title, $title.' 실패');
+        }, '모델 수정');
     }
 
 
     public function destroy(Request $request, int $id)
     {
-        $title = '모델 삭제';
         return ApiResponse::handle(function () use ($id) {
             return ModelService::destoryModel($id);
-        }, $title, $title.' 실패');
+        }, '모델 삭제');
     }
 
 }

app/Http/Controllers/Api/V1/ProductController.php

@@ -19,7 +19,7 @@ public function getCategory(Request $request)
     {
         return ApiResponse::handle(function () use ($request) {
             return ProductService::getCategory($request);
-        }, '제품 카테고리 조회 성공', '제품 카테고리 조회 실패');
+        }, '제품 카테고리 조회');
     }
 
 

app/Http/Controllers/Api/V1/UserController.php

@@ -7,7 +7,7 @@
 use App\Services\MemberService;
 use App\Helpers\ApiResponse;
 
-class MemberController extends Controller
+class UserController extends Controller
 {
     public function index(Request $request)
     {
@@ -37,19 +37,14 @@ public function store(Request $request)
     {
         return ApiResponse::handle(function () use ($request) {
             return MemberService::setMember($request->all());
-        }, '회원등록 성공', '회원등록 실패');
+        }, '회원등록');
     }
 
     public function show($userNo)
     {
-        try {
-            $result = MemberService::getMember($userNo);
-            return ApiResponse::success($result['data'], '회원 상세조회 성공',$result['query']);
-        } catch (\Throwable $e) {
-            return ApiResponse::error('회원 상세조회 실패', 500, [
-                'details' => $e->getMessage(),
-            ]);
-        }
+        return ApiResponse::handle(function () use ($userNo) {
+            return MemberService::getMember($userNo);
+        }, '회원 상세조회');
     }
 
 
@@ -57,7 +52,38 @@ public function me(Request $request)
     {
         return ApiResponse::handle(function () use ($request) {
             return MemberService::getMyInfo($request);
-        }, '나의 정보 조회 성공', '나의 정보 조회 실패');
+        }, '나의 정보 조회');
+    }
+
+
+    public function meUpdate(Request $request)
+    {
+        return ApiResponse::handle(function () use ($request) {
+            return MemberService::getMyUpdate($request);
+        }, '나의 정보 수정');
+    }
+
+
+    public function changePassword(Request $request)
+    {
+        return ApiResponse::handle(function () use ($request) {
+            return MemberService::setMyPassword($request);
+        }, '나의 비밀번호 수정');
+    }
+
+    public function tenants(Request $request)
+    {
+        return ApiResponse::handle(function () use ($request) {
+            return MemberService::getMyTenants($request);
+        }, '나의 테넌트 목록 조회');
+    }
+
+    public function switchTenant(Request $request)
+    {
+       $tenant_id = $request->tenant_id;
+        return ApiResponse::handle(function () use ($tenant_id) {
+            return MemberService::switchMyTenant($tenant_id);
+        }, '활성 테넌트 전환');
     }
 
     /**
@@ -75,25 +101,5 @@ public function update(Request $request, string $id)
     {
         //
     }
-
-    /**
-     * Remove the specified resource from storage.
-     */
-    public function delAdmin($userNo, Request $request)
-    {
-        return ApiResponse::handle(function () use ($userNo, $request) {
-            return MemberService::delAdmin($userNo);
-        }, '관리자 제외 성공', '관리자 제외 실패');
-    }
-
-    /**
-     * 관리자 설정
-     */
-    public function setAdmin($userNo, Request $request)
-    {
-        return ApiResponse::handle(function () use ($userNo, $request) {
-            return MemberService::setAdmin($userNo);
-        }, '관리자 설정 성공', '관리자 설정 실패');
-    }
 }
 

app/Models/Members/User.php

@@ -3,17 +3,50 @@
 namespace App\Models\Members;
 
 use App\Models\Commons\Role;
-use App\Models\File;
+use App\Models\Commons\File;
+use App\Models\Tenants\Tenant;
 use App\Traits\ModelTrait;
 use Illuminate\Database\Eloquent\SoftDeletes;
 use Illuminate\Foundation\Auth\User as Authenticatable;
 use Illuminate\Notifications\Notifiable;
 use Laravel\Sanctum\HasApiTokens;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
 
 class User extends Authenticatable
 {
     use HasApiTokens, Notifiable, SoftDeletes, ModelTrait;
 
+    protected $fillable = [
+        'name',
+        'phone',
+        'email',
+        'options',
+        'profile_photo_path',
+    ];
+
+    protected $guarded = [
+        'id',
+        'user_id',
+        'password',
+        'remember_token',
+        'two_factor_secret',
+        'two_factor_recovery_codes',
+        'two_factor_confirmed_at',
+        'email_verified_at',
+        'last_login_at',
+        'current_team_id',
+        'deleted_at',
+        'created_at',
+        'updated_at',
+    ];
+
+    protected $casts = [
+        'email_verified_at' => 'datetime',
+        'last_login_at'     => 'datetime',
+        'options'        => 'array',
+        'deleted_at'        => 'datetime',
+    ];
+
     protected $hidden = [
         'password', 'remember_token',
         'two_factor_secret', 'two_factor_recovery_codes', 'two_factor_confirmed_at'
@@ -24,9 +57,8 @@ public function userTenants()
         return $this->hasMany(UserTenant::class);
     }
 
-    public function userTenant() // 단일 기본 테넌트
+    public function userTenant()
     {
-        // 예시: 첫 번째(기본) 테넌트 반환
         return $this->hasOne(UserTenant::class)->where('is_active', 1);
     }
 
@@ -37,8 +69,7 @@ public function userRoles()
 
     public function roles()
     {
-        return $this->belongsToMany(Role::class, 'user_roles')
-            ->withPivot('tenant_id', 'assigned_at');
+        return $this->belongsToMany(Role::class, 'user_roles')->withPivot('tenant_id', 'assigned_at');
     }
 
     public function userTenantById($tenantId)
@@ -50,4 +81,12 @@ public function files()
     {
         return $this->morphMany(File::class, 'fileable');
     }
+
+    public function tenantsMembership(): BelongsToMany
+    {
+        return $this->belongsToMany(Tenant::class, 'user_tenants', 'user_id', 'tenant_id')
+            ->as('membership') // pivot 대신 membership으로 표기
+            ->withPivot(['is_active', 'is_default', 'joined_at', 'left_at', 'deleted_at'])
+            ->wherePivotNull('deleted_at'); // 소프트삭제 제외
+    }
 }

app/Models/Members/UserTenant.php

@@ -13,7 +13,26 @@ class UserTenant extends Model
     use SoftDeletes, ModelTrait, BelongsToTenant;
 
     protected $fillable = [
-        'user_id', 'tenant_id', 'is_active', 'joined_at', 'left_at'
+        'user_id', 'tenant_id', 'is_active', 'is_default', 'joined_at', 'left_at'
+    ];
+
+    protected $guarded = [
+        'id',
+        'created_at',
+        'updated_at',
+        'deleted_at',
+    ];
+
+    protected $casts = [
+        'joined_at'      => 'datetime',
+        'left_at'      => 'datetime',
+        'created_at'      => 'datetime',
+        'updated_at'      => 'datetime',
+        'deleted_at'      => 'datetime',
+    ];
+
+    protected $hidden = [
+        'deleted_at',
     ];
 
     public function user()

app/Models/Tenants/Tenant.php

@@ -31,11 +31,28 @@ class Tenant extends Model
         'billing_tp_code',
     ];
 
+    protected $guarded = [
+        'id',
+        'created_at',
+        'updated_at',
+        'deleted_at',
+        'plan_id',
+        'subscription_id',
+    ];
+
     protected $casts = [
         'trial_ends_at'   => 'datetime',
         'expires_at'      => 'datetime',
         'last_paid_at'    => 'datetime',
         'max_users'       => 'integer',
+        'created_at'      => 'datetime',
+        'updated_at'      => 'datetime',
+        'deleted_at'      => 'datetime',
+    ];
+
+    protected $hidden = [
+        'admin_memo',
+        'deleted_at',
     ];
 
     // 관계 정의 (예시)

app/Services/MemberService.php

@@ -3,8 +3,11 @@
 namespace App\Services;
 
 use App\Helpers\ApiResponse;
-use App\Models\Members\User;
 use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\Hash;
+use App\Models\Members\User;
+use App\Models\Members\UserTenant;
 
 class MemberService
 {
@@ -64,118 +67,131 @@ public static function getMyInfo()
     }
 
     /**
-     * 회원 등록 또는 수정
+     * 내정보 수정
      */
-    public static function setMember(array $params)
+    public static function getMyUpdate($request)
     {
-        if ($res = ApiResponse::validate(isset($params['user_id']), '아이디 없음')) return $res;
-        if ($res = ApiResponse::validate(isset($params['user_ncnm']), '이름 없음')) return $res;
+        $debug = app()->environment('local');
+        if ($debug) DB::enableQueryLog();
 
-        $pwd1 = $params['user_pwd1'] ?? null;
-        $pwd2 = $params['user_pwd2'] ?? null;
-        if ($res = ApiResponse::validate(
-            !$pwd1 || $pwd1 === $pwd2,
-            '비밀번호가 일치하지 않음'
-        )) return $res;
+        $apiUser = app('api_user');
 
-        $now = now();
 
-        $data = [
-            'USER_EMAIL' => $params['user_email'] ?? null,
-            'USER_HP' => $params['user_hp'] ?? null,
-            'USER_IP' => $params['user_ip'] ?? null,
-            'ALT_DTTM' => $now,
-        ];
+        // 요청으로 받은 수정 데이터 유효성 검사
+        $validatedData = $request->validate([
+            'name'  => 'sometimes|string|max:255',
+            'phone' => 'sometimes|string|max:20',
+            'email' => 'sometimes|email|max:100',
+            'options' => 'nullable|json',
+            'profile_photo_path' => 'nullable|string|max:255',
+        ]);
 
-        if (!empty($params['user_start_dt'])) {
-            $data['USER_START_DT'] = $params['user_start_dt'];
-        }
-        if (!empty($params['user_end_dt'])) {
-            $data['USER_END_DT'] = $params['user_end_dt'];
+        $user = User::find($apiUser);
+
+        if (!$user) {
+            return ApiResponse::error('User not found.', 404);
         }
 
-        // 신규 등록
-        if (empty($params['user_no'])) {
+        // 사용자 정보 업데이트
+        $user->update($validatedData);
 
-            // 초기 비빌번호 설정이 없으면 0000 으로 셋팅
-            $pwd = $pwd1 ?? '0000';
+        // 수정 성공 시 success 반환
+        return ApiResponse::response('success');
+    }
 
-            $data += [
-                'USER_ID' => $params['user_id'],
-                'USER_PWD' => hash('sha256', $pwd),
-                'USER_NCNM' => $params['user_ncnm'] ?? null,
-                'USER_PART' => $params['user_part'] ?? null,
-                'USER_DEPT' => $params['user_dept'] ?? null,
-                'USER_ROLE' => $params['user_role'] ?? null,
-                'USER_STATUS' => $params['user_status'] ?? null,
-                'USER_MEMO' => $params['user_memo'] ?? null,
-                'REG_DTTM' => $now,
-                'ALT_DTTM' => $now,
-            ];
+    /**
+     * 내 비밀번호 수정
+     */
+    public static function setMyPassword($request)
+    {
+        $debug = app()->environment('local');
+        if ($debug) DB::enableQueryLog();
 
-            DB::table('SITE_USER_INFO')->insert($data);
+        $apiUserId = app('api_user'); // 현재 로그인한 사용자 PK
+
+        // 유효성 검사 (확인 비밀번호는 선택)
+        $validated = $request->validate([
+            'current_password' => 'required|string',
+            'new_password'     => 'required|string|min:8|max:64',
+        ]);
+
+        // 선택적으로 확인 비밀번호가 온 경우 체크
+        if ($request->filled('new_password_confirmation') &&
+            $request->input('new_password_confirmation') !== $validated['new_password']) {
+            return ApiResponse::error('비밀번호 확인이 일치하지 않습니다.', 400);
         }
 
-        // 수정
-        else {
-            if (!empty($pwd1)) {
-                $data['USER_PWD'] = hash('sha256', $pwd1);
-            }
-
-            if (AdminPermissionService::hasPermission(session('Adm.token'), 'AC')) {
-                $data += [
-                    'USER_ID' => $params['user_id'],
-                    'USER_NCNM' => $params['user_ncnm'],
-                    'USER_PART' => $params['user_part'],
-                    'USER_DEPT' => $params['user_dept'],
-                    'USER_ROLE' => $params['user_role'],
-                    'USER_STATUS' => $params['user_status'],
-                    'USER_MEMO' => $params['user_memo'],
-                    'ALT_DTTM' => $now,
-                ];
-            }
-
-            DB::table('SITE_USER_INFO')
-                ->where('USER_NO', $params['user_no'])
-                ->update($data);
+        // 유저 조회
+        $user = User::find($apiUserId);
+        if (!$user) {
+            return ApiResponse::error('유저를 찾을 수 없음', 404);
         }
 
+        // 현재 비밀번호 확인
+        if (!Hash::check($validated['current_password'], $user->password)) {
+            return ApiResponse::error('현재 비밀번호가 일치하지 않습니다.', 400);
+        }
+
+        // 기존 비밀번호와 동일한지 방지
+        if (Hash::check($validated['new_password'], $user->password)) {
+            return ApiResponse::error('새 비밀번호가 기존 비밀번호와 동일합니다.', 400);
+        }
+
+        // 비밀번호 변경 (guarded 우회: 직접 대입 + save)
+        $user->password = Hash::make($validated['new_password']);
+        $saved = $user->save();
+
+        // (선택) 모든 기존 토큰 무효화하려면 아래 주석 해제
+        // $user->tokens()->delete();
+
         return ApiResponse::response('success');
     }
 
     /**
-     * 관리자 권한 삭제
+     * 나의 테넌트 목록
      */
-    public static function delAdmin(int $userNo)
+    public static function getMyTenants()
     {
-        DB::table('SITE_ADMIN')->where('UNO', $userNo)->delete();
-        DB::table('SITE_USER_INFO')
-            ->where('USER_NO', $userNo)
-            ->update(['USER_STATUS' => '02']);
+        $debug = app()->environment('local');
+        if ($debug) DB::enableQueryLog();
 
-        return ApiResponse::response('success');
+        $apiUser = app('api_user');
+        $data = UserTenant::join('tenants', 'user_tenants.tenant_id', '=', 'tenants.id')
+            ->where('user_tenants.user_id', $apiUser)
+            ->get([
+                'tenants.id',
+                'tenants.company_name',
+                'user_tenants.is_active',
+                'user_tenants.is_default'
+            ]);
+
+        return ApiResponse::response('result', $data);
     }
 
-    /**
-     * 관리자 권한 등록
-     */
-    public static function setAdmin(int $userNo)
-    {
-        $mem = DB::table('SITE_USER_INFO')
-            ->select('USER_ROLE', 'USER_PART')
-            ->where('USER_NO', $userNo)
-            ->first();
-        if (!$mem) {
-            return ApiResponse::error('존재하지 않는 회원입니다.', 404);
-        }
 
-        DB::table('SITE_ADMIN')->updateOrInsert(
-            ['UNO' => $userNo],
-            ['LEVEL' => 'public', 'COMMENT' => '일반관리자']
-        );
-        DB::table('SITE_USER_INFO')
-            ->where('USER_NO', $userNo)
-            ->update(['USER_STATUS' => '01']);
+    /**
+     * 나의 테넌트 전환
+     */
+    public static function switchMyTenant(int $tenantId)
+    {
+        $debug = app()->environment('local');
+        if ($debug) DB::enableQueryLog();
+
+        $apiUser = app('api_user');
+
+        // 1) 현재 유저의 기본 테넌트를 모두 해제
+        UserTenant::where('user_id', $apiUser)
+            ->where('is_default', 1)
+            ->update(['is_default' => 0]);
+
+        // 2) 지정한 tenant_id를 기본 테넌트로 설정
+        $updated = UserTenant::where('user_id', $apiUser)
+            ->where('tenant_id', $tenantId)
+            ->update(['is_default' => 1]);
+
+        if (!$updated) {
+            return ApiResponse::error('해당 테넌트를 찾을 수 없습니다.', 404);
+        }
 
         return ApiResponse::response('success');
     }

app/Swagger/v1/UserApi.php

@@ -0,0 +1,300 @@
+<?php
+
+namespace App\Swagger\v1;
+
+/**
+ * @OA\Tag(name="Auth", description="로그인/로그아웃")
+ * @OA\Tag(name="User", description="사용자 본인 정보/비밀번호 변경 등")
+ */
+
+
+/**
+ * @OA\Schema(
+ *     schema="Member",
+ *     type="object",
+ *     description="회원 기본 정보",
+ *     required={"id","user_id","name","email"},
+ *     @OA\Property(property="id", type="integer", example=1),
+ *     @OA\Property(property="user_id", type="string", example="hamss"),
+ *     @OA\Property(property="phone", type="string", nullable=true, example="010-4820-9104"),
+ *     @OA\Property(property="options", type="string", nullable=true, example=null),
+ *     @OA\Property(property="name", type="string", example="Kent"),
+ *     @OA\Property(property="email", type="string", example="codebridge@gmail.com"),
+ *     @OA\Property(property="email_verified_at", type="string", format="date-time", nullable=true, example=null),
+ *     @OA\Property(property="last_login_at", type="string", format="date-time", nullable=true, example=null),
+ *     @OA\Property(property="current_team_id", type="integer", nullable=true, example=null),
+ *     @OA\Property(property="profile_photo_path", type="string", nullable=true, example=null),
+ *     @OA\Property(property="created_at", type="string", format="date-time", example="2025-07-16 18:28:41"),
+ *     @OA\Property(property="updated_at", type="string", format="date-time", example="2025-07-25 23:13:06"),
+ *     @OA\Property(property="deleted_at", type="string", format="date-time", nullable=true, example=null)
+ * )
+ *
+ * @OA\Schema(
+ *     schema="MemberPagination",
+ *     type="object",
+ *     description="라라벨 LengthAwarePaginator 기본 구조",
+ *     @OA\Property(property="current_page", type="integer", example=1),
+ *     @OA\Property(
+ *         property="data",
+ *         type="array",
+ *         @OA\Items(ref="#/components/schemas/Member")
+ *     ),
+ *     @OA\Property(property="first_page_url", type="string", example="/api/v1/users/index?page=1"),
+ *     @OA\Property(property="from", type="integer", example=1),
+ *     @OA\Property(property="last_page", type="integer", example=1),
+ *     @OA\Property(property="last_page_url", type="string", example="/api/v1/users/index?page=1"),
+ *     @OA\Property(
+ *         property="links",
+ *         type="array",
+ *         @OA\Items(
+ *             type="object",
+ *             @OA\Property(property="url", type="string", nullable=true, example=null),
+ *             @OA\Property(property="label", type="string", example="&laquo; Previous"),
+ *             @OA\Property(property="active", type="boolean", example=false)
+ *         )
+ *     ),
+ *     @OA\Property(property="next_page_url", type="string", nullable=true, example=null),
+ *     @OA\Property(property="path", type="string", example="/api/v1/users/index"),
+ *     @OA\Property(property="per_page", type="integer", example=20),
+ *     @OA\Property(property="prev_page_url", type="string", nullable=true, example=null),
+ *     @OA\Property(property="to", type="integer", example=3),
+ *     @OA\Property(property="total", type="integer", example=3)
+ * )
+ *
+ * @OA\Schema(
+ *     schema="TenantBrief",
+ *     type="object",
+ *     description="간단 테넌트 정보",
+ *     required={"id","company_name"},
+ *     @OA\Property(property="id", type="integer", example=1),
+ *     @OA\Property(property="company_name", type="string", example="(주)경동기업"),
+ *     @OA\Property(property="code", type="string", example="KDCOM"),
+ *     @OA\Property(property="email", type="string", example="kd5130@naver.com"),
+ *     @OA\Property(property="phone", type="string", example="01083935130"),
+ *     @OA\Property(property="address", type="string", example="경기도 김포시 통진읍 옹정로 45-22"),
+ *     @OA\Property(property="business_num", type="string", example="1398700333"),
+ *     @OA\Property(property="corp_reg_no", type="string", nullable=true, example=null),
+ *     @OA\Property(property="ceo_name", type="string", example="이대표"),
+ *     @OA\Property(property="homepage", type="string", nullable=true, example=null),
+ *     @OA\Property(property="fax", type="string", nullable=true, example=null),
+ *     @OA\Property(property="logo", type="string", nullable=true, example=null),
+ *     @OA\Property(property="admin_memo", type="string", nullable=true, example=null),
+ *     @OA\Property(property="options", type="string", nullable=true, example=null)
+ * )
+ *
+ * @OA\Schema(
+ *     schema="MeResponseData",
+ *     type="object",
+ *     description="내 정보 + 테넌트 정보",
+ *     @OA\Property(property="user", ref="#/components/schemas/Member"),
+ *     @OA\Property(property="tenant", ref="#/components/schemas/TenantBrief")
+ * )
+ */
+class UserApi
+{
+
+    /**
+     * @OA\Get(
+     *     path="/api/v1/users/me",
+     *     summary="내 정보 조회",
+     *     description="내 정보와 활성 테넌트 정보를 반환합니다.",
+     *     tags={"User"},
+     *     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/MeResponseData"))
+     *             }
+     *         )
+     *     ),
+     *     @OA\Response(response=401, description="인증 실패 (헤더 누락, 유효하지 않은 토큰/키 등)", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=405, description="허용되지 않는 메서드", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function me() {}
+
+    /**
+     * @OA\Put(
+     *     path="/api/v1/users/me",
+     *     tags={"User"},
+     *     summary="내 정보 수정",
+     *     description="이름/연락처 등 프로필 정보를 수정합니다.",
+     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *     @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/UserUpdateRequest")),
+     *     @OA\Response(
+     *         response=200,
+     *         description="수정 성공",
+     *         @OA\JsonContent(
+     *             type="object",
+     *              @OA\Property(property="success", type="boolean", example=true),
+     *              @OA\Property(property="message", type="string", example="나의 정보 수정 성공"),
+     *              @OA\Property(property="data", type="string", example="Success")
+     *         )
+     *     ),
+     *     @OA\Response(response=400, description="필수 파라미터 누락", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=403, description="권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=404, description="존재하지 않는 URI 또는 데이터", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=405, description="허용되지 않는 메서드", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function updateMe() {}
+
+    /**
+     * @OA\Put(
+     *     path="/api/v1/users/me/password",
+     *     tags={"User"},
+     *     summary="비밀번호 변경",
+     *     description="현재 비밀번호 검증 후 새 비밀번호로 변경합니다.",
+     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *     @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/PasswordChangeRequest")),
+     *      @OA\Response(
+     *          response=204,
+     *          description="변경 성공(콘텐츠 없음)",
+     *          @OA\JsonContent(
+     *              @OA\Property(property="success", type="boolean", example=true),
+     *              @OA\Property(property="message", type="string", example="변경 성공"),
+     *              @OA\Property(property="data", type="object", nullable=true, example=null)
+     *          )
+     *      ),
+     *     @OA\Response(response=400, description="필수 파라미터 누락", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=403, description="권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=405, description="허용되지 않는 메서드", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function changePassword() {}
+
+    /**
+     * @OA\Get(
+     *     path="/api/v1/users/me/tenants",
+     *     tags={"User"},
+     *     summary="내 테넌트 목록",
+     *     description="사용자가 소속된 테넌트 목록을 반환합니다.",
+     *     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="tenant_id", type="integer", example=1),
+     *                             @OA\Property(property="tenant_name", type="string", example="경동기업"),
+     *                             @OA\Property(property="is_active", type="boolean", example=true)
+     *                         )
+     *                     )
+     *                 )
+     *             }
+     *         )
+     *     ),
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=403, description="권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=404, description="존재하지 않는 URI 또는 데이터", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=405, description="허용되지 않는 메서드", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function myTenants() {}
+
+    /**
+     * @OA\Patch(
+     *     path="/api/v1/users/me/tenants/switch",
+     *     tags={"User"},
+     *     summary="활성 테넌트 전환",
+     *     description="현재 세션/토큰의 활성 테넌트를 전환합니다.",
+     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *     @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/SwitchTenantRequest")),
+     *      @OA\Response(
+     *          response=204,
+     *          description="전환 성공(콘텐츠 없음)",
+     *          @OA\JsonContent(
+     *              @OA\Property(property="success", type="boolean", example=true),
+     *              @OA\Property(property="message", type="string", example="변경 성공"),
+     *              @OA\Property(property="data", type="object", nullable=true, example=null)
+     *          )
+     *      ),
+     *     @OA\Response(response=400, description="필수 파라미터 누락", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=403, description="권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=404, description="존재하지 않는 URI 또는 데이터", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=405, description="허용되지 않는 메서드", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function switchTenant() {}
+
+
+    /**
+     * @OA\Get(
+     *     path="/api/v1/users/index",
+     *     summary="회원 목록 조회",
+     *     description="회원 목록을 페이징 형태로 반환합니다.",
+     *     tags={"User"},
+     *     security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
+     *     @OA\Parameter(ref="#/components/parameters/Page"),
+     *     @OA\Parameter(ref="#/components/parameters/Size"),
+     *     @OA\Response(
+     *         response=200,
+     *         description="회원 목록 조회 성공",
+     *         @OA\JsonContent(
+     *             allOf={
+     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *                 @OA\Schema(
+     *                     @OA\Property(property="data", ref="#/components/schemas/MemberPagination")
+     *                 )
+     *             }
+     *         )
+     *     ),
+     *     @OA\Response(response=400, description="필수 파라미터 누락", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=403, description="권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=404, description="존재하지 않는 URI 또는 데이터", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=405, description="허용되지 않는 메서드", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function index() {}
+
+    /**
+     * @OA\Get(
+     *     path="/api/v1/users/show/{user_no}",
+     *     summary="회원 상세조회",
+     *     description="user_no 기준으로 회원 상세 정보를 조회합니다.",
+     *     tags={"User"},
+     *     security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
+     *     @OA\Parameter(
+     *         name="user_no",
+     *         in="path",
+     *         required=true,
+     *         description="회원 번호 (USER_NO)",
+     *         @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/Member"))
+     *             }
+     *         )
+     *     ),
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=404, description="회원 정보 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=405, description="허용되지 않는 메서드", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function show() {}
+}