도자 공방 운영 허브 API 문서

1. 공통 기준

대상: Next.js 기반 웹 서비스의 화면과 서버 기능 연결
데이터 범위: 모든 운영 데이터는 로그인한 생활도자 공방 안에서만 조회·수정합니다. 다른 생활도자 공방 데이터는 절대 조회되지 않습니다. (NFR-001)
인증 방식
- 대표 운영자·보조 강사: 로그인 후 발급된 세션 또는 인증 정보 사용
- 회원: 공방에서 전달한 회원 전용 초대 주소와 최초 접근 코드로 본인 확인 후 회원 전용 세션 사용
날짜 형식: YYYY-MM-DD
시간 형식: YYYY-MM-DDTHH:mm:ssZ
작품 번호 예시: 2608-01
공통 오류 응답 형식

{
  "message": "사용자가 이해할 수 있는 오류 안내 문구",
  "field": "오류가 난 입력 항목",
  "code": "처리용 오류 코드"
}

사진은 회원 정보와 연결되는 자료이므로 로그인한 권한 범위 안에서만 볼 수 있습니다. 사진 주소는 외부에 공개하지 않고, 접근 권한을 확인한 뒤 제공합니다. (NFR-002)
작품, 회원권, 선반 위치를 동시에 수정할 때는 마지막 수정 시각을 함께 보내 최신 데이터인지 확인합니다. 다른 사용자가 먼저 수정했다면 저장하지 않고 최신 내용을 보여 줍니다. (NFR-003)
모바일 웹에서 사진 촬영, 작품 번호 검색, 단계 변경을 빠르게 수행할 수 있어야 합니다. (NFR-004, NFR-005)
화면에서 사용하는 버튼, 입력칸, 오류 문구는 키보드와 화면 읽기 도구로도 이용할 수 있어야 합니다. (NFR-006)
작품 번호 정정, 단계 변경, 선반 칸 변경, 회원권 잔여 횟수 변경은 변경 이력을 남깁니다. (NFR-007)
지원 브라우저 범위는 개발 시작 전 확정이 필요합니다. 일반적인 최신 모바일·데스크톱 브라우저를 우선 지원 대상으로 합니다. (NFR-008)

2. 로그인과 역할별 접근

운영자 로그인 — `POST /api/auth/operator/login`

목적: 대표 운영자와 보조 강사가 로그인해 운영자 대시보드로 이동합니다. (FR-001, UIR-001)
인증 여부: 불필요
요청값

{
  "loginId": "operator@example.com",
  "password": "비밀번호"
}

성공 응답

{
  "user": {
    "id": "operator_01",
    "name": "김도자",
    "role": "대표 운영자",
    "studioId": "studio_01"
  },
  "redirectPath": "/dashboard"
}

사용자 오류 상황
- 아이디 또는 비밀번호가 맞지 않으면 아이디 또는 비밀번호를 다시 확인해 주세요.를 표시합니다.
- 비활성화된 계정이면 현재 사용할 수 없는 계정입니다.를 표시합니다.
- 로그인에 성공해도 다른 생활도자 공방의 데이터에는 접근할 수 없습니다.

회원 본인 확인 — `POST /api/member-access/verify`

목적: 회원이 초대 주소와 최초 접근 코드로 본인 확인 후, 본인의 작품 조회 화면으로 이동합니다. (FR-001, FR-016, UIR-001, UIR-010)
인증 여부: 불필요
요청값

{
  "inviteToken": "초대주소에 포함된_값",
  "accessCode": "123456"
}

성공 응답

{
  "member": {
    "id": "member_01",
    "name": "홍길동"
  },
  "redirectPath": "/my-works"
}

사용자 오류 상황
- 최초 접근 코드가 틀리면 접근 코드를 다시 확인해 주세요.를 표시합니다.
- 만료된 초대 주소면 초대 주소의 사용 기간이 지났습니다. 공방에 새 주소를 요청해 주세요.를 표시합니다.
- 다른 회원의 초대 주소를 사용하거나 주소를 임의로 바꾼 경우 내 작품 정보에 접근할 수 없습니다.를 표시합니다.

로그아웃 — `POST /api/auth/logout`

목적: 운영자 또는 회원의 현재 로그인 상태를 종료합니다. (FR-001)
인증 여부: 필요
요청값: 없음
성공 응답

{
  "message": "로그아웃되었습니다."
}

사용자 오류 상황
- 이미 로그인 상태가 끝난 경우에도 로그인 화면으로 이동시킵니다.

3. 초기 설정과 공방 작업 기준

초기 설정 현황 조회 — `GET /api/setup/status`

목적: 대표 운영자가 현재 초기 설정 진행 상태와 미완료 항목을 확인합니다. (FR-002, UIR-002)
인증 여부: 대표 운영자 필요
요청값: 없음
성공 응답

{
  "isOperatingStarted": false,
  "steps": [
    { "key": "shelves", "label": "선반과 선반 칸 등록", "completed": true },
    { "key": "stageDurations", "label": "단계별 기본 소요 기간 설정", "completed": true },
    { "key": "members", "label": "현재 회원 등록", "completed": true },
    { "key": "works", "label": "현재 보관 중인 작품 등록", "completed": false }
  ],
  "summary": {
    "registeredMembers": 40,
    "registeredWorksByStage": {
      "건조": 12,
      "초벌 대기": 18,
      "초벌 완료": 5,
      "시유": 7,
      "재벌 대기": 10,
      "완성": 0
    },
    "worksWithoutLocation": 2
  }
}

사용자 오류 상황
- 보조 강사가 접근하면 초기 설정 시작과 운영 시작 확정은 대표 운영자만 할 수 있습니다.를 표시합니다.

