evo-dispatch 버그 신고 공간 v1

• 상태: 구현 —, 이미지 첨부, 분류, Android·iOS 분류
• 주소: POST /mcp/bugs (MCP Streamable HTTP, stateless)
• 버그 형식: schemas/bug-report.schema.json
• 대상: 올리는 쪽은 evo 제품(Evo CLI·웹 채팅·에뮬레이터·Mac·Windows·Android·iOS 앱) 사용자. 처리하는 쪽은 그 분류를 맡은 프로젝트의 개발 에이전트(개발 요청 공간 dev-requests.md §5.2)

dispatch의 세 공간:

공간	주소	쓰는 쪽	규격
세션 요청 공간	/mcp (dispatch_*)	같은 사용자의 evo 세션끼리	client-protocol.md
버그 신고 공간	/mcp/bugs (bug_report·bug_mine)	evo 제품 사용자(로그인 토큰)	이 문서
개발 요청 공간	/mcp/dev	프로젝트 개발 에이전트(가져가기 키)	dev-requests.md

1. 하는 일

evo 제품 사용자가 제품을 골라 버그를 올리고(오류 화면 캡처 이미지를 붙일 수 있다), 자기가 올린 버그의 처리 상태와 처리 메모를 본다. 그 제품을 개발하는 쪽이 버그를 하나씩 가져가 처리하고 메모를 남겨 닫는다.

• 올린 사람은 자기 버그만 본다. 다른 사람 버그는 보이지 않는다.
• 처리하는 쪽에는 올린 사람 신원이 보이지 않는다. 로그인 클라이언트(client, 토큰 azp)만 보인다.
• evo 제품은 개발 요청 공간(/mcp/dev)을 쓰지 않는다. 사용자가 알릴 것은 이 공간으로 올린다.
• 서버 설정 BOARD_ENABLED로 개발 요청 공간과 함께 켠다. 기본은 꺼짐이다(폐쇄망 조직 배포에서는 쓰지 않는다). 꺼져 있으면 /mcp/bugs가 없다(404).

2. 분류

사용자는 버그를 올릴 때 분류(product)를 고른다. 분류마다 처리하는 프로젝트가 하나 있고, 그 프로젝트의 가져가기 키로만 처리한다.

분류(product)	무엇의 버그	처리하는 프로젝트(가져가기 키)
CLI	Evo CLI	evo-cli
CHAT	evo 웹 채팅	evo-service
EMULATOR	evo 에뮬레이터	evo-emulator
MAC	evo Mac 앱	evo-mac
WINDOWS	evo Windows 앱	evo-windows
ANDROID	evo Android 앱	evo-android
IOS	evo iOS 앱	evo-ios
DISPATCH	dispatch(세션 요청이 안 간다, 버그 신고가 안 된다 등)	evo-dispatch

• 서버 설정 BUGS_PRODUCTS(분류=프로젝트, 쉼표 구분)로 바꾼다. 비우면 위 표다. 분류는 대문자(^[A-Z][A-Z0-9_]{0,31}$), 처리 프로젝트는 BOARD_PROJECTS 안이고 프로젝트마다 분류 하나다. 틀리면 서버가 시작하지 않는다.
• 목록 밖 분류로는 올릴 수 없다(invalid_request). bug_report의 입력 형식 product enum이 이 목록이다.
• 사용자가 고른 분류가 맞지 않으면 처리하는 쪽이 메모와 함께 닫고 맞는 분류로 다시 올리라고 안내하거나, 개발 요청 공간으로 그 프로젝트에 알린다.

3. 인증

• Keycloak access token(Authorization: Bearer)만 받는다. 검증은 /mcp와 같다(서명, iss, exp, 허용 azp, 토큰 종류, 설정했으면 aud). 조직·개인 로그인 모두 받는다.
• 사용자는 토큰의 iss + sub다. 조직과 개인에서 아이디가 같아도 다른 사용자다.
• 가져가기 키(dbk_...)는 HTTP 401이다. 토큰이 없거나 맞지 않아도 HTTP 401이다.
• evo 제품의 기본 등록은 개인용 로그인일 때만 한다(§7). 개인용 로그인은 개인용 Keycloak 인증 서버(evo-personal-auth, 렐름 evo)가 발급한 토큰으로 로그인한 경우다. 클라이언트(azp)는 조직용과 같다(evo-cli·evo-desktop·evo-web).

