본 문서는 가챠 무인 판매기 프로젝트의 장치 등록 시스템 요구사항이 기존 대비 어떻게 개선되었는지를 정리한 보고서입니다. 프로젝트 참여자 및 이해관계자가 명확하게 변경 사항을 이해하고 시스템 구현에 반영할 수 있도록 하기 위함입니다.
- 명확한 프롬프트 작성을 통해 AI 코드 생성 모델의 정확도 향상
- 요구사항 명세 구체화를 통한 구현 품질 및 일관성 제고
- 실제 시스템 수준 고려사항 반영으로 운영 가능성 확보
| 항목 | 기존 요구사항 | 개선된 요구사항 |
|---|---|---|
| 요구사항 수준 | 간략한 기능 설명 중심 | 상세 API 명세 및 동작 흐름 포함 |
| 코드 생성 대상 | 추상적인 지시문 중심 | SRP 기반 계층형 아키텍처 명시 |
| API 명세 | 거의 없음 | 메서드, URI, 본문, 응답 예시 포함 |
| 비즈니스 로직 | 장치 등록 및 승인 여부 | 등록 → 상태 조회 → 승인/거부 → 큐 발급 로직 명확화 |
| 보안 고려 | 관리자 기능만 JWT 인증 | 관리자 JWT + 장치 인증 제외 명확 분리 |
| 폴더 구조 | 미정 | Controller / Service / Domain / Interface 로 계층 분리 제안 |
| 확장성 고려 | 없음 | SQS 모듈 추상화로 Kafka 전환 가능성 고려 |
| 장애 처리 | 미정 | 중복 등록, 실패 응답 코드 및 메시지 설계 포함 |
| 프론트 요구사항 | 미정 | React 기반 관리자 대시보드 요구사항 포함 |
| 설계 가이드 | 없음 | SRP, 의존성 주입, Swagger 문서화 등 고급 설계 포함 |
- 자판기 → 중앙 서버 등록 → 관리 승인 → 메시지 큐 발급
- NestJS 기반의 REST API 백엔드
- DynamoDB, SQS 기반의 서버리스 구조 고려
- FR-1 ~ FR-4 로 기능별 상세화
- 각 API 요청/응답 형식 명시
- 상태 전이와 예외 처리까지 포함한 시나리오 기반 설계
- 명확한 계층 분리를 통해 유닛 테스트 및 확장성 확보
- messaging, db, auth interface 분리로 유지보수 용이성 향상
- 관리자 인증 (JWT) 적용 범위 명시
- DTO 및 Zod/Joi 기반 입력 유효성 검증 요구
- React 기반 관리자 대시보드 명세 포함
- 장치 리스트업, 승인/거부 버튼, 상태 시각화 UI 요구 포함
| 항목 | 기대 효과 |
|---|---|
| AI 코드 생성 품질 향상 | 프롬프트와 명세가 구체화됨에 따라 요구사항 반영률 향상 |
| 시스템 구현 일관성 | 계층 구조 및 모듈 규칙이 명확하여 팀 단위 협업 용이 |
| 테스트 용이성 | SRP 구조 및 모듈화로 유닛 테스트 범위 명확 |
| 확장 고려 | 추후 Kafka, PostgreSQL, GraphQL 등으로의 전환이 쉬움 |
| 운영 안정성 | 장애 대응 및 예외 처리가 요구사항에 반영됨 |
/docs/하위에 본 README와 요구사항 명세 문서를 포함- 요구사항 변경 시 PR 템플릿에 변경 사항 요약 필수
- 시스템 구현과 요구사항 간의 정합성 검토 주기 설정 (예: 스프린트마다)
작성일: 2025-08-07
문서 책임자: 관우 조
문서 버전: v3.0