Todo-Project/docs/API.md

# API 문서 (API.md)

## 🚀 API 개요

Todo-Project REST API는 간결하고 직관적인 할일 관리 기능을 제공합니다.

### 기본 정보
- **Base URL**: `http://localhost:9000/api`
- **인증 방식**: JWT Bearer Token
- **응답 형식**: JSON
- **API 버전**: v1

### 포트 설정
- **Frontend**: http://localhost:4000
- **Backend API**: http://localhost:9000
- **Database**: localhost:5434

## 🔐 인증

### 로그인
```http
POST /api/auth/login
Content-Type: application/json

{
    "email": "user@example.com",
    "password": "password123",
    "remember_me": false
}
```

**응답:**
```json
{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "token_type": "bearer",
    "expires_in": 1800
}
```

### 기기 등록 (개인용 최적화)
```http
POST /api/auth/register-device
Content-Type: application/json
Authorization: Bearer {access_token}

{
    "device_name": "내 iPhone",
    "fingerprint": "abc123def456",
    "platform": "mobile"
}
```

**응답:**
```json
{
    "device_token": "long-term-device-token-here",
    "expires_at": "2024-02-15T10:30:00Z",
    "device_id": "device-uuid"
}
```

### 기기 토큰 로그인
```http
POST /api/auth/device-login
Content-Type: application/json

{
    "device_token": "long-term-device-token-here"
}
```

## 📋 할일 관리

### 할일 목록 조회
```http
GET /api/todos?status=active&limit=50&offset=0
Authorization: Bearer {access_token}
```

**쿼리 파라미터:**
- `status`: `draft`, `scheduled`, `active`, `completed`, `delayed`
- `limit`: 페이지당 항목 수 (기본: 50)
- `offset`: 시작 위치 (기본: 0)

**응답:**
```json
{
    "todos": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "user_id": "550e8400-e29b-41d4-a716-446655440001",
            "content": "프로젝트 기획서 작성",
            "status": "active",
            "created_at": "2024-01-15T09:00:00Z",
            "start_date": "2024-01-15T10:00:00Z",
            "estimated_minutes": 120,
            "completed_at": null,
            "delayed_until": null,
            "parent_id": null,
            "split_order": null,
            "comment_count": 2
        }
    ],
    "total": 1,
    "has_more": false
}
```

### 할일 생성
```http
POST /api/todos
Content-Type: application/json
Authorization: Bearer {access_token}

{
    "content": "새로운 할일 내용"
}
```

**응답:**
```json
{
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "user_id": "550e8400-e29b-41d4-a716-446655440001",
    "content": "새로운 할일 내용",
    "status": "draft",
    "created_at": "2024-01-15T09:30:00Z",
    "start_date": null,
    "estimated_minutes": null,
    "completed_at": null,
    "delayed_until": null,
    "parent_id": null,
    "split_order": null,
    "comment_count": 0
}
```

### 할일 일정 설정
```http
POST /api/todos/{todo_id}/schedule
Content-Type: application/json
Authorization: Bearer {access_token}

{
    "start_date": "2024-01-16T14:00:00Z",
    "estimated_minutes": 90
}
```

**응답:** 업데이트된 할일 객체

### 할일 완료 처리
```http
PUT /api/todos/{todo_id}/complete
Authorization: Bearer {access_token}
```

**응답:** 완료된 할일 객체 (status: "completed", completed_at 설정됨)

### 할일 지연 처리
```http
PUT /api/todos/{todo_id}/delay
Content-Type: application/json
Authorization: Bearer {access_token}

{
    "delayed_until": "2024-01-17T10:00:00Z"
}
```

### 할일 분할
```http
POST /api/todos/{todo_id}/split
Content-Type: application/json
Authorization: Bearer {access_token}

{
    "subtasks": [
        "1단계: 요구사항 분석",
        "2단계: 설계 문서 작성",
        "3단계: 검토 및 수정"
    ],
    "estimated_minutes_per_task": [30, 60, 30]
}
```

**응답:** 생성된 하위 할일들의 배열

### 할일 상세 조회 (댓글 포함)
```http
GET /api/todos/{todo_id}
Authorization: Bearer {access_token}
```

**응답:**
```json
{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "550e8400-e29b-41d4-a716-446655440001",
    "content": "프로젝트 기획서 작성",
    "status": "active",
    "created_at": "2024-01-15T09:00:00Z",
    "start_date": "2024-01-15T10:00:00Z",
    "estimated_minutes": 120,
    "completed_at": null,
    "delayed_until": null,
    "parent_id": null,
    "split_order": null,
    "comment_count": 2,
    "comments": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440003",
            "todo_item_id": "550e8400-e29b-41d4-a716-446655440000",
            "user_id": "550e8400-e29b-41d4-a716-446655440001",
            "content": "진행 상황 메모",
            "created_at": "2024-01-15T11:00:00Z",
            "updated_at": "2024-01-15T11:00:00Z"
        }
    ]
}
```

## 💬 댓글/메모 관리

### 댓글 추가
```http
POST /api/todos/{todo_id}/comments
Content-Type: application/json
Authorization: Bearer {access_token}

{
    "content": "진행 상황 업데이트"
}
```

### 댓글 목록 조회
```http
GET /api/todos/{todo_id}/comments
Authorization: Bearer {access_token}
```

## 📊 통계 및 대시보드