4. 상태

open ──take──▶ taken ──close(note)──▶ closed
                 └──release──▶ open

상태	올린 사람에게 보이는 뜻
open	접수됨. 아직 아무도 보지 않았다
taken	확인 중. 개발 쪽이 가져갔다
closed	처리 끝. note에 결과가 있다

• 닫을 때 메모(note, 1~1000자)가 꼭 있다. 올린 사람은 bug_mine에서 이 메모를 본다.
• 올린 사람이 취소하는 기능은 없다. 잘못 올렸으면 개발 쪽이 메모와 함께 닫는다.

5. tool

tool	인자	결과
bug_report	product(§2), title(1200자), body(Markdown, 116384자: 증상, 재현 순서, 기대한 동작), 선택 version(1100자, 제품 버전), 선택 os(1100자), 선택 links(최대 20, {url, label?}), 선택 images(§5.1)	올린 버그($defs/reported, 첨부가 있으면 image_count)
bug_mine	선택 limit(1~50, 기본 20)	{"bugs":[...]} 최근 순($defs/reported: id·제품·제목·상태, closed면 note, 첨부가 있으면 image_count, 올린 시각·바뀐 시각)

• 결과에는 본문·첨부 이미지와 처리한 쪽 정보가 없다.
• 결과 담기, 오류 모양, 모르는 JSON-RPC 메서드, 읽을 수 없는 본문은 개발 요청 공간과 같다(dev-requests.md §5.3). 오류 코드: invalid_request, unauthorized, rate_limited, internal_error.
• 한도: 사용자마다 1분 요청 수(기본 300, 넘으면 HTTP 429와 Retry-After). bug_report는 사용자마다 1시간 10건(기본, DISPATCH_BUG_REPORTS_PER_HOUR)이고, 넘으면 tool 오류 rate_limited로 저장하지 않는다.
• 본문에 비밀정보(토큰·비밀번호·내부 주소·개인정보)를 넣지 않는다. 서버는 본문과 토큰을 로그에 남기지 않는다.
• 요청 본문 상한은 이 주소만 5MiB(기본, DISPATCH_BUGS_MAX_BODY_BYTES)다. 넘으면 HTTP 413 invalid_request. 다른 주소는 256KiB 그대로다.
• tool 설명·입력 형식은 모델 요청마다 붙으므로 짧게 둔다(두 tool 합계 1200바이트 미만, 테스트로 지킨다).

5.1 첨부 이미지

bug_report의 images: 오류 화면 등의 캡처.

"images": [ { "mime_type": "image/png", "data": "<base64>" } ]

• 최대 3장. 형식은 image/png·image/jpeg·image/webp. 장당 디코드 크기 1MiB 이하.
• 서버는 base64와 파일 앞부분 서명(PNG 89 50 4E 47…, JPEG FF D8 FF, WebP RIFF….WEBP)이 mime_type과 맞는지 본다. 하나라도 맞지 않으면 버그 전체가 invalid_request이고 저장하지 않는다. 크기 변환·압축은 하지 않으니 큰 화면은 보내는 쪽이 줄여서(예: 긴 변 1600px JPEG) 보낸다.
• 올린 사람은 첨부 수(image_count)만 다시 본다. 이미지는 그 제품의 처리하는 쪽(가져간 키)만 bug_image로 받는다(dev-requests.md §5.2).
• 화면에 비밀정보·다른 사람 개인정보가 찍히지 않게 한다. 앱 양식에서는 보내기 전에 미리 보여 준다.

6. 보존

1분마다 도는 정리 작업(client-protocol.md §7)이 closed 버그를 닫힌 뒤(updated_at) 30일이 지나면 첨부 이미지와 함께 지운다. 기간은 application.yml의 dispatch.retention.bug-report(기본 30d)다. open·taken 버그는 지우지 않는다. 지운 버그는 bug_mine에 나오지 않는다.

7. evo 제품 연동

공통:

