request.json

{
  "paths": {
    "/api/requests": {
      "get": {
        "tags": ["Request"],
        "summary": "신청 목록 조회",
        "description": "로그인 사용자의 커미션 신청 목록을 조회합니다.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          {
            "name": "filter",
            "in": "query",
            "required": false,
            "schema": { 
              "type": "string", 
              "enum": ["all", "ongoing", "completed"],
              "default": "all"
            },
            "description": "필터 조건 (all: 전체, ongoing: 신청중, completed: 신청완료)"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": { "type": "integer"},
            "description": "페이지 번호"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 10 },
            "description": "페이지당 항목 수"
          }
        ],
        "responses": {
          "200": {
            "description": "신청 목록 조회 성공",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resultType": { "type": "string", "example": "SUCCESS" },
                    "error": { "type": "null", "example": null },
                    "success": {
                      "type": "object",
                      "properties": {
                        "requests": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "requestId": { "type": "integer", "example": 1 },
                              "status": { 
                                "type": "string", 
                                "enum": ["PENDING", "APPROVED", "IN_PROGRESS", "SUBMITTED", "COMPLETED", "CANCELED", "REJECTED"],
                                "example": "IN_PROGRESS" 
                              },
                              "title": { "type": "string", "example": "낙서 타입 커미션" },
                              "price": { "type": "integer", "example": 40000 },
                              "thumbnailImageUrl": { 
                                "type": "string", 
                                "nullable": true,
                                "example": "https://cdn.com/thumbnail.jpg" 
                              },
                              "progressPercent": { 
                                "type": "integer", 
                                "nullable": true,
                                "example": 50,
                                "description": "진행률 (0, 50, 100 또는 null)"
                              },
                              "createdAt": { "type": "string", "format": "date-time", "example": "2025-07-01T10:00:00.000Z" },
                              "artist": {
                                "type": "object",
                                "properties": {
                                  "id": { "type": "integer", "example": 10 },
                                  "nickname": { "type": "string", "example": "키르" }
                                }
                              },
                              "commission": {
                                "type": "object",
                                "properties": {
                                  "id": { "type": "integer", "example": 5 }
                                }
                              }
                            }
                          }
                        },
                        "pagination": {
                          "type": "object",
                          "properties": {
                            "page": { "type": "integer", "example": 1 },
                            "limit": { "type": "integer", "example": 10 },
                            "totalCount": { "type": "integer", "example": 25 },
                            "totalPages": { "type": "integer", "example": 3 }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/requests/{requestId}": {
      "get": {
        "tags": ["Request"],
        "summary": "신청함 상세 조회",
        "description": "로그인 사용자의 특정 커미션 신청 상세 정보를 조회합니다.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          {
            "name": "requestId",
            "in": "path",
            "required": true,
            "schema": { "type": "integer", "format": "int64" },
            "description": "커미션 신청 ID"
          }
        ],
        "responses": {
          "200": {
            "description": "신청함 상세 조회 성공",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resultType": { "type": "string", "example": "SUCCESS" },
                    "error": { "type": "null", "example": null },
                    "success": {
                      "type": "object",
                      "properties": {
                        "request": {
                          "type": "object",
                          "properties": {
                            "id": { "type": "integer", "example": 123 },
                            "status": { 
                              "$ref": "#/components/schemas/RequestStatus",
                              "example": "IN_PROGRESS" 
                            },
                            "totalPrice": { "type": "integer", "example": 55000 },
                            "createdAt": { "type": "string", "format": "date-time", "example": "2025-07-24T10:00:00.000Z" }
                          }
                        },
                        "commission": {
                          "type": "object",
                          "properties": {
                            "id": { "type": "integer", "example": 1 },
                            "title": { "type": "string", "example": "낙서 타입 커미션" },
                            "thumbnailImageUrl": { 
                              "type": "string", 
                              "nullable": true,
                              "example": "https://example.com/image.jpg" 
                            },
                            "artist": {
                              "type": "object",
                              "properties": {
                                "id": { "type": "integer", "example": 2 },
                                "nickname": { "type": "string", "example": "키르" }
                              }
                            }
                          }
                        },
                        "payment": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "minPrice": { "type": "integer", "example": 40000 },
                            "additionalPrice": { "type": "integer", "example": 15000 },
                            "totalPrice": { "type": "integer", "example": 55000 },
                            "paidAt": { 
                              "type": "string", 
                              "format": "date-time", 
                              "nullable": true,
                              "example": "2025-07-24T11:30:00.000Z" 
                            }
                          },
                          "description": "CANCELED/REJECTED 상태인 경우 null"
                        },
                        "timeline": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": { 
                                "type": "string",
                                "enum": ["APPROVED", "PAID", "IN_PROGRESS", "SUBMITTED", "COMPLETED"],
                                "example": "APPROVED"
                              },
                              "timestamp": { 
                                "type": "string", 
                                "format": "date-time", 
                                "example": "2025-07-24T11:00:00.000Z" 
                              }
                            }
                          },
                          "description": "실제 발생한 이벤트만 포함. CANCELED/REJECTED 상태인 경우 빈 배열"
                        },
                        "formData": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": { "type": "string", "example": "1" },
                              "label": { "type": "string", "example": "당일마감 옵션" },
                              "value": { 
                                "oneOf": [
                                  { "type": "string" },
                                  { "type": "array", "items": { "type": "string" } },
                                  { "type": "null" }
                                ],
                                "example": "O"
                              },
                              "type": { 
                                "type": "string", 
                                "enum": ["radio", "textarea", "file"],
                                "example": "radio" 
                              }
                            }
                          },
                          "description": "신청 시 입력한 폼 데이터"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Request를 찾을 수 없음 (존재하지 않거나 권한 없음)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resultType": { "type": "string", "example": "FAIL" },
                    "error": { "type": "string", "example": "Request id를 찾을 수 없습니다." },
                    "success": { "type": "null", "example": null }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/requests/{requestId}/status": {
      "patch": {
        "tags": ["Request"],
        "summary": "커미션 상태 변경",
        "description": "커미션 신청(request)의 상태를 변경합니다. 상태 변경은 신청자 또는 작가만 수행할 수 있으며, 변경 가능한 상태는 조건에 따라 제한됩니다.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          {
            "name": "requestId",
            "in": "path",
            "required": true,
            "schema": { "type": "integer", "format": "int64" },
            "description": "커미션 신청 ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": ["PENDING", "CANCELED", "APPROVED", "REJECTED", "IN_PROGRESS", "SUBMITTED", "COMPLETED"],
                    "description": "변경할 상태"
                  }
                },
                "required": ["status"],
                "example": {
                  "status": "CANCELED"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "상태 변경 성공",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resultType": { "type": "string", "example": "SUCCESS" },
                    "error": { "type": "null", "example": null },
                    "success": {
                      "type": "object",
                      "properties": {
                        "requestId": { "type": "integer", "example": 123 },
                        "newStatus": { "type": "string", "example": "CANCELED" },
                        "message": { "type": "string", "example": "상태가 성공적으로 변경되었습니다." }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "잘못된 요청 (유효하지 않은 상태 변경, 이미 변경된 상태)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resultType": { "type": "string", "example": "FAIL" },
                    "error": { "type": "string", "example": "유효하지 않은 상태 변경입니다." },
                    "success": { "type": "null", "example": null }
                  }
                }
              }
            }
          },
          "403": {
            "description": "권한 없음",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resultType": { "type": "string", "example": "FAIL" },
                    "error": { "type": "string", "example": "권한이 없는 사용자입니다." },
                    "success": { "type": "null", "example": null }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Request를 찾을 수 없음",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resultType": { "type": "string", "example": "FAIL" },
                    "error": { "type": "string", "example": "Request id를 찾을 수 없습니다." },
                    "success": { "type": "null", "example": null }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/requests/{requestId}/forms": {
      "get": {
        "tags": ["Request"],
        "summary": "제출된 신청서 조회",
        "description": "사용자가 제출한 신청서의 상세 정보를 조회합니다. 커미션 정보, 작가 정보, 작성한 폼 내용, 신청 내용을 포함합니다.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "requestId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            },
            "description": "신청서 ID"
          }
        ],
        "responses": {
          "200": {
            "description": "제출된 신청서 조회 성공",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resultType": { "type": "string", "example": "SUCCESS" },
                    "error": { "type": "null", "example": null },
                    "success": {
                      "type": "object",
                      "properties": {
                        "requestId": { "type": "integer", "example": 1 },
                        "status": { 
                          "type": "string", 
                          "enum": ["PENDING", "APPROVED", "REJECTED", "IN_PROGRESS", "SUBMITTED", "COMPLETED", "CANCELED"],
                          "example": "PENDING" 
                        },
                        "displayTime": { 
                          "type": "string", 
                          "format": "date-time", 
                          "description": "CANCELED 상태면 updatedAt, 그 외에는 createdAt",
                          "example": "2025-07-01T10:00:00.000Z" 
                        },
                        "commission": {
                          "type": "object",
                          "properties": {
                            "id": { "type": "integer", "example": 12 },
                            "title": { "type": "string", "example": "커미션 제목" }
                          }
                        },
                        "artist": {
                          "type": "object",
                          "properties": {
                            "id": { "type": "integer", "example": 4 },
                            "nickname": { "type": "string", "example": "위시" },
                            "profileImageUrl": { 
                              "type": "string", 
                              "nullable": true,
                              "example": "https://example.com/profile.jpg" 
                            }
                          }
                        },
                        "formResponses": {
                          "type": "array",
                          "description": "커스텀 필드들의 질문-답변 쌍",
                          "items": {
                            "type": "object",
                            "properties": {
                              "questionId": { "type": "string", "example": "1" },
                              "questionLabel": { "type": "string", "example": "당일마감" },
                              "answer": { "type": "string", "example": "O" }
                            }
                          }
                        },
                        "requestContent": {
                          "type": "object",
                          "properties": {
                            "text": { 
                              "type": "string", 
                              "nullable": true, 
                              "example": "예쁘게 그려주세요 ~" 
                            },
                            "images": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": { "type": "integer", "example": 101 },
                                  "imageUrl": { "type": "string", "example": "https://example.com/request-image1.jpg" },
                                  "orderIndex": { "type": "integer", "example": 0 }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RequestStatus": {
        "type": "string",
        "enum": ["PENDING", "CANCELED", "APPROVED", "REJECTED", "IN_PROGRESS", "SUBMITTED", "COMPLETED"],
        "description": "커미션 신청 상태"
      }
    }
  }
}