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

2025-08-14 00:55:08 +09:00
parent 93042d189d
commit be89d149de
13 changed files with 660 additions and 181 deletions
--- a/app/Helpers/ApiResponse.php
+++ b/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(),
            ]);
        }
--- a/app/Http/Controllers/Api/V1/BomController.php
+++ b/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 삭제');
    }

 }
--- a/app/Http/Controllers/Api/V1/FileController.php
+++ b/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());
-        }, '파일 정보 조회 성공', '파일 정보 조회 실패');
+        }, '파일 정보 조회');
    }
 }
--- a/app/Http/Controllers/Api/V1/MaterialController.php
+++ b/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.' 실패');
+        }, '제품 삭제');
    }
 }
--- a/app/Http/Controllers/Api/V1/ModelController.php
+++ b/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.' 실패');
+        }, '모델 삭제');
    }

 }
--- a/app/Http/Controllers/Api/V1/ProductController.php
+++ b/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);
-        }, '제품 카테고리 조회 성공', '제품 카테고리 조회 실패');
+        }, '제품 카테고리 조회');
    }


--- a/app/Http/Controllers/Api/V1/MemberController.php
+++ b/app/Http/Controllers/Api/V1/MemberController.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);
-        }, '관리자 설정 성공', '관리자 설정 실패');
-    }
 }

--- a/app/Models/Members/User.php
+++ b/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'); // 소프트삭제 제외
+    }
 }
--- a/app/Models/Members/UserTenant.php
+++ b/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()
--- a/app/Models/Tenants/Tenant.php
+++ b/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',
    ];

    // 관계 정의 (예시)
--- a/app/Services/MemberService.php
+++ b/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');
    }
--- a/app/Swagger/v1/UserApi.php
+++ b/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() {}
+}
--- a/routes/api.php
+++ b/routes/api.php
@@ -11,6 +11,8 @@
 use App\Http\Controllers\Api\V1\MaterialController;
 use App\Http\Controllers\Api\V1\ModelController;
 use App\Http\Controllers\Api\V1\BomController;
