SamProject/sam-react-prod
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[docs]: 프로젝트 문서 추가

Browse Source 
세부 항목:
- 인증 및 미들웨어 구현 가이드
- 품목 관리 마이그레이션 가이드
- API 분석 및 요구사항 문서
- 대시보드 통합 완료 문서
- 브라우저 호환성 및 쿠키 처리 가이드
- Next.js 15 마이그레이션 참고 문서

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
byeongcheolryu
2025-11-13 21:17:43 +09:00
parent 85e51b2e2a
commit 2307b1f2c0
39 changed files with 19423 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

327
claudedocs/[REF] api-analysis.md Normal file
View File

@@ -0,0 +1,327 @@
# SAM API 분석 결과
API 문서: https://api.5130.co.kr/docs?api-docs-v1.json
## 🔍 핵심 발견사항
### 1. 인증 방식
**현재 API 문서에서 확인된 인증 방식:**
```
❌ 세션 쿠키 기반 (Sanctum SPA 모드) - 없음
✅ Bearer Token (JWT) 방식
✅ API Key 방식
```
### 2. 보안 스킴
```yaml
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY (추정)
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
```
**사용 패턴:**
- 대부분의 엔드포인트: `ApiKeyAuth` OR `BearerAuth`
- 두 방식 중 선택 가능
### 3. User 관련 엔드포인트 (Admin)
**POST /api/v1/admin/users** (사용자 생성)
```json
{
"name": "string", // 필수
"email": "string", // 필수
"password": "string", // 필수
"user_id": "string", // 선택
"phone": "string", // 선택
"roles": ["string"] // 선택
}
```
**성공 응답 (201):**
```json
{
"id": 1,
"name": "John Doe",
"email": "user@example.com",
"created_at": "2024-01-01T00:00:00Z"
}
```
**에러 응답:**
- 409: 이메일 중복
- 400: 필수 파라미터 누락
## ⚠️ 중요한 발견
### 인증 엔드포인트가 문서에 없음
**현재 문서에서 찾을 수 없는 엔드포인트:**
```
❌ POST /api/auth/login
❌ POST /api/auth/register
❌ POST /api/auth/logout
❌ GET /api/auth/user
❌ POST /api/auth/refresh
❌ GET /sanctum/csrf-cookie
```
**이유:**
1. 아직 구성 중이라 문서화 안됨
2. 별도 인증 서버 존재 가능성
3. 다른 경로에 존재 (예: /api/v1/auth/*)
## 🎯 설계 조정 필요
### 원래 설계 (Sanctum SPA 모드)
```
인증: HTTP-only 쿠키
저장: 서버 세션
CSRF: 필요
Middleware: 쿠키 확인
```
### 새로운 설계 (Bearer Token 모드)
```
인증: JWT Bearer Token
저장: localStorage 또는 쿠키
CSRF: 불필요
Middleware: Token 확인 (클라이언트 사이드)
```
## 📋 두 가지 시나리오
### 시나리오 A: Bearer Token (JWT) 방식
**장점:**
- 현재 API 구조와 일치
- Stateless (서버 세션 불필요)
- 모바일 앱 지원 용이
- API Key 또는 Token 선택 가능
**단점:**
- XSS 취약 (localStorage 사용 시)
- Token 관리 복잡 (refresh token 등)
- CORS 이슈 가능성
**구현 방식:**
```typescript
// 1. 로그인 → JWT 토큰 받기
const { token } = await login(email, password);
localStorage.setItem('token', token);
// 2. API 요청 시 토큰 포함
fetch('/api/endpoint', {
headers: {
'Authorization': `Bearer ${token}`
}
});
// 3. Middleware는 클라이언트에서 체크
// (서버 Middleware에서는 체크 불가)
```
**Middleware 제약:**
- Next.js Middleware는 서버사이드 실행
- localStorage 접근 불가
- Token 검증 어려움
- **→ 클라이언트 가드 컴포넌트 필요**
---
### 시나리오 B: 세션 쿠키 방식 (권장)
**장점:**
- 서버 Middleware에서 인증 체크 가능
- XSS 방어 (HTTP-only 쿠키)
- CSRF 토큰으로 보안 강화
- 기존 설계 그대로 사용
**단점:**
- Laravel API 수정 필요
- 세션 관리 필요
**필요한 Laravel 변경:**
```php
// config/sanctum.php
'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', 'localhost:3000')),
// API Routes
Route::post('/login', [AuthController::class, 'login']); // 세션 생성
Route::post('/logout', [AuthController::class, 'logout'])->middleware('auth:sanctum');
Route::get('/user', [AuthController::class, 'user'])->middleware('auth:sanctum');
```
**프론트엔드는 기존 설계 그대로:**
```typescript
// Middleware에서 쿠키 확인
const sessionCookie = request.cookies.get('laravel_session');
if (!sessionCookie) redirect('/login');
```
---
## 🤔 권장사항
### 1차 선택: **백엔드 개발자와 협의 필요**
**질문할 사항:**
```
Q1. 인증 방식이 정해졌나요?
A. Bearer Token (JWT)
B. 세션 쿠키 (Sanctum SPA)
C. 둘 다 지원
Q2. 로그인/회원가입 API 경로는?
예: POST /api/v1/auth/login?
Q3. 로그인 응답 형식은?
A. { token: "xxx" } // JWT
B. { user: {...} } // 세션 + 쿠키
Q4. Token refresh 로직 있나요? (JWT인 경우)
Q5. CORS 설정 완료?
- Allow Origin: http://localhost:3000
- Allow Credentials: true (쿠키 사용 시)
```
### 2차 선택: **시나리오별 구현 방식**
#### Option A: Bearer Token으로 진행
```typescript
// 장점: 현재 API 구조 그대로 사용
// 단점: Middleware 인증 체크 불가, 클라이언트 가드 필요
// lib/auth/token-client.ts
class TokenClient {
async login(email: string, password: string) {
const { token } = await fetch('/api/v1/auth/login', {
method: 'POST',
body: JSON.stringify({ email, password })
}).then(r => r.json());
localStorage.setItem('auth_token', token);
}
getToken() {
return localStorage.getItem('auth_token');
}
}
// components/ProtectedRoute.tsx (클라이언트 가드)
function ProtectedRoute({ children }) {
const token = localStorage.getItem('auth_token');
if (!token) {
redirect('/login');
}
return children;
}
```
#### Option B: 세션 쿠키로 진행 (권장)
```typescript
// 장점: Middleware 인증, 보안 강화
// 단점: Laravel API 수정 필요
// 기존 설계 문서 그대로 구현
// claudedocs/authentication-design.md 참고
```
---
## 📝 다음 단계
### 1. 백엔드 개발자와 협의 ✅ 최우선
**확인 사항:**
- [ ] 인증 방식 확정 (JWT vs 세션)
- [ ] 로그인/회원가입 API 경로
- [ ] 응답 형식
- [ ] CORS 설정
### 2. 협의 결과에 따라
**A. Bearer Token 방식:**
- [ ] Token 클라이언트 구현
- [ ] AuthContext (Token 저장/관리)
- [ ] 클라이언트 가드 컴포넌트
- [ ] API 인터셉터 (Token 자동 추가)
**B. 세션 쿠키 방식:**
- [ ] 기존 설계 그대로 구현
- [ ] Sanctum 클라이언트
- [ ] Middleware 인증 로직
- [ ] 로그인/회원가입 페이지
### 3. API 테스트
**Bearer Token 테스트:**
```bash
# 로그인
curl -X POST https://api.5130.co.kr/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"test@test.com","password":"password"}'
# 응답 예상
{"token": "eyJhbGciOiJIUzI1NiIs..."}
# 인증 요청
curl -X GET https://api.5130.co.kr/api/v1/user \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
```
**세션 쿠키 테스트:**
```bash
# CSRF 토큰
curl -X GET https://api.5130.co.kr/sanctum/csrf-cookie -c cookies.txt
# 로그인
curl -X POST https://api.5130.co.kr/api/login \
-b cookies.txt -c cookies.txt \
-d '{"email":"test@test.com","password":"password"}'
# 사용자 정보
curl -X GET https://api.5130.co.kr/api/user \
-b cookies.txt
```
---
## 🎯 현재 상태
**대기 사항:**
1. ✅ API 문서 분석 완료
2. ⏳ 인증 방식 확정 대기
3. ⏳ 실제 로그인 API 경로 확인 대기
4. ⏳ 응답 형식 확인 대기
**다음 액션:**
- 백엔드 개발자와 인증 방식 협의
- 결정되면 즉시 구현 시작
---
## 💡 개인적 권장
**세션 쿠키 방식 (Sanctum SPA) 추천 이유:**
1. **보안**: HTTP-only 쿠키로 XSS 방어
2. **Middleware 활용**: 서버사이드 인증 체크
3. **간단함**: CSRF 토큰만 관리하면 됨
4. **Laravel 친화적**: Sanctum이 기본 제공
5. **우리 설계와 완벽히 일치**: 기존 문서 그대로 사용
하지만 최종 결정은 백엔드 아키텍처와 요구사항에 따라야 합니다!
**백엔드 개발자에게 이 문서 공유 후 협의 추천** 👍