# M-Project API 문서 ## 개요 작업보고서 시스템의 FastAPI 백엔드 API 엔드포인트 문서 **Base URL:** `http://localhost:16000` --- ## 인증 (Authentication) ### JWT 토큰 기반 인증 - **토큰 타입:** Bearer Token - **만료 시간:** 7일 (10080분) - **헤더:** `Authorization: Bearer ` --- ## API 엔드포인트 ### 🔐 인증 관련 API (`/api/auth`) #### 1. 로그인 ```http POST /api/auth/login Content-Type: application/x-www-form-urlencoded username=hyungi&password=djg3-jj34-X3Q3 ``` **응답:** ```json { "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", "token_type": "bearer", "user": { "id": 1, "username": "hyungi", "full_name": "관리자", "role": "admin", "is_active": true, "created_at": "2024-01-01T00:00:00" } } ``` #### 2. 현재 사용자 정보 ```http GET /api/auth/me Authorization: Bearer ``` #### 3. 사용자 생성 (관리자만) ```http POST /api/auth/users Authorization: Bearer Content-Type: application/json { "username": "user1", "password": "password123", "full_name": "사용자1", "role": "user" } ``` #### 4. 사용자 목록 조회 (관리자만) ```http GET /api/auth/users?skip=0&limit=100 Authorization: Bearer ``` #### 5. 사용자 수정 (관리자만) ```http PUT /api/auth/users/{user_id} Authorization: Bearer Content-Type: application/json { "full_name": "수정된 이름", "role": "admin" } ``` #### 6. 사용자 삭제 (관리자만) ```http DELETE /api/auth/users/{username} Authorization: Bearer ``` #### 7. 비밀번호 변경 ```http POST /api/auth/change-password Authorization: Bearer Content-Type: application/json { "current_password": "old_password", "new_password": "new_password" } ``` --- ### 📁 프로젝트 관리 API (`/api/projects`) #### 1. 프로젝트 생성 (관리자만) ```http POST /api/projects Authorization: Bearer Content-Type: application/json { "job_no": "JOB-2024-001", "project_name": "신규 프로젝트" } ``` **응답:** ```json { "id": 1, "job_no": "JOB-2024-001", "project_name": "신규 프로젝트", "created_by_id": 1, "created_by": { "id": 1, "username": "hyungi", "full_name": "관리자", "role": "admin" }, "created_at": "2024-01-01T00:00:00", "is_active": true } ``` #### 2. 프로젝트 목록 조회 ```http GET /api/projects?skip=0&limit=100&active_only=true Authorization: Bearer ``` #### 3. 특정 프로젝트 조회 ```http GET /api/projects/{project_id} Authorization: Bearer ``` #### 4. 프로젝트 수정 (관리자만) ```http PUT /api/projects/{project_id} Authorization: Bearer Content-Type: application/json { "project_name": "수정된 프로젝트명", "is_active": true } ``` #### 5. 프로젝트 삭제 (관리자만) ```http DELETE /api/projects/{project_id} Authorization: Bearer ``` --- ### 🚨 부적합 사항 API (`/api/issues`) #### 1. 부적합 사항 생성 ```http POST /api/issues Authorization: Bearer Content-Type: application/json { "category": "material_missing", "description": "자재 누락 발견", "photo": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...", "photo2": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ..." } ``` **카테고리 값:** - `material_missing`: 자재누락 - `design_error`: 설계미스 - `incoming_defect`: 입고자재 불량 - `inspection_miss`: 검사미스 #### 2. 부적합 사항 목록 조회 ```http GET /api/issues?skip=0&limit=100 Authorization: Bearer ``` #### 3. 특정 부적합 사항 조회 ```http GET /api/issues/{issue_id} Authorization: Bearer ``` #### 4. 부적합 사항 수정 ```http PUT /api/issues/{issue_id} Authorization: Bearer Content-Type: application/json { "category": "design_error", "description": "수정된 설명", "work_hours": 2.5, "status": "complete", "detail_notes": "해결 완료" } ``` **상태 값:** - `new`: 신규 - `progress`: 진행중 - `complete`: 완료 #### 5. 부적합 사항 삭제 ```http DELETE /api/issues/{issue_id} Authorization: Bearer ``` --- ### 📊 일일 공수 API (`/api/daily-work`) #### 1. 일일 공수 생성 ```http POST /api/daily-work Authorization: Bearer Content-Type: application/json { "date": "2024-01-01T00:00:00", "worker_count": 10, "overtime_workers": 3, "overtime_hours": 4.0 } ``` #### 2. 일일 공수 목록 조회 ```http GET /api/daily-work?skip=0&limit=100 Authorization: Bearer ``` #### 3. 특정 일일 공수 조회 ```http GET /api/daily-work/{work_id} Authorization: Bearer ``` #### 4. 일일 공수 수정 ```http PUT /api/daily-work/{work_id} Authorization: Bearer Content-Type: application/json { "worker_count": 12, "overtime_workers": 5, "overtime_hours": 6.0 } ``` #### 5. 일일 공수 삭제 ```http DELETE /api/daily-work/{work_id} Authorization: Bearer ``` --- ### 📈 보고서 API (`/api/reports`) #### 1. 보고서 생성 ```http POST /api/reports/generate Authorization: Bearer Content-Type: application/json { "start_date": "2024-01-01T00:00:00", "end_date": "2024-01-31T23:59:59" } ``` **응답:** ```json { "start_date": "2024-01-01T00:00:00", "end_date": "2024-01-31T23:59:59", "total_hours": 156.5, "total_issues": 25, "category_stats": { "material_missing": 10, "dimension_defect": 8, "incoming_defect": 7 }, "completed_issues": 20, "average_resolution_time": 2.3 } ``` --- ## 헬스체크 ### 서버 상태 확인 ```http GET /api/health ``` **응답:** ```json { "status": "healthy" } ``` --- ## 에러 응답 형식 ### 인증 오류 (401) ```json { "detail": "Could not validate credentials" } ``` ### 권한 오류 (403) ```json { "detail": "관리자 권한이 필요합니다." } ``` ### 리소스 없음 (404) ```json { "detail": "프로젝트를 찾을 수 없습니다." } ``` ### 유효성 검사 오류 (422) ```json { "detail": [ { "loc": ["body", "job_no"], "msg": "field required", "type": "value_error.missing" } ] } ``` --- ## 파일 업로드 ### 이미지 업로드 - **형식:** Base64 인코딩된 이미지 데이터 - **지원 형식:** JPEG, PNG, GIF, WebP - **최대 크기:** 10MB - **저장 위치:** `/app/uploads/` ### Base64 형식 예시 ``` data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwCdABmX/9k= ``` --- ## 개발 환경 설정 ### 환경 변수 ```env DATABASE_URL=postgresql://mproject:mproject2024@db:5432/mproject SECRET_KEY=your-secret-key-here-change-in-production ALGORITHM=HS256 ACCESS_TOKEN_EXPIRE_MINUTES=10080 ADMIN_USERNAME=hyungi ADMIN_PASSWORD=djg3-jj34-X3Q3 TZ=Asia/Seoul ``` ### Docker 컨테이너 실행 ```bash docker-compose up -d ``` ### API 문서 확인 - **Swagger UI:** http://localhost:16000/docs - **ReDoc:** http://localhost:16000/redoc