초기 설정 운영 시작 확정 — `POST /api/setup/complete`

목적: 현재 회원과 작품 등록 범위를 확인한 뒤 생활도자 공방의 운영 시작 상태를 확정합니다. (FR-002, UIR-002)
인증 여부: 대표 운영자 필요
요청값

{
  "confirmedWorkScope": "현재 보관 중인 작품 52점 등록 완료"
}

성공 응답

{
  "isOperatingStarted": true,
  "message": "운영을 시작할 수 있습니다."
}

사용자 오류 상황
- 선반 칸, 단계별 기본 소요 기간, 필수 작품 정보 등이 빠진 경우 미완료된 설정 항목을 먼저 확인해 주세요.와 항목 목록을 표시합니다.
- 작품 번호가 중복된 작품은 등록 완료 작품 수에 포함하지 않습니다.

공방 작업 기준 조회 — `GET /api/studio/work-settings`

목적: 현재 생활도자 공방의 단계별 선반, 선반 칸, 선반 사진, 단계별 기본 소요 기간을 불러옵니다. (FR-003, UIR-012)
인증 여부: 대표 운영자 또는 보조 강사 필요
요청값: 없음
성공 응답

{
  "stages": [
    {
      "name": "초벌 대기",
      "defaultDaysToCompletion": 18,
      "shelves": [
        {
          "id": "shelf_21",
          "name": "초벌 대기 2번 선반",
          "photoUrl": "권한 확인 후 제공되는 사진 주소",
          "slots": [
            { "id": "slot_211", "label": "1칸", "isActive": true },
            { "id": "slot_212", "label": "2칸", "isActive": true }
          ]
        }
      ]
    }
  ]
}

사용자 오류 상황
- 작업 기준이 아직 없으면 공방 작업 기준을 먼저 등록해 주세요.를 표시합니다.

공방 작업 기준 저장 — `PUT /api/studio/work-settings`

목적: 대표 운영자가 단계별 선반·선반 칸과 예상 완성 시점 계산용 기본 소요 기간을 등록하거나 수정합니다. (FR-003, UIR-012)
인증 여부: 대표 운영자 필요
요청값

{
  "stages": [
    {
      "name": "초벌 대기",
      "defaultDaysToCompletion": 18,
      "shelves": [
        {
          "id": "shelf_21",
          "name": "초벌 대기 2번 선반",
          "photoId": "file_001",
          "slots": [
            { "id": "slot_211", "label": "1칸" },
            { "id": "slot_212", "label": "2칸" }
          ]
        }
      ]
    }
  ]
}

성공 응답

{
  "message": "공방 작업 기준이 저장되었습니다.",
  "updatedAt": "2026-08-21T10:30:00Z"
}

사용자 오류 상황
- 같은 선반에 같은 선반 칸 번호를 등록하면 같은 선반 안에서는 선반 칸 번호를 중복할 수 없습니다.를 표시합니다.
- 작품이 남아 있는 선반 또는 선반 칸을 삭제하려 하면 이 선반 칸에 작품이 있어 삭제할 수 없습니다. 작품을 먼저 옮겨 주세요.를 표시합니다.
- 기본 소요 기간이 없는 단계는 예상 완성 시점을 계산할 수 없습니다.로 표시합니다.

사진 업로드 — `POST /api/files/images`

목적: 작품 사진 또는 선반 사진을 모바일 웹에서 촬영하거나 선택해 업로드합니다. (FR-003, FR-007)
인증 여부: 대표 운영자 또는 보조 강사 필요
요청값: multipart/form-data

항목	설명
`image`	업로드할 사진 파일
`purpose`	`work` 또는 `shelf`

성공 응답

{
  "fileId": "file_001",
  "previewUrl": "권한 확인 후 제공되는 미리보기 주소"
}

사용자 오류 상황
- 사진 업로드가 실패하면 사진을 올리지 못했습니다. 네트워크를 확인한 뒤 다시 시도해 주세요.를 표시합니다.
- 지원하지 않는 파일이면 사진 파일만 올릴 수 있습니다.를 표시합니다.

4. 회원과 회원권 관리

회원 목록 조회 — `GET /api/members`

목적: 운영자가 회원을 검색하고 회원권 잔여 횟수, 유효기간, 연결 작품 수를 확인합니다. (FR-004, FR-005, UIR-009)
인증 여부: 대표 운영자 또는 보조 강사 필요
요청값

쿼리값	설명
`query`	회원명 또는 회원 식별 정보 검색어
`status`	`active`, `inactive`, `all`
`page`	페이지 번호
`size`	한 번에 볼 회원 수

성공 응답

{
  "items": [
    {
      "id": "member_01",
      "name": "홍길동",
      "status": "active",
      "membershipPass": {
        "name": "월 정기권",
        "remainingCount": 6,
        "validUntil": "2026-08-31",
        "isExpired": false
      },
      "connectedWorkCount": 4
    }
  ],
  "page": 1,
  "totalCount": 40
}

사용자 오류 상황
- 검색 결과가 없으면 조건에 맞는 회원이 없습니다.를 표시합니다.
- 다른 생활도자 공방의 회원은 검색 결과에 포함하지 않습니다.

회원 등록 — `POST /api/members`

목적: 운영자가 새 회원을 등록합니다. (FR-004, UIR-009)
인증 여부: 대표 운영자 또는 보조 강사 필요
요청값

{
  "name": "홍길동",
  "memberIdentifier": "전화번호 뒤 4자리 등 공방이 정한 식별 정보",
  "status": "active"
}

성공 응답

{
  "id": "member_01",
  "name": "홍길동",
  "message": "회원이 등록되었습니다."
}

