refactor: 기술 부채 문서 정리 및 간소화

- 해결 완료된 항목들 정리 - 불필요한 코드 예시 제거 - 핵심 미해결 이슈 중심으로 재구성 - Rate Limiting 완료 항목 추가 - 100줄 내외로 문서 최적화
2025-09-15 19:40:25 +09:00 · 2025-09-15 19:40:25 +09:00 · ee53089adc
commit ee53089adc
parent 81b997da9b
1 changed files with 66 additions and 342 deletions
--- a/plans/250831_todo_and_tech_debt.md
+++ b/plans/250831_todo_and_tech_debt.md
@ -1,382 +1,106 @@
 # 기술 부채 정리

 ## 작성일: 2025년 8월 31일
-## 최종 수정: 2025년 9월 4일
+## 최종 수정: 2025년 9월 15일

-## 250831 Slack OAuth 구현 완료 후 남은 과제
-
-### 1. 임시 코드 방식 통일 🔴
+## 🔴 미해결 주요 이슈

+### 1. 임시 코드 방식 제거 필요
 **현재 상황**:
- Gmail 로그인: 임시 코드 → `/auth/verify` → JWT
- Slack 로그인: 임시 코드 → `/auth/verify` → JWT
- 프론트엔드가 통일된 방식 사용 중
-
-**문제점**:
- 임시 코드 사용이 불필요한 복잡도 추가
- Redis 의존성 증가
- 60초 TTL로 인한 타이밍 이슈 가능성
+- Gmail/Slack 모두 임시 코드 → `/auth/verify` → JWT
+- 불필요한 Redis 의존성, 60초 TTL 제한

 **개선 방안**:
-```javascript
-// Option 1: JWT 직접 전달 (보안 검토)
-return RedirectResponse(f"{redirect_uri}#token={jwt_token}")
+- JWT 직접 전달 또는 Secure cookie 사용
+- Redis 의존성 제거

-// Option 2: Secure cookie 사용
-response = RedirectResponse(redirect_uri)
-response.set_cookie("auth_token", jwt_token, secure=True, httponly=True)
-```
-
-### ✅ python-multipart 의존성 이슈 해결 완료
-
-**해결일**: 2025-09-04
-**해결 방법**:
- `requirements.txt`에 `python-multipart>=0.0.6` 추가 완료
- Docker 이미지 재빌드 완료
- 의존성 확인 완료
-
-## 2. 긴급 해결 사항 🔴
-
-### ✅ Git Merge Conflict 해결 완료
-**해결일**: 2025-08-31 16:15
-**해결 방법**: 
- rebase 대신 merge 전략으로 변경
- `git config pull.rebase false` 설정
- 충돌 파일 수동 병합 후 push 완료
- 커밋: `5bb14a6` - merge: Slack OAuth implementation with upstream changes
-
-### DB 스키마 불일치
+### 2. DB 스키마 불일치
 **문제**:
- `companies` 테이블 vs `workspaces` 테이블 공존
- `SlackWorkspace` 모델이 잘못된 FK 참조
- Relationship 주석 처리로 임시 해결 중
-
-**현재 상태**:
-```sql
-- 실제 DB
-slack_workspaces.company_id → companies.id
-workspace_members.workspace_id → workspaces.id
-
-- 모델 파일 (잘못됨)
-SlackWorkspace.workspace_id → workspaces.id (실제로는 company_id)
-```
+- companies vs workspaces 테이블 공존
+- SlackWorkspace 모델 FK 오류 (company_id를 workspace_id로 참조)

 **해결 계획**:
 1. 데이터 백업
-2. companies 데이터를 workspaces로 마이그레이션
+2. companies → workspaces 마이그레이션
 3. FK 관계 재설정
 4. 모델 파일 통일

-### 3. 환경 변수 하드코딩 제거 🟡
-
-**현재 하드코딩된 값들**:
+### 3. 하드코딩된 URL 제거 🔴
+**위치**:
 ```python
 # app/providers/slack.py
-login_callback_url = "https://auth.ro-being.com/auth/slack/login/callback"  # Line 175
-redirect_uri = state_info.get("redirect_uri", "http://localhost:3000")  # Line 268
+login_callback_url = "https://auth.ro-being.com/auth/slack/login/callback"
+redirect_uri = "http://localhost:3000"

 # frontend-customer/src/contexts/auth-context.tsx
-fetch('https://auth.ro-being.com/auth/verify', {  # Line 79
+fetch('https://auth.ro-being.com/auth/verify')
 ```