+use App\Http\Controllers\Api\V1\TenantController;
+use App\Http\Controllers\Api\V1\UserController;

 // error test
 Route::get('/test-error', function () {
@@ -27,49 +29,145 @@
    Route::middleware('auth.apikey')->group(function () {

        # Auth API
-        Route::post('/login', [ApiController::class, 'login']);
+        Route::post('login', [ApiController::class, 'login']);
        Route::middleware('auth:sanctum')->post('/logout', [ApiController::class, 'logout']);


        // Admin API
-        Route::post('/admin/list', [AdminApiController::class, 'list'])->middleware('permission:SR'); // 관리자 리스트 조회
+        Route::post('admin/list', [AdminApiController::class, 'list'])->middleware('permission:SR'); // 관리자 리스트 조회


        // Common API
        Route::prefix('common')->group(function () {
-            Route::get('/code', [CommonController::class, 'getComeCode'])->name('common.code'); // 공통코드 조회
+            Route::get('code', [CommonController::class, 'getComeCode'])->name('v1.common.code'); // 공통코드 조회
        });


        // Product API
        Route::prefix('product')->group(function () {
-            Route::get('/category', [ProductController::class, 'getCategory'])->name('product.category'); // 제품 카테고리
+            Route::get('category', [ProductController::class, 'getCategory'])->name('v1.product.category'); // 제품 카테고리
        });


        // Member API
-        Route::prefix('member')->group(function () {
-            Route::get('/me', [MemberController::class, 'me'])->name('member.me');               // 내 정보 조회
-            Route::get('/index', [MemberController::class, 'index'])->name('member.index');               // 회원 목록 조회
-            Route::get('/show/{user_no}', [MemberController::class, 'show'])->name('member.show');        // 회원 상세 조회
-            Route::post('/store', [MemberController::class, 'store'])->name('member.store')->middleware('permission:AC');               // 회원 저장 (등록/수정)
+        Route::prefix('users')->group(function () {
+            Route::get('index', [UserController::class, 'index'])->name('v1.users.index');                            // 회원 목록 조회
+            Route::get('show/{user_no}', [UserController::class, 'show'])->name('v1.users.show');                     // 회원 상세 조회
+            Route::post('store', [UserController::class, 'store'])->name('v1.users.store')->middleware('permission:AC');               // 회원 저장 (등록/수정)
+
+            Route::get('me', [UserController::class, 'me'])->name('v1.users.users.me');                               // 내 정보 조회
+            Route::put('me', [UserController::class, 'meUpdate'])->name('v1.users.me.update');                          // 내 정보 수정
+            Route::put('me/password', [UserController::class, 'changePassword'])->name('v1.users.me.password');       // 비밀번호 변겅
+
+            Route::get('me/tenants', [UserController::class, 'tenants'])->name('v1.users.me.tenants.index');            // 내 테넌트 목록
+            Route::patch('me/tenants/switch',[UserController::class, 'switchTenant'])->name('v1.users.me.tenants.switch');  // 활성 테넌트 전환
+        });
        });


        // File API
        Route::prefix('file')->group(function () {
-            Route::post('/upload', [FileController::class, 'upload'])->name('file.upload');      // 파일 업로드 (등록/수정)
-            Route::get('/list', [FileController::class, 'list'])->name('file.list');             // 파일 목록 조회
-            Route::delete('/delete', [FileController::class, 'delete'])->name('file.delete');    // 파일 삭제
-            Route::get('/info', [FileController::class, 'findFile'])->name('file.info');         // 파일 정보 조회
-        });
+            Route::post('upload', [FileController::class, 'upload'])->name('v1.file.upload');      // 파일 업로드 (등록/수정)
+            Route::get('list', [FileController::class, 'list'])->name('v1.file.list');             // 파일 목록 조회
+            Route::delete('delete', [FileController::class, 'delete'])->name('v1.file.delete');    // 파일 삭제
+            Route::get('info', [FileController::class, 'findFile'])->name('v1.file.info');         // 파일 정보 조회


        // Material, Model, BOM API
-        Route::resource('materials', MaterialController::class)->except(['create', 'edit']); // 자재관리
-        Route::resource('models', ModelController::class)->except(['create', 'edit']); // 모델관리
-        Route::resource('boms', BomController::class)->except(['create', 'edit']); // BOM관리
+        Route::resource('materials', MaterialController::class)->except(['v1.create', 'edit']); // 자재관리
+        Route::resource('models', ModelController::class)->except(['v1.create', 'edit']); // 모델관리
+        Route::resource('boms', BomController::class)->except(['v1.create', 'edit']); // BOM관리

    });
 });

