# 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 확장 시 영향 범위 파악