-**개선 방안**:
- 환경변수로 추출
- 개발/스테이징/프로덕션 환경 분리
-
-### 4. 사용자 매핑 로직 개선 🟡
-
-**현재 로직**:
-1. slack_user_mapping 확인
-2. 없으면 email로 사용자 조회
-3. 없으면 새 사용자 생성
+**해결**: 환경변수로 추출 (dev/staging/prod 분리)

+### 4. 사용자 매핑 로직 개선
 **문제점**:
- email이 변경되면 중복 계정 생성 가능
- workspace 없이 로그인 시 매핑 생성 불가
- username 생성 로직이 분산됨
+- email 변경 시 중복 계정 생성 가능
+- workspace 없이 매핑 불가
+- username 생성 로직 분산

-**개선 방안**:
-```python
-# 통합 사용자 식별 서비스 필요
-class UserIdentityService:
-    def find_or_create_user(provider, provider_id, email, metadata)
-    def link_accounts(user_id, provider, provider_id)
-    def merge_duplicate_users(primary_id, duplicate_ids)
-```
+**해결**: UserIdentityService 통합 서비스 구현

-## 3. 중요도 높음 🟡
+## ✅ 해결 완료 항목

-### ✅ Frontend-Backend 인증 방식 불일치 해결 완료
-**해결일**: 2025-08-31 16:25
-**해결 방법**:
- 프론트엔드 코드 수정하여 `/auth/verify` 엔드포인트 사용
- Gmail과 Slack 모두 동일한 임시 코드 방식으로 통일
- 커밋: `4cd28f1` - fix: Slack OAuth 로그인
+### 2025-09-15 해결
+- Rate Limiting 구현 완료

-### Frontend-Backend 인증 방식 최종 개선
-**현재 상태**:
- Frontend: Gmail 방식 (`/auth/verify` 임시 코드)
- Slack: JWT 직접 전달 계획 → 임시 코드로 변경
+### 2025-09-04 해결
+- python-multipart 의존성 추가 완료
+- Docker dangling 이미지 39개 제거 (3.9GB 회수)
+- nginx 권한 644 정상 확인
+- Redis TTL 자동 만료 정상 작동
+- PostgreSQL 테이블 robeings 소유권 확인
+- git config pull.rebase false 설정 완료

-## 250904 해결된 인프라 문제 ✅
+### 2025-08-31 해결
+- Slack OAuth 2.0 로그인 구현
+- Frontend-Backend 인증 방식 통일 (임시 코드 방식)
+- Git merge conflict 해결 (커밋: 5bb14a6)

