Enterprise Admin Studio - 아키텍처 설계 문서 (ARCHITECTURE.md)

1. 개요 (Overview)

Enterprise Admin Studio는 Windows 및 기업 인프라의 3대 핵심 컴포넌트인 Active Directory (AD DS), NetApp ONTAP 스토리지 (Qtree, Quota, Share), Microsoft SQL Server를 단일 화면에서 통합 모니터링 및 제어할 수 있는 모던 UI 기반의 관리 콘솔입니다.

본 프로젝트는 PowerShell 7 / Windows PowerShell 5.1과 .NET WPF (XAML) 기술을 기반으로 구축되었으며, 차후 엔터프라이즈 환경에서 필요 시 C# (.NET 8+ / WPF / WinUI 3) 환경으로의 100% 무손실 전환이 가능하도록 철저한 계층 분리(Separation of Concerns) 아키텍처를 채택했습니다.

2. 전체 시스템 구조도 (System Architecture)

flowchart TD
    subgraph Presentation_Layer ["Presentation Layer (UI/XAML)"]
        MW["MainWindow.xaml\n(Fluent Dark Frame, Sidebar Navigation, Mode Badge)"]
        Styles["Styles/Theme.xaml\n(Color Palette, Modern Controls, Icons)"]
        
        subgraph Views ["Views (Dynamic UserControls)"]
            V1["DashboardView.xaml\n(KPI Cards, Audit Grid)"]
            V2["ActiveDirectoryView.xaml\n(User Grid, Detail Inspector)"]
            V3["NetAppView.xaml\n(Qtree, Quota, CIFS/NFS Tabs)"]
            V4["SqlDatabaseView.xaml\n(DB Grid, T-SQL Console)"]
            V5["SettingsView.xaml\n(Endpoint Config, Diagnostic)"]
        end
    end

    subgraph Application_Core ["Application Core (PowerShell Routing & Cache)"]
        Entry["Start-App.ps1\n(Application Entrypoint & Event Dispatcher)"]
        Router["Page Navigator & ViewCache\n(Fast Instant Page Switching)"]
        Config["config.json & ConfigService.ps1\n(Persistent Configuration Engine)"]
    end

    subgraph Service_Layer ["Service / Business Logic Layer (Modules)"]
        AD_SVC["ADService.ps1\n[IActiveDirectoryService]"]
        NETAPP_SVC["NetAppService.ps1\n[INetAppStorageService]"]
        SQL_SVC["SqlService.ps1\n[ISqlServerService]"]
    end

    subgraph Infrastructure_Targets ["Target Enterprise Infrastructure"]
        DC["Active Directory Domain Controller\n(LDAP / LDAPS Port 389/636)"]
        ONTAP["NetApp ONTAP Cluster\n(REST API v2 / HTTPS 443)"]
        MSSQL["MS SQL Server Instance\n(TDS Protocol / TCP 1433)"]
    end

    MW --> Router
    Router --> Views
    Styles -.-> MW
    Styles -.-> Views
    
    Entry --> Router
    Entry --> Config
    
    Views --> AD_SVC
    Views --> NETAPP_SVC
    Views --> SQL_SVC

    AD_SVC --> DC
    NETAPP_SVC --> ONTAP
    SQL_SVC --> MSSQL

3. 계층별 상세 설계 (Layer Details)

3.1 Presentation Layer (XAML UI)

Fluent Modern Dark 테마:
- 배경: #0F172A (Slate Dark), 카드/사이드바: #1E293B, 액센트: #3B82F6 / #6366F1
- 표준 WPF 컨트롤 템플릿(Button, TextBox, RadioButton, DataGrid, TabControl, Border)을 모던 라운딩 처리
네이티브 아이콘 시스템:
- 외부 폰트 설치나 대용량 SVG 의존성 없이 Windows 10/11 기본 탑재 글꼴인 Segoe MDL2 Assets의 유니코드 글리프(예: , , ) 사용
Dynamic View Hosting:
- MainWindow.xaml 내 ContentControl x:Name="MainContentHost"에 각 View를 동적 인스턴스화
- ViewCache 해시테이블을 두어 최초 로드 후 페이지 전환 시 재파싱 비용을 제거하여 네이티브 수준의 부드러운 전환 구현

3.2 Service & Integration Layer (비즈니스 로직)

A. Active Directory 연동 (`ADService.ps1`)

기술 스택: Windows 기본 내장 .NET System.DirectoryServices
프로토콜: LDAP (Port 389) 또는 LDAPS (Port 636)
동작 원리:
1. DirectoryEntry를 통해 지정된 도메인 컨트롤러 또는 기본 도메인에 바인딩 (자격증명 지원)
2. DirectorySearcher를 이용해 (&(objectCategory=person)(objectClass=user)) 필터링 및 페이징(PageSize = 1000) 처리
3. 속성 매핑:
  - userAccountControl: 0x0002 비트 연산을 통한 활성/비활성 판정 및 변경
  - lockoutTime: 정수값을 통한 잠금 여부 확인 및 lockoutTime = 0 커밋을 통한 계정 잠금 해제
  - Invoke("SetPassword", ...): 안전한 비밀번호 초기화 및 pwdLastSet = 0 강제 변경 플래그