사용자 오류 상황
- 이름이 같은 회원이 있으면 이름이 같은 회원이 있습니다. 식별 정보와 연결 작품을 확인해 주세요.를 표시합니다.
- 필수 식별 정보가 없으면 회원 구분에 필요한 정보를 입력해 주세요.를 표시합니다.

회원 상세 조회 — `GET /api/members/{memberId}`

목적: 회원의 회원권, 잔여 횟수, 유효기간, 연결된 작품, 회원 전용 조회 발급 상태를 확인합니다. (FR-004, FR-005, UIR-009)
인증 여부: 대표 운영자 또는 보조 강사 필요
성공 응답

{
  "id": "member_01",
  "name": "홍길동",
  "status": "active",
  "membershipPass": {
    "id": "pass_01",
    "name": "월 정기권",
    "remainingCount": 6,
    "validUntil": "2026-08-31",
    "memo": "체험 후 등록 할인"
  },
  "works": [
    {
      "id": "work_01",
      "workNumber": "2608-01",
      "currentStage": "초벌 대기",
      "shelfSlotLabel": "초벌 대기 2번 선반 1칸",
      "estimatedCompletionDate": "2026-09-12"
    }
  ],
  "memberAccess": {
    "isIssued": true,
    "expiresAt": "2026-12-31"
  }
}

사용자 오류 상황
- 현재 생활도자 공방에 없는 회원 주소로 접근하면 회원 정보를 찾을 수 없습니다.를 표시합니다.

회원 전용 조회 초대 정보 발급 — `POST /api/members/{memberId}/access-invites`

목적: 운영자가 회원 전용 내 작품 조회를 사용할 수 있도록 초대 주소와 최초 접근 정보를 발급합니다. (FR-004, FR-016, UIR-009)
인증 여부: 대표 운영자 또는 보조 강사 필요
요청값

{
  "expiresAt": "2026-12-31"
}

성공 응답

{
  "inviteUrl": "https://service.example/member-access/...",
  "initialAccessCode": "123456",
  "expiresAt": "2026-12-31"
}

사용자 오류 상황
- 비활성 회원에게 발급하려 하면 비활성 회원에게는 초대 정보를 발급할 수 없습니다.를 표시합니다.

회원권 등록·수정 — `PUT /api/members/{memberId}/membership-pass`

목적: 월 정기권, 10회권 등 회원권 종류와 잔여 횟수, 유효기간을 관리합니다. (FR-005, UIR-009)
인증 여부: 대표 운영자 또는 보조 강사 필요
요청값

{
  "name": "10회권",
  "remainingCount": 8,
  "validUntil": "2026-10-31",
  "memo": "체험 후 등록 할인",
  "changeReason": "신규 등록 또는 이용 횟수 조정 사유",
  "lastUpdatedAt": "2026-08-21T09:00:00Z"
}

성공 응답

{
  "membershipPass": {
    "id": "pass_01",
    "name": "10회권",
    "remainingCount": 8,
    "validUntil": "2026-10-31"
  },
  "changeHistoryAdded": true
}

사용자 오류 상황
- 잔여 횟수를 음수로 입력하면 잔여 횟수는 0보다 작게 저장할 수 없습니다.를 표시합니다.
- 잔여 횟수 변경 사유가 없으면 횟수를 변경한 이유를 입력해 주세요.를 표시합니다.
- 다른 운영자가 먼저 수정했다면 다른 사용자가 회원권 정보를 변경했습니다. 최신 내용을 확인한 뒤 다시 저장해 주세요.를 표시합니다.
- 유효기간이 지난 회원권은 응답에서 기간 만료 상태를 함께 표시합니다.

회원권 잔여 횟수 변경 이력 조회 — `GET /api/members/{memberId}/membership-pass/history`

목적: 회원권 잔여 횟수의 변경 전후 값, 변경자, 변경 시각과 사유를 확인합니다. (FR-005, UIR-009)
인증 여부: 대표 운영자 또는 보조 강사 필요
성공 응답

{
  "items": [
    {
      "beforeCount": 10,
      "afterCount": 8,
      "reason": "수업 2회 이용",
      "changedBy": "보조 강사",
      "changedAt": "2026-08-21T10:00:00Z"
    }
  ]
}

사용자 오류 상황
- 회원권이 등록되지 않은 회원이면 등록된 회원권이 없습니다.를 표시합니다.

5. 작품 번호와 작품 등록

다음 작품 번호 제안 — `GET /api/work-numbers/suggestion`

목적: 제작 연월을 기준으로 다음 작품 번호를 제안하고, 저장 전 중복 여부를 확인할 수 있게 합니다. (FR-006, UIR-006)
인증 여부: 대표 운영자 또는 보조 강사 필요
요청값

쿼리값	설명
`productionMonth`	제작 연월 4자리. 예: `2608`

성공 응답

{
  "suggestedWorkNumber": "2608-01",
  "formatGuide": "제작 연월 4자리-순번으로 입력합니다. 예: 2608-01"
}

사용자 오류 상황
- 같은 달 작품이 99점을 넘는 경우 현재 번호 규칙으로는 처리 기준이 확정되지 않았으므로 해당 월의 작품 번호 규칙을 확인해 주세요.를 표시합니다.
- 2608-01 형식이 아니거나 일곱 자를 넘으면 저장 단계에서 입력을 막습니다.

작품 번호 중복 확인 — `GET /api/work-numbers/check`

목적: 작품 등록 또는 작품 번호 정정 전에 현재 생활도자 공방 안에서 작품 번호 중복 여부를 확인합니다. (FR-006, UIR-006, UIR-007)
인증 여부: 대표 운영자 또는 보조 강사 필요
요청값