-### Redis
- **Redis 키 TTL**: 자동 만료 정상 작동 중, 만료된 키 없음 확인
- **oauth:state 키**: 60초 TTL 정상 작동
-
-### PostgreSQL  
- **테이블 소유권**: 모든 테이블 robeings 사용자 소유 확인 완료
- **테이블 목록**: companies, conversation_logs, gmail_audit_logs, gmail_tokens 등
-
-### Docker & 로그
- **로그 모니터링**: /mnt/hdd/logs/ 구조화 저장 중
- **로그 정리**: 매일 새벽 4시 자동 실행, 30일 보관
- **Docker 이미지 정리**: 2025-09-04 dangling 이미지 39개 제거 (3.9GB 회수)
-
-### 환경변수
- **Frontend**: VITE_AUTH_SERVER_URL 환경변수 사용 중
- **auth-server**: .env 파일로 관리 중
-
-### Git 설정
- **pull.rebase**: false 설정 완료 (2025-09-04)
- **전략**: merge 방식으로 통일
- **적용 범위**: 51123 admin, 51124 admin, happybell80
-
-## 4. 250831 작업 요약
-
-### 완료된 작업 ✅
-1. **Slack OAuth 2.0 (OIDC) 로그인 구현**
-   - `/auth/slack/login` 엔드포인트 구현
-   - `/auth/slack/login/callback` POST/GET 지원
-   - JWT 토큰 발급 (30일 유효기간)
-   - Redis 임시 코드 저장 (60초 TTL)
-
-2. **사용자 매핑 시스템**
-   - slack_user_mapping 테이블 활용
-   - 하이브리드 접근: Slack ID → Email fallback
-   - 자동 사용자 생성
-
-3. **프론트엔드 통합**
-   - auth-context.tsx 수정
-   - `/auth/verify` 엔드포인트 사용
-   - Gmail과 동일한 방식으로 통일
-
-4. **배포 및 운영**
-   - ✅ python-multipart 의존성 추가 (2025-09-04 완료)
-   - Docker 이미지 재빌드
-   - ✅ nginx 권한 문제 해결 (2025-09-04 확인 - 644 권한 정상)
-
-### 미해결 과제 📋
-1. **기술 부채**
-   - 임시 코드 방식 제거 검토
-   - DB 스키마 통일 (companies → workspaces)
-
-2. **개선 사항**
-   - 사용자 통합 인증 서비스
-   - OAuth 토큰 갱신 로직
-   - 에러 핸들링 강화
-
-3. **문서화**
-   - API 문서 업데이트
-   - 배포 가이드 작성
-   - 트러블슈팅 가이드 추가
-
-**영향**:
- 불필요한 Redis 호출
- 60초 시간 제한
- 복잡한 인증 플로우
-
-**해결 방법**:
-1. Frontend `auth-context.tsx` 수정
-   - JWT 직접 처리 로직 구현
-   - Provider별 분기 처리
-2. 또는 통합 인증 서비스 구현
-
-### 하드코딩된 설정값
-**위치 및 내용**:
-```python
-# /home/admin/auth-server/app/providers/slack.py
-redirect_uri = "http://localhost:3000"  # 하드코딩
-login_callback_url = "https://auth.ro-being.com/auth/slack/login/callback"
-
-# docker-compose.yml
-DATABASE_URL=postgresql://robeings:robeings@192.168.219.45/main_db
-```
-
-**해결**:
- `.env` 파일로 이동
- 환경별 설정 분리 (dev/staging/prod)
-
-## 3. 개선 사항 🟢
-
-### 코드 품질
-1. **에러 처리 개선**
-   - 구체적인 에러 메시지
-   - 사용자 친화적 에러 페이지
-   - 로깅 강화
-
-2. **테스트 추가**
-   - 단위 테스트
-   - 통합 테스트
-   - E2E 테스트
-
-3. **문서화**
-   - API 문서 (OpenAPI/Swagger)
-   - 시퀀스 다이어그램
-   - 배포 가이드
+## 🟡 개선 필요 사항

 ### 보안 강화
-1. **토큰 관리**
-   - Refresh Token 구현
-   - 토큰 암호화 저장
-   - Rate Limiting
+- Refresh Token 구현
+- PKCE 적용
+- 토큰 암호화 저장

-2. **OAuth 개선**
-   - PKCE 구현
-   - State 파라미터 강화
-   - Nonce 추가
+### 코드 품질
+- 에러 처리 개선 (구체적 메시지)
+- 테스트 추가 (단위/통합/E2E)
+- API 문서화 (OpenAPI/Swagger)

-## 4. 장기 로드맵 📅
+## 📋 작업 요약

-### Q4 2025
- [ ] DB 스키마 통일
- [ ] Frontend 인증 방식 통일
- [ ] 환경변수 정리
- [ ] Git 충돌 해결
+### 완료된 작업
+1. **Slack OAuth 구현**: `/auth/slack/login`, JWT 30일, Redis 60초 TTL
+2. **사용자 매핑**: slack_user_mapping 테이블 활용
+3. **프론트엔드 통합**: auth-context.tsx 수정, Gmail과 통일

-### Q1 2026
- [ ] Multi-tenant 아키텍처
- [ ] SSO 구현
- [ ] 2FA 지원
- [ ] 감사 로그
+### 미해결 과제
+1. **기술 부채**: 임시 코드 제거, DB 스키마 통일
+2. **개선 사항**: 통합 인증 서비스, OAuth 토큰 갱신
+3. **문서화**: API 문서, 배포 가이드, 트러블슈팅