4. Fallback 메커니즘: AD 환경이 아닌 로컬 PC나 개발 환경에서는 자동으로 Mock 데이터 및 데모 시뮬레이션으로 안전하게 동작

B. NetApp ONTAP 스토리지 연동 (`NetAppService.ps1`)

기술 스택: NetApp ONTAP 9.6+ 표준 REST API (HTTPS RESTful)
엔드포인트 매핑:
- Qtree 관리: GET /api/storage/qtrees, POST /api/storage/qtrees
- Quota 한도/모니터링: GET /api/storage/quota/rules, GET /api/storage/quota/reports
- CIFS 파일 공유: GET /api/protocols/cifs/shares, POST /api/protocols/cifs/shares
- NFS 내보내기 정책: GET /api/protocols/nfs/export-policies
- 클러스터 상태 진단: GET /api/cluster
보안 및 인증: HTTP Basic Authentication 및 자체 서명 SSL 인증서 무시 처리(IgnoreSslErrors) 옵션 내장

C. MS SQL Server 연동 (`SqlService.ps1`)

기술 스택: .NET 기본 제공 System.Data.SqlClient
프로토콜: Tabular Data Stream (TDS, Port 1433)
동작 원리:
1. Windows 통합 인증(Integrated Security) 및 SQL Server 계정(User ID / Password) 인증 동시 지원
2. sys.databases, sys.master_files, msdb.dbo.backupset 카탈로그 뷰를 조인하여 실제 데이터베이스 상태, 용량, 복구 모델, 최종 Full 백업 일시 동적 집계
3. BACKUP DATABASE [{0}] TO DISK = '{1}' WITH INIT, STATS = 10 실제 데이터베이스 백업 수행
4. T-SQL 간이 쿼리 실행기: 사용자 입력을 파싱하여 SqlDataAdapter로 DataTable에 적재 후 결과 포맷팅

4. C# (.NET 8 / WPF / WinUI 3) 마이그레이션 로드맵

향후 C# 솔루션으로 승격(Promote) 시 100% 매핑되도록 설계되었습니다.

4.1 XAML 파일의 무수정 재사용

Views/*.xaml 및 Styles/Theme.xaml은 표준 WPF 문법을 준수합니다. C# 프로젝트에 그대로 포함하고 아래와 같이 코드 비하인드만 연결하면 됩니다:

namespace ModernAdminStudio.Views;

public partial class ActiveDirectoryView : UserControl
{
    public ActiveDirectoryView()
    {
        InitializeComponent();
    }
}

4.2 MVVM 및 DI (의존성 주입) 패턴 매핑

// Program.cs 또는 App.xaml.cs
services.AddSingleton<IActiveDirectoryService, ActiveDirectoryService>();
services.AddSingleton<INetAppStorageService, NetAppStorageService>();
services.AddSingleton<ISqlServerService, SqlServerService>();

services.AddTransient<DashboardViewModel>();
services.AddTransient<ActiveDirectoryViewModel>();
services.AddTransient<NetAppViewModel>();
services.AddTransient<SqlDatabaseViewModel>();
services.AddTransient<SettingsViewModel>();

4.3 서비스 인터페이스 정의서 (C# Blueprint)

public interface IActiveDirectoryService
{
    Task<IEnumerable<AdUserDto>> GetUsersAsync(string filter);
    Task<OperationResult> UnlockAccountAsync(string samAccountName);
    Task<OperationResult> ResetPasswordAsync(string samAccountName, string newPassword);
    Task<OperationResult> SetAccountStateAsync(string samAccountName, bool enable);
    Task<ConnectionResult> TestConnectionAsync();
}

public interface INetAppStorageService
{
    Task<IEnumerable<QtreeDto>> GetQtreesAsync(string svm);
    Task<IEnumerable<QuotaDto>> GetQuotasAsync(string svm);
    Task<IEnumerable<ShareDto>> GetSharesAsync(string svm);
    Task<OperationResult> CreateQtreeAsync(CreateQtreeRequest request);
    Task<OperationResult> CreateShareAsync(CreateShareRequest request);
    Task<ConnectionResult> TestConnectionAsync();
}

public interface ISqlServerService
{
    Task<IEnumerable<DatabaseInfoDto>> GetDatabasesAsync();
    Task<OperationResult> BackupDatabaseAsync(string databaseName, string targetPath);
    Task<QueryResultDto> ExecuteQuerySnippetAsync(string query);
    Task<ConnectionResult> TestConnectionAsync();
}

8.1 KiB Raw Blame History