SATTIE 문서화 작업 플랜

- 외부 클라이언트가 API를 빠르게 연동할 수 있는 개발가이드를 제공한다.

카테고리: docs | 읽기시간: 2분 | 원문: 다운로드

SATTIE 문서화 작업 플랜

1. 목적

• 외부 클라이언트가 API를 빠르게 연동할 수 있는 개발가이드를 제공한다.
• 내부 유지보수 개발자가 구조/운영/변경 절차를 안정적으로 수행할 수 있는 가이드를 제공한다.
• 현재 구현 상태와 문서 내용의 불일치를 최소화한다.

2. 산출물

• docs/API_CLIENT_GUIDE.md
• 대상: 외부 API 연동 개발자
• 범위: 엔드포인트 사용법, 요청/응답 예시, 에러 처리, 연동 패턴
• docs/MAINTAINER_GUIDE.md
• 대상: 내부 유지보수 개발자
• 범위: 아키텍처, 코드 구조, 데이터 저장소, 운영/장애 대응, 변경 절차

3. 진행 순서

1. 작업플랜 문서 작성 (docs/WORK_PLAN.md)
2. 외부 클라이언트용 개발가이드 작성 (docs/API_CLIENT_GUIDE.md)
3. 내부 유지보수 개발자용 가이드 작성 (docs/MAINTAINER_GUIDE.md)
4. 정합성 점검

• 엔드포인트/파라미터/응답/오류코드가 실제 코드와 일치하는지 확인
• 랜덤 생성기(/images/generate)와 OSM 생성기(/osm/images/generate, /osm/images/generate-all)의 패턴 차이를 명확히 표기
• 저장 경로(mock_store/random, mock_store/osm)와 UI 동작 연계를 문서에 반영

4. 작성 원칙

• 구현된 사실만 기술하고, 미구현 사항은 명확히 구분한다.
• 예시는 바로 실행 가능한 curl 중심으로 작성한다.
• 에러 케이스(400/404/422/502)를 요청 패턴과 함께 설명한다.
• 외부용 문서는 “어떻게 호출하면 되는지”에 집중하고, 내부용 문서는 “왜 이렇게 구성했는지/어떻게 수정할지”에 집중한다.

5. 완료 기준

• 외부용 문서만 보고도 다음 시나리오를 구현할 수 있어야 한다.
• 랜덤 단건 생성 파일 다운로드
• OSM 단건 생성 파일 다운로드
• OSM 일괄 생성 후 항목별 다운로드
• 내부용 문서만 보고도 다음 작업을 수행할 수 있어야 한다.
• 서버 기동/로그 확인/기본 장애 대응
• API 설명(OpenAPI) 수정
• 포맷/레벨/Provider 확장 시 영향 범위 파악