쿼리값	설명
`workNumber`	확인할 작품 번호
`excludeWorkId`	번호 정정 중인 기존 작품 ID. 새 작품 등록 시 생략

성공 응답

{
  "workNumber": "2608-01",
  "isAvailable": true
}

사용자 오류 상황
- 이미 사용 중이면 같은 생활도자 공방에 이미 등록된 작품 번호입니다.를 표시합니다.
- 다른 생활도자 공방에서 같은 번호를 쓰는 것은 중복으로 처리하지 않습니다.

작품 등록 — `POST /api/works`

목적: 작품 번호, 회원, 작품 사진, 현재 제작 단계, 선반 칸을 연결해 작품 한 점을 등록합니다. (FR-006, FR-007, FR-015, UIR-006)
인증 여부: 대표 운영자 또는 보조 강사 필요
요청값

{
  "workNumber": "2608-01",
  "memberId": "member_01",
  "photoId": "file_001",
  "currentStage": "초벌 대기",
  "shelfSlotId": "slot_211",
  "widthCm": 9.5,
  "heightCm": 11,
  "kilnPlannedDate": "2026-08-28"
}

항목	필수 여부	설명
`workNumber`	필수	작품 바닥에 새긴 작품 번호
`memberId`	필수	작품 소유 회원
`photoId`	필수	작품 사진
`currentStage`	필수	현재 제작 단계
`shelfSlotId`	필수	현재 단계에 연결된 선반 칸
`widthCm`, `heightCm`	선택	다음 가마 후보 비교용 크기·높이
`kilnPlannedDate`	선택	초벌 대기 또는 재벌 대기 작품의 가마 예정일

성공 응답

{
  "id": "work_01",
  "workNumber": "2608-01",
  "currentStage": "초벌 대기",
  "shelfSlotLabel": "초벌 대기 2번 선반 1칸",
  "estimatedCompletionDate": "2026-09-12",
  "message": "작품이 등록되었습니다."
}

사용자 오류 상황
- 작품 번호, 회원, 작품 사진, 현재 제작 단계, 선반 칸 중 하나라도 없으면 필수 작품 정보를 모두 입력해 주세요.를 표시합니다.
- 선택한 선반 칸이 현재 제작 단계와 맞지 않으면 선택한 단계에서 사용할 수 있는 선반 칸을 선택해 주세요.를 표시합니다.
- 번호가 중복되면 이미 등록된 작품 번호입니다.를 표시합니다.
- 사진 업로드가 끝나지 않으면 작품 정보를 임시 저장하고 사진 업로드를 다시 시도해 주세요.를 표시합니다.

작품 상세 조회 — `GET /api/works/{workId}`

목적: 운영자가 작품 번호 하나로 작품의 사진, 회원, 현재 제작 단계, 선반 칸, 예상 완성 시점, 회원권 잔여 횟수와 변경 이력을 확인합니다. (FR-008, FR-015, UIR-007)
인증 여부: 대표 운영자 또는 보조 강사 필요
성공 응답

{
  "id": "work_01",
  "workNumber": "2608-01",
  "photoUrl": "권한 확인 후 제공되는 사진 주소",
  "member": {
    "id": "member_01",
    "name": "홍길동",
    "remainingCount": 6
  },
  "currentStage": "초벌 대기",
  "shelf": {
    "id": "shelf_21",
    "name": "초벌 대기 2번 선반"
  },
  "shelfSlot": {
    "id": "slot_211",
    "label": "1칸"
  },
  "dimensions": {
    "widthCm": 9.5,
    "heightCm": 11
  },
  "kilnPlannedDate": "2026-08-28",
  "estimatedCompletionDate": "2026-09-12",
  "lastUpdatedAt": "2026-08-21T10:00:00Z"
}

사용자 오류 상황
- 다른 생활도자 공방의 작품 주소로 접근하면 작품을 찾을 수 없습니다.를 표시합니다.

작품 번호 검색 — `GET /api/works/search`

목적: 운영자가 작품 번호로 작품을 즉시 찾습니다. 일부 번호를 입력하면 현재 생활도자 공방 안의 후보만 보여 줍니다. (FR-008, UIR-004, UIR-007)
인증 여부: 대표 운영자 또는 보조 강사 필요
요청값

쿼리값	설명
`workNumber`	전체 또는 일부 작품 번호

성공 응답

{
  "items": [
    {
      "id": "work_01",
      "workNumber": "2608-01",
      "photoUrl": "권한 확인 후 제공되는 사진 주소",
      "memberName": "홍길동",
      "currentStage": "초벌 대기",
      "shelfSlotLabel": "초벌 대기 2번 선반 1칸",
      "estimatedCompletionDate": "2026-09-12"
    }
  ]
}

사용자 오류 상황
- 일치하는 작품이 없으면 입력값을 유지한 채 등록된 작품이 없습니다.를 표시합니다.

작품 수정과 작품 번호 정정 — `PUT /api/works/{workId}`

목적: 작품 사진, 회원, 크기·높이, 가마 예정일을 수정하거나 작품 번호를 정정합니다. 번호 정정 시 이전 번호 기록을 남깁니다. (FR-006, FR-007, FR-015, UIR-006, UIR-007)
인증 여부: 대표 운영자 또는 보조 강사 필요
요청값

{
  "workNumber": "2608-02",
  "memberId": "member_01",
  "photoId": "file_002",
  "widthCm": 9.5,
  "heightCm": 11,
  "kilnPlannedDate": "2026-08-29",
  "lastUpdatedAt": "2026-08-21T10:00:00Z"
}

성공 응답

{
  "id": "work_01",
  "workNumber": "2608-02",
  "estimatedCompletionDate": "2026-09-13",
  "workNumberCorrectionHistoryAdded": true
}

