Skip to content

Commit f2f3261

Browse files
1Seob1Seob
authored
docs(global): 프로젝트 README 온보딩 가이드 정비 (#185)
* chore(infra): 로컬 Codex 스킬 추적 제거 * docs(global): 프로젝트 README 온보딩 가이드 정비 * docs(global): README 저장소 clone 경로 수정 * docs(global): README 서비스 링크와 소개 이미지 추가 * docs(global): README 소개 이미지 크기 조정
1 parent f10e76b commit f2f3261

3 files changed

Lines changed: 160 additions & 54 deletions

File tree

‎.gitignore‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,4 +45,6 @@ node_modules
4545
# 오늘의 리포트 프롬프트
4646
/src/main/resources/secret/
4747

48-
AGENTS.md
48+
AGENTS.md
49+
.codex/
50+
PROJECT_LOG.md

‎README.md‎

Lines changed: 157 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,88 +1,192 @@
1-
# ⏳ Nadab BE
1+
# Nadab Backend
22

3-
### 🔗️ Note
4-
> 이 문서는 [Saerok 프로젝트](https://github.com/DevKor-github/saerok-BE)의 README를 참고하여 구성하였으며, Nadab의 컨벤션에 맞게 수정되었습니다.
3+
<p align="center">
4+
<img src="docs/images/nadab-banner.png" alt="Nadab 서비스 소개" width="500">
5+
</p>
6+
7+
사용자의 일상 답변을 바탕으로 AI 일간·주간·월간·유형 리포트를 생성하고, 친구·소셜 상호작용과 운영 기능을 제공하는 Spring Boot 백엔드 서버입니다.
8+
9+
---
10+
11+
## 서비스 링크
12+
13+
- [App Store](https://apps.apple.com/us/app/%EB%82%98%EB%8B%B5-ai-%EC%9E%90%EA%B8%B0%EC%84%B1%EC%B0%B0-%EA%B8%B0%EB%A1%9D-%EB%B0%8F-%EA%B0%90%EC%A0%95-%EB%B6%84%EC%84%9D-%EC%9D%BC%EA%B8%B0/id6761776437)
14+
- [Google Play](https://play.google.com/store/apps/details?id=com.nadab.app)
15+
- [Web](https://www.nadab.app/)
516

617
---
718

8-
## 🛠️ Stacks
19+
## 기술 스택
920

10-
- JAVA 21
11-
- Spring Boot 3.5.7
12-
- PostgreSQL
13-
- JPA (Hibernate)
14-
- Gradle
15-
- GitHub Actions + AWS EC2 (CI/CD)
21+
| 구분 | 기술 |
22+
| --- | --- |
23+
| Language | Java 21 |
24+
| Framework | Spring Boot 3.5.7, Spring Security, Spring Data JPA |
25+
| Database | PostgreSQL, Flyway |
26+
| AI | Spring AI, OpenAI, Google Gemini |
27+
| Infrastructure | AWS EC2, S3, KMS, Firebase Cloud Messaging |
28+
| API / View | Swagger/OpenAPI, Thymeleaf |
29+
| Test | JUnit 5, Mockito, AssertJ, Testcontainers |
30+
| Build / CI/CD | Gradle, GitHub Actions |
1631

1732
---
1833

19-
## 🧾 Commit Convention
34+
## 주요 기능
2035

21-
Nadab은 Conventional Commits 규칙을 기반으로 commitlint를 사용해 커밋 메시지 품질을 관리합니다.
36+
- OAuth 및 이메일 기반 인증, JWT 토큰 관리
37+
- 오늘의 질문과 답변 기록, 이미지 처리
38+
- AI 기반 일간·주간·월간·유형 리포트 생성
39+
- 친구, 피드 공유, 댓글, 좋아요, 신고·차단
40+
- 푸시 알림, 이메일 인증, 알림 설정
41+
- 앱 버전, 사용자 통계 등 관리자 기능
42+
- 사용자 지갑 및 크리스탈 이력 관리
2243

23-
모든 커밋은 아래와 같이 지정된 type / scope / subject 형식을 따라야 하며, 규칙을 위반하면 커밋이 거부됩니다.
44+
---
45+
46+
## 로컬 개발 환경 설정
47+
48+
### 1. 저장소 클론
49+
50+
```bash
51+
git clone https://github.com/DevKor-github/nadab-BE.git
52+
cd nadab-BE
2453
```
25-
<type>(<scope>): <subject>
2654

27-
<body>
55+
커밋 도구를 사용하려면 Node.js를 설치한 뒤 패키지를 설치합니다.
56+
57+
```bash
58+
npm install
2859
```
2960

61+
### 2. JDK 설정
62+
63+
- JDK 21을 설치합니다.
64+
- IntelliJ에서 프로젝트 루트 또는 `build.gradle`을 프로젝트로 엽니다.
65+
- Project SDK와 Gradle JVM을 JDK 21로 설정합니다.
3066

31-
### 1. type (무엇을 했는가)
67+
### 3. PostgreSQL 준비
3268

33-
| 타입 | 설명 |
34-
|------|------|
35-
| ✨ `feat` | 새로운 기능 추가 |
36-
| 🐛 `fix` | 버그 수정 |
37-
| 📚 `docs` | 문서 관련 변경 (예: README, 주석) |
38-
| 💎 `style` | 코드 의미에는 영향을 주지 않는 스타일 변경 (포맷, 세미콜론 등) |
39-
| 📦 `refactor` | 리팩토링 (기능 변경 없이 구조 개선) |
40-
| 🚀 `perf` | 성능 개선 |
41-
| 🚨 `test` | 테스트 코드 추가/보완 |
42-
| ⚙️ `ci` | CI 설정 및 관련 스크립트 변경 |
43-
| ♻️ `chore` | 기타 작업 (예: 패키지 설치, 설정 파일 변경, 디렉토리 정리 등) |
44-
| 🗑 `revert` | 이전 커밋 되돌리기 |
69+
로컬 PostgreSQL에 사용할 데이터베이스를 생성합니다. 애플리케이션 시작 시 Flyway가 `src/main/resources/db/migration`의 마이그레이션을 자동 적용하며, Hibernate는 스키마를 `validate` 모드로 검증합니다.
4570

4671
---
4772

48-
### 2. scope (어디를 바꿨는가)
73+
## 테스트
74+
75+
단위 테스트는 JUnit 5, Mockito, AssertJ를 사용합니다. 데이터베이스 통합 테스트는 PostgreSQL Testcontainers를 사용하므로 Docker Desktop이 실행 중이어야 합니다.
76+
77+
```powershell
78+
# 전체 테스트
79+
.\gradlew.bat test
80+
81+
# 단일 테스트 클래스
82+
.\gradlew.bat test --tests "com.devkor.ifive.nadab.domain.auth.application.AuthServiceV2Test"
83+
```
4984

50-
| Scope | 설명 |
51-
|:-------------|:---------------------------------------------|
52-
| 🔐 `auth` | 인증/인가 도메인 |
53-
| 🙋‍♂️ `user` | 사용자 도메인 |
54-
| 🤖 `ai` | AI 처리 |
55-
| 👥 `friend` | 친구 도메인 |
56-
| 📧 `notify` | 알림/이메일 전송 |
57-
| 🛠️ `infra` | 설정/인프라 |
58-
| 🗄️ `db` | 데이터베이스 및 마이그레이션 |
59-
| 🌎 `global` | 공용 설정 및 전역 리소스 |
85+
`develop` 브랜치 대상 Pull Request에는 GitHub Actions가 전체 테스트를 자동 실행합니다.
6086

6187
---
6288

63-
### 3. subject (무슨 일이 일어났는가)
89+
## 배포 환경
6490

65-
- 변경된 내용을 한 줄로 간결하게 요약합니다.
66-
- 한국어로 자연스럽게 작성하며, 읽는 사람이 바로 이해할 수 있도록 합니다.
67-
- 문장 끝에는 마침표(.)를 붙이지 않습니다.
91+
- `develop` 브랜치 push: 개발 EC2 자동 배포
92+
- `main` 브랜치 push: 운영 EC2 자동 배포
93+
- GitHub Actions에서 JDK 21로 실행 JAR을 빌드합니다.
94+
- 빌드 산출물을 SCP로 EC2에 전송하고 프로필별 환경 변수를 주입해 애플리케이션을 재시작합니다.
95+
- PostgreSQL, S3, KMS, Firebase 및 외부 AI API는 환경별 자격 증명으로 연동합니다.
6896

69-
> 예: 회원 탈퇴 기능 추가, 토큰 재발급 로직 수정, 빌드 스크립트 구조 개선
97+
배포 관련 secret은 GitHub Environment의 `dev`, `prod` 설정에서 관리하며 저장소에 직접 기록하지 않습니다.
7098

7199
---
72100

73-
### 4. body (왜 그렇게 했는가)
101+
## 브랜치 전략
74102

75-
- 선택 항목이지만, 기능 수정이나 리팩토링 등 맥락이 필요한 변경이라면 작성합니다.
76-
- “무엇을 바꿨고, 왜 바꿨는지”를 중심으로 구체적으로 설명합니다.
77-
> 예:
78-
사용자 조회 시 불필요한 쿼리가 반복 실행되어 응답 속도가 저하되었습니다.
79-
쿼리 캐싱을 적용하여 데이터 접근 횟수를 줄이고 성능을 개선했습니다.
103+
- `main`: 운영 배포 브랜치
104+
- `develop`: 개발 통합 및 개발 서버 배포 브랜치
105+
- 기능 개발 브랜치: `feat/*`, `fix/*`, `refactor/*`, `chore/*` 등 작업 목적에 맞게 생성
106+
107+
기능 브랜치는 `develop`을 기준으로 작업하고 Pull Request를 통해 병합합니다. 운영 반영은 `develop`에서 검증된 변경을 `main`으로 병합해 진행합니다.
80108

81109
---
82110

83-
### 설치 및 사용법
111+
## 프로젝트 구조
112+
113+
```text
114+
src
115+
├─ main
116+
│ ├─ java/com/devkor/ifive/nadab
117+
│ │ ├─ domain # 비즈니스 도메인
118+
│ │ └─ global # 공통 설정, 보안, 예외, 인프라, 유틸리티
119+
│ └─ resources
120+
│ ├─ db/migration # Flyway 마이그레이션
121+
│ ├─ templates # 관리자·통계 Thymeleaf 화면
122+
│ └─ application*.yml
123+
└─ test
124+
└─ java/com/devkor/ifive/nadab
125+
└─ infra # Testcontainers 및 테스트 빌더
126+
```
127+
128+
각 도메인은 기능에 따라 다음 계층을 조합합니다.
129+
130+
- `api`: Controller와 요청·응답 DTO
131+
- `application`: 유스케이스, 트랜잭션, 이벤트, 스케줄러
132+
- `core`: Entity, Repository, Domain Service, 내부 모델
133+
- `infra`: 외부 AI API, 스토리지 등 외부 연동 구현
134+
135+
공통 설정과 여러 도메인이 함께 사용하는 기능은 `global`에 둡니다. 데이터베이스 스키마 변경은 JPA 설정에 의존하지 않고 Flyway 마이그레이션으로 관리합니다.
136+
137+
---
138+
139+
## 커밋 컨벤션
140+
141+
Conventional Commits 기반의 commitlint, Husky, Commitizen을 사용합니다.
142+
143+
```text
144+
<type>(<scope>): <subject>
145+
146+
<body>
147+
```
148+
149+
### Type
150+
151+
| Type | 설명 |
152+
| --- | --- |
153+
| `feat` | 새로운 기능 추가 |
154+
| `fix` | 버그 수정 |
155+
| `docs` | 문서 변경 |
156+
| `chore` | 빌드·설정 등 기타 작업 |
157+
| `style` | 동작에 영향을 주지 않는 스타일 변경 |
158+
| `refactor` | 기능 변경 없는 구조 개선 |
159+
| `test` | 테스트 추가 또는 보완 |
160+
| `perf` | 성능 개선 |
161+
| `ci` | CI/CD 설정 변경 |
162+
| `revert` | 이전 커밋 되돌리기 |
163+
164+
### Scope
165+
166+
허용 scope는 다음과 같습니다.
167+
168+
```text
169+
admin, auth, user, ai, report, moderation, search, stats,
170+
friend, social, notify, infra, db, global
171+
```
172+
173+
- subject는 변경 내용을 한국어로 간결하게 작성합니다.
174+
- subject 끝에 마침표를 붙이지 않습니다.
175+
- 맥락이 필요한 변경은 body에 무엇을 바꿨고 왜 바꿨는지 작성합니다.
176+
- scope는 생략할 수 있지만, 사용할 경우 허용 목록 중 하나를 선택해야 합니다.
177+
178+
```bash
179+
# 직접 작성
180+
git commit -m "feat(report): 월간 리포트 조회 기능 추가"
181+
182+
# Commitizen 프롬프트 사용
183+
npm run commit
184+
```
185+
186+
---
84187

85-
- 터미널에서 `npm install`을 실행하여 commitlint를 설치합니다.
86-
- 커밋 시 터미널에서 `npm run commit` 입력을 통해 커밋합니다.
188+
## 참고
87189

190+
- 마이그레이션: `src/main/resources/db/migration`
191+
- CI/CD: `.github/workflows`
88192

‎docs/images/nadab-banner.png‎

606 KB
Loading

0 commit comments

Comments
 (0)