# WBX Spring Core — 프로젝트 구조

```
wbx-spring-core/
├── build.gradle                        # Gradle 빌드 (Spring Boot 3.5, Java 21)
├── settings.gradle
├── gradlew / gradlew.bat               # Gradle Wrapper (별도 설치 불필요)
├── Dockerfile                          # 컨테이너 빌드 (Temurin 21 JRE Alpine)
├── docker-compose.yml                  # 프로덕션 (App + MySQL + Redis)
├── docker-compose-dev.yml              # 로컬 개발 인프라 (MySQL/PG + Redis)
├── .dockerignore
├── .editorconfig                       # IDE 공통 코드 스타일
├── .gitignore
├── .github/workflows/ci.yml            # GitHub Actions CI
│
├── docs/                               # ★ 문서
│   ├── 00-setup-guide.md               # 설치/배포 가이드
│   └── 01-project-structure.md         # 프로젝트 구조 (본 문서)
│
├── src/main/java/kr/co/accura/wbx/spring/
│   ├── WbxSpringCoreApplication.java   # 메인 (@SpringBootApplication)
│   ├── HealthController.java           # GET /health
│   │
│   ├── auth/                           # 인증 (18파일)
│   │   ├── WbxUser.java                # 사용자 Entity
│   │   ├── WbxUserDetails.java         # Spring Security UserDetails
│   │   ├── WbxUserRepository.java
│   │   ├── AuthController.java         # login/register/me/refresh/logout/mfa
│   │   ├── JwtProvider.java            # JWT 발급/검증 (WBX 호환)
│   │   ├── JwtFilter.java              # Bearer Token 필터
│   │   ├── ApiKeyFilter.java           # X-API-Key 서버-서버 인증
│   │   ├── PasswordPolicy.java         # 비밀번호 규칙 검증
│   │   ├── RefreshTokenService.java    # Refresh Token 관리
│   │   ├── WbxRefreshToken.java        # Entity
│   │   ├── RefreshTokenRepository.java
│   │   ├── WbxLoginHistory.java        # 로그인 이력 Entity
│   │   ├── LoginHistoryRepository.java
│   │   ├── MfaService.java             # TOTP 생성/검증/백업코드
│   │   ├── MfaController.java          # MFA setup/verify/disable
│   │   ├── WbxTotpSecret.java          # TOTP 시크릿 Entity
│   │   ├── TotpSecretRepository.java
│   │   └── SsoSuccessHandler.java      # Azure Entra OAuth2 성공 핸들러
│   │
│   ├── rbac/                           # 권한 (7파일)
│   │   ├── DeptScope.java              # OWN/DEPT/COMPANY + toSpec()
│   │   ├── PermissionEvaluator.java    # @wbx.check()
│   │   ├── WbxRole.java               # 역할 Entity
│   │   ├── WbxUserRole.java           # 사용자-역할 매핑
│   │   ├── WbxUserRoleRepository.java
│   │   ├── RolePermission.java         # 역할-권한
│   │   └── RolePermissionRepository.java
│   │
│   ├── approval/                       # 결재 엔진 (9파일)
│   │   ├── ApprovalHandler.java        # 핸들러 인터페이스
│   │   ├── ApprovalHandlerRegistry.java # 자동 수집 Registry
│   │   ├── UnifiedApprovalController.java # 통합 API
│   │   ├── ApprovalCompletedEvent.java # Spring Event
│   │   ├── ApprovalResult.java         # 결과 DTO
│   │   ├── ApprovalHistoryDto.java
│   │   ├── ApprovalLineDto.java
│   │   ├── ApprovalPendingDto.java
│   │   └── ActionRequest.java
│   │
│   ├── notification/                   # 알림 (4파일)
│   │   ├── SseNotificationService.java # SSE 실시간 알림
│   │   ├── NotificationController.java # /notifications/stream
│   │   ├── Notification.java           # Entity
│   │   └── NotificationDto.java
│   │
│   ├── audit/                          # 감사 로그 (3파일)
│   │   ├── AuditLogService.java
│   │   ├── WbxAuditLog.java
│   │   └── AuditLogRepository.java
│   │
│   ├── file/                           # 파일 스토리지 (6파일)
│   │   ├── FileStorageService.java     # 인터페이스 (upload/download/delete/getPresignedUrl)
│   │   ├── LocalFileStorageService.java # 로컬 구현
│   │   ├── AzureBlobStorageService.java # Azure Blob (SAS Token)
│   │   ├── AwsS3StorageService.java    # AWS S3
│   │   ├── GcpStorageService.java      # GCP Cloud Storage
│   │   └── WbxFileUpload.java          # Entity
│   │
│   ├── datasource/                     # Multi-DataSource (4파일)
│   │   ├── DataSource.java             # @DataSource 어노테이션
│   │   ├── WbxRoutingDataSource.java   # ThreadLocal 기반 라우팅
│   │   ├── DataSourceAspect.java       # AOP
│   │   └── MultiDataSourceConfig.java  # Bean 설정
│   │
│   ├── compat/                         # WBX 호환 (2파일)
│   │   ├── WbxErrorHandler.java        # detail 키 에러
│   │   └── WbxPaginationConfig.java    # skip/limit → Pageable
│   │
│   ├── config/                         # 설정 (5파일)
│   │   ├── WbxSpringProperties.java    # wbx.spring.* 설정
│   │   ├── SecurityAutoConfig.java     # 2 FilterChain (Admin+API+SSO)
│   │   ├── CorsAutoConfig.java
│   │   ├── OpenApiConfig.java          # Swagger
│   │   └── WbxSystemConfig.java        # K-V 설정 Entity
│   │
│   ├── common/                         # 공통 (4파일)
│   │   ├── BaseEntity.java             # JPA Auditing
│   │   ├── BusinessException.java
│   │   ├── NotFoundException.java
│   │   └── SecurityUtils.java
│   │
│   └── admin/                          # 관리자 (6파일)
│       ├── AdminViewController.java    # Thymeleaf 11화면 + 25 엔드포인트
│       ├── AdminLoginController.java   # /admin/login
│       ├── AdminUserDetailsService.java # 폼 로그인 인증
│       ├── AdminController.java        # Admin REST API
│       ├── WbxRoleRepository.java
│       └── WbxSystemConfigRepository.java
│
├── src/main/resources/
│   ├── application.yml                 # 메인 설정 (로컬 개발)
│   ├── application-prod.yml            # 프로덕션 (Flyway, 로깅)
│   ├── application-mysql.yml           # MySQL 프로필
│   ├── application-postgresql.yml      # PostgreSQL 프로필
│   ├── application-oracle.yml          # Oracle 프로필
│   ├── application-mssql.yml           # MSSQL 프로필
│   ├── application-azure.yml           # Azure (SSO + Blob)
│   ├── application-aws.yml             # AWS (Cognito + S3)
│   ├── application-test.yml            # 테스트 (H2 인메모리)
│   ├── templates/admin/                # Thymeleaf 템플릿 (12화면)
│   │   ├── login.html
│   │   ├── dashboard.html
│   │   ├── users.html
│   │   ├── user-detail.html
│   │   ├── roles.html
│   │   ├── role-detail.html
│   │   ├── permissions.html
│   │   ├── login-history.html
│   │   ├── audit-logs.html
│   │   ├── config.html
│   │   ├── system-health.html
│   │   └── fragments.html              # 사이드바 공통
│   ├── static/admin/css/admin.css      # Admin UI 스타일
│   └── db/migration/                   # Flyway SQL (4종 DBMS)
│       ├── common/
│       │   ├── V001__seed_roles.sql
│       │   └── V002__seed_system_config.sql
│       ├── mysql/V001__create_tables.sql
│       ├── postgresql/V001__create_tables.sql
│       ├── oracle/V001__create_tables.sql
│       └── mssql/V001__create_tables.sql
│
└── src/test/java/                      # 테스트
```

