Skip to content

Commit c9f520c

Browse files
Hyeseung-OHHyeseung-OH
authored
docs(readme): readme 수정
docs(readme): readme 수정
2 parents 3332eef + 2d89682 commit c9f520c

File tree

1 file changed

+91
-31
lines changed

1 file changed

+91
-31
lines changed

‎README.md‎

Lines changed: 91 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,20 @@
1-
# PortfolioIQ - GitHub Repository Quality Analysis Service
1+
# PortfolioIQ
22

33
## 📋 프로젝트 개요
44
### PortfolioIQ = Portfolio + IQ (Insight & Quality)
55

66
> **“당신의 포트폴리오에 인사이트와 품질을 더하다."**
7+
> GitHub Repository Quality Analysis Service
78
89
**PortfolioIQ**는 GitHub 저장소의 품질을 AI 기반으로 자동 분석하고 평가하는 웹 서비스입니다. <br />
910
개발자들이 포트폴리오로 사용하는 저장소의 README 품질, 테스트 구성, 커밋 이력, CI/CD 설정 등을 종합적으로 분석하여 객관적인 점수와 구체적인 개선 방향을 제시합니다.
1011

1112
### 🎯 프로젝트 목표
12-
취업 및 이직을 준비하는 개발자들은 포트폴리오로 GitHub 저장소를 제출하지만, 객관적인 피드백을 즉시 받기 어렵습니다. 멘토나 현직자에게 리포지토리 검토를 요청하기에는 시간과 비용이 많이 들고, 스스로 점검하기에는 무엇을 개선해야 할지 판단하기 어렵습니다.
1313

14-
본 프로젝트는 사용자가 GitHub 저장소 URL만 입력하면 AI가 README 품질, 코드 구조, 커밋 패턴, 문서화 수준 등을 종합 분석하여 점수화하고, "README에 설치 방법이 없습니다", "테스트 코드를 추가해 보세요"와 같은 구체적이고 실질적인 개선 방향을 제시하는 서비스를 제공하고자 합니다. 이를 통해 개발자들이 포트폴리오로 사용하는 리포지토리의 품질을 스스로 개선하고, 취업 경쟁력을 높일 수 있도록 돕는 것이 목표입니다.
1514
- **즉각적인 피드백 제공**: GitHub 저장소 URL 입력만으로 실시간 품질 분석
1615
- **객관적인 평가 기준**: AI 기반 정량적 점수(0-100점)와 정성적 피드백 제공
1716
- **구체적인 개선 방향**: "README에 설치 방법 추가", "테스트 코드 작성" 등 실질적인 가이드 제시
18-
- **커뮤니티**: 분석 결과 오픈소스화를 통한 집단 지성 기반 포트폴리오 품질 향상
17+
- **커뮤니티**: 오픈 커뮤니티 기반으로 우수 사례를 공유할 수 있는 플랫폼 구축
1918

2019

2120
### 👥 타겟 사용자
@@ -30,8 +29,10 @@
3029
- **팀 구성**: 4인 (Full-stack)
3130
- 임병수: User 도메인 (회원가입, 로그인, 인증/인가)
3231
- 우성현: Evaluation 도메인 (OpenAI API 연동)
33-
- 오혜승: Repository 도메인 (GitHub API 연동)
34-
- 양희원: Community 도메인 (게시판, 댓글)
32+
- 오혜승: Analysis, Repository 도메인 (GitHub API 연동)
33+
- 양희원: Analysis, Community 도메인 (게시판, 댓글)
34+
35+
### 📊 데이터 흐름
3536

3637
---
3738

@@ -41,39 +42,47 @@
4142
```
4243
- Java 21 (LTS)
4344
- Spring Boot 3.5.6
44-
- Spring Security 6.x (JWT 인증)
45-
- Spring Data JPA (Hibernate 6.x)
45+
- Spring Security 6.x + JWT (jjwt 0.13.0)
46+
- Spring Data JPA (Hibernate)
47+
- Spring WebFlux (비동기 HTTP 클라이언트)
4648
- MySQL 8.0+ / H2 (테스트)
47-
- Redis
49+
- Redis (이메일 인증 코드 캐싱)
50+
- Spring Validation (입력값 검증)
4851
```
4952

