diff --git a/SPMS.API/Documents/CleanArchitecture.png b/SPMS.API/Documents/CleanArchitecture.png new file mode 100644 index 0000000..dba728c Binary files /dev/null and b/SPMS.API/Documents/CleanArchitecture.png differ diff --git a/SPMS.API/Documents/GitFlow.md b/SPMS.API/Documents/GitFlow.md new file mode 100644 index 0000000..9a1a38f --- /dev/null +++ b/SPMS.API/Documents/GitFlow.md @@ -0,0 +1,219 @@ +# 1. Branching Model (Git-Flow 방식) + +- 각 브랜치는 사용하는 시점에서 생성을 하고 이슈가 해결(PR까지 완료) 된 경우 제거한다. + - 단, main, develop 브랜치는 **절대 삭제하지 않는다**. + +## 1.1. 브랜치 명명 규칙 + +- 형식 : 타입`/#이슈번호-작업요약` +- 규칙 + - `/` : 브랜치를 폴더 구조로 묶어준다. + - `-` : 단어 사이를 연결하며, 띄어쓰기는 금지한다. + - `#` : 이슈 추적을 위해 이슈 번호를 명시한다. + - **영문 소문자**만 사용한다.(한글 금지) +- 예시 + - feature/#1-admin-login + - fix/#20-jwt-error +- 예외 + - main, develop 브랜치의 명칭은 변하지 않는다. + - release 브랜치는 `release/v버전` 의 형식으로 작성한다. + +## 1.2. 브랜치 전략표 + +| 타입 | 의미 | 브랜치 명 예시 | 생성위치 | +| --- | --- | --- | --- | +| main | 배포 가능 최신 상용 상태 | main | - | +| develop | 다음 배포를 위한 통합 브랜치 | develop | - | +| feature | 새로운 기능 개발 | feature/#1-admin-login | develop | +| fix | 개발 중 버그 수정 | fix/#20-jwt-error | develop, release | +| refactor | 기능 변경 없는 코드 개선 | refactor/#13-folder-structure | develop | +| hotfix | [긴급] 운영 서버 버그 수정 | hotfix/#99-prd-db-error | main | +| release | 배포 버전 준비 | release/v1.0.0 | develop | + +## 1.3. Branch Life Cycle + +### 1.3.1. ***준비 과정*** + +- main / develop 브랜치 생성 및 초기화 + +### 1.3.2. ***개발 과정*** + +1. develop 에서 feature 브랜치 생성해 개발한다. (이슈 생성 필수) +2. 개발 완료 후 devlop으로 **커밋 > PR > 머지**를 수행한다. +3. 개발 중 발견된 버그는 develop에서 fix 브랜치를 생성하여 수정한다. (이슈 생성 필수) +4. 위 과정을 반복하다 배포 스펙이 완성되면 배포 준비 단계로 넘어간다. + +### 1.3.3. ***배포 준비 과정*** + +1. develop 에서 `release/vX.X.X` 브랜치를 생성한다. (Code Freeze 상태) + - 이후 develop 에서는 다음 버전을 위한 개발을 진행해도 된다. +2. QA 중 발견된 버그는 release 브랜치에서 fix 브랜치를 생성해 release에 직접 커밋한다. (이슈 생성 필수) +3. 최종 테스트가 완료되면 배포 단계로 넘어간다. + +### 1.3.4. ***배포 과정*** + +1. 정기 배포: + - release 브랜치를 main 에 머지하고 해당 버전에 대한 태그를 붙인다. + - 배포가 완료되면 release 브랜치를 develop 에 백머지(back-merge)하여 변경 사항을 동기화한다. + - 두 브랜치에 머지가 완료되면 release 브랜치는 **삭제**한다. +2. 긴급 배포 + - main 에서 hotfix 브랜치를 생성하여 버그를 수정한다. (이슈 생성 필수) + - 검증 원칙 + - hotfix 브랜치는 main 에 머지하기 전에 반드시 **로컬 테스트**와 **스테이징 검증**을 통과해야 한다. + - 검증과정에서 발생하는 수정 사항은 오직 hotfix 브랜치 내부에서만 커밋한다. + - 검증이 완료되기 전까지는 절대 main 브랜치에 PR을 머지하지 않는다. + - 배포 및 동기화 + - 검증이 완료되면 main 에 머지하고 해당 버전에 대한 태그를 붙인다. (버전 patch 상승) + - 동시에 develop 에도 백머지(back-merge)를 수행하여 다음 버전 개발에 반영되게 변경 사항을 동기화한다. + - 모든 작업이 완료되면 hotfix 브랜치는 **삭제**한다. + +# 2. Commit Message + +- 형식: `타입: 설명 (이슈번호)` + - 타입: [2.1. Commit Type](https://www.notion.so/Git-Version-Control-2ed4d57b3bf0805cb29fff784579d427?pvs=21) 참고 + - 설명: 언어 상관없이 편하게 내용 작성 + - 이슈번호 + - 일반: 해당 커밋이 어떠한 이슈의 참조인지 알려준다. (예: feat: 로그인 구현(#1)) + - 동작: 해당 커밋이 연결된 이슈의 상황을 변경함 (PR 작성시 확인) + 1. Close, Closes, Closed : 해당 커밋을 끝으로 이슈 닫기 (예: feat: 로그인 구현(Closes #1)) + 2. Fix, Fixes, Fixed : 해당 커밋을 끝으로 버그 수정되어 이슈 닫기 (예: fix: DB 예외 처리(Fixes #21)) + 3. Resolve, Resolves, Resolved : 무언가 해결이 되어 이슈 닫기 (예: feat: 푸시 구현(Resolves #13)) + +## 2.1. Commit Type + +- 커밋의 메시지는 [Conventional Commits](https://www.conventionalcommits.org/ko/v1.0.0/) 의 규칙을 따른다. + +> 커밋 메시지만 보고 소프트웨어의 버전을 올릴 수 있게 하자. +> +- 소프트웨어 버전은 `Major.Minor.Patch` 로 보통 세자리로 구성이 되는데 커밋 메시지만 보고도 세 자리 중 어디를 올려야 하는지에 대한 가이드이다. (초기 배포 시점의 계산이 아니라 배포 후 부터 계산한다.) + +### **2.1.1. fix** + +- 상황: 로직상의 오류, 오타, 크래시 등을 수정했으나 기능 명세는 변하지 않았다. +- 커밋: `fix: 화면 오타 수정 (Fixes #23)` +- 브랜치 + - `hotfix` 브랜치: 이미 배포된 버전을 긴급 수정하는 것이므로 배포 시 `Patch 버전이 상승` 한다. + - `fix` 브랜치: 다음 버전을 출시 하기 위한 안정화 과정이므로 버전 숫자는 변하지 않는다. + - `feature` / `develop` 브랜치: 다음 버전을 출시 하기 위한 개발 과정이므로 버전 숫자는 변하지 않는다. + +### **2.1.2. feat** + +- 상황: 기획대로 새로운 기능이 코드에 추가되었다. +- 커밋: `feat: 외부 결제 추가 (Closes #34)` +- 브랜치 + - `feature` 브랜치: 오직 이 브랜치에서만 사용한다. 당장 버전이 변하지는 않지만 이후 배포가 되면 `Minor 버전 상승` 의 근거가 된다. + +### **2.1.3. BREAKING CHANGE** + +- 상황: 이전 버전과 완전 호환되지 않는 기술적인 변경이 발생한다. +- 커밋: `feat!: 유저 API 전체 변경` (해당 타입의 뒤에 `!`를 붙인다.) +- 브랜치 + - `feature` 브랜치: 다음 버전을 위한 대공사이므로 개발 단계에서 수행한다. + - 다른 브랜치: 선언 불가 + - feature > develop > release > main 으로 머지 되면 `Major 버전이 상승` 한다. +- 해당 타입은 다른 타입에 붙어서 사용되므로 독자적으로 사용되지는 않는다. + +--- + +### **2.1.4.** test + +- 상황 + 1. 새로운 테스트 코드 작성할 때 + 2. 기존 테스트 코드에 문제가 있어 테스트 코드만 수정할 때 (기능의 수정은 이루어지지 않는다.) + 3. 테스트 데이터를 수정하거나 리팩토링 할 때 +- 커밋: `test: 로그인 API 테스트` +- 브랜치 + - 개발 수정 가능한 모든 브랜치 어디서든 사용 가능하다. + +### **2.1.5.** chore + +- 상황: 소스 코드는 건드리지 않고 빌드 설정, 패키지 업데이트, 라이브러리 설치 등을 수정했다. +- 커밋: `chore: JSON 패키지 업데이트` +- 브랜치 + - 개발 수정 가능한 모든 브랜치 어디서든 사용 가능하다. + +### **2.1.6.** refactor + +- 상황: 기능과 결과는 100% 동일하지만 내부 코드 구조를 개선하거나 성능을 최적화했다. +- 커밋: `refactor: 로그인 화면 개편` +- 브랜치 + - `feature` / `refactor` 브랜치: 주로 개발 단계에서 사용한다. + - `fix` 브랜치: 사용은 가능하나 브랜치의 역할이 다르니 최소한으로 사용한다. + - 다른 브랜치: 선언 불가 + +### **2.1.7.** style + +- 상황: 코드의 동작과 전혀 상관없는 띄어쓰기, 줄 바꿈, 들여쓰기 등을 수정했다. +- 커밋: `style: 불필요한 공백 제거` +- 브랜치 + - 개발 수정 가능한 모든 브랜치 어디서든 사용 가능하다. +- 표 + + | **브랜치 (Branch)** | **feat** | **fix** | **BREAKINGCHANGE** | **test / chore / style** | **refactor** | **비고 (Note)** | + |:-----------------:|:-----------------:|:-----------------:|:------------------:|:------------------------:|:-----------------:|:----------------------------------------| + | **main** | ❌ | ❌ | ❌ | ❌ | ❌ | **Merge Only**
(직접 커밋 금지) | + | **develop** | ❌ | ❌ | ❌ | ❌ | ❌ | **Merge Only**
(직접 커밋 금지) | + | **feature/...** | **⭕**
**(주력)** | ⭕
(자체수정) | **⭕**
**(가능)** | ⭕ | ⭕ | 모든 작업이 가능한 **자유 구역** | + | **fix/...** | ❌ | **⭕**
**(주력)** | ❌ | ⭕ | 🔺
(최소한) | 기능 추가 절대 금지
테스트 보강 가능 | + | **hotfix/...** | ❌ | **⭕**
**(주력)** | ❌ | ⭕ | ❌ | **[긴급]** 긴급 수정 및
검증용 테스트만 허용 | + | **release/...** | ❌ | **⭕**
**(주력)** | ❌ | ⭕ | ❌ | **[배포전]** 안정화 및
검증용 테스트만 허용 | + | **refactor/...** | ❌ | ❌ | ❌ | ⭕ | **⭕**
**(주력)** | 동작 변경 금지 (fix 불가)
기능 추가 금지 (feat 불가) | + +--- + +# 3. Pull Request(PR) Message + +- 프로젝트 최상단 폴더에 `.gitea/pull_request_template.md` 혹은 `.github/` 폴더에 저장하면 PR 생성시 자동으로 내용이 채워진다. +- 타이틀 + - PR 은 결국 main 이나 develop 브랜치의 커밋이 되기에 타이틀은 [2. Commit Message](https://www.notion.so/Git-Version-Control-2ed4d57b3bf0805cb29fff784579d427?pvs=21)를 따라서 작성한다. + - 형식: `타입: 작업한 커밋들 요약 설명 (이슈번호)` +- 본문 + + ```markdown + ## 📋 작업 요약 + - {작업 3줄 요약} + + ## 🔗 관련 이슈 (Related Issues) + Closes # + + ## 🛠️ 작업 내용 (Changes) + - [ ] {작업 내용 1} + - [ ] {작업 내용 2} + + ## 📢 리뷰어 참고 사항 (To Reviewers) + - 없을시 비워둠 + - {리뷰어 참고 사항} + + ## ✅ 체크리스트 (Self Checklist) + - [ ] 빌드(Build)가 성공적으로 수행되었는가? + - [ ] 모든 단위 테스트(Unit Test)를 통과하였는가? + - [ ] 불필요한 로그나 주석을 제거하였는가? + - [ ] 컨벤션(Clean Architecture, Naming)을 준수하였는가? + - [ ] 기밀 정보(비밀번호, 키 등)가 하드코딩 되어있지 않은가? + + ## 📸 스크린샷 / 테스트 로그 (Screenshots/Logs) + - 없을시 비워둠 + ``` + // 테스트 로그 작성 + ``` + ``` + + +--- + +# 4. 태그(Tag)를 붙이는 2가지 타이밍 + +- 태그(Tag)는 개발자가 코드에 찍는 **최종 승인 도장**으로, 아무때나 찍는 게 아니라 사용자에게 배포되는 버전 번호가 확정되는 순간에만 작성한다. +- 태그는 오직 main 브랜치에 코드가 머지된 직후에만 붙이는 것을 원칙으로 한다. + +## 4.1. 정기 배포 + +- 상황: release/v1.0.0 브랜치에서 모든 QA를 끝내고 main 브랜치에 PR 후 merge 진행 +- 버전: v1.0.0 → v1.1.0 +- 태그: v1.1.0 + +## 4.2. 긴급 배포 + +- 상황: hotfix/… 브랜치에서 main에서 발생한 급한 오류를 해결하고 main 브랜치에 PR 후 merge 진행 +- 버전: v1.1.0 → v1.1.1 +- 태그: v1.1.1 \ No newline at end of file diff --git a/SPMS.API/Documents/ProjectRule.md b/SPMS.API/Documents/ProjectRule.md deleted file mode 100644 index bb0a732..0000000 --- a/SPMS.API/Documents/ProjectRule.md +++ /dev/null @@ -1,54 +0,0 @@ -## 기술 스택 -| 기술 | 스택 | -|:------------------|:------------------------| -| Framework | .NET 9.0 / ASP.NET Core | -| Database | MariaDB | -| ORM | Entity Framework Core | -| API Documentation | Swagger | -| Logging | Serilog | - -## 프로젝트 구조 -프로젝트는 다음과 같은 구조로 구성되어 있다. - -### Clean Architecture -- 프로젝트는 클린 아키텍처(Clean Architecture)를 기반으로 설계한다. -- 의존성 방향은 **항상 `외부`에서 `내부`** 로 향한다. - - 외부 : DB, UI, API 등 - - 내부 : 비즈니스 로직, 도메인, 애플리케이션 서비스 등 -- - -### 폴더 구조 -```plaintext -SPMS.Server/ -├── 1.Domain/ # 순수 비즈니스 영역 : 외부 의존성 절대 금지! -│ ├── Entities/ # DB 테이블과 매핑될 핵심 객체 (Service, Device, Log...) -│ ├── Enums/ # OsType, SendStatus, TargetType 등 -│ ├── Constants/ # 시스템 전역 상수 (에러 메시지 등) -│ └── Exceptions/ # 비즈니스 로직 전용 예외 (BusinessException) -│ -├── 2.Application/ # [중재자] 흐름 제어 및 인터페이스 정의 -│ ├── Common/ # 공통 응답 포맷 (ResultWrapper, PagedResult) -│ ├── DTOs/ # Request/Response 모델 (서비스 간 데이터 전달용) -│ ├── Interfaces/ # 구현체가 없는 설계도 모음 -│ │ ├── Services/ # IServiceService, IPushService -│ │ ├── Repositories/ # IServiceRepository (DB 접근용 인터페이스) -│ │ └── Infra/ # ICryptoHelper, IFcmClient (외부 기술 인터페이스) -│ └── Services/ # 비즈니스 로직 구현체 (ServiceService, PushService) -│ # 주의: 여기서는 DB나 암호화 라이브러리를 직접 쓰지 않고 '인터페이스'만 주입받아 씀 -│ -├── 3.Infrastructure/ # 실제 기술 구현 (DB, 암호화, FCM) -│ ├── Persistence/ # DB 관련 -│ │ ├── Context/ # AppDbContext (EF Core 설정) -│ │ └── Repositories/ # ServiceRepository (실제 쿼리 수행) -│ ├── Security/ # 암호화/인증 구현 (AesHelper, RsaHelper, JwtGenerator) -│ └── External/ # 외부 시스템 연동 (FcmClient, ApnsClient) -│ -├── 4.Presentation/ # 외부와 연결 -│ ├── Controllers/ # API 엔드포인트 -│ ├── Middlewares/ # GlobalExceptionHandling, Logging -│ └── Filters/ # 권한 체크 등 (AuthFilter) -│ -├── appsettings.json -├── appsettings.Development.json -└── Program.cs -```아 \ No newline at end of file diff --git a/SPMS.API/Documents/ServerDevelopmentGuide.md b/SPMS.API/Documents/ServerDevelopmentGuide.md new file mode 100644 index 0000000..edc31cf --- /dev/null +++ b/SPMS.API/Documents/ServerDevelopmentGuide.md @@ -0,0 +1,326 @@ +# 1. 기술 스택 및 환경 +| 기술 | 스택 | +|:----------|:------------------------------------| +| Framework | .NET 9.0 / ASP .NET Core | +| Database | MariaDB (Server Version AutoDetect) | +| ORM | Entity Framework Core (Code-First) | +| API Docs | Swagger (OpenAPI) | +| Cache | Redis | +| MQ | RabbitMQ | +| Logging | Serilog | +| Testing | xUnit, Moq | + +--- +# 2. 코드 컨벤션 +## 2.1. 명명 규칙 +- PascalCase (대문자 시작): 클래스명, 메서드명, 프로퍼티명, 파일명, public 필드 +- camelCase (소문자 시작): 로컬 변수, 매개 변수 +- _camelCase (언더바 시작): private 필드 +- Interface 는 반드시 접두사 `I` 를 붙인다. +- 비동기 메서드는 접미사 `Async` 를 붙인다. + +## 2.2. 문법 규칙 + +- `var` 사용: 자료형을 명확하게 우변에서 확인 가능할 경우에는 var를 적극 사용한다. + - 리턴 타입이 뭔지 모르는 경우에는 명시를 해준다. + ```csharp + var user = new User(); // 가능 + + var count = GetCount(); // 불가능 + int count = GetCount(); // 리턴 타입을 명시해줄 것 + ``` +- 비동기(Asnyc/Await) 동작: I/O 작업(DB, API호출, 파일)은 **무조건 비동기**로 작성한다. + - 비동기 동작을 하는 메서드의 이름 뒤에는 `Asnyc` 를 붙인다. + - void 대신 `Task` 또는 `Task`를 반환한다. +- LINQ: 가독성을 해치지 않는 선에서 적극 사용하되, 복잡한 쿼리는 쿼리 구문이나 분할 작성 할 것 +- 주석 및 문서화 (Swagger): API 정의서와의 동기화를 위해 Controller와 DTO의 모든 Public 멤버에는 반드시 XML 주석(`/// `)을 작성해야 한다. + +- + +--- + +# 3. 아키텍쳐 및 개발 표준 + +## 3.1. 개요 + +- 의존성의 방향은 항상 외부에서 내부로만 향한다. +- 프로젝트 분리: 프로젝트는 클린 아키텍쳐를 기반으로 하여 물리적으로 4개의 .csproj 로 분리해 참조 규칙을 **강제**한다. +