### 할일 통계
```http
GET /api/todos/stats
Authorization: Bearer {access_token}
```

**응답:**
```json
{
    "total_count": 25,
    "draft_count": 5,
    "scheduled_count": 8,
    "active_count": 7,
    "completed_count": 4,
    "delayed_count": 1,
    "completion_rate": 16.0
}
```

### 활성 할일 조회 (시간 기반 자동 활성화)
```http
GET /api/todos/active
Authorization: Bearer {access_token}
```

**기능:** scheduled 상태의 할일 중 시작 시간이 지난 것들을 자동으로 active로 변경하고 반환

## 👤 사용자 관리

### 현재 사용자 정보
```http
GET /api/users/me
Authorization: Bearer {access_token}
```

**응답:**
```json
{
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "email": "user@example.com",
    "full_name": "사용자 이름",
    "is_active": true,
    "is_admin": false,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-15T09:00:00Z",
    "last_login_at": "2024-01-15T09:00:00Z",
    "timezone": "Asia/Seoul",
    "language": "ko"
}
```

### 사용자 정보 수정
```http
PUT /api/users/me
Content-Type: application/json
Authorization: Bearer {access_token}

{
    "full_name": "새로운 이름",
    "timezone": "Asia/Seoul",
    "language": "ko"
}
```

## 🔗 시놀로지 연동 (1단계)

### 시놀로지 설정 테스트
```http
POST /api/synology/test-connection
Content-Type: application/json
Authorization: Bearer {access_token}

{
    "dsm_url": "https://your-nas.synology.me:5001",
    "username": "todo_user",
    "password": "password123"
}
```

**응답:**
```json
{
    "dsm_connection": "success",
    "calendar_connection": "success",
    "mail_connection": "success",
    "available_services": ["Calendar", "MailPlus"]
}
```

### 캘린더 동기화 수동 실행
```http
POST /api/synology/sync-calendar/{todo_id}
Authorization: Bearer {access_token}
```

### 메일 알림 발송
```http
POST /api/synology/send-notification/{todo_id}
Authorization: Bearer {access_token}
```

## 🔧 시스템 관리

### 헬스 체크
```http
GET /api/health
```

**응답:**
```json
{
    "status": "healthy",
    "timestamp": "2024-01-15T12:00:00Z",
    "version": "0.1.0",
    "database": "connected",
    "synology_integration": "enabled"
}
```

### API 정보
```http
GET /api/info
```

**응답:**
```json
{
    "name": "Todo Project API",
    "version": "0.1.0",
    "description": "간결하고 스마트한 개인용 할일 관리 시스템",
    "docs_url": "/docs",
    "redoc_url": "/redoc"
}
```

## 📝 오류 응답

### 표준 오류 형식
```json
{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "입력 데이터가 유효하지 않습니다.",
        "details": {
            "field": "content",
            "issue": "최소 1자 이상 입력해야 합니다."
        }
    },
    "timestamp": "2024-01-15T12:00:00Z"
}
```

### 주요 오류 코드
- `AUTHENTICATION_ERROR`: 인증 실패
- `AUTHORIZATION_ERROR`: 권한 없음
- `VALIDATION_ERROR`: 입력 데이터 검증 실패
- `NOT_FOUND`: 리소스를 찾을 수 없음
- `CONFLICT`: 데이터 충돌
- `RATE_LIMIT_EXCEEDED`: 요청 한도 초과
- `SYNOLOGY_CONNECTION_ERROR`: 시놀로지 연동 오류

### HTTP 상태 코드
- `200`: 성공
- `201`: 생성 성공
- `400`: 잘못된 요청
- `401`: 인증 필요
- `403`: 권한 없음
- `404`: 찾을 수 없음
- `409`: 충돌
- `422`: 검증 실패
- `429`: 요청 한도 초과
- `500`: 서버 오류

## 🚀 SDK 및 클라이언트

### JavaScript 클라이언트 예제
```javascript
class TodoAPI {
    constructor(baseURL = 'http://localhost:9000/api') {
        this.baseURL = baseURL;
        this.token = localStorage.getItem('access_token');
    }
    
    async createTodo(content) {
        const response = await fetch(`${this.baseURL}/todos`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${this.token}`
            },
            body: JSON.stringify({ content })
        });
        
        return await response.json();
    }
    
    async getTodos(status = null) {
        const params = status ? `?status=${status}` : '';
        const response = await fetch(`${this.baseURL}/todos${params}`, {
            headers: {
                'Authorization': `Bearer ${this.token}`
            }
        });
        
        return await response.json();
    }
    
    async completeTodo(todoId) {
        const response = await fetch(`${this.baseURL}/todos/${todoId}/complete`, {
            method: 'PUT',
            headers: {
                'Authorization': `Bearer ${this.token}`
            }
        });
        
        return await response.json();
    }
}

// 사용 예제
const api = new TodoAPI();

// 할일 생성
const newTodo = await api.createTodo('새로운 할일');

// 할일 목록 조회
const activeTodos = await api.getTodos('active');

// 할일 완료
await api.completeTodo(newTodo.id);
```

## 📚 추가 리소스

- **Swagger UI**: http://localhost:9000/docs
- **ReDoc**: http://localhost:9000/redoc
- **OpenAPI Spec**: http://localhost:9000/openapi.json

이 API 문서를 통해 Todo-Project의 모든 기능을 활용할 수 있습니다!