사용자 오류 상황
- 수정한 작품 번호가 이미 사용 중이면 같은 생활도자 공방에 이미 등록된 작품 번호입니다.를 표시합니다.
- 다른 사용자가 먼저 수정했다면 다른 사용자가 작품 정보를 변경했습니다. 최신 내용을 확인해 주세요.를 표시합니다.
- 작품 번호 형식이 맞지 않으면 작품 번호는 2608-01 형식으로 입력해 주세요.를 표시합니다.

작품 변경 이력 조회 — `GET /api/works/{workId}/histories`

목적: 작품의 단계 변경 이력, 위치 변경 이력, 작품 번호 정정 기록을 확인합니다. (FR-006, FR-008, FR-010, UIR-007)
인증 여부: 대표 운영자 또는 보조 강사 필요
요청값

쿼리값	설명
`type`	`stage`, `location`, `workNumber`, `all`

성공 응답

{
  "items": [
    {
      "type": "stage",
      "beforeValue": "건조",
      "afterValue": "초벌 대기",
      "changedBy": "대표 운영자",
      "changedAt": "2026-08-21T11:00:00Z"
    },
    {
      "type": "location",
      "beforeValue": "건조 1번 선반 2칸",
      "afterValue": "초벌 대기 2번 선반 1칸",
      "changedBy": "대표 운영자",
      "changedAt": "2026-08-21T11:00:00Z"
    }
  ]
}

사용자 오류 상황
- 기록이 없으면 아직 변경 이력이 없습니다.를 표시합니다.

6. 작품 목록, 단계 변경과 운영자 대시보드

단계별 작품 목록 조회 — `GET /api/works`

목적: 현재 제작 단계와 선반 칸을 기준으로 작품을 찾고, 여러 작품을 선택해 다음 작업을 시작합니다. (FR-009, UIR-005)
인증 여부: 대표 운영자 또는 보조 강사 필요
요청값

쿼리값	설명
`stage`	현재 제작 단계
`shelfId`	선반 ID
`memberQuery`	회원명 검색어
`workNumber`	작품 번호 검색어
`page`	페이지 번호
`size`	한 번에 볼 작품 수

성공 응답

{
  "items": [
    {
      "id": "work_01",
      "workNumber": "2608-01",
      "photoUrl": "권한 확인 후 제공되는 사진 주소",
      "memberName": "홍길동",
      "currentStage": "초벌 대기",
      "shelfSlotLabel": "초벌 대기 2번 선반 1칸",
      "estimatedCompletionDate": "2026-09-12",
      "hasPhotoIssue": false,
      "isOnInactiveShelf": false
    }
  ],
  "totalCount": 18
}

사용자 오류 상황
- 조건에 맞는 작품이 없으면 조건에 맞는 작품이 없습니다.를 표시하고 필터 해제 기능을 제공합니다.
- 사진을 불러오지 못하면 대체 이미지를 보여 주고 작품 사진을 확인할 수 없습니다.를 표시합니다.
- 비활성 선반에 남은 작품에는 선반 확인 필요 경고를 표시합니다.

작품 단계와 선반 칸 변경 — `PATCH /api/works/{workId}/stage-location`

목적: 작품 한 점의 현재 제작 단계 또는 선반 칸을 변경하고, 단계 변경 이력과 위치 변경 이력을 남깁니다. (FR-010, FR-015, UIR-007)
인증 여부: 대표 운영자 또는 보조 강사 필요
요청값

{
  "nextStage": "시유",
  "nextShelfSlotId": "slot_310",
  "correctionReason": null,
  "lastUpdatedAt": "2026-08-21T10:00:00Z"
}

항목	설명
`nextStage`	변경할 현재 제작 단계
`nextShelfSlotId`	새 단계 또는 같은 단계에서 사용할 선반 칸
`correctionReason`	이전 단계로 되돌리는 경우 필수
`lastUpdatedAt`	다른 사용자의 선행 수정 여부 확인값

성공 응답

{
  "workId": "work_01",
  "currentStage": "시유",
  "shelfSlotLabel": "시유 1번 선반 3칸",
  "estimatedCompletionDate": "2026-09-10",
  "stageHistoryAdded": true,
  "locationHistoryAdded": true
}

사용자 오류 상황
- 새 단계와 맞지 않는 선반 칸을 선택하면 변경할 단계에서 사용할 수 있는 선반 칸을 선택해 주세요.를 표시합니다.
- 이전 단계로 되돌리면서 사유를 입력하지 않으면 단계를 되돌리는 이유를 입력해 주세요.를 표시합니다.
- 다른 사용자가 먼저 변경하면 다른 사용자가 작품 위치 또는 단계를 변경했습니다. 최신 상태를 확인해 주세요.를 표시합니다.
- 저장 실패 시 기존 단계와 선반 칸은 유지합니다.

여러 작품 상태 한꺼번에 변경 — `POST /api/works/bulk-stage-location`

목적: 선반 또는 가마 목록에서 여러 작품을 선택해 동일한 현재 제작 단계와 선반 칸으로 한꺼번에 변경합니다. (FR-011, FR-015, UIR-008)
인증 여부: 대표 운영자 또는 보조 강사 필요
요청값

{
  "works": [
    {
      "workId": "work_01",
      "lastUpdatedAt": "2026-08-21T10:00:00Z"
    },
    {
      "workId": "work_02",
      "lastUpdatedAt": "2026-08-21T10:03:00Z"
    }
  ],
  "nextStage": "초벌 완료",
  "nextShelfSlotId": "slot_410"
}

성공 응답