-### Q2 2026
- [ ] 마이크로서비스 분리
- [ ] API Gateway 도입
- [ ] 중앙 인증 서버
- [ ] 모니터링 대시보드
+## 📌 관련 문서
+- [미해결 항목 매트릭스](./000000_unresolved_items_matrix.md)
+- [인증 시스템 아키텍처](../300_architecture/380_authentication_system.md)
+- [Slack OAuth 구현](../troubleshooting/250831_slack_oauth_login_implementation.md)

-## 5. 현재 작업 중인 파일 목록
-
-### 수정된 파일 (commit 필요)
-```bash
-/home/admin/auth-server/
-├── app/
-│   ├── api/gmail_refresh.py (CONFLICT)
-│   ├── models/workspace.py
-│   ├── providers/
-│   │   ├── gmail.py (CONFLICT)
-│   │   ├── gmail_passport.py (CONFLICT)
-│   │   └── slack.py (NEW IMPLEMENTATION)
-├── docker-compose.yml
-└── tokens/unknown_gmail.json
-
-/home/heejae/frontend-customer/
-└── src/contexts/auth-context.tsx
-```
-
-### 신규 생성된 문서
-```bash
-/home/heejae/DOCS/
-├── troubleshooting/
-│   └── 250831_slack_oauth_login_implementation.md
-├── 300_architecture/
-│   └── 380_authentication_system.md
-└── plans/
-    └── 250831_todo_and_tech_debt.md (this file)
-```
-
-## 6. 명령어 참조
-
-### Docker 관련
-```bash
-# Auth server 재시작
-cd /home/admin/auth-server
-docker compose down && docker compose up -d --build
-
-# 로그 확인
-docker logs auth-server --tail 100 -f
-docker logs auth-redis --tail 50
-```
-
-### Git 관련
-```bash
-# 충돌 해결
-git status
-git diff <file>
-git add <file>
-git commit -m "fix: resolve conflicts"
-
-# 변경사항 확인
-git log --oneline -10
-git diff HEAD~1
-```
-
-### DB 관련
-```bash
-# PostgreSQL 접속
-PGPASSWORD=robeings psql -h localhost -U robeings -d main_db
-
-# 테이블 구조 확인
-\d companies
-\d workspaces
-\d slack_workspaces
-\d users
-\d slack_user_mapping
-
-# 데이터 확인
-SELECT * FROM companies;
-SELECT * FROM workspaces;
-SELECT * FROM slack_workspaces;
-```
-
-### Redis 관련
-```bash
-# Redis CLI
-docker exec -it auth-redis redis-cli
-
-# Keys 확인
-KEYS oauth:state:*
-KEYS auth:temp:*
-
-# TTL 확인
-TTL oauth:state:<uuid>
-```
-
-## 7. 연락처 및 참고
-
-### 관련 시스템
- Auth Server: https://auth.ro-being.com (포트 9000)
- Frontend: https://ro-being.com (포트 3000)
- Gitea: https://git.ro-being.com
- PostgreSQL: 192.168.219.45:5432
- Redis: localhost:6379
-
-### 환경변수 위치
+## 환경변수 위치
 - `/home/admin/auth-server/.env`
- `/home/heejae/frontend-customer/.env`
+- `/home/admin/frontend-customer/.env`

-### 주요 문서
- [Slack OAuth 구현 상세](./troubleshooting/250831_slack_oauth_login_implementation.md)
- [인증 시스템 아키텍처](./300_architecture/380_authentication_system.md)
- [UUID 변환 시스템](./300_architecture/uuid_conversion_system.md)
-
-## 8. 체크리스트
-
-### 배포 전 확인사항
- [ ] Git 충돌 해결
- [ ] 환경변수 설정
- [ ] DB 마이그레이션
- [ ] Docker 이미지 빌드
- [ ] 로그 모니터링
- [ ] 에러 처리 테스트
- [ ] 롤백 계획 수립
-
-### 테스트 시나리오
- [ ] Gmail 로그인
- [ ] Slack 로그인
- [ ] 기존 사용자 연동
- [ ] 신규 사용자 생성
- [ ] 토큰 만료 처리
- [ ] 에러 케이스
- [ ] 동시 로그인
+## 체크리스트
+- [ ] 하드코딩 URL 환경변수화
+- [ ] DB 스키마 통일 (companies → workspaces)
+- [ ] 임시 코드 방식 제거
+- [ ] UserIdentityService 구현
+- [ ] Refresh Token 구현
+- [ ] PKCE 적용