## 패키지별 요약

| 패키지 | 파일 | 핵심 |
|--------|:----:|------|
| auth | 18 | JWT, Login, Register, Refresh, Password, ApiKey, MFA/TOTP, SSO, LoginHistory |
| rbac | 7 | DeptScope, PermissionEvaluator(@wbx), Role, UserRole, Permission |
| approval | 9 | Handler(interface), Registry, UnifiedController, Event |
| notification | 4 | SSE, Controller, Entity |
| audit | 3 | AuditLogService, Entity |
| file | 6 | StorageService(interface), Local, Azure, AWS, GCP |
| datasource | 4 | @DataSource, RoutingDataSource, AOP, MultiConfig |
| compat | 2 | ErrorHandler, Pagination |
| config | 5 | Properties, Security, CORS, OpenAPI, SystemConfig |
| common | 4 | BaseEntity, Exception, SecurityUtils |
| admin | 6 | Thymeleaf Admin Console (12화면, 24 엔드포인트) |
| **합계** | **70** | |

## DB 테이블 (11개, Hibernate 자동 생성 / Flyway 마이그레이션)

| 테이블 | Entity | 용도 |
|--------|--------|------|
| wbx_users | WbxUser | 사용자 (SSO, MFA 필드 포함) |
| wbx_roles | WbxRole | 역할 |
| wbx_user_roles | WbxUserRole | 사용자-역할 |
| wbx_role_permissions | RolePermission | 역할-권한 (module+action+scope) |
| wbx_refresh_tokens | WbxRefreshToken | JWT 갱신 토큰 |
| wbx_totp_secrets | WbxTotpSecret | MFA TOTP 시크릿 (AES 암호화) |
| wbx_login_history | WbxLoginHistory | 로그인 이력 |
| wbx_notifications | Notification | 알림 |
| wbx_audit_logs | WbxAuditLog | 감사 로그 |
| wbx_file_uploads | WbxFileUpload | 파일 이력 |
| wbx_system_config | WbxSystemConfig | 시스템 설정 (K-V) |

## REST API

| Method | Path | 인증 | 설명 |
|--------|------|:---:|------|
| GET | /health | - | 헬스 체크 |
| POST | /api/auth/login | - | 로그인 → JWT (MFA 분기) |
| POST | /api/auth/register | - | 회원가입 |
| GET | /api/auth/me | JWT | 내 정보 |
| PUT | /api/auth/password/change | JWT | 비밀번호 변경 |
| POST | /api/auth/refresh | - | 토큰 갱신 |
| POST | /api/auth/logout | JWT | 로그아웃 |
| POST | /api/auth/mfa/verify | - | MFA 2단계 검증 |
| POST | /api/auth/mfa/setup | JWT | MFA 설정 시작 (QR) |
| POST | /api/auth/mfa/setup/verify | JWT | MFA 활성화 + 백업코드 |
| DELETE | /api/auth/mfa | JWT | MFA 비활성화 |
| POST | /api/auth/mfa/backup-verify | - | 백업코드 인증 |
| GET | /api/notifications/stream | JWT | SSE 실시간 알림 |
| GET | /api/notifications/unread-count | JWT | 미읽음 수 |
| POST | /api/approvals/unified/action/{type}/{id}/approve | JWT | 결재 승인 |
| POST | /api/approvals/unified/action/{type}/{id}/reject | JWT | 결재 반려 |
| GET | /api/approvals/unified/pending | JWT | 결재 대기 |