{
  "successItems": [
    {
      "workId": "work_01",
      "workNumber": "2608-01",
      "currentStage": "초벌 완료",
      "shelfSlotLabel": "초벌 완료 1번 선반 1칸"
    }
  ],
  "failedItems": [
    {
      "workId": "work_02",
      "workNumber": "2608-02",
      "reason": "다른 사용자가 먼저 작품 정보를 수정했습니다."
    }
  ]
}

사용자 오류 상황
- 선택한 작품이 없으면 변경할 작품을 한 점 이상 선택해 주세요.를 표시합니다.
- 초벌 대기 작품과 재벌 대기 작품을 같은 가마 관련 변경으로 처리하려 하면 초벌 대기 작품과 재벌 대기 작품은 나누어 처리해 주세요.를 표시합니다.
- 일부 작품만 변경 가능한 경우 성공 작품만 저장하고 실패 작품과 이유를 보여 줍니다.

운영자 대시보드 조회 — `GET /api/dashboard`

목적: 운영자가 단계별 작품 수, 초벌·재벌 대기 작품 수, 오늘 확인할 작품과 회원, 다음 가마 후보 일부를 한 화면에서 확인합니다. (FR-012, FR-013, FR-014, UIR-003, UIR-004)
인증 여부: 대표 운영자 또는 보조 강사 필요
요청값: 없음
성공 응답

{
  "workCountsByStage": {
    "건조": 12,
    "초벌 대기": 18,
    "초벌 완료": 5,
    "시유": 7,
    "재벌 대기": 10,
    "완성": 8
  },
  "kilnWaitingCounts": {
    "초벌": 18,
    "재벌": 10
  },
  "todayToCheck": {
    "works": [
      {
        "workId": "work_01",
        "workNumber": "2608-01",
        "reason": "예상 완성 시점이 가까움"
      }
    ],
    "members": [
      {
        "memberId": "member_01",
        "name": "홍길동",
        "reason": "회원권 유효기간 확인 필요"
      }
    ]
  },
  "warnings": {
    "worksWithoutStageOrShelfSlot": 2,
    "membersWithoutMembershipPass": 1
  },
  "nextKilnCandidatesPreview": {
    "초벌": 18,
    "재벌": 10
  }
}

사용자 오류 상황
- 등록 작품이 없으면 등록된 작품이 없습니다. 초기 설정 또는 작품 등록을 시작해 주세요.를 표시합니다.
- 단계 또는 선반 칸이 누락된 작품은 경고 영역에 별도로 표시합니다.
- 회원권이 없거나 잔여 횟수를 쓰지 않는 회원은 등록된 회원권 없음으로 표시합니다.

7. 가마 대기와 다음 가마 후보

가마 대기 작품 조회 — `GET /api/kiln-waiting/works`

목적: 초벌 대기 작품과 재벌 대기 작품을 섞지 않고 각각 확인합니다. (FR-013, UIR-004)
인증 여부: 대표 운영자 또는 보조 강사 필요
요청값

쿼리값	설명
`firingType`	필수. `bisque`(초벌) 또는 `glaze`(재벌)
`shelfId`	선택한 선반으로 목록 좁히기
`sort`	`waitingLongest`, `workNumber`, `height` 등

성공 응답

{
  "firingType": "bisque",
  "stage": "초벌 대기",
  "totalCount": 18,
  "items": [
    {
      "workId": "work_01",
      "workNumber": "2608-01",
      "memberName": "홍길동",
      "photoUrl": "권한 확인 후 제공되는 사진 주소",
      "shelfSlotLabel": "초벌 대기 2번 선반 1칸",
      "widthCm": 9.5,
      "heightCm": 11,
      "waitingSince": "2026-08-15",
      "kilnPlannedDate": "2026-08-28"
    }
  ]
}

사용자 오류 상황
- 초벌과 재벌을 동시에 요청하면 초벌 대기와 재벌 대기 작품은 따로 확인해 주세요.를 표시합니다.
- 대기 작품이 없으면 현재 가마 대기 작품이 없습니다.를 표시합니다.

다음 가마 후보 비교 조회 — `GET /api/kiln-candidates`

목적: 운영자가 초벌 또는 재벌 중 하나를 선택해 작품 크기·높이, 대기 기간, 선반 위치, 가마 예정일을 비교하고 다음 가마 후보를 고릅니다. (FR-014, UIR-011)
인증 여부: 대표 운영자 또는 보조 강사 필요
요청값

쿼리값	설명
`firingType`	필수. `bisque` 또는 `glaze`
`sort`	`waitingLongest`, `height`, `workNumber`
`selectedWorkIds`	선택한 후보 작품 ID 목록. 선택 전에는 생략 가능

성공 응답

{
  "firingType": "bisque",
  "candidateWorks": [
    {
      "workId": "work_01",
      "workNumber": "2608-01",
      "photoUrl": "권한 확인 후 제공되는 사진 주소",
      "shelfSlotLabel": "초벌 대기 2번 선반 1칸",
      "widthCm": 9.5,
      "heightCm": 11,
      "waitingSince": "2026-08-15",
      "kilnPlannedDate": "2026-08-28"
    }
  ],
  "selectedSummary": {
    "selectedCount": 0,
    "maxHeightCm": null
  },
  "fillRatio": null,
  "fillRatioNotice": "가마 채움 비율 자동 계산은 가마 크기와 작품별 부피 계산 기준 확정 후 제공됩니다."
}

사용자 오류 상황
- 재벌 대기 작품을 초벌 후보로 요청하면 선택한 가마 종류와 작품의 현재 제작 단계가 맞지 않습니다.를 표시합니다.
- 크기 또는 높이가 없는 작품은 크기 또는 높이 미입력으로 표시해 운영자가 실물을 확인할 수 있게 합니다.

