{"openapi":"3.1.0","info":{"title":"마키나코어 아카이브, 라운지 API","version":"0.1.0","description":"사람이 읽는 문서: /docs"},"servers":[{"url":"https://test-api.machina-core.com"}],"components":{"securitySchemes":{"member":{"type":"http","scheme":"bearer","description":"샵바이 accessToken. 개발: dev-member-1001"},"admin":{"type":"apiKey","in":"cookie","name":"mc_admin"}}},"paths":{"/api/v1/meta":{"get":{"tags":["공통"],"summary":"코드표 한 번에 받기","description":"기능 스위치(features), 라운지 탭(loungeTabs), IP 탭, 아카이브 카테고리, 크루 말머리, 신고 사유, 닉네임 규칙을 준다. 앱 시작 때 1번 부르고 저장해 두십시오. features.lounge=false 이면 아카이브만 먼저 연 상태이므로 라운지 메뉴를 숨기십시오. 라운지 탭은 loungeTabs 순서대로 그리십시오. 마키나 랩(2027 고도화)과 건의 별도 탭은 운영 설정에 따라 들어오거나 빠집니다.\n\n인증: 인증 없음","security":[],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{"analytics":{"ga4MeasurementId":"G-CNGFY7HTKQ"},"features":{"openScope":"ALL","archive":true,"lounge":true,"lab":false,"suggestionMode":"CATEGORY","bannedWordMode":"HIDE"},"mallBaseUrl":"https://machina-core.com","loungeTabs":[{"value":"ALL","label":"전체"},{"value":"NOTICE","label":"공지"},{"value":"EVENT","label":"이벤트"},{"value":"CREW","label":"마키나 크루"}],"crewFilterCategories":[{"value":"POSING","label":"포징"}],"archiveBlockTypes":[{"value":"TEXT","label":"본문"}],"ips":[{"id":1,"code":"metalcardbot","name":"메탈카드봇","isOwn":true}],"archiveCategories":[{"value":"DESIGN","label":"설계와 구조"}],"boards":[{"value":"NOTICE","label":"공지"}],"crewCategories":[{"value":"POSING","label":"포징"}],"reportReasons":[{"value":"ABUSE","label":"비방, 욕설"}],"nicknameRule":{"min":2,"max":12,"pattern":"^[가-힣A-Za-z0-9]+$","changeIntervalDays":30}}}}}}}}},"/api/v1/me":{"get":{"tags":["회원"],"summary":"내 라운지 프로필","description":"처음 부르면 서버가 랜덤 닉네임으로 프로필을 만든다. 로그인 직후 1번 부르십시오.\n\n요구사항: CM-06, LG-05\n\n인증: 회원 토큰 필수","security":[{"member":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{"memberNo":"1001","nickname":"용감한드라이버1001","crewBadge":null,"canChangeNicknameAt":null,"restricted":false,"restrictedUntil":null,"unreadNotificationCount":2}}}}},"4XX":{"description":"401 UNAUTHORIZED: 토큰이 없거나 만료됨"}}}},"/api/v1/me/nickname":{"patch":{"tags":["회원"],"summary":"닉네임 바꾸기","description":"서버가 비속어, 비방어(관리자 금칙어 목록), IP 이름과 같은 닉네임, 관리자 사칭 단어를 검사합니다. 프론트는 따로 검사하지 않아도 됩니다. 어떤 단어에 걸렸는지는 알려 주지 않습니다(우회 방지).\n\n요구사항: LG-05\n\n인증: 회원 토큰 필수","security":[{"member":[]}],"parameters":[],"requestBody":{"content":{"application/json":{"example":{"nickname":"블레이드팬"}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{"nickname":"블레이드팬"}}}}},"4XX":{"description":"409 NICKNAME_TAKEN\n409 CONFLICT: 변경 간격 미충족\n422 VALIDATION\n422 BANNED_WORD: 비속어, 비방어\n422 NICKNAME_RESERVED: IP, 캐릭터명 단독, 운영진, 멤버십 사칭(NEW)\n409 CONFLICT: 30일, 12개월 3회 제한(details.canChangeAt)"}}},"get":{"tags":["회원"],"summary":"닉네임 미리 검사","description":"available=false 이면 message 를 입력창 아래에 보여 주십시오. code: VALIDATION(글자 수, 글자 종류) / BANNED_WORD(비속어, 비방어) / NICKNAME_RESERVED(IP 이름, 관리자 사칭) / NICKNAME_TAKEN(다른 회원이 씀). 변경 간격(30일)은 검사하지 않습니다.\n\n요구사항: LG-05\n\n인증: 회원 토큰 필수","security":[{"member":[]}],"parameters":[{"name":"nickname","in":"query","required":true,"description":"string - 검사할 닉네임","schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{"available":false,"code":"NICKNAME_RESERVED","message":"IP 이름이나 운영자로 오해할 수 있는 닉네임은 쓸 수 없습니다."}}}}}}}},"/api/v1/me/notifications":{"get":{"tags":["회원"],"summary":"내 알림 목록","description":"link 는 화면 경로 힌트다(/lounge/posts/{id}, /me/points, /archive/{id}). 프론트 라우트에 맞게 바꾸십시오.\n\n요구사항: LB-02\n\n인증: 회원 토큰 필수","security":[{"member":[]}],"parameters":[{"name":"unreadOnly","in":"query","required":false,"description":"boolean - true 이면 안 읽은 알림만","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"number - 페이지 번호(1부터). 기본 1","schema":{"type":"string"}},{"name":"size","in":"query","required":false,"description":"number - 페이지 크기. 기본 20, 최대 100","schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":[{"id":5,"type":"QNA_ANSWERED","typeLabel":"질문 답변","title":"마키나 랩에 내 질문의 답변이 올라왔습니다: ...","link":"/lounge/posts/11","read":false,"createdAt":"2026-10-15T08:27:33.850Z"}]}}}}}}},"/api/v1/me/notifications/read":{"post":{"tags":["회원"],"summary":"알림 읽음 처리","description":"인증: 회원 토큰 필수","security":[{"member":[]}],"parameters":[],"requestBody":{"content":{"application/json":{"example":{"ids":[5]}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{"updated":1}}}}}}}},"/api/v1/me/points":{"get":{"tags":["회원"],"summary":"내 적립 내역(라운지 보상분)","description":"이 서버가 지급, 회수한 성공 건만 준다. 적립금 잔액은 샵바이 마이페이지 API 를 쓰십시오. meta.totalAmount 는 이 서버 지급 합계다.\n\n요구사항: PT-03\n\n인증: 회원 토큰 필수","security":[{"member":[]}],"parameters":[{"name":"page","in":"query","required":false,"description":"number - 페이지 번호(1부터). 기본 1","schema":{"type":"string"}},{"name":"size","in":"query","required":false,"description":"number - 페이지 크기. 기본 20, 최대 100","schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":[{"id":5,"date":"2026-10-15T08:27:30.847Z","amount":500,"reason":"기믹 선호도 투표 참여"}]}}}}}}},"/api/v1/me/questions":{"get":{"tags":["회원"],"summary":"내 랩 질문과 처리 상태","description":"요구사항: LB-02\n\n인증: 회원 토큰 필수","security":[{"member":[]}],"parameters":[{"name":"page","in":"query","required":false,"description":"number - 페이지 번호(1부터). 기본 1","schema":{"type":"string"}},{"name":"size","in":"query","required":false,"description":"number - 페이지 크기. 기본 20, 최대 100","schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":[{"id":7,"title":"카드 인식 원리","body":"...","productName":"메탈카드봇 블레이드","status":"ANSWERED","statusLabel":"답변 발행","qnaPostId":11,"createdAt":"...","answeredAt":"..."}]}}}}}}},"/api/v1/me/posts":{"get":{"tags":["회원"],"summary":"내가 쓴 크루 게시글","description":"숨김 처리된 글도 status, hiddenReason 과 함께 준다.\n\n인증: 회원 토큰 필수","security":[{"member":[]}],"parameters":[{"name":"page","in":"query","required":false,"description":"number - 페이지 번호(1부터). 기본 1","schema":{"type":"string"}},{"name":"size","in":"query","required":false,"description":"number - 페이지 크기. 기본 20, 최대 100","schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/v1/archives":{"get":{"tags":["아카이브"],"summary":"아카이브 목록","description":"요구사항: AR-01\n\n인증: 인증 없음","security":[],"parameters":[{"name":"ipId","in":"query","required":false,"description":"number - IP 탭(meta.ips[].id)","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"string - 카테고리 코드(meta.archiveCategories[].value). 대표, 추가 카테고리 모두 찾음. 운영자가 추가, 삭제하므로 값을 하드코딩하지 마십시오","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"latest|recommended|popular - 최신순(기본) / 추천순(운영자가 정한 노출 순서, 같으면 최신순) / 인기순(조회 수 많은 순, 같으면 최신순). 기획 결정 2026-10-29","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"string - 제목, 요약 검색. 50자 이하","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"number - 페이지 번호(1부터). 기본 1","schema":{"type":"string"}},{"name":"size","in":"query","required":false,"description":"number - 페이지 크기. 기본 20, 최대 100","schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":[{"id":1,"title":"메탈카드봇 S3 블레이드, 첫 스케치부터 양산까지","summary":"...","category":"BEHIND","categoryLabel":"제작 비하인드","ip":{"id":1,"code":"metalcardbot","name":"메탈카드봇","isOwn":true},"thumbnailUrl":"http://192.168.17.87:4000/uploads/seed/archive-0-thumb.webp","pinned":true,"publishedAt":"...","viewCount":420,"commentCount":1}]}}}}}}},"/api/v1/archives/pinned":{"get":{"tags":["아카이브"],"summary":"아카이브 상단 고정글","description":"목록(GET /api/v1/archives) 위에 그리십시오. 목록에는 고정글이 들어가지 않습니다. 최대 20개, 노출 순서(sortOrder) 큰 값이 먼저.\n\n요구사항: AR-01\n\n인증: 인증 없음","security":[],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":[{"id":1,"title":"렉스카이저 블랙에디션이 만들어지기까지","pinned":true,"categories":[{"value":"BEHIND","label":"제작 비하인드"}]}]}}}}}}},"/api/v1/archives/{id}":{"get":{"tags":["아카이브"],"summary":"아카이브 상세(위지윅 본문 html, 비회원은 잠금, 상품 카드, 공유)","description":"html 은 백오피스 위지윅 편집기(Quill)로 쓴 본문입니다. 서버가 허용한 태그(p, h2, h3, strong, em, u, s, a, blockquote, ul, ol, li, img, iframe, hr)만 남긴 안전한 값입니다. 그대로 innerHTML 로 넣고, 태그별 글꼴과 간격은 스킨 CSS 로 정하십시오. 이미지 주소는 절대 URL 입니다. 유튜브 영상은 iframe(youtube-nocookie) 입니다. 비회원이면 회원 전용 구분선 위까지만 오고, 그 안의 영상은 <div class=\"mc-video-locked\">회원만 재생합니다</div> 로 바뀝니다. lock.locked=true 이면 본문 아래에 잠금 안내와 [로그인] [회원가입] 버튼을 그리고, 버튼은 lock.loginUrl, lock.signupUrl(돌아올 주소 포함)로 보내십시오. relatedProducts 는 샵바이 상품 카드 값입니다(샵바이 호출이 실패하면 name 등이 null). share 는 공유 버튼 값입니다. 조회 수는 같은 회원(또는 같은 X-Anon-Id)이면 하루에 1번만 오릅니다.\n\n요구사항: AR-02, AR-04\n\n인증: 선택(회원이면 토큰)","security":[],"parameters":[{"name":"id","in":"path","required":true,"description":"콘텐츠 id","schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{"id":1,"title":"...","isMember":false,"commentEnabled":true,"toc":[{"id":"toc-1","text":"변신의 시작은 카드를 꽂는 손끝에서","level":2,"locked":false},{"id":"toc-2","text":"세 가지 슬롯 방식, 그리고 선택","level":2,"locked":true}],"categories":[{"value":"BEHIND","label":"제작 비하인드"},{"value":"COLLAB","label":"한정판·컬래버레이션 제작기"}],"navigation":{"prev":{"id":2,"title":"합체 후에도 흔들리지 않는 결합부 설계 노트"},"next":null},"moreFromIp":{"ip":{"id":1,"code":"metalcardbot","name":"메탈카드봇","isOwn":true,"iconUrl":"http://192.168.17.87:4000/uploads/ip/ip-metalcardbot.webp"},"items":[{"id":4,"title":"...","categories":[{"value":"SETTING","label":"미공개 설정"}]}]},"html":"<h2 id=\"toc-1\">대표 이미지와 도입부</h2><p><img src=\"http://192.168.17.87:4000/uploads/real/p136690811-1.webp\" alt=\"\"></p><p>이 콘텐츠는 <strong>IP 홀더만</strong> 공개하는 자료입니다.</p>","lock":{"locked":true,"message":"이어지는 내용은 회원만 볼 수 있습니다. 로그인하거나 회원가입하십시오.","teaser":"초기 스케치, 설계도, 목업 비교","loginUrl":"https://machina-core.com/member/login?returnUrl=https%3A%2F%2Fmachina-core.com%2Farchive%2F1","signupUrl":"https://machina-core.com/member/register-term?returnUrl=https%3A%2F%2Fmachina-core.com%2Farchive%2F1&source=archive&contentId=1"},"relatedProductNos":["136690811"],"relatedProducts":[{"productNo":"136690811","name":"메탈카드봇W 고스트레인","imageUrl":"https://shopby-images.cdn-nhncommerce.com/...jpg","salePrice":120000,"discountedPrice":95900,"soldOut":false,"brandName":"메탈카드봇","discountRate":20,"url":"https://machina-core.com/product/136690811"}],"share":{"url":"http://192.168.17.87:4000/s/a/1","title":"...","description":"...","imageUrl":"http://192.168.17.87:4000/uploads/seed/archive-0-thumb.webp"}}}}}},"4XX":{"description":"404 NOT_FOUND: 없거나 발행 전"}}}},"/api/v1/archives/{id}/events":{"post":{"tags":["아카이브"],"summary":"전환 측정 이벤트 보내기","description":"요구사항: AR-05, AR-08\n\n인증: 선택(회원이면 토큰)","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"type":"LOCK_IMPRESSION","anonId":"anon-x1y2"}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{"recorded":true}}}}}}}},"/api/v1/archives/{id}/comments":{"get":{"tags":["아카이브"],"summary":"아카이브 댓글 목록","description":"구조는 게시글 댓글과 같다(replies 포함).\n\n요구사항: AR-10\n\n인증: 선택(회원이면 토큰)","security":[],"parameters":[{"name":"page","in":"query","required":false,"description":"number - 페이지 번호(1부터). 기본 1","schema":{"type":"string"}},{"name":"size","in":"query","required":false,"description":"number - 페이지 크기. 기본 20, 최대 100","schema":{"type":"string"}},{"name":"flat","in":"query","required":false,"description":"true|false - true 이면 대댓글 포함 한 줄씩 페이지를 나눔(depth 0/1)","schema":{"type":"string"}},{"name":"mine","in":"query","required":false,"description":"true|false - true 이면 내 댓글만: 내가 쓴 댓글, 내가 대댓글을 단 댓글 묶음. 로그인 필요(없으면 401)","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}},"post":{"tags":["아카이브"],"summary":"아카이브 댓글 쓰기","description":"요구사항: AR-10\n\n인증: 회원 토큰 필수","security":[{"member":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"body":"초기 스케치가 멋집니다.","parentId":null}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/v1/lounge/pinned":{"get":{"tags":["라운지"],"summary":"라운지 위쪽 고정 게시글","description":"공지, 이벤트 고정 글과 우수 크루 글(featured=true). 공지, 이벤트, 우수 크루 순서. 최대 10개.\n\n요구사항: LG-01\n\n인증: 선택(회원이면 토큰)","security":[],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/v1/posts":{"get":{"tags":["라운지"],"summary":"게시글 목록(최신순)","description":"thumbnailUrl 이 null 이면 기본 썸네일을 그리십시오(LG-02). author.type=ADMIN 이면 author.profile(답변 프로필)을 그리십시오.\n\n요구사항: LG-01, LG-02\n\n인증: 선택(회원이면 토큰)","security":[],"parameters":[{"name":"tab","in":"query","required":false,"description":"ALL|NOTICE|EVENT|CREW|SUGGESTION|LAB - 탭. 기본 ALL. meta.loungeTabs 의 value 를 그대로 보내십시오. 마키나 랩이 꺼져 있으면 LAB 은 404 FEATURE_OFF","schema":{"type":"string"}},{"name":"board","in":"query","required":false,"description":"ALL|NOTICE|EVENT|LAB|CREW - (이전 값) tab 이 없을 때만 읽는다","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"POSING|REVIEW|FANART|CUSTOM|SUGGESTION - 크루 말머리","schema":{"type":"string"}},{"name":"ipId","in":"query","required":false,"description":"number - IP","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"string - 제목 검색","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"number - 페이지 번호(1부터). 기본 1","schema":{"type":"string"}},{"name":"size","in":"query","required":false,"description":"number - 페이지 크기. 기본 20, 최대 100","schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":[{"id":6,"board":"CREW","boardLabel":"마키나 크루","category":"POSING","categoryLabel":"포징","title":"블레이드 전투 포즈 3종","thumbnailUrl":"...","ip":null,"author":{"type":"MEMBER","nickname":"강철커맨더","crewBadge":"CREW","isMe":false},"pinned":false,"featured":false,"hasPoll":false,"suggestionStatus":null,"likeCount":3,"commentCount":3,"viewCount":45,"createdAt":"..."}]}}}}}},"post":{"tags":["라운지"],"summary":"크루 게시글 쓰기","description":"금칙어 처리 방식(meta.features.bannedWordMode)이 HIDE 이면 금칙어가 있어도 201 로 저장하고 숨긴다. 이때 응답은 { id, status: HIDDEN, moderation: { hidden: true, message } } 이다. message 를 회원에게 보여 주고 내 글 목록으로 보내십시오. BLOCK 이면 422 BANNED_WORD 다.\n\n요구사항: CR-01\n\n인증: 회원 토큰 필수","security":[{"member":[]}],"parameters":[],"requestBody":{"content":{"application/json":{"example":{"category":"POSING","title":"블레이드 전투 포즈","body":"관절 각도를 바꿔 찍었습니다.","ipId":1,"imageUrls":["http://192.168.17.87:4000/uploads/post/202610/abc.webp"]}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{"id":11,"status":"HIDDEN","moderation":{"hidden":true,"message":"운영 정책에 맞지 않는 단어가 있어 글을 숨겼습니다. 운영자가 확인한 뒤 다시 공개합니다."}}}}}},"4XX":{"description":"403 MEMBER_RESTRICTED\n422 BANNED_WORD(BLOCK 모드)"}}}},"/api/v1/posts/{id}":{"get":{"tags":["라운지"],"summary":"게시글 상세(투표, Q&A, 보상 포함)","description":"본문은 bodyHtml 을 그리십시오. 공지, 이벤트는 운영자가 위지윅 편집기로 쓴 HTML, 회원 글은 평문을 바꾼 HTML 입니다(bodyFormat=HTML|TEXT). share 는 공유 버튼 값이다(share.url = /s/p/{id} 미리보기 링크). 마키나 랩이 꺼져 있으면 LAB 게시글은 404 다. polls[]: 게시글 안의 투표 문항(2개 이상이면 설문). phase=OPEN 일 때만 참여 버튼을 켜십시오. myVote 가 있으면 참여 완료로 그리십시오. voteCount, ratio, totalVotes 는 결과 공개 시점에만 들어온다. qna 가 있으면 마키나 랩 공식 Q&A 레이아웃(질문 요약 → 답변 프로필 → 답변)으로 그리십시오.\n\n인증: 선택(회원이면 토큰)","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{"id":2,"board":"EVENT","title":"[투표] 이번 주 기믹 선호도 투표","body":"...","images":[],"author":{"type":"ADMIN","profile":{"displayName":"조립 연구원","title":"조립 전문가","avatarUrl":"http://192.168.17.87:4000/uploads/seed/avatar-assembly.webp","badge":"LAB"}},"likedByMe":false,"canEdit":false,"polls":[{"id":1,"question":"가장 보고 싶은 기믹을 고르십시오.","type":"SINGLE","maxChoices":null,"phase":"OPEN","resultVisibility":"AFTER_CLOSE","startsAt":"...","endsAt":"...","options":[{"id":1,"label":"카드 슬롯 발광","imageUrl":null}],"totalVotes":null,"myVote":null}],"reward":{"amount":500,"rule":"PARTICIPATION","ruleLabel":"참여","mode":"INSTANT","modeLabel":"즉시 지급","reason":"기믹 선호도 투표 참여"},"qna":null,"share":{"url":"http://192.168.17.87:4000/s/p/2","title":"[투표] 이번 주 기믹 선호도 투표","description":"...","imageUrl":null}}}}}}}},"patch":{"tags":["라운지"],"summary":"내 게시글 수정","description":"보낸 필드만 바뀐다. imageUrls 를 보내면 이미지 목록을 통째로 바꾼다.\n\n요구사항: LG-03\n\n인증: 회원 토큰 필수","security":[{"member":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"title":"수정한 제목"}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}},"delete":{"tags":["라운지"],"summary":"내 게시글 삭제","description":"요구사항: LG-03\n\n인증: 회원 토큰 필수","security":[{"member":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/v1/posts/{id}/like":{"post":{"tags":["라운지"],"summary":"좋아요","description":"취소는 같은 경로에 DELETE.\n\n요구사항: LG-04\n\n인증: 회원 토큰 필수","security":[{"member":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{"liked":true,"likeCount":4}}}}}}},"delete":{"tags":["라운지"],"summary":"좋아요 취소","description":"요구사항: LG-04\n\n인증: 회원 토큰 필수","security":[{"member":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{"liked":false,"likeCount":3}}}}}}}},"/api/v1/posts/{id}/comments":{"get":{"tags":["라운지"],"summary":"댓글 목록(대댓글 포함)","description":"최상위 댓글 기준으로 페이지를 나눈다. 각 댓글의 replies 에 대댓글이 모두 들어 있다. 대댓글은 1단계만 있다. 삭제, 숨김 댓글은 author=null, status 와 안내 문구로 온다.\n\n요구사항: LG-04\n\n인증: 선택(회원이면 토큰)","security":[],"parameters":[{"name":"page","in":"query","required":false,"description":"number - 페이지 번호(1부터). 기본 1","schema":{"type":"string"}},{"name":"size","in":"query","required":false,"description":"number - 페이지 크기. 기본 20, 최대 100","schema":{"type":"string"}},{"name":"flat","in":"query","required":false,"description":"true|false - true 이면 대댓글 포함 한 줄씩","schema":{"type":"string"}},{"name":"mine","in":"query","required":false,"description":"true|false - true 이면 내 댓글만(로그인 필요)","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":[{"id":1,"parentId":null,"author":{"type":"MEMBER","nickname":"용감한드라이버1001","crewBadge":null,"isMe":false},"body":"두 번째 포즈가 제일 멋집니다.","status":"PUBLISHED","createdAt":"...","updatedAt":"...","replies":[{"id":2,"parentId":1,"author":{"type":"MEMBER","nickname":"강철커맨더","crewBadge":"CREW","isMe":false},"body":"감사합니다.","status":"PUBLISHED"},{"id":3,"parentId":1,"author":{"type":"ADMIN","profile":{"displayName":"조립 연구원","title":"조립 전문가","avatarUrl":"http://192.168.17.87:4000/uploads/seed/avatar-assembly.webp","badge":"LAB"}},"body":"우수 게시글 후보로 올렸습니다.","status":"PUBLISHED"}]}]}}}}}},"post":{"tags":["라운지"],"summary":"댓글, 대댓글 쓰기","description":"응답에 moderation 이 붙는다. 금칙어로 숨겼으면 moderation.hidden=true 와 안내 문구가 온다(HIDE 모드).\n\n요구사항: LG-04\n\n인증: 회원 토큰 필수","security":[{"member":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"body":"동의합니다.","parentId":1}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}},"4XX":{"description":"403 MEMBER_RESTRICTED\n422 BANNED_WORD(BLOCK 모드)"}}}},"/api/v1/comments/{id}":{"patch":{"tags":["아카이브"],"summary":"내 댓글 수정(아카이브, 라운지 공통)","description":"id 는 댓글 목록의 id 입니다. 내 댓글(author.isMe=true)만 고칩니다. 응답은 고친 댓글 1건입니다.\n\n요구사항: AR-10, LG-04\n\n인증: 회원 토큰 필수","security":[{"member":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"body":"고친 내용"}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}},"4XX":{"description":"401 UNAUTHORIZED\n403 FORBIDDEN: 남의 댓글, 숨김된 댓글\n403 MEMBER_RESTRICTED\n404 NOT_FOUND: 없거나 삭제된 댓글\n422 VALIDATION: 500자 초과\n422 BANNED_WORD(BLOCK 모드)"}}},"delete":{"tags":["아카이브"],"summary":"내 댓글 삭제(아카이브, 라운지 공통)","description":"내 댓글만 지웁니다. 목록에서 '삭제된 댓글입니다.'(status=DELETED, author=null)로 바뀝니다. 대댓글은 남습니다. 대댓글이 없는 삭제 댓글은 목록에서 빠집니다.\n\n요구사항: AR-10, LG-04\n\n인증: 회원 토큰 필수","security":[{"member":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}},"4XX":{"description":"401 UNAUTHORIZED\n403 FORBIDDEN: 남의 댓글\n403 MEMBER_RESTRICTED\n404 NOT_FOUND: 없거나 이미 삭제된 댓글"}}}},"/api/v1/reports":{"post":{"tags":["라운지"],"summary":"게시글, 댓글 신고","description":"같은 대상은 1번만 신고한다. 신고가 기준(기본 3건) 이상이면 서버가 대상을 임시 숨김한다.\n\n요구사항: LG-06\n\n인증: 회원 토큰 필수","security":[{"member":[]}],"parameters":[],"requestBody":{"content":{"application/json":{"example":{"targetType":"POST","targetId":10,"reason":"SALES","detail":"판매 글입니다."}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}},"4XX":{"description":"409 CONFLICT: 이미 신고\n400 BAD_REQUEST: 본인 글"}}}},"/api/v1/polls/{id}/votes":{"post":{"tags":["라운지"],"summary":"투표, 설문 문항 답하기","description":"문항마다 1번만 답한다. 설문은 문항마다 이 API 를 부른다. 즉시 지급 보상이면 모든 문항을 답한 순간 reward 에 지급 결과가 온다.\n\n요구사항: VT-02, PT-01\n\n인증: 회원 토큰 필수","security":[{"member":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"optionIds":[3]}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{"pollId":1,"optionIds":[3],"textAnswer":null,"reward":{"status":"SUCCESS","txnId":5}}}}}},"4XX":{"description":"409 ALREADY_VOTED\n409 POLL_CLOSED\n422 VALIDATION"}}}},"/api/v1/lab/questions":{"post":{"tags":["마키나 랩"],"summary":"비공개 질문 제출(2027 고도화, 설정으로 켬)","description":"마키나 랩이 꺼져 있으면(meta.features.lab=false) 404 FEATURE_OFF 다.\n\n요구사항: LB-01\n\n인증: 회원 토큰 필수","security":[{"member":[]}],"parameters":[],"requestBody":{"content":{"application/json":{"example":{"title":"카드 인식 원리","body":"카드를 꽂으면 어떻게 인식하나요?","productName":"메탈카드봇 블레이드","productNo":"1001"}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{"id":7,"status":"RECEIVED","message":"질문이 접수되었습니다. 답변이 발행되면 알림으로 알려 드립니다."}}}}}}}},"/api/v1/uploads":{"post":{"tags":["공통"],"summary":"이미지 올리기(크루 게시글 첨부)","description":"multipart/form-data 의 file 필드에 이미지 1장. png, jpg, webp, gif / 10MB 이하. 서버가 webp 로 바꾼다.\n\n인증: 회원 토큰 필수","security":[{"member":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{"url":"http://192.168.17.87:4000/uploads/post/202610/uuid.webp","bytes":51234,"width":1080,"height":1080,"originalName":"pose.jpg"}}}}}}}},"/api/v1/track":{"post":{"tags":["공통"],"summary":"가입 완료와 유입 경로 기록","description":"샵바이 회원가입 완료 화면에서 1번 부르십시오. 가입 화면 주소에 source, place 가 있으면 보관했다가 그대로 보내십시오.\n\n요구사항: ST-03, EX-01\n\n인증: 선택(회원이면 토큰)","security":[],"parameters":[],"requestBody":{"content":{"application/json":{"example":{"type":"SIGNUP_COMPLETE","source":"popup","place":"seongsu"}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/s/a/{id}":{"get":{"tags":["공유"],"summary":"아카이브 공유 미리보기 페이지(HTML)","description":"API 가 아니라 공유 링크다. og:title, og:image 를 서버에서 그린 HTML 을 주고, 사람은 쇼핑몰 아카이브 상세(설정 archivePath)로 바로 이동한다. 카카오톡, 페이스북 수집기가 이 주소를 열 수 있어야 하므로 운영에서는 공개 도메인(PUBLIC_BASE_URL)에 둡니다.\n\n요구사항: AR-10\n\n인증: 인증 없음","security":[],"parameters":[{"name":"id","in":"path","required":true,"description":"콘텐츠 id","schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/s/p/{id}":{"get":{"tags":["공유"],"summary":"라운지 게시글 공유 미리보기 페이지(HTML)","description":"아카이브 공유 링크와 같다. 쇼핑몰 라운지 상세(설정 loungePath)로 이동한다.\n\n요구사항: LG-10\n\n인증: 인증 없음","security":[],"parameters":[{"name":"id","in":"path","required":true,"description":"게시글 id","schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/q/{place}":{"get":{"tags":["공유"],"summary":"팝업 QR 주소(장소별 집계 후 가입 화면으로 이동)","description":"QR 스캔(QR_SCAN)을 장소별로 기록하고 쇼핑몰 회원가입 화면(설정 signupPath)으로 302 이동한다. 이동 주소 뒤에 ?source=popup&place=seongsu 를 붙인다.\n\n요구사항: EX-01\n\n인증: 인증 없음","security":[],"parameters":[{"name":"place","in":"path","required":true,"description":"장소 값. 영문, 숫자, -, _ 로 40자 이하. 예: seongsu","schema":{"type":"string"}},{"name":"s","in":"query","required":false,"description":"popup|qr - 유입 경로. 기본 popup","schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/v1/dev/members":{"get":{"tags":["개발용"],"summary":"시험용 회원 토큰 목록(DEV_AUTH=true 일 때만)","description":"Authorization: Bearer dev-member-1001 처럼 쓰십시오. 목록에 없는 번호도 처음 호출할 때 회원이 생긴다. 운영 서버에서는 404.\n\n인증: 인증 없음","security":[],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":[{"memberNo":"1001","nickname":"용감한드라이버1001","status":"ACTIVE","crewBadge":null,"token":"dev-member-1001"}]}}}}}}},"/api/admin/me":{"get":{"tags":["백오피스"],"summary":"로그인한 관리자와 연동 상태","description":"인증: 백오피스 로그인","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/dashboard":{"get":{"tags":["백오피스"],"summary":"처리 대기 건, 오늘, 7일 지표","description":"features.openScope=ARCHIVE_ONLY 이면 화면이 archiveToday(아카이브 오늘 지표)를 먼저 보인다.\n\n요구사항: ST-01\n\n인증: 백오피스 로그인","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/archives":{"get":{"tags":["백오피스"],"summary":"아카이브 목록(상태, 카테고리, IP, 검색)","description":"요구사항: AR-09\n\n인증: 백오피스 로그인","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}},"post":{"tags":["백오피스"],"summary":"아카이브 게시글 등록(임시저장으로 만듦)","description":"아카이브 게시글은 운영자가 백오피스 [아카이브] > [새 콘텐츠] 화면(/admin/archives/new)에서 등록합니다. 이 화면이 부르는 API 가 이것입니다. 사용자 화면(쇼핑몰)에서는 부르지 않습니다. 순서: 1) POST /api/admin/uploads 로 이미지를 올린다. 2) 이 API 로 만든다(상태 DRAFT). 3) POST /api/admin/archives/{id}/status {\"action\":\"publish\"} 로 발행한다. 발행해야 GET /api/v1/archives 목록에 보입니다. 백오피스 로그인 쿠키(mc_admin)가 필요합니다. 개발 서버는 /admin/login 의 [개발용 로그인]으로 쿠키를 받습니다.\n\n요구사항: AR-03\n\n인증: 백오피스 운영 관리자 이상","security":[{"admin":[]}],"parameters":[],"requestBody":{"content":{"application/json":{"example":{"title":"메탈카드봇 S3 블레이드, 첫 스케치부터 양산까지","summary":"제작진이 직접 공개하는 개발 과정","category":"BEHIND","ipId":1,"thumbnailUrl":"http://192.168.17.87:4000/uploads/archive/202610/cover.webp","pinned":false,"sortOrder":0,"commentEnabled":true,"bodyHtml":"<p><img src=\"http://192.168.17.87:4000/uploads/archive/202610/cover.webp\"></p><p>이 콘텐츠는 <strong>IP 홀더만</strong> 공개하는 자료입니다.</p><hr class=\"mc-lock\"><h2>초기 디자인과 설계</h2><iframe src=\"https://www.youtube-nocookie.com/embed/aqz-KE-bpKQ\"></iframe>","productNos":["136690811"]}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{"id":5,"title":"...","status":"DRAFT","statusLabel":"임시저장","live":false,"bodyHtml":"<p>...</p>","productNos":["136690811"]}}}}},"4XX":{"description":"401 UNAUTHORIZED: 백오피스 로그인 필요\n403 FORBIDDEN: 열람자 권한\n422 VALIDATION: 입력 값 오류(details 확인)"}}}},"/api/admin/uploads":{"post":{"tags":["백오피스"],"summary":"백오피스 이미지 올리기(대표 이미지, 본문 이미지)","description":"multipart/form-data 로 보내십시오. file = 이미지 1장(png, jpg, webp, gif, 10MB 이하), folder = archive. 서버가 webp 로 바꿉니다. 응답의 url 을 thumbnailUrl 이나 본문 HTML 의 img src 에 넣으십시오. 백오피스 편집기는 이미지 단추로 이 API 를 부릅니다.\n\n인증: 백오피스 운영 관리자 이상","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{"url":"http://192.168.17.87:4000/uploads/archive/202610/uuid.webp","bytes":81234,"width":1440,"height":810,"originalName":"cover.jpg"}}}}}}}},"/api/admin/archives/{id}":{"get":{"tags":["백오피스"],"summary":"아카이브 1건(편집용, 발행 전 포함)","description":"인증: 백오피스 로그인","security":[{"admin":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}},"put":{"tags":["백오피스"],"summary":"아카이브 저장(위지윅 본문 통째로)","description":"회원 전용 구분선은 1개까지 둡니다. 발행하려면 구분선 위에 글이나 이미지가 있어야 합니다.\n\n요구사항: AR-03\n\n인증: 백오피스 운영 관리자 이상","security":[{"admin":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"title":"...","category":"BEHIND","ipId":1,"thumbnailUrl":"...","bodyHtml":"<p>공개 부분</p><hr class=\"mc-lock\"><p>회원 전용 부분</p>","productNos":["136690811"]}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/archives/{id}/status":{"post":{"tags":["백오피스"],"summary":"발행, 예약 발행, 숨김, 임시저장","description":"발행, 예약하려면 목록 대표 이미지가 있고, 회원 전용 구분선 위에 글이나 이미지가 있어야 합니다.\n\n요구사항: AR-09\n\n인증: 백오피스 운영 관리자 이상","security":[{"admin":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"action":"publish"}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/archives/bulk":{"post":{"tags":["백오피스"],"summary":"일괄 숨김, 고정, 삭제","description":"요구사항: CM-09\n\n인증: 백오피스 운영 관리자 이상","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/posts":{"get":{"tags":["백오피스"],"summary":"라운지 게시글 목록(숨김 포함)","description":"인증: 백오피스 로그인","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}},"post":{"tags":["백오피스"],"summary":"공지, 이벤트, 연구노트 쓰기(투표, 보상 포함)","description":"공지, 이벤트의 body 는 위지윅 HTML 입니다(bodyFormat=HTML 로 저장). 마키나 랩 글은 평문입니다. 적립금 메뉴를 끈 동안에는 reward 를 넣으면 404 FEATURE_OFF 입니다.\n\n요구사항: LG-07, VT-01\n\n인증: 백오피스 운영 관리자 이상","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/posts/{id}/action":{"post":{"tags":["백오피스"],"summary":"숨김, 고정, 삭제, 건의 상태","description":"요구사항: LG-06\n\n인증: 백오피스 운영 관리자 이상","security":[{"admin":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/posts/{id}/reward":{"post":{"tags":["백오피스"],"summary":"마감 후 보상 일괄 지급","description":"요구사항: PT-02\n\n인증: 백오피스 운영 관리자 이상","security":[{"admin":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/comments":{"get":{"tags":["백오피스"],"summary":"댓글 목록","description":"인증: 백오피스 로그인","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}},"post":{"tags":["백오피스"],"summary":"관리자 댓글(답변 프로필)","description":"인증: 백오피스 운영 관리자 이상","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/lab/questions":{"get":{"tags":["백오피스"],"summary":"질문 접수함","description":"요구사항: LB-03\n\n인증: 백오피스 로그인","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/lab/qna":{"post":{"tags":["백오피스"],"summary":"질문 묶어 공식 Q&A 발행","description":"요구사항: LB-04, LB-06\n\n인증: 백오피스 운영 관리자 이상","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/profiles":{"get":{"tags":["백오피스"],"summary":"답변 프로필 목록","description":"요구사항: LB-05\n\n인증: 백오피스 로그인","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/polls":{"get":{"tags":["백오피스"],"summary":"투표, 설문 현황","description":"요구사항: VT-04\n\n인증: 백오피스 로그인","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/polls/{postId}/export":{"get":{"tags":["백오피스"],"summary":"참여자 명단 엑셀(.xlsx). ?format=csv 이면 CSV. 회원번호 가림","description":"요구사항: VT-04\n\n인증: 백오피스 운영 관리자 이상","security":[{"admin":[]}],"parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/archive-categories":{"get":{"tags":["백오피스"],"summary":"아카이브 카테고리 목록(쓰는 글 수 포함). POST 추가, PATCH /{code} 이름, 순서, DELETE /{code} 삭제(글에서 함께 뺌)","description":"인증: 백오피스 로그인","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/banned-words":{"get":{"tags":["백오피스"],"summary":"금칙어 목록(q 검색, scope ALL|NICKNAME|RESERVED, 페이지). POST 추가(scope, exact), PATCH /{id}, DELETE /{id}, POST /check 닉네임 검사해 보기","description":"요구사항: LG-06\n\n인증: 백오피스 로그인","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/crew-activity":{"get":{"tags":["백오피스"],"summary":"크루 월별 활동 현황(?month=YYYY-MM): 전반, 후반 유효 활동 수, 시스템 판정, 검토 대기, 박탈 이력. POST /judge { month } 판정 만들기(검토 대기, 매월 1일 자동). PATCH /decision { month, memberNo, decision, note } 최종 결정 바꾸기. POST /apply { month } 반영. POST /remove { memberNos, reason } 특이 사례 즉시 박탈","description":"인증: 백오피스 로그인","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/reports":{"get":{"tags":["백오피스"],"summary":"신고 목록(대상별 묶음)","description":"요구사항: LG-06\n\n인증: 백오피스 로그인","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/members":{"get":{"tags":["백오피스"],"summary":"회원 목록과 활동 수","description":"인증: 백오피스 로그인","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/points":{"get":{"tags":["백오피스"],"summary":"적립금 원장","description":"요구사항: PT-04\n\n인증: 백오피스 로그인","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}},"post":{"tags":["백오피스"],"summary":"관리자 지급, 회수","description":"요구사항: PT-03\n\n인증: 백오피스 운영 관리자 이상","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/stats":{"get":{"tags":["백오피스"],"summary":"기간 통계","description":"요구사항: ST-02 ~ ST-05\n\n인증: 백오피스 로그인","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/settings":{"get":{"tags":["백오피스"],"summary":"운영 설정(오픈 범위, 마키나 랩, 건의 운영 방식, 금칙어 처리, 신고 기준, 쇼핑몰 주소)","description":"인증: 백오피스 로그인","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}},"put":{"tags":["백오피스"],"summary":"운영 설정 바꾸기","description":"인증: 백오피스 슈퍼 관리자","security":[{"admin":[]}],"parameters":[],"requestBody":{"content":{"application/json":{"example":{"key":"openScope","value":"ARCHIVE_ONLY"}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/menus":{"get":{"tags":["백오피스"],"summary":"메뉴 관리: 메뉴마다 사용 여부와 들어올 수 있는 역할","description":"요구사항: CM-03\n\n인증: 백오피스 슈퍼 관리자","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}},"put":{"tags":["백오피스"],"summary":"메뉴 1개 켜고 끄기, 역할 바꾸기","description":"끈 메뉴는 화면과 그 메뉴의 API 를 모두 막습니다(404 FEATURE_OFF). 역할이 없으면 403 FORBIDDEN 입니다. 슈퍼 관리자는 켠 메뉴에 항상 들어옵니다. 적립금(points) 메뉴를 끄면 투표 보상 지급과 재처리도 멈춥니다.\n\n요구사항: CM-03\n\n인증: 백오피스 슈퍼 관리자","security":[{"admin":[]}],"parameters":[],"requestBody":{"content":{"application/json":{"example":{"key":"points","enabled":false,"roles":["SUPER","OPERATOR"]}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}},"/api/admin/stats/ga":{"get":{"tags":["백오피스"],"summary":"GA4 사이트 행동(페이지뷰, 사용자, 참여 시간, 이벤트)","description":"서버가 GA4 Data API(runReport)를 불러 10분 동안 기억합니다. 아카이브, 라운지 상세 주소(운영 설정의 경로)에서 콘텐츠 id 를 꺼내 제목과 맞춥니다. GA 를 연결하지 않았으면 configured=false, 호출이 실패하면 error 에 이유가 옵니다.\n\n요구사항: AR-11, ST-02\n\n인증: 백오피스 로그인","security":[{"admin":[]}],"parameters":[{"name":"from","in":"query","required":false,"description":"YYYY-MM-DD - 시작일(기본 30일 전)","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"YYYY-MM-DD - 종료일(기본 오늘)","schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{"configured":true,"propertyId":"123456789","measurementId":"G-CNGFY7HTKQ","auth":"OAUTH","error":null,"data":{"overview":[{"date":"2026-10-18","activeUsers":320,"sessions":410,"pageViews":1500,"avgEngagementSec":74,"newUsers":120}],"archives":[{"id":1,"title":"...","views":230,"users":180,"avgEngagementSec":95}],"posts":[],"events":[{"name":"archive_view","count":230,"users":180}]}}}}}}}}},"/api/admin/audit":{"get":{"tags":["백오피스"],"summary":"관리 이력","description":"요구사항: CM-04\n\n인증: 백오피스 운영 관리자 이상","security":[{"admin":[]}],"parameters":[],"responses":{"200":{"description":"성공","content":{"application/json":{"example":{"ok":true,"data":{}}}}}}}}}}