• 기본 등록: Evo CLI·Windows·Mac은 개인용 로그인(개인용 인증 서버 evo-personal-auth로 로그인)일 때 세션 요청 공간(/mcp)과 버그 신고 공간(/mcp/bugs)을 기본으로 등록한다(번들). 조직용 로그인일 때는 기본 등록하지 않는다. 개발 요청 공간은 등록하지 않는다.
• 토큰은 지금 로그인 토큰을 그대로 붙인다(/mcp와 같다). 세션 header(X-Dispatch-Client-Kind·X-Dispatch-Session-Id)와 활성 신호는 필요 없다.
• 옛 공용 요청 공간(/mcp/board)을 등록했거나 부르는 곳이 있으면 지운다. 그 주소는 없앴다(, dev-requests.md §8).
• <dispatch 도메인>은 배포 담당에게 받는다. 주소는 저장소·문서에 적지 않는다.

7.1 Evo CLI

• MCP 서버 dispatch-bugs(https://<dispatch 도메인>/mcp/bugs)를 개인용 로그인일 때 기본으로 등록하고 로그인 토큰을 붙인다.
• 모델이 bug_report·bug_mine을 부른다. 사용자가 “evo 버그 신고해줘”, “내가 올린 버그 어떻게 됐어?“처럼 말할 때 쓴다. product는 CLI가 기본이고, 사용자가 다른 제품(웹 채팅·에뮬레이터·Mac·Windows 앱·dispatch) 버그라고 하면 그 분류를 고른다.
• version에는 Evo CLI 버전, os에는 운영체제를 넣는다.
• 사용자가 화면 캡처·이미지 파일을 주면 images로 붙인다(§5.1, 1MiB를 넘으면 줄인다).

7.2 evo Windows·Mac 앱

• 개인용 로그인일 때 앱 안의 모델에 dispatch-bugs를 기본으로 등록한다(Evo CLI와 같다).
• 앱 화면에서 런타임이 tool을 직접 부를 수 있다(MCP JSON-RPC tools/call, 모델을 거치지 않음).
  • 버그 신고 양식: 제목·내용과 화면 캡처(최대 3장, 붙여넣기·파일 선택·지금 화면 캡처)를 받고 product(자기 앱: WINDOWS·MAC, 사용자가 고를 수 있게 다른 분류도 둔다), version(앱 버전), os를 채워 bug_report. 캡처는 보내기 전에 미리 보여 주고 1MiB를 넘으면 줄인다.
  • 내 버그 목록: bug_mine 결과의 상태(접수·확인 중·처리 끝), 처리 메모, 첨부 수를 보여 준다.
• 결과는 content[0].text의 JSON이다.

7.3 evo 웹 채팅

• 웹 채팅(evo-service)은 사용자 본인 로그인 토큰(azp evo-web)으로 bug_report·bug_mine을 부르는 버그 신고 화면을 둔다. 기본 분류는 CHAT. 옛 웹 ‘요청 공간’ 화면(/mcp/board)을 이 화면으로 바꾼다.
• 버그 신고 화면은 제목·내용·분류·화면 캡처(§5.1)를 받고, 내 버그 목록에 상태·처리 메모·첨부 수를 보여 준다.

8. 변경 이력

버전	날짜	내용
v1	2026-10-28	최초 작성. 버그 신고 공간 /mcp/bugs(bug_report·bug_mine), 처리 tool은 개발 요청 공간 /mcp/dev(bug_list·bug_take·bug_release·bug_close). 개인용 로그인일 때 제품 기본 등록
v2	2026-10-28	. product를 프로젝트 이름에서 버그 분류(CLI·CHAT·EMULATOR·MAC·WINDOWS·DISPATCH)로 바꿨다(§2). 분류마다 처리 프로젝트(설정 BUGS_PRODUCTS 분류=프로젝트). 기존 버그 행은 V9에서 바뀐다. 웹 채팅 연동 §7.3. 개인용 로그인 문구를 ’개인용 인증 서버로 로그인’으로. 깨지는 변경: product 값(evo-cli → CLI 등). 아직 연동한 제품이 없어 전환 기간 없이 바꾼다
v1.1	2026-10-28	. bug_report 선택 images(png·jpeg·webp, 최대 3장, 장당 1MiB, §5.1), 결과 image_count, 이 주소 본문 상한 5MiB. 처리 쪽 bug_image. 기존 인자·결과 변경 없음(추가만)
v2.1	2026-11-02	. 기본 분류에 ANDROID(evo-android)·IOS(evo-ios) 추가(§2). 기존 분류·값 변경 없음