확인 필요: 가마 종류별 채워진 공간 비율은 운영자가 가장 먼저 보고 싶은 정보입니다. 다만 자동 계산에는 가마 내부 크기와 작품 부피·배치 기준이 필요하며, 첫 개발 범위에서는 계산 기준이 확정되지 않았습니다. 따라서 첫 개발에서는 초벌·재벌 대기 작품 수와 크기·높이 비교를 제공하고, 채움 비율 자동 계산은 기준 확정 후 추가합니다.

다음 가마 후보 선택 저장 — `POST /api/kiln-candidates/selections`

목적: 운영자가 비교한 작품을 다음 초벌 또는 재벌 작업 후보로 저장해 대시보드와 가마 후보 화면에서 다시 확인합니다. 실제 가마 회차 생성·적재·소성 처리는 첫 개발 범위에 포함하지 않습니다. (FR-014, UIR-011)
인증 여부: 대표 운영자 또는 보조 강사 필요
요청값

{
  "firingType": "bisque",
  "workIds": ["work_01", "work_02", "work_03"],
  "memo": "8월 마지막 주 초벌 후보"
}

성공 응답

{
  "selectionId": "kiln_selection_01",
  "firingType": "bisque",
  "selectedCount": 3,
  "message": "다음 초벌 후보가 저장되었습니다."
}

사용자 오류 상황
- 초벌과 재벌 작품을 함께 선택하면 초벌 후보와 재벌 후보는 분리해서 저장해 주세요.를 표시합니다.
- 현재 가마 대기 상태가 아닌 작품을 선택하면 가마 대기 작품만 후보로 선택할 수 있습니다.를 표시합니다.

8. 예상 완성 시점

예상 완성 시점 재계산 — `POST /api/works/{workId}/estimated-completion/recalculate`

목적: 현재 제작 단계의 기본 소요 기간 또는 초벌·재벌 대기 작품의 가마 예정일을 기준으로 예상 완성 시점을 계산하거나 다시 계산합니다. (FR-015, UIR-006, UIR-007, UIR-010)
인증 여부: 대표 운영자 또는 보조 강사 필요
요청값

{
  "kilnPlannedDate": "2026-08-28"
}

성공 응답

{
  "workId": "work_01",
  "currentStage": "초벌 대기",
  "calculationBase": "가마 예정일",
  "estimatedCompletionDate": "2026-09-12"
}

사용자 오류 상황
- 단계별 기본 소요 기간이 없으면 현재 제작 단계의 기본 소요 기간이 설정되지 않았습니다.를 표시합니다.
- 초벌 대기·재벌 대기가 아닌 작품에 가마 예정일을 넣으려 하면 가마 예정일은 초벌 대기 또는 재벌 대기 작품에만 입력할 수 있습니다.를 표시합니다.
- 완성 작품은 날짜 대신 완성 상태를 반환합니다.

작품 등록, 작품 수정, 단계 변경, 여러 작품 상태 한꺼번에 변경 시에도 이 계산을 자동 적용합니다. 운영자 화면과 회원 전용 내 작품 조회는 같은 계산 결과를 사용합니다. (FR-015)

9. 회원 전용 내 작품 조회

내 작품 목록 조회 — `GET /api/my/works`

목적: 회원이 본인에게 연결된 작품의 사진, 현재 제작 단계, 예상 완성 시점, 완성 여부를 조회합니다. (FR-016, UIR-010)
인증 여부: 회원 전용 인증 필요
요청값: 없음
성공 응답

{
  "member": {
    "name": "홍길동"
  },
  "items": [
    {
      "workId": "work_01",
      "workNumber": "2608-01",
      "photoUrl": "회원 본인만 조회할 수 있는 사진 주소",
      "currentStage": "초벌 대기",
      "estimatedCompletion": {
        "status": "예상",
        "date": "2026-09-12",
        "displayText": "2026년 9월 12일 예상"
      },
      "isCompleted": false
    },
    {
      "workId": "work_02",
      "workNumber": "2607-15",
      "photoUrl": "회원 본인만 조회할 수 있는 사진 주소",
      "currentStage": "완성",
      "estimatedCompletion": {
        "status": "완성",
        "date": null,
        "displayText": "완성"
      },
      "isCompleted": true
    }
  ]
}

사용자 오류 상황
- 회원 전용 인증이 없거나 만료되면 내 작품을 보려면 다시 본인 확인을 해 주세요.를 표시합니다.
- 회원에게 연결된 작품이 없으면 현재 조회할 작품이 없습니다.를 표시합니다.
- 다른 회원 작품 ID를 주소에 직접 넣어도 조회되지 않으며 내 작품 정보에 접근할 수 없습니다.를 표시합니다.

10. 화면별 API 연결 요약

