40 lines
2.2 KiB
Markdown
40 lines
2.2 KiB
Markdown
# Project Structure Baseline
|
|
|
|
- Related REQ: N/A
|
|
|
|
## 목표
|
|
`portfolio-hub` 구현 및 유지보수 시 디렉토리 책임을 명확히 하여 API/CLI/도메인/저장소 변경의 영향 범위를 예측 가능하게 유지한다.
|
|
|
|
## Target Baseline Structure
|
|
|
|
| 경로 | 책임 | 구현 메모 |
|
|
| --- | --- | --- |
|
|
| `docs/SRS/` | 외부 계약, 승인 기준, REQ 상태 관리 | requirement source of truth |
|
|
| `docs/technical/` | 구현 상세 설계와 운영 메모 | SRS를 재정의하지 않음 |
|
|
| `app/api/` | HTTP 라우트, 요청/응답 경계 | 서비스 계층 호출 전담 |
|
|
| `app/cli/` | Typer CLI 명령과 입출력 | 서비스 계층 재사용 |
|
|
| `app/services/` | 유스케이스 조합, 권한/검증 흐름 | API/CLI 공통 오케스트레이션 |
|
|
| `app/domain/` | 포트폴리오 비즈니스 규칙 | 기술 의존성 최소화 |
|
|
| `app/repositories/` | 영속성 인터페이스와 구현체 | DB feature flag 지원 |
|
|
| `app/schemas/` | API 계약 스키마(Pydantic) | 요청/응답 안정성 |
|
|
| `migrations/` | Alembic 마이그레이션 | 스키마 변경 이력 |
|
|
| `tests/` | API/도메인/CLI/계약 테스트 | 회귀 방지 게이트 |
|
|
|
|
## Root-Level Exception Rules
|
|
- 루트에는 `README.md`, `pyproject.toml`, `alembic.ini`, `.github/` 등 저장소 메타파일만 둔다.
|
|
- 실행 코드와 테스트 코드는 목적 디렉토리로 수렴시킨다.
|
|
|
|
## Documentation Responsibilities
|
|
- `README.md`: 빠른 시작, 실행 방법, 운영 필수 변수 요약
|
|
- `docs/SRS/`: 왜(Why), 무엇(What), 수락 기준
|
|
- `docs/technical/`: 어떻게(How), 모듈 경계, 예시 흐름
|
|
|
|
## Validation Notes
|
|
- 신규 모듈 추가 시 책임이 상기 경로 정의와 충돌하지 않는지 확인한다.
|
|
- API 계약 변경 시 `app/schemas/`와 `docs/technical/api-contracts.md`를 함께 동기화한다.
|
|
- 스키마 변경 시 `migrations/versions/`와 문서 업데이트를 같은 변경 단위에 포함한다.
|
|
|
|
## Open Implementation Points
|
|
- Redis/Loki 실제 운영 경로가 코드에 전면 반영되면 `app/core/` 또는 별도 infra 패키지 분리 여부를 확정한다.
|
|
- 태그 검색 기능(`REQ-002`) 구현 시 서비스/리포지토리 경계의 책임 분리를 추가 명세한다.
|