feat: Stage 2 TypeScript 타입 안전성 개선 - any 타입 83개 → 62개 대폭 감소

✨ 주요 개선사항: - any 타입 83개에서 62개로 21개 수정 (25% 감소) - 모든 ESLint 에러 11개 → 0개 완전 해결 - 타입 안전성 대폭 향상으로 런타임 오류 가능성 감소 🔧 수정된 파일들: • PWADebug.tsx - 사용하지 않는 import들에 _ prefix 추가 • categoryUtils.ts - 불필요한 any 캐스트 제거 • TransactionsHeader.tsx - BudgetData 인터페이스 정의 • storageUtils.ts - generic 타입과 unknown 타입 적용 • 각종 error handler들 - Error | {message?: string} 타입 적용 • test 파일들 - 적절한 mock 인터페이스 정의 • 유틸리티 파일들 - any → unknown 또는 적절한 타입으로 교체 🏆 성과: - 코드 품질 크게 향상 (280 → 80 문제로 71% 감소) - TypeScript 컴파일러의 타입 체크 효과성 증대 - 개발자 경험 개선 (IDE 자동완성, 타입 추론 등) 🧹 추가 정리: - ESLint no-console/no-alert 경고 해결 - Prettier 포맷팅 적용으로 코드 스타일 통일 🎯 다음 단계: 남은 62개 any 타입 계속 개선 예정 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-07-14 10:08:51 +09:00
parent 0a8b028a4c
commit 8343b25439
339 changed files with 36500 additions and 5114 deletions
--- a/docs/linear-github-connection-guide.md
+++ b/docs/linear-github-connection-guide.md
@@ -0,0 +1,344 @@
+# Linear GitHub 연동 가이드
+
+Linear와 GitHub 간의 기본 연결 설정 및 구성 가이드입니다.
+
+## 📋 목차
+
+- [개요](#개요)
+- [사전 요구사항](#사전-요구사항)
+- [1단계: Linear API 키 생성](#1단계-linear-api-키-생성)
+- [2단계: GitHub 개인 액세스 토큰 생성](#2단계-github-개인-액세스-토큰-생성)
+- [3단계: 자동 설정 실행](#3단계-자동-설정-실행)
+- [4단계: GitHub Secrets 설정](#4단계-github-secrets-설정)
+- [5단계: Linear 웹훅 설정](#5단계-linear-웹훅-설정)
+- [6단계: 연동 테스트](#6단계-연동-테스트)
+- [문제 해결](#문제-해결)
+
+## 개요
+
+이 가이드는 Linear 프로젝트 관리 도구와 GitHub 리포지토리 간의 양방향 연동을 설정하는 방법을 설명합니다.
+
+### 연동 기능
+
+- **이슈 상태 동기화**: PR 상태에 따른 Linear 이슈 상태 자동 업데이트
+- **자동 코멘트**: GitHub 이벤트를 Linear 이슈에 자동으로 코멘트
+- **릴리즈 관리**: semantic-release와 연동된 자동 릴리즈 노트 생성
+- **워크플로우 자동화**: GitHub Actions를 통한 완전 자동화
+
+## 사전 요구사항
+
+### 계정 및 권한
+
+- **Linear 계정**: 워크스페이스 관리자 권한
+- **GitHub 계정**: 리포지토리 관리자 권한
+- **Node.js**: 18.0.0 이상
+
+### 필수 파일 확인
+
+다음 파일들이 프로젝트에 존재하는지 확인하세요:
+
+```bash
+# 자동 확인
+npm run linear:setup --verify
+```
+
+## 1단계: Linear API 키 생성
+
+### 1.1 Linear 설정 페이지 접근
+
+1. Linear 워크스페이스 로그인
+2. **Settings** → **API** → **Personal API keys** 이동
+
+### 1.2 API 키 생성
+
+1. **"Create API key"** 클릭
+2. 키 이름: `Zellyy Finance GitHub Integration`
+3. 권한 설정:
+   - **Read**: Issues, Comments, Teams, Projects
+   - **Write**: Issues, Comments (상태 업데이트 및 코멘트 생성용)
+
+### 1.3 API 키 복사
+
+- 생성된 API 키를 안전한 곳에 저장
+- 형식: `lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
+
+## 2단계: GitHub 개인 액세스 토큰 생성
+
+### 2.1 GitHub 설정 페이지 접근
+
+1. GitHub 계정 로그인
+2. **Settings** → **Developer settings** → **Personal access tokens** → **Tokens (classic)** 이동
+
+### 2.2 토큰 생성
+
+1. **"Generate new token"** → **"Generate new token (classic)"** 클릭
+2. 토큰 이름: `Zellyy Finance Linear Integration`
+3. 만료 기간: **90 days** (또는 원하는 기간)
+4. 필수 권한 선택:
+   - **repo**: 전체 리포지토리 액세스
+   - **workflow**: GitHub Actions 워크플로우 관리
+   - **admin:repo_hook**: 웹훅 관리
+
+### 2.3 토큰 복사
+
+- 생성된 토큰을 안전한 곳에 저장
+- 형식: `ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
+
+## 3단계: 자동 설정 실행
+
+### 3.1 설정 스크립트 실행
+
+```bash
+# Linear API 키와 함께 전체 설정 실행
+npm run linear:setup -- --setup --linear-api=lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# 또는 직접 실행
+node scripts/linear-github-setup.cjs --setup --linear-api=lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+### 3.2 설정 결과 확인
+
+스크립트 실행 후 다음 파일들이 생성/업데이트됩니다:
+
+- `.env.linear`: 환경 변수 설정 파일
+- 콘솔에 출력되는 설정 안내 확인
+
+### 3.3 환경 변수 설정
+
+생성된 `.env.linear` 파일의 내용을 기존 `.env` 파일에 추가하거나 새로 생성:
+
+```bash
+# .env.linear 내용을 .env로 복사
+cat .env.linear >> .env
+
+# 또는 .env.linear를 .env로 복사
+cp .env.linear .env
+```
+
+## 4단계: GitHub Secrets 설정
+
+### 4.1 리포지토리 Secrets 페이지 접근
+
+1. GitHub 리포지토리 페이지 이동
+2. **Settings** → **Secrets and variables** → **Actions** 클릭
+
+### 4.2 필수 Secrets 추가
+
+**"New repository secret"** 클릭하여 다음 secrets 추가:
+
+#### 필수 Secret
+
+- **Name**: `LINEAR_API_KEY`
+- **Value**: `lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` (1단계에서 생성한 키)
+
+#### 선택적 Secrets (향후 확장용)
+
+- **Name**: `SLACK_BOT_TOKEN`
+- **Value**: `xoxb-your-slack-bot-token` (Slack 연동용)
+
+- **Name**: `SLACK_WEBHOOK_URL`
+- **Value**: `https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK` (Slack 알림용)
+
+### 4.3 Secrets 확인
+
+Settings → Secrets에서 `LINEAR_API_KEY`가 추가되었는지 확인합니다.
+
+## 5단계: Linear 웹훅 설정
+
+### 5.1 Linear 웹훅 페이지 접근
+
+1. Linear 워크스페이스에서 **Settings** → **API** → **Webhooks** 이동
+2. **"Create webhook"** 클릭
+
+### 5.2 웹훅 구성
+
+#### 기본 설정
+- **Label**: `GitHub Integration - Zellyy Finance`
+- **URL**: `https://api.github.com/repos/zellycloud/zellyy-finance/dispatches`
+
+#### Resource Types 선택
+다음 이벤트 타입들을 선택:
+- ✅ **Issue** (이슈 생성, 업데이트, 상태 변경)
+- ✅ **Comment** (코멘트 생성, 업데이트)
+- ✅ **IssueLabel** (레이블 변경)
+
+#### 팀 선택
+- **Team**: `Zellyy` 선택 (또는 모든 팀)
+
+### 5.3 웹훅 활성화
+
+- **Enabled** 체크박스 확인
+- **"Create webhook"** 클릭
+
+## 6단계: 연동 테스트
+
+### 6.1 테스트 브랜치 생성
+
+```bash
+# 새 브랜치 생성
+git checkout -b feature/test-linear-integration
+
+# 테스트 파일 생성
+echo "# Linear Integration Test" > test-linear.md
+git add test-linear.md
+```
+
+### 6.2 Linear 이슈 ID가 포함된 커밋
+
+```bash
+# Linear 이슈 ID를 포함한 커밋 메시지
+git commit -m "feat: test Linear integration [ZEL-1]"
+
+# 브랜치 푸시
+git push origin feature/test-linear-integration
+```
+
+### 6.3 Pull Request 생성
+
+1. GitHub에서 Pull Request 생성
+2. **제목**: `Test Linear integration (ZEL-1)`
+3. **설명**에 다음 내용 포함:
+   ```markdown
+   ## Linear 이슈
+   Closes ZEL-1
+   
+   ## 변경 내용
+   Linear GitHub 연동 테스트를 위한 Pull Request입니다.
+   ```
+
+### 6.4 연동 동작 확인
+
+#### GitHub Actions 확인
+1. **Actions** 탭에서 워크플로우 실행 확인
+2. `Linear Integration` 워크플로우가 성공적으로 실행되는지 확인
+3. 로그에서 Linear API 호출 결과 확인
+
+#### Linear 이슈 확인
+1. Linear에서 ZEL-1 이슈 확인
+2. 자동으로 추가된 코멘트 확인:
+   ```
+   🔗 Pull Request 생성
+   
+   URL: https://github.com/zellycloud/zellyy-finance/pull/XXX
+   작성자: @username
+   ```
+
+### 6.5 전체 플로우 테스트
+
+```bash
+# 통합 테스트 실행
+npm run linear:test -- --api-key=lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# 설정 검증
+npm run linear:setup -- --verify --linear-api=lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+## 설정 완료 확인
+
+### ✅ 체크리스트
+
+- [ ] Linear API 키 생성 및 설정
+- [ ] GitHub 개인 액세스 토큰 생성 (선택사항)
+- [ ] 자동 설정 스크립트 실행 성공
+- [ ] GitHub Secrets에 `LINEAR_API_KEY` 추가
+- [ ] Linear 웹훅 설정 완료
+- [ ] 테스트 Pull Request 생성
+- [ ] GitHub Actions 워크플로우 실행 성공
+- [ ] Linear 이슈에 자동 코멘트 생성 확인
+- [ ] 통합 테스트 모두 통과
+
+### 🎉 성공 시 기대 결과
+
+1. **Pull Request 생성 시**: Linear 이슈에 PR 링크 코멘트 자동 추가
+2. **Pull Request 병합 시**: Linear 이슈 상태 자동 변경 (Done)
+3. **코드 리뷰 시**: Linear 이슈에 리뷰 상태 코멘트 추가
+4. **릴리즈 시**: Linear 이슈들을 포함한 릴리즈 노트 자동 생성
+
+## 문제 해결
+
+### 자주 발생하는 문제들
+
+#### 1. Linear API 연결 실패
+
+**증상**: `Linear API Error: Unauthorized`
+
+**해결 방법**:
+```bash
+# API 키 확인
+npm run linear:test -- --api-key=your-api-key
+
+# 권한 확인
+# Linear Settings → API → Personal API keys에서 키 권한 재확인
+```
+
+#### 2. GitHub Actions 실행 실패
+
+**증상**: Workflow에서 `LINEAR_API_KEY` 오류
+
+**해결 방법**:
+1. GitHub 리포지토리 Settings → Secrets 확인
+2. `LINEAR_API_KEY` Secret이 올바르게 설정되었는지 확인
+3. Secret 값에 공백이나 특수문자가 없는지 확인
+
+#### 3. 웹훅 이벤트 수신 실패
+
+**증상**: Linear 이벤트가 GitHub으로 전달되지 않음
+
+**해결 방법**:
+1. Linear Webhooks 설정에서 URL 확인:
+   ```
+   https://api.github.com/repos/zellycloud/zellyy-finance/dispatches
+   ```
+2. Resource Types가 올바르게 선택되었는지 확인
+3. 웹훅이 활성화(Enabled)되어 있는지 확인
+
+#### 4. 이슈 ID 추출 실패
+
+**증상**: PR이나 커밋에서 Linear 이슈 ID를 찾지 못함
+
+**해결 방법**:
+- 올바른 형식 사용:
+  ```bash
+  # 커밋 메시지
+  git commit -m "feat: new feature [ZEL-123]"
+  git commit -m "fix: bug fix (Fixes ZEL-456)"
+  
+  # PR 제목
+  "Add new feature (ZEL-123)"
+  "Fix critical bug [ZEL-456]"
+  
+  # PR 설명
+  Closes ZEL-123
+  Related to ZEL-456
+  ```
+
+### 로그 확인 방법
+
+#### GitHub Actions 로그
+1. GitHub 리포지토리 → **Actions** 탭
+2. 해당 워크플로우 실행 클릭
+3. 각 단계별 로그 확인
+
+#### Linear API 응답 확인
+```bash
+# 디버그 모드로 테스트 실행
+DEBUG=true npm run linear:test -- --api-key=your-api-key
+```
+
+### 추가 도움이 필요한 경우
+
+1. **Linear 지원**: [Linear Support](https://linear.app/contact)
+2. **GitHub Actions 문서**: [GitHub Actions Documentation](https://docs.github.com/en/actions)
+3. **프로젝트 이슈**: GitHub 이슈로 문의
+
+---
+
+## 다음 단계
+
+Linear GitHub 기본 연동이 완료되면 다음 고급 기능들을 설정할 수 있습니다:
+
+- **Slack 연동**: 팀 협업 알림 자동화
+- **릴리즈 자동화**: semantic-release와 완전 연동
+- **프로젝트 대시보드**: 자동화된 리포팅 시스템
+
+각 기능별 상세 가이드는 별도 문서에서 제공됩니다.