통신 계약 (contracts)
갱신일 2026-07-29 · server 미러 기준
5d7305d
heymoa-web / heymoa-server / heymoa-ai가 분리 작업하기 위한 스키마의 단일 출처다. 이 폴더는 스키마 파일만 소유한다 — 그 파일들을 어떻게 쓰고 어떻게 갱신하는가는 interfaces/가 소유한다. 같은 규칙을 양쪽에 쓰지 않는다.
| 찾는 것 | 어디 |
|---|---|
| 스키마·필드·enum 값 | 이 폴더의 yml (아래 표) |
| owner·source·mirror·status·검증·소비자, 갱신 절차 | interfaces/api-registry.md — 계약을 고치기 전에 항상 |
| 인증·오류·식별자·멱등성·시간·SSE 종료 규약 | interfaces/common-conventions.md |
| 경계별 사용법 | interfaces/server-web.md · interfaces/server-ai.md |
설계 근거: 3-서비스 아키텍처 교차 서비스 정본: develop/MVP1/README.md
파일
파일은 경계 하나에 하나다. 이름은 {프로토콜}-{경계} 규칙을 따른다.
| 파일 | 경계 | 성격 |
|---|---|---|
| openapi3-server.yml | web → server public REST (/v1/** 34경로) + ai → server internal REST (/internal/v1/** 3경로) | 생성물 미러 — heymoa-server 빌드(restdocs-api-spec)가 생성. 손으로 수정 금지 |
| asyncapi-web-server.yml | web ↔ server 비동기 (전사 STOMP·노트 토픽 + agent 채팅 SSE) | 합본 — 전사 STOMP·노트 토픽 구간은 heymoa-server/asyncapi.yml 미러, SSE 구간은 이 파일이 원본 |
| asyncapi-server-ai.yml | server ↔ ai 채팅 SSE | 계획 문서 — 이벤트는 web-server 파일을 $ref |
| openapi3-ai.yml | server → ai 내부 REST + 분석 결과 callback | 수기 원본 — 계약이 먼저, 구현이 따라온다 |
| agent-chat-flow.md | web → server → ai 채팅 루프 | 흐름 서술 (계약 아님) — 시퀀스 + 경계 규칙 |
openapi3-server.yml이 두 경계를 함께 담는 것은 생성 구조상 불가피하다. server가 받는 모든 경로의 생성물이라 ai가 부르는 /internal/v1/** 3경로도 포함된다. web은 이 3경로를 제거한 사본으로 클라이언트를 생성한다 — 절차는 api-registry.md.
고치기 전에
미러를 직접 고치면 다음 생성에서 덮인다. 어느 파일이 원본이고 무엇이 바뀌면 무엇을 해야 하는지는 interfaces/api-registry.md의 동기화 방향·갱신 표가 정본이다. 요약하면:
- server REST가 바뀌면 → server 코드를 고치고 재생성한다 (이 폴더가 아니다)
- 전사 STOMP·노트 토픽이 바뀌면 → **
heymoa-server/asyncapi.yml**을 고치고 여기로 복사한다 - agent 채팅 SSE가 바뀌면 → **
asyncapi-web-server.yml**만 고친다 (server-ai가$ref하므로 자동 반영) - ai 내부 REST가 바뀌면 → **
openapi3-ai.yml**을 먼저 고치고 구현이 따라간다
문법 검증: npx --yes @asyncapi/cli validate <파일> (asyncapi 3종).
검증 강도가 파일마다 다르다는 점은 api-registry.md §4에 있다.
계약을 바꿨으면 관련 repo PR과 Linear에 그 commit SHA를 남긴다.
SSE 이벤트가 한 곳에만 있는 이유
server는 heymoa-ai의 채팅 SSE를 **변환 없이 통과(passthrough)**시킨다. 그래서 web 구간과 ai 구간의
이벤트 포맷은 같을 수밖에 없고, 사본을 두면 갈라진다. 단일 출처는 asyncapi-web-server.yml이다 —
실제 코드로 검증되는 쪽이 web 구간이기 때문이다. asyncapi-server-ai.yml은 이를 $ref한다.
경계별 인증
세 경계의 인증 방식과 server → ai 방향이 비어 있는 이유는
interfaces/common-conventions.md §4가 정본이다.
계약 파일 쪽 근거는 openapi3-ai.yml의 info.description에 미결로 등재되어 있다.
분석 결과 callback(POST /internal/v1/callbacks/analyses/{analysisId})은
heymoa-ai가 보내는 요청이므로 openapi3-ai.yml의 OpenAPI callbacks로 정의한다.
heymoa-server의 생성 스펙에도 수신 측 경로로 포함돼 있다.
기획 v2 (2026-07-22, 오프라인 회의 중심)
기획: pm/2-product/feature-specs/ · 이슈: APP-102 에픽
- 챗봇 2종: 개인(스코프 workspace|note, 활성 세션 1개) + 공유(노트 소속, ACTIVE에만 쓰기, 입력 잠금)
- 도구 연동은 워크스페이스 단위:
/v1/workspaces/{workspaceId}/integrations/* - 쓰기 도구 승인:
tool_approval_request/tool_approval_resolved이벤트 + 승인 API - v2 서버 구현 완료(2026-07-23, APP-102 체인): 모든 v2 경로가 미러에 흡수돼
수기 초안
heymoa-server.v2-draft.openapi.yml은 삭제했다. web→server REST의 단일 출처는 미러다.