5053
### Frontend
5154
```
52-
- Next.js 15.5.3 (App Router)
53-
- React 19.1.0
54-
- TypeScript 5.9.2
55-
- Tailwind CSS 4.1.13
56-
- Context API + useReducer
55+
- Next.js 15.0.0 (App Router)
56+
- React 18.3.1
57+
- TypeScript 5.6.2
58+
- Tailwind CSS 4.1.15
59+
- TanStack React Query 5.56.2 (서버 상태 관리)
60+
- Zod 3.23.8 (스키마 검증)
61+
- Framer Motion 12.23.24 (애니메이션)
62+
- Recharts 3.3.0 (차트 시각화)
5763
```
5864

5965
### External APIs
6066
```
6167
- GitHub REST API (저장소 메타데이터 수집)
62-
- OpenAI API (gpt-4o-mini, 품질 평가)
68+
- OpenAI API (gpt-5-nano, 품질 평가)
6369
```
6470

6571
### Communication
6672
```
6773
- SSE (Server-Sent Events) - 실시간 분석 진행 상황 전달
74+
- Backend: Spring WebFlux SseEmitter
75+
- Frontend: @microsoft/fetch-event-source 2.0.1
6876
- JavaMailSender (SMTP) - 이메일 인증
6977
```
7078

7179
### DevOps & Tools
7280
```
73-
- Build: Gradle (Kotlin DSL)
81+
- Build: Gradle 8.x (Kotlin DSL)
82+
- Containerization: Docker
7483
- API Docs: Springdoc OpenAPI 2.7.0 (Swagger UI)
7584
- Version Control: Git/GitHub (GitHub Flow)
76-
- Testing: Postman, JUnit 5
85+
- Testing: JUnit 5, Mockito, Spring Security Test
7786
- IDE: IntelliJ IDEA, Cursor
7887
```
7988

@@ -92,20 +101,55 @@
92101

93102
### 환경 변수 설정
94103