화면	연결 기능
로그인과 회원 본인 확인 (UIR-001)	운영자 로그인, 회원 본인 확인, 로그아웃 (FR-001)
초기 설정 (UIR-002)	초기 설정 현황 조회, 공방 작업 기준 저장, 회원 등록, 작품 등록, 운영 시작 확정 (FR-002, FR-003, FR-004, FR-007)
운영자 대시보드 (UIR-003)	운영자 대시보드 조회, 작품 번호 검색, 가마 대기 작품 조회, 다음 가마 후보 비교 (FR-008, FR-012, FR-013, FR-014)
메인 화면 (UIR-004)	운영자 대시보드 조회, 작품 번호 검색, 단계별 작품 목록, 가마 대기 작품 조회 (FR-008, FR-009, FR-012, FR-013)
단계별 작품 목록 (UIR-005)	단계별 작품 목록 조회, 여러 작품 상태 한꺼번에 변경 (FR-009, FR-011)
작품 등록·수정 (UIR-006)	사진 업로드, 작품 번호 제안·중복 확인, 작품 등록·수정, 예상 완성 시점 계산 (FR-006, FR-007, FR-015)
작품 번호 검색과 작품 상세 (UIR-007)	작품 번호 검색, 작품 상세 조회, 작품 변경 이력 조회, 단계·선반 칸 변경 (FR-008, FR-010, FR-015)
여러 작품 상태 한꺼번에 변경 (UIR-008)	여러 작품 상태 한꺼번에 변경 (FR-011, FR-015)
회원 목록과 회원 상세 (UIR-009)	회원 목록·상세, 회원 등록, 회원 전용 초대 발급, 회원권 관리·이력 조회 (FR-004, FR-005, FR-016)
회원 전용 내 작품 조회 (UIR-010)	회원 본인 확인, 내 작품 목록 조회 (FR-001, FR-016)
다음 가마 후보 비교 (UIR-011)	가마 대기 작품 조회, 다음 가마 후보 비교·선택 저장 (FR-013, FR-014)
공방 작업 기준 설정 (UIR-012)	공방 작업 기준 조회·저장, 선반 사진 업로드 (FR-003)

기능 연결 방식

도자 공방 운영 허브 API 문서

1. 공통 기준

2. 로그인과 역할별 접근

운영자 로그인 — POST /api/auth/operator/login

회원 본인 확인 — POST /api/member-access/verify

로그아웃 — POST /api/auth/logout

3. 초기 설정과 공방 작업 기준

초기 설정 현황 조회 — GET /api/setup/status

초기 설정 운영 시작 확정 — POST /api/setup/complete

공방 작업 기준 조회 — GET /api/studio/work-settings

공방 작업 기준 저장 — PUT /api/studio/work-settings

사진 업로드 — POST /api/files/images

4. 회원과 회원권 관리

회원 목록 조회 — GET /api/members

회원 등록 — POST /api/members

회원 상세 조회 — GET /api/members/{memberId}

회원 전용 조회 초대 정보 발급 — POST /api/members/{memberId}/access-invites

회원권 등록·수정 — PUT /api/members/{memberId}/membership-pass

회원권 잔여 횟수 변경 이력 조회 — GET /api/members/{memberId}/membership-pass/history

5. 작품 번호와 작품 등록

다음 작품 번호 제안 — GET /api/work-numbers/suggestion

작품 번호 중복 확인 — GET /api/work-numbers/check

작품 등록 — POST /api/works

작품 상세 조회 — GET /api/works/{workId}

작품 번호 검색 — GET /api/works/search

작품 수정과 작품 번호 정정 — PUT /api/works/{workId}

작품 변경 이력 조회 — GET /api/works/{workId}/histories

6. 작품 목록, 단계 변경과 운영자 대시보드

단계별 작품 목록 조회 — GET /api/works

작품 단계와 선반 칸 변경 — PATCH /api/works/{workId}/stage-location

여러 작품 상태 한꺼번에 변경 — POST /api/works/bulk-stage-location

운영자 대시보드 조회 — GET /api/dashboard

7. 가마 대기와 다음 가마 후보

가마 대기 작품 조회 — GET /api/kiln-waiting/works

다음 가마 후보 비교 조회 — GET /api/kiln-candidates

다음 가마 후보 선택 저장 — POST /api/kiln-candidates/selections

8. 예상 완성 시점

예상 완성 시점 재계산 — POST /api/works/{workId}/estimated-completion/recalculate

9. 회원 전용 내 작품 조회

내 작품 목록 조회 — GET /api/my/works

10. 화면별 API 연결 요약

운영자 로그인 — `POST /api/auth/operator/login`

회원 본인 확인 — `POST /api/member-access/verify`

로그아웃 — `POST /api/auth/logout`

초기 설정 현황 조회 — `GET /api/setup/status`

초기 설정 운영 시작 확정 — `POST /api/setup/complete`

공방 작업 기준 조회 — `GET /api/studio/work-settings`

공방 작업 기준 저장 — `PUT /api/studio/work-settings`

사진 업로드 — `POST /api/files/images`

회원 목록 조회 — `GET /api/members`

회원 등록 — `POST /api/members`

회원 상세 조회 — `GET /api/members/{memberId}`

회원 전용 조회 초대 정보 발급 — `POST /api/members/{memberId}/access-invites`

회원권 등록·수정 — `PUT /api/members/{memberId}/membership-pass`

회원권 잔여 횟수 변경 이력 조회 — `GET /api/members/{memberId}/membership-pass/history`

다음 작품 번호 제안 — `GET /api/work-numbers/suggestion`

작품 번호 중복 확인 — `GET /api/work-numbers/check`

작품 등록 — `POST /api/works`

작품 상세 조회 — `GET /api/works/{workId}`

작품 번호 검색 — `GET /api/works/search`

작품 수정과 작품 번호 정정 — `PUT /api/works/{workId}`

작품 변경 이력 조회 — `GET /api/works/{workId}/histories`

단계별 작품 목록 조회 — `GET /api/works`

작품 단계와 선반 칸 변경 — `PATCH /api/works/{workId}/stage-location`

여러 작품 상태 한꺼번에 변경 — `POST /api/works/bulk-stage-location`

운영자 대시보드 조회 — `GET /api/dashboard`

가마 대기 작품 조회 — `GET /api/kiln-waiting/works`

다음 가마 후보 비교 조회 — `GET /api/kiln-candidates`

다음 가마 후보 선택 저장 — `POST /api/kiln-candidates/selections`

예상 완성 시점 재계산 — `POST /api/works/{workId}/estimated-completion/recalculate`

내 작품 목록 조회 — `GET /api/my/works`