hyungi/Todo-Project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Todo-Project/docs/API.md
Hyungi Ahn 761757c12e Initial commit: Todo Project with dashboard, classification center, and upload functionality 
- 📱 PWA 지원: 홈화면 추가 가능한 Progressive Web App
- 🎨 M-Project 색상 스키마: 하늘색, 주황색, 회색, 흰색 일관된 디자인
- 📊 대시보드: 데스크톱 캘린더 뷰 + 모바일 일일 뷰 반응형 디자인
- 📥 분류 센터: Gmail 스타일 받은편지함으로 스마트 분류 시스템
- 🤖 AI 분류 제안: 키워드 기반 자동 분류 제안 및 일괄 처리
- 📷 업로드 모달: 데스크톱(파일 선택) + 모바일(카메라/갤러리) 최적화
- 🏷️ 3가지 분류: Todo(시작일), 캘린더(마감일), 체크리스트(무기한)
- 📋 체크리스트: 진행률 표시 및 완료 토글 기능
- 🔄 시놀로지 연동 준비: 메일플러스 연동을 위한 구조 설계
- 📱 반응형 UI: 모든 페이지 모바일 최적화 완료
2025-09-19 08:52:49 +09:00

10 KiB
Raw Permalink Blame History

API 문서 (API.md)

🚀 API 개요

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

기본 정보

  • Base URL: http://localhost:9000/api
  • 인증 방식: JWT Bearer Token
  • 응답 형식: JSON
  • API 버전: v1

포트 설정

🔐 인증

로그인

POST /api/auth/login
Content-Type: application/json

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

응답:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "token_type": "bearer",
    "expires_in": 1800
}

기기 등록 (개인용 최적화)

POST /api/auth/register-device
Content-Type: application/json
Authorization: Bearer {access_token}

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

응답:

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

기기 토큰 로그인

POST /api/auth/device-login
Content-Type: application/json

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

📋 할일 관리

할일 목록 조회

GET /api/todos?status=active&limit=50&offset=0
Authorization: Bearer {access_token}

쿼리 파라미터:

  • status: draft, scheduled, active, completed, delayed
  • limit: 페이지당 항목 수 (기본: 50)
  • offset: 시작 위치 (기본: 0)

응답:

{
    "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
}

할일 생성

POST /api/todos
Content-Type: application/json
Authorization: Bearer {access_token}

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

응답:

{
    "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
}

할일 일정 설정

POST /api/todos/{todo_id}/schedule
Content-Type: application/json
Authorization: Bearer {access_token}

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

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

할일 완료 처리

PUT /api/todos/{todo_id}/complete
Authorization: Bearer {access_token}

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

할일 지연 처리

PUT /api/todos/{todo_id}/delay
Content-Type: application/json
Authorization: Bearer {access_token}

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

할일 분할

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]
}

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

할일 상세 조회 (댓글 포함)

GET /api/todos/{todo_id}
Authorization: Bearer {access_token}

응답:

{
    "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"
        }
    ]
}

💬 댓글/메모 관리

댓글 추가

POST /api/todos/{todo_id}/comments
Content-Type: application/json
Authorization: Bearer {access_token}

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

댓글 목록 조회

GET /api/todos/{todo_id}/comments
Authorization: Bearer {access_token}

📊 통계 및 대시보드

할일 통계

GET /api/todos/stats
Authorization: Bearer {access_token}

응답:

{
    "total_count": 25,
    "draft_count": 5,
    "scheduled_count": 8,
    "active_count": 7,
    "completed_count": 4,
    "delayed_count": 1,
    "completion_rate": 16.0
}

활성 할일 조회 (시간 기반 자동 활성화)

GET /api/todos/active
Authorization: Bearer {access_token}

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

👤 사용자 관리

현재 사용자 정보

GET /api/users/me
Authorization: Bearer {access_token}

응답:

{
    "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"
}

사용자 정보 수정

PUT /api/users/me
Content-Type: application/json
Authorization: Bearer {access_token}

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

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

시놀로지 설정 테스트

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"
}

응답:

{
    "dsm_connection": "success",
    "calendar_connection": "success",
    "mail_connection": "success",
    "available_services": ["Calendar", "MailPlus"]
}

캘린더 동기화 수동 실행

POST /api/synology/sync-calendar/{todo_id}
Authorization: Bearer {access_token}

메일 알림 발송

POST /api/synology/send-notification/{todo_id}
Authorization: Bearer {access_token}

🔧 시스템 관리

헬스 체크

GET /api/health

응답:

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

API 정보

GET /api/info

응답:

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

📝 오류 응답

표준 오류 형식

{
    "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 클라이언트 예제

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);

📚 추가 리소스

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

Reference in New Issue View Git Blame Copy Permalink