95-
`.env` 파일 생성:
104+
#### 1. GitHub Personal Access Token 발급
105+
1. GitHub 로그인 후 Settings → Developer settings → Personal access tokens → Tokens (classic)
106+
2. Generate new token 클릭
107+
3. 필요한 권한 체크: `repo` (전체), `read:org`
108+
4. 생성된 토큰을 `GITHUB_TOKEN`에 설정
109+
110+
#### 2. OpenAI API Key 발급
111+
1. [OpenAI Platform](https://platform.openai.com/) 회원가입/로그인
112+
2. API keys 메뉴에서 Create new secret key
113+
3. 생성된 키를 `OPENAI_API_KEY`에 설정
114+
115+
#### 3. Google 앱 비밀번호 발급
116+
1. Google 계정 2단계 인증 활성화 필수
117+
2. [앱 비밀번호 생성](https://myaccount.google.com/apppasswords)
118+
3. 생성된 16자리 비밀번호를 `MAIL_PASSWORD`에 설정
119+
120+
#### 4. JWT Secret Key 생성
121+
```bash
122+
# 안전한 랜덤 키 생성 (최소 32자 이상 권장)
123+
openssl rand -base64 32
124+
```
125+
126+
#### 5. `.env` 파일 생성 (프로젝트 루트에 생성)
96127
```properties
97128
# Database
98-
DB_URL=jdbc:mysql://localhost:3306/DATABASE_NAME?serverTimezone=Asia/Seoul&characterEncoding=UTF-8
99-
DB_USERNAME=YOUR_USERNAME
100-
DB_PASSWORD=YOUR_PASSWORD
129+
DB_URL=jdbc:mysql://localhost:3306/portfolioiq?serverTimezone=Asia/Seoul&characterEncoding=UTF-8
130+
DB_USERNAME=root
131+
DB_PASSWORD=yourpassword
101132

102133
# GitHub API
103-
GITHUB_TOKEN=발급받은 토큰 값
134+
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
135+
136+
# OpenAI API
137+
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
104138

105-
# 추후 내용 추가 예정
139+
# Google SMTP
140+
MAIL_ID[email protected]
141+
MAIL_PASSWORD=xxxx xxxx xxxx xxxx
106142

143+
# JWT
144+
SECRET_KEY=생성된_32자_이상의_랜덤_키
107145
```
108146

147+
**⚠️ 보안 주의사항**
148+
- `.env` 파일은 절대 Git에 커밋하지 마세요 (`.gitignore`에 포함 필수)
149+
- 각자 본인의 API 키를 발급받아 사용하세요
150+
- 프로덕션 환경에서는 환경 변수로 관리하세요
151+
152+
109153
### 실행 방법
110154

111155
#### Backend 실행
@@ -123,7 +167,7 @@ npm run dev
123167

124168
### API 문서 접근
125169
```
126-
http://localhost:8080/swagger-ui.html
170+
http://localhost:8080/swagger-ui/index.html
127171
```
128172

129173
---
@@ -133,7 +177,7 @@ http://localhost:8080/swagger-ui.html
133177
### Git 브랜치 전략 (GitHub Flow)
134178

135179
```
136-
main (배포용, 직접 Push 금지, 병합 후 브랜치 삭)
180+
main (배포용, 직접 Push 금지, 병합 후 브랜치 삭제 권장)
137181
├── feature/user-login
138182
├── feature/github-api-integration
139183
├── feature/analysis-orchestration
@@ -186,16 +230,32 @@ feat(analysis): GitHub 저장소 메타데이터 수집 API 구현
186230

187231
| 이름 | 역할 | GitHub |
188232
|------|------|--------|
189-
| 임병수 | User Domain | [@LimByeongSu](https://github.com/LimByeongSu) |
190-
| 우성현 | Evaluation Domain | [@samuel426](https://github.com/samuel426) |
191-
| 오혜승 | Repository Domain | [@Hyeseung-OH](https://github.com/Hyeseung-OH) |
192-
| 양희원 | Community Domain | [@Plectranthus](https://github.com/Plectranthus) |
233+
| 임병수 | [BE] User Domain | [@LimByeongSu](https://github.com/LimByeongSu) |
234+
| 우성현 | [FULL] Evaluation Domain | [@samuel426](https://github.com/samuel426) |
235+
| 오혜승 | [FULL] Analysis, Repository Domain | [@Hyeseung-OH](https://github.com/Hyeseung-OH) |
236+
| 양희원 | [FULL] Analysis, Community Domain | [@Plectranthus](https://github.com/Plectranthus) |
193237

194238
---
195239

196240
## 📄 라이선스
197-
198-
이 프로젝트는 교육 목적으로 개발되었습니다.
241+
본 프로젝트는 교육 목적으로 개발되었으며, 다음 오픈소스 라이브러리들을 사용합니다:
242+
243+
#### Backend
244+
- Spring Boot Framework (Apache 2.0)
245+
- Spring Security (Apache 2.0)
246+
- MySQL Connector/J (GPL 2.0 with FOSS Exception)
247+
- OpenAI Java SDK (MIT)
248+
- jjwt (Apache 2.0)
249+
250+
#### Frontend
251+
- Next.js (MIT)
252+
- React (MIT)
253+
- TanStack React Query (MIT)
254+
- Tailwind CSS (MIT)
255+
256+
### 외부 API 이용 약관
257+
- **GitHub API**: [GitHub Terms of Service](https://docs.github.com/en/site-policy/github-terms/github-terms-of-service) 준수
258+
- **OpenAI API**: [OpenAI Terms of Use](https://openai.com/policies/terms-of-use) 준수
199259

200260
---
201261

0 commit comments

Comments
 (0)