feat: 근태관리/직원관리 API 구현

- AttendanceController, AttendanceService 추가
- EmployeeController, EmployeeService 추가
- Attendance 모델 및 마이그레이션 추가
- TenantUserProfile에 employee_status 컬럼 추가
- DepartmentService 트리 조회 기능 개선
- Swagger 문서 추가 (AttendanceApi, EmployeeApi)
- API 라우트 등록

app/Models/Tenants/TenantUserProfile.php

@@ -4,8 +4,18 @@
 
 use App\Models\Members\User;
 use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
 
 /**
+ * 테넌트별 사용자 프로필 (사원 정보)
+ *
+ * @property int $id
+ * @property int $tenant_id
+ * @property int $user_id
+ * @property int|null $department_id
+ * @property string $employee_status active|leave|resigned
+ * @property array|null $json_extra
+ *
  * @mixin IdeHelperTenantUserProfile
  */
 class TenantUserProfile extends Model
@@ -22,23 +32,133 @@ class TenantUserProfile extends Model
         'job_title_key',
         'work_location_key',
         'employment_type_key',
+        'employee_status',
         'manager_user_id',
         'json_extra',
-        'created_at',
-        'updated_at',
         'profile_photo_path',
         'display_name',
     ];
 
-    // 관계: users 테이블은 전역이라 App\Models\User 로 연결
-    public function user()
+    // =========================================================================
+    // 관계 정의
+    // =========================================================================
+
+    public function user(): BelongsTo
     {
         return $this->belongsTo(User::class, 'user_id');
     }
 
-    // 조직, 직급 등은 옵션/코드 참조 가능 (필요시 추가)
-    public function department()
+    public function department(): BelongsTo
     {
         return $this->belongsTo(Department::class, 'department_id');
     }
+
+    public function manager(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'manager_user_id');
+    }
+
+    // =========================================================================
+    // json_extra 헬퍼 메서드
+    // =========================================================================
+
+    /**
+     * json_extra에서 특정 키 값 가져오기
+     */
+    public function getJsonExtraValue(string $key, mixed $default = null): mixed
+    {
+        return $this->json_extra[$key] ?? $default;
+    }
+
+    /**
+     * json_extra에 특정 키 값 설정
+     */
+    public function setJsonExtraValue(string $key, mixed $value): void
+    {
+        $extra = $this->json_extra ?? [];
+        if ($value === null) {
+            unset($extra[$key]);
+        } else {
+            $extra[$key] = $value;
+        }
+        $this->json_extra = $extra;
+    }
+
+    /**
+     * 사원 정보 일괄 업데이트 (json_extra)
+     */
+    public function updateEmployeeInfo(array $data): void
+    {
+        $allowedKeys = [
+            'employee_code',
+            'resident_number',
+            'gender',
+            'address',
+            'salary',
+            'hire_date',
+            'rank',
+            'bank_account',
+            'work_type',
+            'contract_info',
+            'emergency_contact',
+            'education',
+            'certifications',
+        ];
+
+        $extra = $this->json_extra ?? [];
+        foreach ($allowedKeys as $key) {
+            if (array_key_exists($key, $data)) {
+                if ($data[$key] === null) {
+                    unset($extra[$key]);
+                } else {
+                    $extra[$key] = $data[$key];
+                }
+            }
+        }
+        $this->json_extra = $extra;
+        $this->save();
+    }
+
+    // =========================================================================
+    // json_extra Accessor (자주 사용하는 필드)
+    // =========================================================================
+
+    public function getEmployeeCodeAttribute(): ?string
+    {
+        return $this->json_extra['employee_code'] ?? null;
+    }
+
+    public function getHireDateAttribute(): ?string
+    {
+        return $this->json_extra['hire_date'] ?? null;
+    }
+
+    public function getAddressAttribute(): ?string
+    {
+        return $this->json_extra['address'] ?? null;
+    }
+
+    public function getEmergencyContactAttribute(): ?string
+    {
+        return $this->json_extra['emergency_contact'] ?? null;
+    }
+
+    // =========================================================================
+    // 스코프
+    // =========================================================================
+
+    public function scopeActive($query)
+    {
+        return $query->where('employee_status', 'active');
+    }
+
+    public function scopeOnLeave($query)
+    {
+        return $query->where('employee_status', 'leave');
+    }
+
+    public function scopeResigned($query)
+    {
+        return $query->where('employee_status', 'resigned');
+    }
 }