Skip to content

Week4/auth tdd wip #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kocory1 merged 4 commits into from
Mar 22, 2026
Merged

Week4/auth tdd wip #19

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
357a3dd
feat: week4 GitHub OAuth + tree selection flow
Ara5429 Mar 19, 2026
2636a8f
feat: Git Trees API for /files, drop traverse_cap; docs + openapi
Ara5429 Mar 21, 2026
6144c2c
docs: add week4 PR draft with API list
Ara5429 Mar 21, 2026
8623439
Merge branch 'main' into week4/auth-tdd-wip
Ara5429 Mar 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 64 additions & 41 deletions docs/API_Auth_Spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,12 @@

### 공통 규칙

> 공통 요청 형식, 공통 에러 코드, score_label 기준은 `API_Common.md` 참고.
> 공통 요청 형식, 공통 에러 코드는 `API_Common.md` 참고.

- **인증 흐름:**
`GET /api/auth/github/login` → 브라우저가 GitHub OAuth authorize URL로 이동 → 사용자 승인 →
`GET /api/auth/github/callback`(code, state 수신) → 서버가 access_token 교환 및 세션 발급 →
이후 `GET /api/me`로 현재 로그인 유저 확인, 다른 API는 세션 쿠키 또는 `Authorization: Bearer <app-session-token>`으로 호출.
`GET /api/auth/github/login` → 브라우저가 GitHub OAuth authorize URL로 이동 → 사용자 승인 →
`GET /api/auth/github/callback`(code, state 수신) → 서버가 access_token 교환 및 세션 발급 →
이후 `GET /api/me`로 현재 로그인 유저 확인, 다른 API는 세션 쿠키 또는 `Authorization: Bearer <app-session-token>`으로 호출.

-- **에러 응답 포맷(공통):**

Expand All @@ -42,9 +42,11 @@ curl -i -X GET "https://example.com/api/auth/github/login"

#### 2. Request Header

| Header | 설명 | 필수 |
|--------|------|------|
| (없음) | 쿠키/Authorization 불필요 | N |

| Header | 설명 | 필수 |
| ------ | -------------------- | --- |
| (없음) | 쿠키/Authorization 불필요 | N |


#### 3. Request Element

Expand All @@ -53,11 +55,14 @@ curl -i -X GET "https://example.com/api/auth/github/login"
#### 4. Response

**302 Found**

- `Location` 헤더에 GitHub OAuth authorize URL이 담겨 해당 URL로 리다이렉트된다.

| 상태코드 | error | 발생조건 |
|----------|-------|----------|
| 500 | INTERNAL_SERVER_ERROR | GitHub OAuth 환경변수(client_id 등) 미설정 |

| 상태코드 | error | 발생조건 |
| ---- | --------------------- | ---------------------------------- |
| 500 | INTERNAL_SERVER_ERROR | GitHub OAuth 환경변수(client_id 등) 미설정 |


> 공통 에러(400/401/403/404/500/502)는 공통 규칙 참고.

Expand All @@ -77,27 +82,34 @@ curl -i -X GET "https://example.com/api/auth/github/callback?code=abc123&state=x

#### 2. Request Header

| Header | 설명 | 필수 |
|--------|------|------|
| (없음) | 쿠키/Authorization 불필요 | N |

| Header | 설명 | 필수 |
| ------ | -------------------- | --- |
| (없음) | 쿠키/Authorization 불필요 | N |


#### 3. Request Element

| 파라미터 | 타입 | 필수 | 설명 |
|----------|------|------|------|
| code | string | Y | GitHub에서 전달하는 인증 코드 |
| state | string | Y | CSRF 방지용 검증 값 |

| 파라미터 | 타입 | 필수 | 설명 |
| ----- | ------ | --- | ------------------- |
| code | string | Y | GitHub에서 전달하는 인증 코드 |
| state | string | Y | CSRF 방지용 검증 값 |


#### 4. Response

**302 Found**

- `Location`: `/dashboard` (성공 시 앱 대시보드로 리다이렉트).
- `Set-Cookie` 헤더로 세션 쿠키 발급.

| 상태코드 | error | 발생조건 |
|----------|-------|----------|
| 400 | BAD_REQUEST | state 불일치 또는 code 누락 |
| 500 | INTERNAL_SERVER_ERROR | GitHub token API 오류 등 서버/외부 오류 |

