M-Project/API_DOCUMENTATION.md

M-Project API 문서

개요

작업보고서 시스템의 FastAPI 백엔드 API 엔드포인트 문서

Base URL: http://localhost:16000

---

인증 (Authentication)

JWT 토큰 기반 인증

• 토큰 타입: Bearer Token
• 만료 시간: 7일 (10080분)
• 헤더: Authorization: Bearer <token>

---

API 엔드포인트

🔐 인증 관련 API (/api/auth)

1. 로그인

POST /api/auth/login
Content-Type: application/x-www-form-urlencoded

username=hyungi&password=djg3-jj34-X3Q3

응답:

{
  "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. 현재 사용자 정보

GET /api/auth/me
Authorization: Bearer <token>

3. 사용자 생성 (관리자만)

POST /api/auth/users
Authorization: Bearer <token>
Content-Type: application/json

{
  "username": "user1",
  "password": "password123",
  "full_name": "사용자1",
  "role": "user"
}

4. 사용자 목록 조회 (관리자만)

GET /api/auth/users?skip=0&limit=100
Authorization: Bearer <token>

5. 사용자 수정 (관리자만)

PUT /api/auth/users/{user_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "full_name": "수정된 이름",
  "role": "admin"
}

6. 사용자 삭제 (관리자만)

DELETE /api/auth/users/{username}
Authorization: Bearer <token>

7. 비밀번호 변경

POST /api/auth/change-password
Authorization: Bearer <token>
Content-Type: application/json

{
  "current_password": "old_password",
  "new_password": "new_password"
}

---

📁 프로젝트 관리 API (/api/projects)

1. 프로젝트 생성 (관리자만)

POST /api/projects
Authorization: Bearer <token>
Content-Type: application/json

{
  "job_no": "JOB-2024-001",
  "project_name": "신규 프로젝트"
}

응답:

{
  "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. 프로젝트 목록 조회

GET /api/projects?skip=0&limit=100&active_only=true
Authorization: Bearer <token>

3. 특정 프로젝트 조회

GET /api/projects/{project_id}
Authorization: Bearer <token>

4. 프로젝트 수정 (관리자만)

PUT /api/projects/{project_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "project_name": "수정된 프로젝트명",
  "is_active": true
}

5. 프로젝트 삭제 (관리자만)

DELETE /api/projects/{project_id}
Authorization: Bearer <token>

---

🚨 부적합 사항 API (/api/issues)

1. 부적합 사항 생성

POST /api/issues
Authorization: Bearer <token>
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. 부적합 사항 목록 조회

GET /api/issues?skip=0&limit=100
Authorization: Bearer <token>

3. 특정 부적합 사항 조회

GET /api/issues/{issue_id}
Authorization: Bearer <token>

4. 부적합 사항 수정

PUT /api/issues/{issue_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "category": "design_error",
  "description": "수정된 설명",
  "work_hours": 2.5,
  "status": "complete",
  "detail_notes": "해결 완료"
}

상태 값:

• new: 신규
• progress: 진행중
• complete: 완료

5. 부적합 사항 삭제

DELETE /api/issues/{issue_id}
Authorization: Bearer <token>

---

📊 일일 공수 API (/api/daily-work)

1. 일일 공수 생성

POST /api/daily-work
Authorization: Bearer <token>
Content-Type: application/json

{
  "date": "2024-01-01T00:00:00",
  "worker_count": 10,
  "overtime_workers": 3,
  "overtime_hours": 4.0
}

2. 일일 공수 목록 조회

GET /api/daily-work?skip=0&limit=100
Authorization: Bearer <token>

3. 특정 일일 공수 조회

GET /api/daily-work/{work_id}
Authorization: Bearer <token>

4. 일일 공수 수정

PUT /api/daily-work/{work_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "worker_count": 12,
  "overtime_workers": 5,
  "overtime_hours": 6.0
}

5. 일일 공수 삭제

DELETE /api/daily-work/{work_id}
Authorization: Bearer <token>

---

📈 보고서 API (/api/reports)

1. 보고서 생성

POST /api/reports/generate
Authorization: Bearer <token>
Content-Type: application/json

{
  "start_date": "2024-01-01T00:00:00",
  "end_date": "2024-01-31T23:59:59"
}

응답:

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

---

헬스체크

서버 상태 확인

GET /api/health

응답:

{
  "status": "healthy"
}

---

에러 응답 형식

인증 오류 (401)

{
  "detail": "Could not validate credentials"
}

권한 오류 (403)

{
  "detail": "관리자 권한이 필요합니다."
}

리소스 없음 (404)

{
  "detail": "프로젝트를 찾을 수 없습니다."
}

유효성 검사 오류 (422)

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

---

개발 환경 설정

환경 변수

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 컨테이너 실행

docker-compose up -d

API 문서 확인

• Swagger UI: http://localhost:16000/docs
• ReDoc: http://localhost:16000/redoc