+- 클린 아키텍쳐 샘플 이미지 + ![CleanArchitecture.png](CleanArchitecture.png) + +## 3.2. 계층 구조 (Layers) +- 계층의 정의는 내부에서 외부 순서로 정의한다. + +### 3.2.1. 계층 (Layers) + +#### 1. Domain (Entities, Enterprise Business Rules) +- 역할: 비즈니스의 핵심 개념, 기업 업무 규칙(Entity)을 정의한다. +- 특징: 외부 라이브러리 (DB, Web, 등)에 대한 의존성이 **없어야** 한다. 순수한 C# 클래스로만 구성된다. +- 요소: Entites, Value Objects, Enums, Domain Exceptions, Repository Interfaces (선택) +#### 2. Application (Use cases, Application Business Rules) +- 역할: 애플리케이션의 비즈니스 로직을 처리하고 도메인과 외부를 연결하는 오케스트레이션 담당한다. +- 특징: 도메인 계층에만 의존하며, 인터페이스를 정의하고 구현은 외부 계층(Infra Structure)에 맡긴다. +- 요소: Service Interfaces, DTOs, Mappers, Validators, Service, Implementations (pure 로직) +#### 3. Infra Structure (Interface Adapters) +- 역할: 애플리케이션 계층에서 정의한 인터페이스를 실제로 구현한다. DB, 외부 API, 파일 시스템 등 외부 세계와 통신한다. +- 특징: 애플리케이션과 도메인을 참조하고 다양한 라이브러리를 사용한다. +- 요소: Repository 구현체, DB Context, 외부 API Client, Migrations +#### 4. Presentation (Frameworks & Drivers) +- 역할: 사용자의 요청(HTTP)을 받아 애플리케이션 계층으로 전달하고 결과를 반환한다. +- 특징: 로직을 가지지 않으며 애플리케이션에 의존한다. +- 요소: Controller, Middlewares, Filters, Program.cs (DI 설정) + +### 3.2.2. 프로젝트 참조 규칙 +- 프로젝트 내에서 참조 설정을 시스템 상에서 해줘서 파일들 간의 물리적인 연결 고리를 룰에 맞게 설정해 줘야 한다. + - Domain: 참조 없음 + - Application: Domain + - Infra Structure: Application, Domain + - Presentation: Application, Infra Structure + +## 3.3. 개발 상세 가이드 + +### 3.3.1. API 프로토콜 및 데이터 규격 +- 클라이언트와 서버 간의 모든 통신은 아래 정의된 Header와 Body 규격을 준수해야 한다. +#### 1. 요청 규격 (Request) +- 클라이언트는 API 호출 시, HTTP Header에 다음 필수 메타데이터를 포함해야 한다. + - 메타데이터들은 로그 컨텍스트 식별을 위해 평문으로 전송한다. + +| 헤더 명 | 설명 및 용도 | 예시 | +| --- |-------------------------------------| --- | +| Content-Type | 전송 데이터 포맷 | application/octet-stream | +| Authorization | JWT 인증 토큰
- L2 등급 이상 필수 | Bearer abcdefg… | +| X-API-KEY | 프로젝트 식별 및 데이터 격리를 위한 고유 키 (테넌트 식별자) | spms_api_custom_key | +| X-Request-ID | 트랜잭션 추적 ID
- 매요청 마다 고유값 생성
- 재사용 금지 | abcdefg-12aa… | + +#### 2. 응답 규격 (Response) +- 서버는 비즈니스 로직의 결과와 상관 없이 항상 아래의 공통 JSON포맷으로 응답한다. + - 단, Body의 내용물인 data 필드는 보안 등급에 따라 암호화될 수 있다. + ```json + { + "req_id": "abcdefg-12aa…", "result": "success", "code": "0000", "msg": "Response Success MESSAGE", "data": { ... } } + ``` - req_id: 요청 헤더의 X-Request-ID를 그대로 반환 (없을 경우 서버 생성), 비동기 응답 식별용 + - result: API 호출 결과에 따라 성공(success) / 실패(fail) 여부 반환 + - code: API 명세서에 선언된 코드 값 반환 (성공시 0000) + - msg: 현재 동작에 대한 결과 메시지 반환 + - data: 현재 동작에 대한 데이터 반환 (E2EE 적용시 암호화된 문자열) + +#### 3. 데이터 매핑 원칙 +- Entity 노출 금지 (Layer: Domain) + - DB 테이블과 매핑되거나 핵심 로직을 가진 객체로, **절대** Controller 밖으로 노출하지 않는다. +- DTO 필수 (Layer: Application): 데이터 전송을 위한 껍데기 객체 + - Controller는 반드시 `Request DTO` 를 받고 `Response DTO` 를 반환해야 한다. + - API 스펙 변경이 도메인 모델에 영향을 주어서는 안되며 그 반대의 경우도 마찬가지이다. +- Body 암호화 정책 + - [3.3.8. 보안 정책](#338-데이터-보안-및-암호화)에 의거 **L3**등급 이상의 data 필드는 암호화된다. + +### 3.3.2. 비즈니스 로직과 의존성 주입 (DI) +#### 1. 비즈니스 로직 위치 +- 단순 데이터 조회 / 저장 + - Repository (Layer: Infra Structure)에서 담당하되, 내부 구현 로직이 없어야 한다. +- 업무 규칙 (유효성 검사, 계산, 흐름 제어) + - 반드시 Service (Layer: Application) 또는 Entity (Layer: Domain) 내부에 위치해야 한다. +- Controller + - 요청을 받고 Service를 호출하고 결과를 DTO로 변환하는 역할만 수행한다. +#### 2. 의존성 역전 원칙 (DIP) +- Interface 정의(Layer: Application) + - 특정한 동작에 대한 정의서를 Application 계층에서 선언한다. + - 예: 유저 정보를 저장하는 기능의 필요 = IUserRepository +- 구현(Layer: Infra Structure) + - 해당 동작의 특별한 동작 구현을 Infra Structure 계층에서 구현한다. + - 예: 저장 기능을 EF Core로 구현 = UserRepository +- 주입 (Layer: Presentation) + - Program.cs 에서 DI를 통해 둘을 연결해준다. + - 예: builder.Services.AddScoped(); + +### 3.3.3. 데이터베이스 접근 (EF Core) +1. Code-First + - C# 엔티티 코드가 메인이 되며 Migration 명령어로 DB를 업데이트 한다. +2. Fluent API 사용 + - Entity 클래스의 순수성을 위해 [Key], [Table] 과 같은 어트리뷰트 대신 DbContext 내 OnModelCreating 또는 별도의 IEntityTypeConfiguration 파일에서 설정한다. +3. Production 배포 전략 + - 개발/스테이징 환경에서는 자동 마이그레이션을 허용하나, 운영(Production) 환경에서는 절대 Database.Migrate() 자동 실행을 금지한다. +4. Script Migration + - 반드시 dotnet ef migrations script 명령어로 SQL 스크립트를 생성하여, DBA 또는 관리자의 검수를 거친 후 수동/CI 파이프라인을 통해 적용한다. + +### 3.3.4. 유효성 관리 + +- FluentValidation 사용: 잦은 if문 대신 `AbstractValidator` 를 상속 받은 별도 클래스로 분리한다. +- 동작: Controller 진입 전 또는 Service 실행 시점에 자동 검증한다. +- 위치: SPMS.Application/Validators + +### 3.3.5. 트랜잭션 관리 + +- 서비스 단위: 하나의 Service 메서드가 하나의 트랜잭션 단위가 된다. +- 원자성 (Atomicity): 원자적인 작업 단위로 모든 작업이 성공적으로 완료되지 않는다면, 즉 하나라도 실패하면 전체 롤백한다. + +### 3.3.6. 예외 처리 + +- Global Handling: 개별 메서드에서 try-catch로 에러를 삼키지 않는다. +- Custom Exception: 비즈니스 로직 에러는 의도적으로 `throw new BusinessExeption(”msg”)`을 발생시킨다 +- Middleware: 전역 미들웨어에서 에러를 잡아 공통 포맷으로 변환하여 응답한다. + +### 3.3.7. 인증 및 접근 제어 + +- 시스템 접근 권한은 ‘Who, Where, How often’ 의 3중 체계로 검증한다. +#### 1. 인증 - JWT +- Stateless 구조를 위해 JWT 방식을 표준으로 한다. +- 구현 + - Authorization 헤더에 Bearer Token 을 담아 전송하며 만료 시 Refresh Token 으로 갱신한다. +#### 2. 인가 - 역할 기반 엑세스 제어 (RBAC) +- 사용자의 Role(Admin, Manager, User) 에 따라 API 접근 권한을 엄격히 분리한다. +- 구현 + - Controller 상단에 `[Authorize(Roles="...")]` 어트리뷰트를 명시해 코드 레벨에서 권한을 강제한다. +#### 3. 네트워크 접근 제어 +- API Key가 탈취되더라도 허용되지 않은 IP에서의 접근을 원천 차단한다. +- 구현 + - 모든 API요청 시 미들웨어에서 클라이언트 IP를 추출한다. + - ServiceIP 테이블에 등록된 IP 대역인지 검증하고 불일치 시 403 Forbidden 처리한다. +#### 4. API 속도 제한 +- Dos 공격 및 루프로 인한 과부하 방지 +- AspNetCoreRateLimit 을 사용하여 IP 주소 또는 API Key 별로 초당/분당 요청 쿼터를 제한한다.(초과시 429 Too Many Requests) + +### 3.3.8. 데이터 보안 및 암호화 +- 데이터의 생명 주기 (저장, 전송) 전반에 걸쳐 데이터 등급에 따른 암호화 정책을 적용한다. + +#### 1. 데이터 등급 분류 + +| 등급 | 암호화 방식 | 대상 | +| --- | --- | --- | +| L1 (Public) | 평문 | 공지사항, 일반 리소스 | +| L2 (Authenticated) | HTTPS + JWT | 일반 서비스 데이터 | +| L3 (Sensitive) | HTTPS + E2EE + AES-256 저장 | API Key, 토큰 | +| L4 (Critical) | HTTPS + E2EE + BCrypt 저장 | 비밀번호 | + +#### 2. 암호화 - 저장 +- 양방향 암호화: 외부 연동에 필요한 민감 정보는 AES-256 (CBC/GCM) 알고리즘으로 암호화해 DB에 저장한다. +- 단방향 해시: 비밀번호 등 복호화가 불필요한 정보는 BCrypt 알고리즘(Salt 포함)을 사용해 해싱 저장한다. (절대 평문 저장 금지) +- Key 관리: 암호화 키는 소스 코드가 아닌 환경 변수 또는 Key Vault로 관리한다. + +#### 3. 암호화 - 전송 +- 적용 대상 : L3, L4 등급의 데이터 전송 시 필수 적용 +- 알고리즘: AES-256 (데이터 암호화) + RSA-2048 (키 교환) 하이브리드 방식 +- 구현 프로세스 + - **[요청 시: Client → Server]** + 1. 암호화 값 생성: Client 는 요청마다 새로운 일회용 대칭키(AES Key) 와 IV 를 생성한다. + 2. 데이터 암호화: 요청 본문을 생성한 Key와 IV로 암호화 한다. + 3. 키 암호화: 생성한 AES Key를 서버의 공개키로 암호화한다. (RSA) + 4. 패킹 구조 (Parsing 효율성을 위해 고정 길이 필드 우선 배치) + - JSON 포맷 사용 금지: 페이로드의 효율성과 구조 은닉을 위해 바이트 배열로 직렬화하여 전송한다. + - 구조: `[ Encrypted AES Key (256 Bytes) ] + [ IV (16 Bytes) ] + [ Encrypted Body (Variable) ]` + - Body가 없는 단순 조회 요청이라도 Key와 IV는 **필수 전송**한다.(Body = 0 Byte) + - 파싱 전략 + - Server는 수신된 바이너리 스트림의 첫 256바이트를 잘라 RSA 복호화하여 AES Key 획득 + - 다음 16바이트를 잘라 IV 획득 + - 나머지 바이트를 AES 복호화해 원본 Body 획득 + - **[응답 시: Server → Client]** + 1. 키 재사용 : 응답 시에는 키 교환을 하지 않고, 요청 패킷에서 획득한 AES Key를 그대로 재사용한다. + 2. 새로운 IV 생성: 보안 강화를 위해 응답을 위한 새로운 IV를 새로 생성한다. + 3. 패킹 구조 (Parsing 효율성을 위해 고정 길이 필드 우선 배치) + - 구조: `[ IV (16 Bytes) ] + [ Encrypted Body (Variable) ]` + - Client 는 자신이 보냈던 Key와 응답에 포함된 IV 를 사용해 복호화 한다. + 4. 복호화: Client는 자신이 갖고 있던 AES Key와 응답 패킷의 IV를 사용해 본문을 복호화한다. + +### 3.3.9. 보안 감사 및 시큐어 코딩 +- 이미 정의된 네트워크/암호화 보안 외에 Application 계층에서 발생할 수 있는 취약점을 방어하고 추적성을 확보한다. +#### 1. 보안 감사 로그 +- 저장소: SystemLog 테이블 (비동기 저장) +- 기록 대상 + - 인증 실패: 로그인 n회 연속 실패, 비인가 프로젝트 키 접근 시도 + - 권한 위반: 401 Unauthorized, 403 Forbidden 응답 발생한 모든 요청 + - 중요한 변경: 관리자에 의한 데이터 변경, 데이터 삭제 행위 +- 로그 마스킹 + - 헤더 및 개인정보는 로그 저장 시 반드시 마스킹 처리를 한다. + - 비밀번호, 암호화 키 원문은 어떠한 경우에도 로그 파일이나 콘솔에 평문으로 출력하지 않는다. +#### 2. 시큐어 코딩 +- SQL Injection 방지: Raw Query 사용을 금지하며 반드시 EF Core(ORM) 메서드나 Parameterized Query 만 사용한다. +- XSS(Cross-Site Scripting) 방지 + - BO 에서 HTML 입력을 허용해야 하는 경우 `