| 상태코드 | error | 발생조건 |
| ---- | --------------------- | ------------------------------ |
| 400 | BAD_REQUEST | state 불일치 또는 code 누락 |
| 500 | INTERNAL_SERVER_ERROR | GitHub token API 오류 등 서버/외부 오류 |


> 공통 에러(400/401/403/404/500/502)는 공통 규칙 참고.

Expand All @@ -118,9 +130,11 @@ curl -i -X GET "https://example.com/api/auth/logout" \

#### 2. Request Header

| Header | 설명 | 필수 |
|--------|------|------|
| Cookie | 세션 쿠키 (있으면 무효화 대상) | N |

| Header | 설명 | 필수 |
| ------ | ------------------ | --- |
| Cookie | 세션 쿠키 (있으면 무효화 대상) | N |


#### 3. Request Element

Expand All @@ -129,11 +143,14 @@ curl -i -X GET "https://example.com/api/auth/logout" \
#### 4. Response

**302 Found**

- `Location`: `/` (루트로 리다이렉트).

| 상태코드 | error | 발생조건 |
|----------|-------|----------|
| (없음) | — | 에러 응답 없음, 항상 302 반환 |

| 상태코드 | error | 발생조건 |
| ---- | ----- | ------------------- |
| (없음) | — | 에러 응답 없음, 항상 302 반환 |


---

Expand All @@ -152,11 +169,13 @@ curl -X GET "https://example.com/api/me" \

#### 2. Request Header

| Header | 설명 | 필수 |
|--------|------|------|
| Cookie | 세션 쿠키 (인증된 경우) | Cookie 또는 Authorization 중 하나 필수 |

| Header | 설명 | 필수 |
| ------------- | ---------------------------- | ------------------------------- |
| Cookie | 세션 쿠키 (인증된 경우) | Cookie 또는 Authorization 중 하나 필수 |
| Authorization | `Bearer <app-session-token>` | Cookie 또는 Authorization 중 하나 필수 |


#### 3. Request Element

