AI Task Planner Backend (Go/Fiber)

AI 자동 일정관리 플래너 백엔드입니다

1) 무엇을 하는 서버인가요?

• 사용자 인증(회원가입/로그인)
• 개인별 Task 관리(CRUD, 상태변경)
• 통계 제공(완료/미룬/예상시간 등)
• 음성으로 Task 생성(Whisper API)

2) 기술 스택

• 언어/프레임워크: Go + Fiber
• DB/ORM: PostgreSQL(Supabase) + GORM
• 인증: JWT
• 배포: Railway (Docker)
• 프론트엔드: https://com-ai-hackathonfrontend-git-a6cf4a-heeseoks-projects-70f577c7.vercel.app/ [Closed]

3) 폴더 구조 한눈에 보기

backend/
├─ cmd/
│  └─ main.go                # 앱 진입점(서버 부팅, 미들웨어, 라우팅)
├─ internal/
│  ├─ config/                # 환경변수 로딩/설정
│  ├─ controllers/           # HTTP 핸들러 (auth, task 등)
│  ├─ database/              # DB 연결/마이그레이션
│  ├─ middleware/            # JWT 인증 등 공통 미들웨어
│  ├─ models/                # GORM 모델(Users, Tasks, Categories ...)
│  ├─ routes/                # 라우팅 묶음 정의
│  └─ services/              # 외부 연동(예: Speech/Whisper)
└─ go.mod / go.sum

핵심 흐름: main.go → routes → controllers → models/database → 응답

4) 핵심 모델(요약)

• User: id, email, password, name
• Task: user_id, task_name, status(pending|in_progress|completed|cancelled|postponed), priority, predicted_duration, ai_labels
• Category: 사용자의 작업 분류(선택)
• TimeLog: 작업 시간 추적(선택)
• TaskHistory: 변경 이력(선택)

모든 Task는 반드시 user_id로 소유자가 구분됩니다(사용자 데이터 격리).

5) 주요 API (요약)

인증

• POST /api/v1/auth/register 회원가입
• POST /api/v1/auth/login 로그인(JWT 발급)
• GET /api/v1/auth/profile 내 정보 조회

Task

• GET /api/v1/tasks 내 Task 목록(페이지네이션/필터 지원)
• POST /api/v1/tasks Task 생성
• GET /api/v1/tasks/:id 단건 조회
• PUT /api/v1/tasks/:id 수정(상태/이름/우선순위/예상시간 등)
• DELETE /api/v1/tasks/:id 삭제
• GET /api/v1/tasks/stats 통계(완료/미룬/예상시간 등)

음성(선택 기능)

• POST /api/v1/tasks/speech 오디오 업로드 → 텍스트 변환 → Task 생성

모든 보호된 API는 Authorization: Bearer 헤더가 필요합니다.

6) 환경 변수

필수 (.env 또는 Railway Variables)

DATABASE_URL=postgresql://...        # Supabase Transaction Pooler 권장(6543)
JWT_SECRET=your-secret
ALLOWED_ORIGINS=http://localhost:3000,https://com-ai-hackathonfrontend-git-a6cf4a-heeseoks-projects-70f577c7.vercel.app
OPENAI_API_KEY=sk-xxx                # 음성 기능 사용 시
PORT=8080                            # 로컬 실행 시

7) 로컬 실행 방법

# 의존성 설치
go mod download

# 서버 실행
go run cmd/main.go

# 헬스체크
curl http://localhost:8080/health

8) 동작 원리(짧게)

1. 요청이 Fiber로 들어오면 JWT 미들웨어가 사용자 식별
2. routes에서 적절한 controller로 전달
3. controller는 GORM을 통해 DB 접근, 사용자별 데이터만 조회/수정
4. 응답은 JSON으로 반환(표준 에러 처리 포함)

9) 배포 정보(요약)

• Railway에 Docker로 배포
• Supabase PostgreSQL 사용(트랜잭션 풀러, prepared statements 비활성화)
• main 브랜치 push → 자동 배포

10) 알아두면 좋은 것

• 사용자 격리를 위해 모든 쿼리에 user_id 조건을 사용
• 상태값은 문자열 상수: pending/in_progress/completed/cancelled/postponed
• 음성 기능은 OPENAI_API_KEY가 없으면 자동 비활성화

질문이나 문제가 있으면 README 상단의 엔드포인트와 /health로 먼저 확인해 주세요.

• 음성 기능은 OPENAI_API_KEY가 없으면 자동 비활성화

질문이나 문제가 있으면 README 상단의 엔드포인트와 /health로 먼저 확인해 주세요.