From a46a5e17ba12581e2ff963a21192faff1fe41a36 Mon Sep 17 00:00:00 2001 From: kusuri12 Date: Thu, 11 Jun 2026 11:36:53 +0900 Subject: [PATCH 01/13] =?UTF-8?q?docs(documents):=20=EC=BB=A8=ED=85=8D?= =?UTF-8?q?=EC=8A=A4=ED=8A=B8=20=ED=85=9C=ED=94=8C=EB=A6=BF=20=EC=9E=91?= =?UTF-8?q?=EC=84=B1=20#40?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../templates/entrydsm-context-xxx.template.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 documents/templates/entrydsm-context-xxx.template.md diff --git a/documents/templates/entrydsm-context-xxx.template.md b/documents/templates/entrydsm-context-xxx.template.md new file mode 100644 index 00000000..9c23b7e7 --- /dev/null +++ b/documents/templates/entrydsm-context-xxx.template.md @@ -0,0 +1,16 @@ +# {Context Name} Context + +## Purpose +> 이 Context가 존재하는 이유를 한 문장으로 작성합니다. + +## Responsibilities +> 이 Context의 책임에 대해 작성합니다. + +## Owns +> 이 Context가 소유하는 데이터/엔티티에 대해서 작성합니다. + +## Dependencies +> 이 Context가 의존하는 Context 또는 외부 시스템에 대해 작성합니다. + +## Out of Scope +> 필요할 경우 이 Context가 책임지지 않는 기능을 작성합니다 From 3bd5b63919e72ccbcc0d7bd483ec905e753b4c2c Mon Sep 17 00:00:00 2001 From: kusuri12 Date: Thu, 11 Jun 2026 11:37:51 +0900 Subject: [PATCH 02/13] =?UTF-8?q?docs(documents):=20=EA=B8=B0=EC=97=AC=20?= =?UTF-8?q?=EA=B0=80=EC=9D=B4=EB=93=9C=20=EB=AC=B8=EC=84=9C=20=EC=8A=A4?= =?UTF-8?q?=ED=83=80=EC=9D=BC=EB=A7=81=20#40?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 207 +++++++++++++++++++++++++++++++----------------- 1 file changed, 135 insertions(+), 72 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2fa836d8..2c7b0a6d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,101 +1,164 @@ # Contributing Guidelines +프로젝트에 기여해주셔서 감사합니다! -When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change. +해당 Repository에 기여하려는 경우, 변경 사항을 적용하기 전에 먼저 이슈(Issue), 이메일 또는 기타 방법을 통해 저장소 소유자와 변경 내용에 대해 논의해 주세요. -Please note we have a code of conduct, please follow it in all your interactions with the project. +또한 프로젝트의 행동 강령을 확인하고, 모든 커뮤니케이션 과정에서 이를 준수해 주시기 바랍니다. + +
+ +## Table of Contents + +1. [Issue](#1-issue) +2. [Branch Strategy](#2-branch-strategy-issue-based-workflow) +3. [Commit Convention](#3-commit-convention) +4. [Pull Request Process](#4-pull-request-process) + +
--- + ## 1. Issue + 새로운 제안이나 버그 발견 시 이슈를 먼저 생성해주세요. -**Issue 탬플릿 사용:** -`.github/ISSUE_TEMPLATE`하위 템플릿과 연계하여 작성해주세요. - -| Issue Type | About | -|---------------|-------------------------------------------| -| bug | Internal bug report | -| chore | Maintenance or housekeeping task | -| documentation | Documentation update or request | -| enhancement | Improvement to an existing feature | -| feature | New feature request | -| incident | Production incident / service outage | -| postmortem | Incident postmortem / root cause analysis | -| question | Internal technical question | - -### **상세 기록** +### Issue 템플릿 사용 + +`.github/ISSUE_TEMPLATE` 하위 템플릿과 연계하여 작성해주세요. + +| Issue Type | About | +| --------------- | ----------------------------------------- | +| `bug` | Internal bug report | +| `chore` | Maintenance or housekeeping task | +| `documentation` | Documentation update or request | +| `enhancement` | Improvement to an existing feature | +| `feature` | New feature request | +| `incident` | Production incident / service outage | +| `postmortem` | Incident postmortem / root cause analysis | +| `question` | Internal technical question | + +### 상세 기록 + Summary를 작성하고, 이슈 유형에 맞게 필요한 내용을 추가로 작성해주세요. -- bug의 경우 재현 방법(Steps to Reproduce)과 기대 결과(Expected Result), 실제 결과(Actual Result)를 상세히 작성해주세요. + +> **bug** 의 경우 재현 방법(Steps to Reproduce)과 기대 결과(Expected Result), 실제 결과(Actual Result)를 상세히 작성해주세요. + +
--- + ## 2. Branch Strategy (Issue-based Workflow) + 모든 브랜치는 생성된 이슈를 기반으로 생성하며, `develop` 브랜치에서 분기합니다. -**브랜치 생성 규칙**: `prefix/(이슈 번호)-Summary` +### 브랜치 생성 규칙 -prefix는 Issue Type과 같습니다. +``` +prefix/{이슈 번호}-Summary +``` + +> `prefix`는 Issue Type과 동일합니다. + +**예시** + +``` +feature/42-add-login-api +fix/57-null-pointer-exception +documentation/8-api-guide +``` + +
--- ## 3. Commit Convention -커밋 메시지는 다음과 같은 형식을 사용합니다: -`Type(Scope): Summary (Issue No)` - -| Type | About | -|-----------------|-----------------------------------| -| **feat** | 새로운 기능 추가 | -| **fix** | 버그 수정 | -| **enhancement** | 기존 기능의 향상 및 개선 | -| **docs** | 문서 수정 (README, 가이드 등) | -| **chore** | 빌드 업무 수정, 패키지 매니저 설정 등 (코드 수정 없음) | -| **hotfix** | 긴급한 버그 수정 | -| **test** | 테스트 코드 추가 및 수정 | -| **refactor** | 코드 리팩토링 (기능 변화 없음) | - -| Scope | About | -|---------------|------------------| -| contracts | 컨트랙트 관련 작업 | -| documents | 일반 문서 관련 작업 | -| packages | 패키지 및 모듈 관련 작업 | -| admission | 입학 서비스 관련 작업 | -| analytics | 분석 서비스 관련 작업 | -| application | 지원서 서비스 관련 작업 | -| document | 특정 문서 파일 관련 작업 | -| evaluation | 평가 서비스 관련 작업 | -| gateway | 게이트웨이 관련 작업 | -| identity | 인증 및 신원 관리 관련 작업 | -| notification | 알림 서비스 관련 작업 | -| observability | 모니터링 및 관측성 관련 작업 | -| schedule | 스케줄 서비스 관련 작업 | -| infra | 인프라 관련 작업 | -| ci | CI/CD 파이프라인 관련 작업 | + +커밋 메시지는 다음과 같은 형식을 사용합니다. + +``` +Type(Scope): Summary (Issue No) +``` + +### Type + +| Type | About | +| --------------- | -------------------------------------------------- | +| `feat` | 새로운 기능 추가 | +| `fix` | 버그 수정 | +| `enhancement` | 기존 기능의 향상 및 개선 | +| `docs` | 문서 수정 (README, 가이드 등) | +| `chore` | 빌드 업무 수정, 패키지 매니저 설정 등 (코드 수정 없음) | +| `hotfix` | 긴급한 버그 수정 | +| `test` | 테스트 코드 추가 및 수정 | +| `refactor` | 코드 리팩토링 (기능 변화 없음) | + +### Scope + +| Scope | About | +| --------------- | ---------------------------- | +| `contracts` | 컨트랙트 관련 작업 | +| `documents` | 일반 문서 관련 작업 | +| `packages` | 패키지 및 모듈 관련 작업 | +| `admission` | 입학 서비스 관련 작업 | +| `analytics` | 분석 서비스 관련 작업 | +| `application` | 지원서 서비스 관련 작업 | +| `document` | 특정 문서 파일 관련 작업 | +| `evaluation` | 평가 서비스 관련 작업 | +| `gateway` | 게이트웨이 관련 작업 | +| `identity` | 인증 및 신원 관리 관련 작업 | +| `notification` | 알림 서비스 관련 작업 | +| `observability` | 모니터링 및 관측성 관련 작업 | +| `schedule` | 스케줄 서비스 관련 작업 | +| `infra` | 인프라 관련 작업 | +| `ci` | CI/CD 파이프라인 관련 작업 | + +
+ --- ## 4. Pull Request Process -* 모든 pull request는 전부 template을 통하여 작성되어야합니다. -* 다음과 같은 형식으로 작성합니다: `Type(Scope): Summary (이슈 번호)` +### PR 제목 형식 + +``` +Type(Scope): Summary #{이슈 번호} +``` + +### PR 템플릿 사용 + +`.github/PULL_REQUEST_TEMPLATE` 하위 템플릿과 연계하여 작성해주세요. + +멀티 템플릿의 경우, PR 생성 URL 뒤에 `&template={템플릿 파일 이름}`을 붙여줘야 합니다. + +``` +https://github.com/EntryDSM/entrydsm-platform/compare/main...documentation/branch-name?expand=1&template=documentation.md +``` + +### 이슈 연결 + +PR 설명란에 아래와 같이 작성하면 PR 머지 시 해당 이슈가 자동으로 닫힙니다. + +``` +Closes #이슈번호 +``` -* 멀티 템플릿의 경우, PR 생성했을 때의 URL 뒤에 `&template={템플릿 파일 이름}` 을 붙여줘야 합니다. - (ex. `https://github.com/EntryDSM/entrydsm-platform/compare/main...documentation/branch-name?expand=1&template=documentation.md`) +### 리뷰 프로세스 -* **PR 템플릿 사용:** -`.github/PULL_REQUEST_TEMPLATE.md`하위 템플릿과 연계하여 작성해주세요. +1. 하나 이상의 승인(Approve)이 필요합니다. +2. 리뷰어의 수정 요청이 있다면 반영 후 다시 알립니다. +3. 승인 완료 후 머지(Merge)를 진행합니다. -* **이슈 연결:** PR 설명란에 `Closes #이슈번호`를 적어 해당 이슈가 자동으로 닫히도록 설정합니다. +### PR 작성 시 주의사항 -* **리뷰 프로세스:** - 1. 하나 이상의 승인(Approve)이 필요합니다. - 2. 리뷰어의 수정 요청이 있다면 반영 후 다시 알립니다. - 3. 승인 완료 후 머지(Merge)를 진행합니다. +- 발생한 Conflict에 대해서는 PR 작성자가 해결합니다. +- 하나의 PR에는 하나의 중심 내용만 포함합니다. + - 기능 구현(feat), 리팩토링(refactor), 버그 수정(fix), 스타일 수정(chore) 등이 섞여있다면 반드시 분리합니다. +- PR 작성 시 GitHub 프로젝트를 선택하지 않습니다. +- 가능한 작은 크기의 PR을 제출하여 리뷰어가 쉽게 검토하도록 합니다. -* **PR 시 주의사항** - * 발생한 Conflict에 대해서는 PR 작성자가 해결합니다. - * 가능 한 작은 크기의 PR을 제출하여 리뷰어가 쉽게 검토하도록 합니다. - * 권장 PR의 크기는 다음과 같습니다: - * 변경된 코드 라인 수: 200 ~ 300라인 이내 - * 파일 개수: 10개 이내 - * 리뷰 소요 시간: 리뷰어가 15 ~ 30분 이내에 전체 내용을 파악하고 피드백을 줄 수 있는 정도 - * 하나의 PR에는 하나의 중심 내용만 넣어야 합니다. - * 기능 구현(feat), 리팩토링(refactor), 버그 수정(fix), 스타일 수정(chore) 등이 섞여있다면 무조건 분리합니다. - * PR 작성 시 github 프로젝트를 선택하지 않습니다. + | 항목 | 권장 기준 | + | ----------------- | ---------------------------- | + | 변경된 코드 라인 | 200 ~ 300 라인 이내 | + | 변경된 파일 수 | 10개 이내 | + | 리뷰 소요 시간 | 15 ~ 30분 이내 파악 및 피드백 가능 | From f0b43b67d3379a2aeaf052afa682d99193343df7 Mon Sep 17 00:00:00 2001 From: kusuri12 Date: Thu, 11 Jun 2026 15:11:37 +0900 Subject: [PATCH 03/13] =?UTF-8?q?docs(documents):=20application=20?= =?UTF-8?q?=EB=B0=8F=20admission=20context=20=EB=AC=B8=EC=84=9C=20?= =?UTF-8?q?=EC=9E=91=EC=84=B1=20#40?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- documents/context/admission.md | 38 ++++++++++++++++++++++++++++++++ documents/context/application.md | 38 ++++++++++++++++++++++++++++++++ 2 files changed, 76 insertions(+) create mode 100644 documents/context/admission.md create mode 100644 documents/context/application.md diff --git a/documents/context/admission.md b/documents/context/admission.md new file mode 100644 index 00000000..b45cf3d4 --- /dev/null +++ b/documents/context/admission.md @@ -0,0 +1,38 @@ +# Admission Context + +## Purpose +> 원서, 일정, 최종 합격, 공지 등록 등의 관리자 관련 업무를 처리합니다. + +## Responsibilities +* 수험번호 자동 부여 +* 합격자 산출 + * 서류 합격 + * 최종 합격 + * 단체 메시지 전송 +* 원서 조회 + * 지원자 목록 조회 + * 엑셀로 내보내기 + * 지원자 상세 조회 + * 수험표 다운로드 + * 원서 조회 및 다운로드 +* 공지 등록 +* QnA 등록 +* 통계 조회(analytics) +* 성적 산출 방식 변경 + +> [!NOTE] +> 아직 미확정된 부분이 일부 존재합니다. 참고해주세요. + +## Owns + +*no body* + +## Dependencies +* application +* notification +* analytics +* document +* evaluation + +## Out of Scope +> 필요할 경우 이 Context가 책임지지 않는 기능을 작성합니다 diff --git a/documents/context/application.md b/documents/context/application.md new file mode 100644 index 00000000..3d050d64 --- /dev/null +++ b/documents/context/application.md @@ -0,0 +1,38 @@ +# Application Context + +## Purpose +> 사용자의 입학 원서를 저장 및 관리합니다. + +## Responsibilities + +* 입학 전형 선택 +* 인적 사항 입력 + * 증명사진, 이름, 생년월일, 보호자 성명 및, 관계, 본인 및, 부모님 연락처, 주소 +* 학교 정보 입력 + * 중학교 이름, 중학교 학번, 중학교 전화번호, 중학교 교사 성명, 중학교 교사 전화번호 + * 학교 검색 시 자동완성 지원 -> 외부 API 사용 +* 성적 입력 + * 학력에 따라서 입력받는 데이터가 다름 + * 출결, 봉사시간, 자격증 및 수상 경력(DSM 알고리즘 대회 입상여부, 정보처리기능사 자격증 취득 여부) +* 자기소개서 및 학업 계획서 입력 +* 입학 원서 임시 저장 + +### 외부 서비스 관련 + +* 성적 산출 이벤트 발행 +* PDF 생성 이벤트 발행 +* 원서 최종 제출 (저장 및 상태 변경 불가) +* 관리자 서비스에 원서 정보 제공 + * 지원자 목록, 지원자 상세, 수험표 다운로드, 원서 조회 및 다운로드 +* 수험번호 부여 + +## Owns +> 이 Context가 소유하는 데이터/엔티티에 대해서 작성합니다. + +## Dependencies +* identity +* admission +* document + +## Out of Scope +* 성적 산출 \ No newline at end of file From 95c9ae08869525f9de57dda2600ae281b4697756 Mon Sep 17 00:00:00 2001 From: kusuri12 Date: Thu, 11 Jun 2026 15:21:54 +0900 Subject: [PATCH 04/13] =?UTF-8?q?docs(documents):=20analytics=20=EB=8F=84?= =?UTF-8?q?=EB=A9=94=EC=9D=B8=EC=9D=98=20context=20=EB=AC=B8=EC=84=9C=20?= =?UTF-8?q?=EC=9E=91=EC=84=B1=20#40?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- documents/context/analytics.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 documents/context/analytics.md diff --git a/documents/context/analytics.md b/documents/context/analytics.md new file mode 100644 index 00000000..57f66fb3 --- /dev/null +++ b/documents/context/analytics.md @@ -0,0 +1,29 @@ +# Analytics Context + +## Purpose +> 각 서비스에서 통계 데이터를 가져옵니다. admission 서비스에 해당 API를 제공합니다. + +* admission에서 통계 데이터를 만들지 않고 analytics 서비스의 API를 조회하는 이유는 admission 서비스가 너무 비대해지는 현상을 방지하기 위함압니다. + +## Responsibilities +* schedule 데이터 조회 + * 전형 일정 단계 + * 원서 제출 기간 + * 전형 마감일 / 일정에 따라 변화 +* application 데이터 조회 + * 신입생 지원률 + * 경쟁률 + * 전형별 접수 현황 + * 지원자 성비 + * 지역별 접수 현황 + +## Owns + +todo + +## Dependencies +* schedule +* application + +## Out of Scope +- 데이터를 직접 저장하지 않고, 필요한 데이터를 담당 서비스에서 조회하여 가져옵니다. \ No newline at end of file From 9cf7cc8812cb9fc5419bea2dcfbf1f1a71d34d75 Mon Sep 17 00:00:00 2001 From: kusuri12 Date: Thu, 11 Jun 2026 16:55:44 +0900 Subject: [PATCH 05/13] =?UTF-8?q?docs(documents):=20document=20=EB=8F=84?= =?UTF-8?q?=EB=A9=94=EC=9D=B8=EC=9D=98=20context=20=EB=AC=B8=EC=84=9C=20?= =?UTF-8?q?=EC=9E=91=EC=84=B1=20#40?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- documents/context/document.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 documents/context/document.md diff --git a/documents/context/document.md b/documents/context/document.md new file mode 100644 index 00000000..071acf7d --- /dev/null +++ b/documents/context/document.md @@ -0,0 +1,23 @@ +# Document Context + +## Purpose +> PDF, Excel, 이미지 파일을 저장하고, 다운로드 URL을 제공하기 위한 서비스입니다. + +## Responsibilities +* 원서 pdf/hwp 다운로드 +* 수험표 pdf/hwp 다운로드 +* 지원자 목록 excel 다운로드 +* 원서 내 증명사진 첨부 +* 공지사항 / QnA / 전형 요강 내 파일 첨부 + * `.pdf`, `.xlsx`, `.jpg`, `.png`, `.webp`, `.hwp`, `.docx` 지원 + +## Owns +* DB에 데이터를 저장하거나, 직접 데이터를 조회하지 않습니다. +* 스토리지 서비스(s3)에 파일을 저장하고, 제공합니다. + +## Dependencies +* 해당 서비스는 타 context에 의존하지 않습니다. +* AWS S3 외부 서비스를 이용합니다. + +## Out of Scope +> 필요할 경우 이 Context가 책임지지 않는 기능을 작성합니다 From 44f9ee6a2f7e8abb3ae047a4f5ea1fba0660c1b4 Mon Sep 17 00:00:00 2001 From: kusuri12 Date: Thu, 11 Jun 2026 17:40:20 +0900 Subject: [PATCH 06/13] =?UTF-8?q?docs(documents):=20evaluation=20=EB=B0=8F?= =?UTF-8?q?=20observability=20context=20=EB=AC=B8=EC=84=9C=20=EC=9E=91?= =?UTF-8?q?=EC=84=B1=20#40?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- documents/context/evaluation.md | 17 +++++++++++++++++ documents/context/observability.md | 17 +++++++++++++++++ 2 files changed, 34 insertions(+) create mode 100644 documents/context/evaluation.md create mode 100644 documents/context/observability.md diff --git a/documents/context/evaluation.md b/documents/context/evaluation.md new file mode 100644 index 00000000..3a049edc --- /dev/null +++ b/documents/context/evaluation.md @@ -0,0 +1,17 @@ +# Evaluation Context + +## Purpose +> 성적을 산출하고 계산합니다. + +## Responsibilities +* 입학 전형 별 성적 계산 +* 성적 수식 변경 ─ admission에 제공하는 API + +## Owns +> 이 Context가 소유하는 데이터/엔티티에 대해서 작성합니다. + +## Dependencies +> 이 Context가 의존하는 Context 또는 외부 시스템에 대해 작성합니다. + +## Out of Scope +> 필요할 경우 이 Context가 책임지지 않는 기능을 작성합니다 diff --git a/documents/context/observability.md b/documents/context/observability.md new file mode 100644 index 00000000..25e89ff3 --- /dev/null +++ b/documents/context/observability.md @@ -0,0 +1,17 @@ +# Observability Context + +## Purpose +> 서버 모니터링 서비스로, 실시간 데이터 전송 API를 제공합니다. + +## Responsibilities +* 서버 모니터링 +* 모니터링 데이터 실시간 전송 API (SSE) + +## Owns +> 이 Context가 소유하는 데이터/엔티티에 대해서 작성합니다. + +## Dependencies +> 이 Context가 의존하는 Context 또는 외부 시스템에 대해 작성합니다. + +## Out of Scope +> 필요할 경우 이 Context가 책임지지 않는 기능을 작성합니다 From 7aa6cbaa93e52bda46298e185d9507ea52ec8603 Mon Sep 17 00:00:00 2001 From: kusuri12 Date: Thu, 11 Jun 2026 18:49:30 +0900 Subject: [PATCH 07/13] =?UTF-8?q?docs(documents):=20schedule,=20notificati?= =?UTF-8?q?on=EC=97=90=20=EB=8C=80=ED=95=9C=20context=20=EB=AC=B8=EC=84=9C?= =?UTF-8?q?=20=EC=9E=91=EC=84=B1=20#40?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- documents/context/notification.md | 21 +++++++++++++++++++++ documents/context/schedule.md | 17 +++++++++++++++++ 2 files changed, 38 insertions(+) create mode 100644 documents/context/notification.md create mode 100644 documents/context/schedule.md diff --git a/documents/context/notification.md b/documents/context/notification.md new file mode 100644 index 00000000..b45199ac --- /dev/null +++ b/documents/context/notification.md @@ -0,0 +1,21 @@ +# Notification Context + +## Purpose +> 공지사항, QnA, 전형요강 게시글을 관리합니다. + +## Responsibilities +* 공지사항, QnA, 전형요강 게시글을 조회합니다. +* 공지사항, QnA, 전형요강 게시글을 관리합니다. + * 게시글 등록 + * 게시글 수정 + * 게시글 삭제 + * 파일 첨부 + +## Owns +> 이 Context가 소유하는 데이터/엔티티에 대해서 작성합니다. + +## Dependencies +* document (첨부된 파일이 있을 경우) + +## Out of Scope +> 필요할 경우 이 Context가 책임지지 않는 기능을 작성합니다 diff --git a/documents/context/schedule.md b/documents/context/schedule.md new file mode 100644 index 00000000..5827fae9 --- /dev/null +++ b/documents/context/schedule.md @@ -0,0 +1,17 @@ +# Schedule Context + +## Purpose +> 원서 일정을 관리하는 서비스입니다. + +## Responsibilities +* 원서 일정 조회 +* 원서 일정 수정 + +## Owns +> 이 Context가 소유하는 데이터/엔티티에 대해서 작성합니다. + +## Dependencies +> 이 Context가 의존하는 Context 또는 외부 시스템에 대해 작성합니다. + +## Out of Scope +> 필요할 경우 이 Context가 책임지지 않는 기능을 작성합니다 From 64ca4f617e34ceb569fce250c121e5eb6ad8de43 Mon Sep 17 00:00:00 2001 From: kusuri12 Date: Thu, 11 Jun 2026 20:09:25 +0900 Subject: [PATCH 08/13] =?UTF-8?q?docs(documents):=20=EC=9A=A9=EC=96=B4=20?= =?UTF-8?q?=EC=82=AC=EC=A0=84=20=EB=AC=B8=EC=84=9C=20=EC=9E=91=EC=84=B1=20?= =?UTF-8?q?#40?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- documents/.keep | 0 documents/glossary.md | 12 ++++++++++++ 2 files changed, 12 insertions(+) delete mode 100644 documents/.keep create mode 100644 documents/glossary.md diff --git a/documents/.keep b/documents/.keep deleted file mode 100644 index e69de29b..00000000 diff --git a/documents/glossary.md b/documents/glossary.md new file mode 100644 index 00000000..fa5db510 --- /dev/null +++ b/documents/glossary.md @@ -0,0 +1,12 @@ +# 용어 사전 + +| 영문명 | 한글명 | 설명 | +|-------------|---------------|---------------------------------------------------------------| +| application | 원서 | | +| analytics | 통계 | | +| schedule | 일정 | 원서 지원 일정, 합격 발표 일정을 다룹니다. | +| qna | 자주 묻는 질문, QnA | 자주 묻는 질문이지만 FAQ가 아닙니다. | +| notice | 공지사항 | notification 서비스와 헷갈리는 것을 방지하기 위해 notice를 사용합니다. | +| notification | 공지 게시글 | 공지사항이 아니라 공지사항, qna, 전형요강 전체를 다루는 서비스입니다. | +| documents | 개발 문서 | 프로젝트 개발, 설계에 대한 문서를 의미합니다. | +| document | 파일 | 단순 문서를 의미하는게 아닌 이미지, pdf, hwp 등 다른 서비스에서 필요한 파일을 제공하는 서비스입니다. | \ No newline at end of file From 5bbda2790ef6934af7856c4f71b41416b5e840a5 Mon Sep 17 00:00:00 2001 From: kusuri12 Date: Thu, 11 Jun 2026 20:11:19 +0900 Subject: [PATCH 09/13] =?UTF-8?q?docs(documents):=20=EC=9A=A9=EC=96=B4=20?= =?UTF-8?q?=EC=82=AC=EC=A0=84=20=EB=AC=B8=EC=84=9C=20=EB=82=B4=20=EC=9E=91?= =?UTF-8?q?=EC=84=B1=20=EA=B7=9C=EC=B9=99=20=EC=B6=94=EA=B0=80=20#40?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- documents/glossary.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/documents/glossary.md b/documents/glossary.md index fa5db510..c743fe18 100644 --- a/documents/glossary.md +++ b/documents/glossary.md @@ -1,5 +1,12 @@ # 용어 사전 +
+작성 규칙 + +1. 영문명과 한글명 2가지를 합께 작성합니다. +2. 혼동이 우려되는 용어가 있을 경우 추가합니다. +
+ | 영문명 | 한글명 | 설명 | |-------------|---------------|---------------------------------------------------------------| | application | 원서 | | From dda1ce1f3a59939a749302aea4415b31267a83de Mon Sep 17 00:00:00 2001 From: kusuri12 Date: Thu, 11 Jun 2026 20:17:07 +0900 Subject: [PATCH 10/13] =?UTF-8?q?docs(documents):=20=EA=B8=B0=EC=97=AC=20?= =?UTF-8?q?=EA=B0=80=EC=9D=B4=EB=93=9C=20=EB=82=B4=20scope=EC=9D=98=20?= =?UTF-8?q?=EC=84=A4=EB=AA=85=EC=9D=84=20=EB=AA=85=EC=84=B8=EC=97=90=20?= =?UTF-8?q?=EB=A7=9E=EA=B2=8C=20=EC=88=98=EC=A0=95=20#40?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2c7b0a6d..f30cbaa6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -95,23 +95,23 @@ Type(Scope): Summary (Issue No) ### Scope -| Scope | About | -| --------------- | ---------------------------- | -| `contracts` | 컨트랙트 관련 작업 | -| `documents` | 일반 문서 관련 작업 | -| `packages` | 패키지 및 모듈 관련 작업 | -| `admission` | 입학 서비스 관련 작업 | -| `analytics` | 분석 서비스 관련 작업 | -| `application` | 지원서 서비스 관련 작업 | -| `document` | 특정 문서 파일 관련 작업 | -| `evaluation` | 평가 서비스 관련 작업 | -| `gateway` | 게이트웨이 관련 작업 | -| `identity` | 인증 및 신원 관리 관련 작업 | -| `notification` | 알림 서비스 관련 작업 | -| `observability` | 모니터링 및 관측성 관련 작업 | -| `schedule` | 스케줄 서비스 관련 작업 | -| `infra` | 인프라 관련 작업 | -| `ci` | CI/CD 파이프라인 관련 작업 | +| Scope | About | +| --------------- |-------------------| +| `contracts` | 컨트랙트 관련 작업 | +| `documents` | 일반 문서 관련 작업 | +| `packages` | 패키지 및 모듈 관련 작업 | +| `admission` | 관리자 서비스 관련 작업 | +| `analytics` | 통계 서비스 관련 작업 | +| `application` | 원서 서비스 관련 작업 | +| `document` | 파일 관련 작업 | +| `evaluation` | 성적 계산 관련 작업 | +| `gateway` | 게이트웨이 관련 작업 | +| `identity` | 인증 및 유저 관리 관련 작업 | +| `notification` | 공지 게시글 서비스 관련 작업 | +| `observability` | 모니터링 관련 작업 | +| `schedule` | 일정 서비스 관련 작업 | +| `infra` | 인프라 관련 작업 | +| `ci` | CI/CD 파이프라인 관련 작업 |
From f85125320f60f12f4c6b7e12d8760c0c9e7b4324 Mon Sep 17 00:00:00 2001 From: kusuri12 Date: Thu, 9 Jul 2026 15:50:36 +0900 Subject: [PATCH 11/13] =?UTF-8?q?docs(documents):=20Domain=20Context=20?= =?UTF-8?q?=EB=AC=B8=EC=84=9C=EB=A5=BC=20=EB=B0=94=EB=80=90=20=EC=84=9C?= =?UTF-8?q?=EB=B9=84=EC=8A=A4=EC=97=90=20=EB=A7=9E=EA=B2=8C=20=EC=88=98?= =?UTF-8?q?=EC=A0=95=20#40?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- documents/context/{admission.md => admin.md} | 16 +++++++--- documents/context/analytics.md | 29 ------------------- documents/context/application.md | 8 +++-- .../context/{document.md => configuration.md} | 4 ++- documents/context/evaluation.md | 17 ----------- documents/context/notification.md | 8 +++-- documents/context/schedule.md | 17 ----------- 7 files changed, 26 insertions(+), 73 deletions(-) rename documents/context/{admission.md => admin.md} (69%) delete mode 100644 documents/context/analytics.md rename documents/context/{document.md => configuration.md} (86%) delete mode 100644 documents/context/evaluation.md delete mode 100644 documents/context/schedule.md diff --git a/documents/context/admission.md b/documents/context/admin.md similarity index 69% rename from documents/context/admission.md rename to documents/context/admin.md index b45cf3d4..2fcb41a3 100644 --- a/documents/context/admission.md +++ b/documents/context/admin.md @@ -1,4 +1,4 @@ -# Admission Context +# Admin Context ## Purpose > 원서, 일정, 최종 합격, 공지 등록 등의 관리자 관련 업무를 처리합니다. @@ -19,6 +19,16 @@ * QnA 등록 * 통계 조회(analytics) * 성적 산출 방식 변경 +* notification.schedule 데이터 조회 +* 전형 일정 단계 +* 원서 제출 기간 +* 전형 마감일 / 일정에 따라 변화 +* application 데이터 조회 + * 신입생 지원률 + * 경쟁률 + * 전형별 접수 현황 + * 지원자 성비 + * 지역별 접수 현황 > [!NOTE] > 아직 미확정된 부분이 일부 존재합니다. 참고해주세요. @@ -30,9 +40,7 @@ ## Dependencies * application * notification -* analytics -* document -* evaluation +* configuration ## Out of Scope > 필요할 경우 이 Context가 책임지지 않는 기능을 작성합니다 diff --git a/documents/context/analytics.md b/documents/context/analytics.md deleted file mode 100644 index 57f66fb3..00000000 --- a/documents/context/analytics.md +++ /dev/null @@ -1,29 +0,0 @@ -# Analytics Context - -## Purpose -> 각 서비스에서 통계 데이터를 가져옵니다. admission 서비스에 해당 API를 제공합니다. - -* admission에서 통계 데이터를 만들지 않고 analytics 서비스의 API를 조회하는 이유는 admission 서비스가 너무 비대해지는 현상을 방지하기 위함압니다. - -## Responsibilities -* schedule 데이터 조회 - * 전형 일정 단계 - * 원서 제출 기간 - * 전형 마감일 / 일정에 따라 변화 -* application 데이터 조회 - * 신입생 지원률 - * 경쟁률 - * 전형별 접수 현황 - * 지원자 성비 - * 지역별 접수 현황 - -## Owns - -todo - -## Dependencies -* schedule -* application - -## Out of Scope -- 데이터를 직접 저장하지 않고, 필요한 데이터를 담당 서비스에서 조회하여 가져옵니다. \ No newline at end of file diff --git a/documents/context/application.md b/documents/context/application.md index 3d050d64..450ffdfb 100644 --- a/documents/context/application.md +++ b/documents/context/application.md @@ -16,6 +16,8 @@ * 출결, 봉사시간, 자격증 및 수상 경력(DSM 알고리즘 대회 입상여부, 정보처리기능사 자격증 취득 여부) * 자기소개서 및 학업 계획서 입력 * 입학 원서 임시 저장 +* 입학 전형 별 성적 계산(evaluation) +* 성적 수식 변경 ─ admin에 제공하는 API ### 외부 서비스 관련 @@ -31,8 +33,8 @@ ## Dependencies * identity -* admission -* document +* admin +* configuration ## Out of Scope -* 성적 산출 \ No newline at end of file +* \ No newline at end of file diff --git a/documents/context/document.md b/documents/context/configuration.md similarity index 86% rename from documents/context/document.md rename to documents/context/configuration.md index 071acf7d..dfa0dbe1 100644 --- a/documents/context/document.md +++ b/documents/context/configuration.md @@ -1,4 +1,6 @@ -# Document Context +# Configuration Context + +> 아래 기술한 내용은 Configuration 서비스 중 Document 도메인에 대한 내용입니다. ## Purpose > PDF, Excel, 이미지 파일을 저장하고, 다운로드 URL을 제공하기 위한 서비스입니다. diff --git a/documents/context/evaluation.md b/documents/context/evaluation.md deleted file mode 100644 index 3a049edc..00000000 --- a/documents/context/evaluation.md +++ /dev/null @@ -1,17 +0,0 @@ -# Evaluation Context - -## Purpose -> 성적을 산출하고 계산합니다. - -## Responsibilities -* 입학 전형 별 성적 계산 -* 성적 수식 변경 ─ admission에 제공하는 API - -## Owns -> 이 Context가 소유하는 데이터/엔티티에 대해서 작성합니다. - -## Dependencies -> 이 Context가 의존하는 Context 또는 외부 시스템에 대해 작성합니다. - -## Out of Scope -> 필요할 경우 이 Context가 책임지지 않는 기능을 작성합니다 diff --git a/documents/context/notification.md b/documents/context/notification.md index b45199ac..22cb11e7 100644 --- a/documents/context/notification.md +++ b/documents/context/notification.md @@ -1,7 +1,9 @@ # Notification Context ## Purpose -> 공지사항, QnA, 전형요강 게시글을 관리합니다. +> 공지사항, QnA, 전형요강 게시글을 관리합니다. +> +> 추가로 원서 일정도 함께 관리합니다. ## Responsibilities * 공지사항, QnA, 전형요강 게시글을 조회합니다. @@ -10,12 +12,14 @@ * 게시글 수정 * 게시글 삭제 * 파일 첨부 +* 원서 일정 조회 +* 원서 일정 수정 ## Owns > 이 Context가 소유하는 데이터/엔티티에 대해서 작성합니다. ## Dependencies -* document (첨부된 파일이 있을 경우) +* configuration (첨부된 파일이 있을 경우) ## Out of Scope > 필요할 경우 이 Context가 책임지지 않는 기능을 작성합니다 diff --git a/documents/context/schedule.md b/documents/context/schedule.md deleted file mode 100644 index 5827fae9..00000000 --- a/documents/context/schedule.md +++ /dev/null @@ -1,17 +0,0 @@ -# Schedule Context - -## Purpose -> 원서 일정을 관리하는 서비스입니다. - -## Responsibilities -* 원서 일정 조회 -* 원서 일정 수정 - -## Owns -> 이 Context가 소유하는 데이터/엔티티에 대해서 작성합니다. - -## Dependencies -> 이 Context가 의존하는 Context 또는 외부 시스템에 대해 작성합니다. - -## Out of Scope -> 필요할 경우 이 Context가 책임지지 않는 기능을 작성합니다 From f794850c2d27bc00eceb9d0dd5b700d5eabc578b Mon Sep 17 00:00:00 2001 From: kusuri12 Date: Thu, 9 Jul 2026 15:52:27 +0900 Subject: [PATCH 12/13] =?UTF-8?q?docs(documents):=20=EC=9A=A9=EC=96=B4=20?= =?UTF-8?q?=EB=AC=B8=EC=84=9C=EC=97=90=EC=84=9C=20=EC=82=AC=EC=9A=A9?= =?UTF-8?q?=ED=95=98=EC=A7=80=20=EC=95=8A=EB=8A=94=20=EC=9A=A9=EC=96=B4=20?= =?UTF-8?q?=EC=A0=9C=EA=B1=B0=20#40?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- documents/glossary.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/documents/glossary.md b/documents/glossary.md index c743fe18..3cb63b6d 100644 --- a/documents/glossary.md +++ b/documents/glossary.md @@ -5,15 +5,15 @@ 1. 영문명과 한글명 2가지를 합께 작성합니다. 2. 혼동이 우려되는 용어가 있을 경우 추가합니다. + -| 영문명 | 한글명 | 설명 | -|-------------|---------------|---------------------------------------------------------------| -| application | 원서 | | -| analytics | 통계 | | -| schedule | 일정 | 원서 지원 일정, 합격 발표 일정을 다룹니다. | -| qna | 자주 묻는 질문, QnA | 자주 묻는 질문이지만 FAQ가 아닙니다. | -| notice | 공지사항 | notification 서비스와 헷갈리는 것을 방지하기 위해 notice를 사용합니다. | +| 영문명 | 한글명 | 설명 | +|--------------|---------------|---------------------------------------------------------------| +| application | 원서 | | +| schedule | 일정 | 원서 지원 일정, 합격 발표 일정을 다룹니다. | +| qna | 자주 묻는 질문, QnA | 자주 묻는 질문이지만 FAQ가 아닙니다. | +| notice | 공지사항 | notification 서비스와 헷갈리는 것을 방지하기 위해 notice를 사용합니다. | | notification | 공지 게시글 | 공지사항이 아니라 공지사항, qna, 전형요강 전체를 다루는 서비스입니다. | -| documents | 개발 문서 | 프로젝트 개발, 설계에 대한 문서를 의미합니다. | -| document | 파일 | 단순 문서를 의미하는게 아닌 이미지, pdf, hwp 등 다른 서비스에서 필요한 파일을 제공하는 서비스입니다. | \ No newline at end of file +| documents | 개발 문서 | 프로젝트 개발, 설계에 대한 문서를 의미합니다. | +| document | 파일 | 단순 문서를 의미하는게 아닌 이미지, pdf, hwp 등 다른 서비스에서 필요한 파일을 제공하는 서비스입니다. | \ No newline at end of file From 768187de0a177f005620a7a2780cedc90b385bce Mon Sep 17 00:00:00 2001 From: kusuri12 Date: Thu, 9 Jul 2026 18:38:45 +0900 Subject: [PATCH 13/13] =?UTF-8?q?docs(documents):=20kotlin=20=EC=BB=A8?= =?UTF-8?q?=EB=B2=A4=EC=85=98=20=EB=AC=B8=EC=84=9C=20=EC=9E=91=EC=84=B1=20?= =?UTF-8?q?#40?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- documents/CONVENTION.md | 269 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 269 insertions(+) create mode 100644 documents/CONVENTION.md diff --git a/documents/CONVENTION.md b/documents/CONVENTION.md new file mode 100644 index 00000000..1a5d0de7 --- /dev/null +++ b/documents/CONVENTION.md @@ -0,0 +1,269 @@ +# Kotlin Convention + +이 문서는 EntryDSM Platform Kotlin 코드 작성 규칙을 정의합니다. + +## Index + +1. [기본 원칙](#1-기본-원칙) +2. [패키지 구조와 의존성 방향](#2-패키지-구조와-의존성-방향) +3. [Naming](#3-naming) +4. [DTO](#4-dto) +5. [Command / Result](#5-command--result) +6. [Domain](#6-domain) +7. [Exception](#7-exception) +8. [Spring](#8-spring) +9. [Nullability](#9-nullability) +10. [Formatting](#10-formatting) +11. [Test](#11-test) +12. [Bazel](#12-bazel) + +## 1. 기본 원칙 + +- Kotlin 공식 코딩 컨벤션을 기본으로 따릅니다. +- 기존 모듈의 패키지 구조, 네이밍, 의존성 방향을 우선합니다. +- 코드 스타일보다 아키텍처 경계를 먼저 지킵니다. +- 불필요한 추상화보다 명확한 도메인 표현을 우선합니다. + +## 2. 패키지 구조 & 의존성 방향 + +### Hexagonal Architecture + +서비스는 멀티모듈과 헥사고날 아키텍처를 기준으로 구성합니다. + +```text +systems/{service}/{service}-adapter-in +systems/{service}/{service}-adapter-out +systems/{service}/{service}-application +systems/{service}/{service}-domain +systems/{service}/{service}-bootstrap +``` + +#### 역할 + +| Module | 역할 | +| --- | --- | +| `adapter-in` | HTTP, gRPC 등 외부 요청 진입점 | +| `adapter-out` | DB, 외부 API, 메시징 등 외부 시스템 연동 | +| `application` | 유스케이스, 서비스, 포트 조합 | +| `domain` | 순수 도메인 모델, 도메인 규칙 | +| `bootstrap` | Spring Boot 실행 및 설정 조립 | + +#### 의존성 방향 + +```text +adapter-in -> application -> domain +adapter-out -> application/domain +bootstrap -> adapter-in, adapter-out, application, domain +``` + +- Controller는 Service 구현체가 아니라 Port 인터페이스에 의존합니다. +- domain 모듈은 Spring, JPA, Web 등 프레임워크에 의존하지 않습니다. +- application 모듈은 유스케이스 흐름을 담당하고 외부 시스템 구현 세부사항을 알지 않습니다. +- adapter-out은 application/domain의 outbound Port를 구현합니다. + +### Layered Architecture + +기본 아키텍처는 헥사고날 아키텍처입니다. 다만 일부 서비스는 복잡도나 기존 구현 방식에 따라 레이어드 아키텍처를 사용할 수 있습니다. + +레이어드 아키텍처를 사용하는 경우 다음 구조를 따릅니다. + +```text +controller -> service -> repository +``` + +#### 역할 + +| Layer | 역할 | +| --- | --- | +| `controller` | HTTP 요청/응답 처리, DTO 변환 | +| `service` | 유스케이스 흐름, 트랜잭션 경계, 도메인 규칙 조합 | +| `repository` | 데이터 저장소 접근 | +| `domain` | 엔티티, 값 객체, 도메인 상태 및 규칙 | + +#### 규칙 + +- Controller는 Repository에 직접 의존하지 않습니다. +- Controller는 Service만 호출합니다. +- Service는 트랜잭션 경계를 담당합니다. +- Repository는 데이터 접근만 담당하고 비즈니스 규칙을 포함하지 않습니다. +- DTO는 Controller 계층에 두고, Entity를 API 응답으로 직접 노출하지 않습니다. +- 서비스가 헥사고날인지 레이어드인지 모듈 구조와 기존 패턴을 먼저 확인한 뒤 동일한 방식을 따릅니다. + +## 3. Naming + +### Class + +| 대상 | 형식 | 예시 | +| --- | --- | --- | +| Controller | `{Domain}Controller` | `AuthController` | +| Service | `{UseCase}Service` | `EnvironmentVariableService` | +| Inbound Port | `{Action}{Domain}UseCase` 또는 `{Domain}Port` | `CreateAccountUseCase`, `AuthPort` | +| Outbound Port | `{Domain}Repository`, `{External}Port` | `AccountRepository` | +| Adapter | `{Domain}{Role}Adapter` | `AccountPersistenceAdapter` | +| Request DTO | `{Action}Request` | `LoginRequest` | +| Response DTO | `{Domain}Response` | `AccountResponse` | +| Command | `{Action}Command` | `SignupCommand` | +| Result | `{Domain}Result` | `UserSummaryResult` | +| Exception | `{Reason}Exception` | `UserNotFoundException` | + +### Function + +- 동사는 행위를 명확히 표현합니다. +- 조회는 `find`, `get`, `read` 중 의미에 맞게 사용합니다. +- 상태 변경은 `create`, `update`, `delete`, `cancel`, `submit` 등 도메인 행위로 표현합니다. + +```kotlin +fun login(command: LoginCommand): UserSummaryResult + +fun cancelApplication(command: CancelApplicationCommand): ApplicationStatusResult +``` + +## 4. DTO + +- DTO는 adapter 계층에 둡니다. +- API 요청/응답 형식과 application 내부 모델을 분리합니다. +- DTO에서 도메인 규칙을 처리하지 않습니다. +- DTO 변환 함수는 단순 매핑만 수행합니다. + +### 이름 형식 + +| 대상 | 형식 | 예시 | +| --- | --- | --- | +| 요청 DTO | `{Action}{Domain}Request` | `LoginRequest`, `SignupRequest`, `CancelApplicationRequest` | +| 응답 DTO | `{Domain}Response` 또는 `{Action}{Domain}Response` | `AccountResponse`, `ApplicationStatusResponse`, `LoginResponse` | +| 목록 응답 DTO | `{Domain}ListResponse` | `AccountListResponse` | +| 상세 응답 DTO | `{Domain}DetailResponse` | `AccountDetailResponse` | +| 공통 응답 DTO | `{Purpose}Response` | `ApiResponse`, `ErrorResponse` | + +단일 API에서만 사용하는 DTO는 API 행위가 드러나도록 작성합니다. + +```kotlin +data class LoginRequest( + val loginId: String, + val password: String, +) + +data class LoginResponse( + val userId: String, + val role: String, + val status: AccountStatus, +) +``` + +도메인 조회처럼 여러 API에서 재사용 가능한 응답은 도메인 중심으로 작성합니다. + +```kotlin +data class AccountResponse( + val userId: String, + val role: String, + val status: AccountStatus, +) + +data class ApplicationStatusResponse( + val applicantStatus: ApplicantStatus, + val submittedAt: Instant?, + val updatedAt: Instant, +) +``` + +응답은 공통 envelope을 사용합니다. + +```kotlin +data class ApiResponse( + val success: Boolean = true, + val data: T?, + val error: Any? = null, +) +``` + +## 5. Command / Result + +- Controller에서 받은 요청은 application Port 호출 전에 Command로 변환합니다. +- application 계층은 Request/Response DTO를 직접 알지 않습니다. +- 조회 결과는 Result 모델로 반환하고 adapter-in에서 Response DTO로 변환합니다. + +```kotlin +data class LoginCommand( + val loginId: String, + val password: String, +) +``` + +## 6. Domain + +- domain 모델은 프레임워크 의존성을 갖지 않습니다. +- 도메인 상태는 enum 또는 value object로 명확히 표현합니다. +- 생성/변경 규칙은 가능한 도메인 내부에 둡니다. +- 단순 데이터 전달만 필요한 경우에도 도메인 의미가 드러나는 이름을 사용합니다. + +## 7. Exception + +- 예외는 도메인 또는 application 의미를 드러내는 이름으로 작성합니다. +- API 에러 응답은 ErrorCode와 Exception Handler에서 일관되게 변환합니다. +- Controller에서 직접 에러 응답을 조립하지 않습니다. + +```kotlin +class UserNotFoundException( + userId: String, +) : RuntimeException("User not found: $userId") +``` + +## 8. Spring + +- `@RestController`, `@RequestMapping` 등 Web annotation은 adapter-in에서만 사용합니다. +- `@Component`, `@Service`, `@Transactional`은 application 또는 adapter 구현체에만 사용합니다. +- domain에는 Spring annotation을 사용하지 않습니다. +- 트랜잭션은 use case 경계에서 선언합니다. + +```kotlin +@Service +@Transactional(readOnly = true) +class AccountService( + private val accountRepository: AccountRepository, +) : ReadAccountUseCase +``` + +## 9. Nullability + +- nullable 타입은 실제로 값이 없을 수 있는 경우에만 사용합니다. +- nullable 값을 받은 직후 의미 있는 기본값 또는 예외로 처리합니다. +- `!!` 사용은 금지합니다. + +```kotlin +val authorization: String? +``` + +## 10. Formatting + +- 한 줄이 길어지면 trailing comma를 사용해 여러 줄로 나눕니다. +- 생성자 파라미터가 2개 이상이면 여러 줄로 작성합니다. +- import wildcard는 사용하지 않습니다. +- 의미 없는 주석은 작성하지 않습니다. + +```kotlin +data class AccountResult( + val userId: String, + val role: String, + val status: AccountStatus, +) +``` + +## 11. Test + +- Controller 테스트는 요청/응답 status, body, header를 검증합니다. +- Service 테스트는 유스케이스 흐름과 예외를 검증합니다. +- domain 테스트는 도메인 규칙이 생긴 시점에 추가합니다. +- 테스트 이름은 어떤 조건에서 어떤 결과가 나오는지 드러나게 작성합니다. + +## 12. Bazel + +- 새 Kotlin 파일을 추가할 때는 해당 모듈 `BUILD.bazel`의 `glob(["src/main/kotlin/**/*.kt"])` 범위에 들어가야 합니다. +- 외부 라이브러리를 사용하는 경우 해당 모듈의 `deps.bzl`에 직접 의존성을 추가합니다. +- transitive dependency에 기대어 컴파일하지 않습니다. + +```python +KOTLIN_DEPS = [ + "@maven//:org_springframework_spring_tx", + "//systems/configuration/configuration-domain:main", +] +```