- Path/Query/Body 없음.
Expand All @@ -175,17 +194,21 @@ curl -X GET "https://example.com/api/me" \
}
```

| 필드 | 타입 | 설명 |
|------|------|------|
| user_id | string | 내부 사용자 식별자 |
| github_login | string | GitHub 로그인 아이디 |
| github_id | integer | GitHub 유저 numeric ID |
| email | string | 이메일 주소 |
| avatar_url | string | 프로필 이미지 URL |

| 상태코드 | error | 발생조건 |
|----------|-------|----------|
| 401 | UNAUTHORIZED | 세션 없음 또는 만료 |
| 필드 | 타입 | 설명 |
| ------------ | ------- | -------------------- |
| user_id | string | 내부 사용자 식별자 |
| github_login | string | GitHub 로그인 아이디 |
| github_id | integer | GitHub 유저 numeric ID |
| email | string | 이메일 주소 |
| avatar_url | string | 프로필 이미지 URL |



| 상태코드 | error | 발생조건 |
| ---- | ------------ | ----------- |
| 401 | UNAUTHORIZED | 세션 없음 또는 만료 |


> 공통 에러(400/401/403/404/500/502)는 공통 규칙 참고.

Expand All @@ -206,4 +229,4 @@ curl -X GET "https://example.com/api/me" \
11. POST /api/cover-letter/inspect — 자소서 검수 (Service)
12. POST /api/portfolio/generate — 포트폴리오 생성 (Service)

6번(문서 업로드)은 선택 단계이며, 이력서/포트폴리오 문서가 없어도 자소서·포트폴리오 생성은 GitHub 임베딩만으로 진행 가능하다.
6번(문서 업로드)은 선택 단계이며, 이력서/포트폴리오 문서가 없어도 자소서·포트폴리오 생성은 GitHub 임베딩만으로 진행 가능하다.
20 changes: 14 additions & 6 deletions docs/API_GitHub_Spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -190,11 +190,18 @@ curl -X PUT "https://example.com/api/user/selected-repos" \
### 3.1 GET `/api/github/repos/{repo_id}/files`

- **설명:** 레포의 파일/디렉터리 트리 조회 (임베딩·포트폴리오 대상 선택용)
- **구현:** GitHub **Git Trees API** 단일 `recursive=1` 호출로 전체 트리를 가져온 뒤, 서버에서 `path`·`depth`으로 필터링한다.
1. `ref`가 없으면 `GET /repos/{owner}/{repo}`로 `default_branch`를 구한다.
2. 브랜치명이면 `GET /repos/{owner}/{repo}/git/ref/heads/{branch}`로 커밋 SHA를 구한다. (커밋 SHA 형태면 `GET /repos/{owner}/{repo}/git/commits/{sha}`로 바로 사용)
3. `GET /repos/{owner}/{repo}/git/commits/{commit_sha}`로 **tree SHA**를 구한다.
4. `GET /repos/{owner}/{repo}/git/trees/{tree_sha}?recursive=1` 한 번으로 평탄(flat) 트리를 받는다.
5. GitHub 응답 `tree[]`에서 `type=blob` → `file`, `type=tree` → `dir`(경로는 디렉터리에 `/` 접미사)으로 매핑한다.
6. `truncated=true`이면 레포가 너무 커서 GitHub이 트리를 잘랐을 때이며, 이 경우 **502**를 반환한다.

#### 1. Request Syntax

```bash
curl -X GET "https://example.com/api/github/repos/123/files?path=/&depth=2&ref=main" \
curl -X GET "https://example.com/api/github/repos/123/files?path=/&depth=-1&ref=main" \
-H "Authorization: Bearer <app-session-token>"
```

Expand All @@ -210,9 +217,9 @@ curl -X GET "https://example.com/api/github/repos/123/files?path=/&depth=2&ref=m
| 파라미터 | 타입 | 필수 | 설명 |
|----------|------|------|------|
| repo_id | integer \| string | Y | Path. GitHub 레포 numeric ID 또는 `"owner/name"` |
| path | string | N | 조회 시작 디렉터리 경로, default="/" |
| depth | integer | N | 탐색 최대 깊이, default=2 |
| ref | string | N | 브랜치명 또는 커밋 SHA, default=레포 default_branch |
| path | string | N | 조회 시작 디렉터리 경로, default="/" (해당 경로 하위만 필터) |
| depth | integer | N | `path` 기준 상대 경로에서 `/` 개수 상한. `-1`이면 깊이 제한 없음 (default=-1) |
| ref | string | N | 브랜치명 또는 커밋 SHA, 생략 시 레포 `default_branch` |

#### 4. Response

Expand All @@ -228,7 +235,8 @@ curl -X GET "https://example.com/api/github/repos/123/files?path=/&depth=2&ref=m
{ "path": "src/app/", "type": "dir" },
{ "path": "src/app/main.py", "type": "file" },
{ "path": "README.md", "type": "file" }
]
],
"visited_nodes": 4
}
```

Expand All @@ -238,7 +246,7 @@ curl -X GET "https://example.com/api/github/repos/123/files?path=/&depth=2&ref=m
| 404 | NOT_FOUND | 레포 또는 경로 없음 |

> 공통 에러(400/401/403/404/500/502)는 공통 규칙 참고.
| 502 | GITHUB_UPSTREAM_ERROR | GitHub 트리 조회 실패 |
| 502 | GITHUB_UPSTREAM_ERROR | GitHub 트리 조회 실패 또는 GitHub `truncated=true` (트리 과대) |

---

Expand Down
19 changes: 10 additions & 9 deletions docs/AUTOFOLIO_DB_스키마_설계.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,15 +21,16 @@

### 2.1 users (유저)


| 컬럼 | 타입 | 설명 |
| ----------------- | -------- | ---------------------- |
| `id` | TEXT PK | 유저 고유 ID (GitHub id 등) |
| `github_username` | TEXT | GitHub 사용자명 |
| `access_token` | TEXT | OAuth 토큰 (암호화 권장) |
| `created_at` | DATETIME | 가입 시각 |
| `updated_at` | DATETIME | 수정 시각 |

| 컬럼 | 타입 | 설명 |
|------|------|------|
| `id` | TEXT PK | 유저 고유 ID (GitHub id 등) |
| `github_username` | TEXT | GitHub 사용자명 |
| `github_id` | INTEGER | GitHub 유저 numeric ID |
| `email` | TEXT | GitHub 이메일(없을 수도 있음) |
| `avatar_url` | TEXT | GitHub 프로필 이미지 URL |
| `access_token` | TEXT | OAuth 토큰 (암호화 권장) |
| `created_at` | DATETIME | 가입 시각 |
| `updated_at` | DATETIME | 수정 시각 |

### 2.2 drafts (자소서 문항 단위)

Expand Down
Loading
Loading