+
+
+// ─────────────────────────────────────────────────────────────
+// 공통 미들웨어 메모:
+//  - 'apikey'   : X-API-KEY 검사 미들웨어 (커스텀)
+//  - 'auth:sanctum' : Bearer 토큰(Sanctum) 인증
+// 필요 시 app/Http/Kernel.php 의 $routeMiddleware 에 별칭 등록
+// ─────────────────────────────────────────────────────────────
+
+/*
+|--------------------------------------------------------------------------
+| V1 - User 영역 (본인 계정)
+|--------------------------------------------------------------------------
+| Swagger: UserApi.php
+|  - POST   /api/v1/auth/login
+|  - POST   /api/v1/auth/logout
+|  - GET    /api/v1/users/me
+|  - PUT    /api/v1/users/me
+|  - PUT    /api/v1/users/me/password
+|  - GET    /api/v1/users/me/tenants
+|  - PATCH  /api/v1/users/me/tenants/switch
+*/
+Route::prefix('v1_DEV')
+    ->middleware(['apikey']) // 모든 엔드포인트는 X-API-KEY 필요
+    ->group(function () {
+
+        // Auth (User)
+        Route::prefix('auth')->group(function () {
+            Route::post('login',  [\App\Http\Controllers\Api\V1\AuthController::class, 'login'])
+                ->name('v1.auth.login'); // Bearer 불필요(로그인)
+
+            Route::post('logout', [\App\Http\Controllers\Api\V1\AuthController::class, 'logout'])
+                ->middleware('auth:sanctum')
+                ->name('v1.auth.logout');
+        });
+
+        // Users (me)
+        Route::prefix('users')->middleware('auth:sanctum')->group(function () {
+            Route::get('me',                 [\App\Http\Controllers\Api\V1\User\MeController::class, 'show'])->name('v1.users.me.show');
+            Route::put('me',                 [\App\Http\Controllers\Api\V1\User\MeController::class, 'update'])->name('v1.users.me.update');
+            Route::put('me/password',        [\App\Http\Controllers\Api\V1\User\MeController::class, 'changePassword'])->name('v1.users.me.password');
+
+            Route::get('me/tenants',         [\App\Http\Controllers\Api\V1\User\TenantController::class, 'index'])->name('v1.users.me.tenants.index');
+            Route::patch('me/tenants/switch',[\App\Http\Controllers\Api\V1\User\TenantController::class, 'switch'])->name('v1.users.me.tenants.switch');
+        });
+    });
+
+
+/*
+|--------------------------------------------------------------------------
+| V1 - Admin 영역 (관리자 전용 사용자 관리)
+|--------------------------------------------------------------------------
+| Swagger: AdminApi.php
+|  - GET    /api/v1/admin/users
+|  - POST   /api/v1/admin/users
+|  - GET    /api/v1/admin/users/{id}
+|  - PUT    /api/v1/admin/users/{id}
+|  - PATCH  /api/v1/admin/users/{id}/status
+|  - DELETE /api/v1/admin/users/{id}
+|  - POST   /api/v1/admin/users/{id}/restore
+|  - POST   /api/v1/admin/users/{id}/roles
+|  - DELETE /api/v1/admin/users/{id}/roles/{role}
+|  - POST   /api/v1/admin/users/{id}/reset-password
+*/
+Route::prefix('v1_DEV/admin')
+    ->middleware(['apikey', 'auth:sanctum', 'can:admin']) // 예: 'can:admin' 또는 커스텀 'is_admin'
+    ->group(function () {
+
+        // 목록/생성
+        Route::get('users',        [\App\Http\Controllers\Api\V1\Admin\UserController::class, 'index'])->name('v1.admin.users.index');
+        Route::post('users',       [\App\Http\Controllers\Api\V1\Admin\UserController::class, 'store'])->name('v1.admin.users.store');
+
+        // 단건
+        Route::get('users/{id}',   [\App\Http\Controllers\Api\V1\Admin\UserController::class, 'show'])->name('v1.admin.users.show');
+        Route::put('users/{id}',   [\App\Http\Controllers\Api\V1\Admin\UserController::class, 'update'])->name('v1.admin.users.update');
+        Route::delete('users/{id}',[\App\Http\Controllers\Api\V1\Admin\UserController::class, 'destroy'])->name('v1.admin.users.destroy');
+
+        // 상태 토글
+        Route::patch('users/{id}/status', [\App\Http\Controllers\Api\V1\Admin\UserStatusController::class, 'toggle'])->name('v1.admin.users.status.toggle');
+
+        // 소프트 삭제 복구
+        Route::post('users/{id}/restore', [\App\Http\Controllers\Api\V1\Admin\UserRestoreController::class, 'restore'])->name('v1.admin.users.restore');
+
+        // 역할 부여/해제
+        Route::post('users/{id}/roles',           [\App\Http\Controllers\Api\V1\Admin\UserRoleController::class, 'attach'])->name('v1.admin.users.roles.attach');
+        Route::delete('users/{id}/roles/{role}',  [\App\Http\Controllers\Api\V1\Admin\UserRoleController::class, 'detach'])->name('v1.admin.users.roles.detach');
+
+        // 비밀번호 초기화
+        Route::post('users/{id}/reset-password', [\App\Http\Controllers\Api\V1\Admin\UserPasswordController::class, 'reset'])->name('v1.admin.users.password.reset');
+    });