accura
476f8a0565
Spring Boot 3.5.0 + Java 21 기반 엔터프라이즈 프레임워크 - Auth: JWT, MFA/TOTP, OAuth2 SSO, PasswordPolicy, LoginHistory - RBAC: Role-Permission, DeptScope, Redis 캐시 - Approval: Handler 패턴 결재 엔진 - Notification: SSE 실시간 알림 - File: Local/Azure Blob/AWS S3/GCP Storage - DataSource: Multi-DB 라우팅 (MySQL/PG/Oracle/MSSQL) - Admin: Thymeleaf 11화면 콘솔 - Compat: WBX FastAPI 호환 (에러/페이징) - Flyway: 4종 DBMS 마이그레이션 - Scripts: install.bat/sh, deploy-prod.sh - Docs: 설치가이드(OnPremise/Cloud), 개발자가이드 PDF Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
11 KiB
11 KiB
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 | 결재 대기 |