52 lines
3.0 KiB
Markdown
52 lines
3.0 KiB
Markdown
# portfolio-hub Technical Specification Index
|
|
|
|
## 목적
|
|
- 이 디렉토리는 `portfolio-hub`의 **구현 상세 설계(How)** 를 관리한다.
|
|
- 승인 기준과 외부 요구사항의 source of truth는 `docs/SRS/`이며, 기술 문서는 해당 요구사항을 구현하기 위한 내부 설계를 정리한다.
|
|
|
|
## 문서 사용 원칙
|
|
1. 외부 계약, acceptance criteria, 상태 전이는 `docs/SRS/`에서 관리한다.
|
|
2. 내부 모듈 책임, 시퀀스, 데이터 흐름, 예시 payload는 `docs/technical/`에서 관리한다.
|
|
3. 기술 문서가 SRS와 충돌하면, 별도 owner 결정 전까지 **SRS를 우선**한다.
|
|
4. 기술 문서를 수정할 때는 관련 REQ ID를 함께 표시해 traceability를 유지한다.
|
|
|
|
## 문서 목록
|
|
|
|
| 문서 | 목적 | 연관 REQ |
|
|
| --- | --- | --- |
|
|
| `project-structure-baseline.md` | 저장소 baseline 디렉토리 구조와 코드/문서 배치 기준 | N/A |
|
|
| `python-runtime-and-packaging.md` | Python 런타임과 `pyproject.toml` 기반 패키징 기준 | N/A |
|
|
| `settings-and-env-loading.md` | `.env`/환경변수 로딩, 필수 키, CORS/운영 설정 규칙 | N/A |
|
|
| `architecture-overview.md` | 시스템 개요, 모듈 책임, 런타임 흐름, 테스트/호환성 기준 | `REQ-003` |
|
|
| `api-contracts.md` | HTTP API 상세 계약, request/response 모델, 대표 payload 예시 | `REQ-001`, `REQ-002`, `REQ-003` |
|
|
| `persistence-and-migrations.md` | PostgreSQL/Timescale 연동, 리포지토리 스위치, Alembic 운영, 스키마 baseline | `REQ-001`, `REQ-003` |
|
|
| `auth-and-token-lifecycle.md` | 로그인/토큰/봇 주체 라이프사이클 및 권한 모델 | N/A |
|
|
| `portfolio-ownership-and-auth-design.md` | 포트폴리오 소유주(`owner_user_id`) 도입, 소유권 접근 제어, 검증 시나리오 설계 | `REQ-004` |
|
|
| `management-cli-operations.md` | `portfoliohub` CLI 명령 책임, 종료코드, 운영 플로우 | N/A |
|
|
| `deployment-and-operations.md` | Linux systemd, Caddy reverse proxy, Docker Compose 운영 절차 | N/A |
|
|
|
|
## 연관 REQ 매핑 표
|
|
|
|
| REQ ID | Technical Docs |
|
|
| --- | --- |
|
|
| `REQ-001` | `api-contracts.md`, `persistence-and-migrations.md` |
|
|
| `REQ-002` | `api-contracts.md` |
|
|
| `REQ-003` | `architecture-overview.md`, `api-contracts.md`, `persistence-and-migrations.md` |
|
|
| `REQ-004` | `auth-and-token-lifecycle.md`, `api-contracts.md`, `persistence-and-migrations.md`, `portfolio-ownership-and-auth-design.md` |
|
|
|
|
## 권장 작성 순서
|
|
1. `project-structure-baseline.md`
|
|
2. `python-runtime-and-packaging.md`
|
|
3. `settings-and-env-loading.md`
|
|
4. `architecture-overview.md`
|
|
5. `api-contracts.md`
|
|
6. `persistence-and-migrations.md`
|
|
7. `auth-and-token-lifecycle.md`
|
|
8. `management-cli-operations.md`
|
|
9. `deployment-and-operations.md`
|
|
|
|
## 추적 규칙
|
|
- 각 기술 문서는 상단에 관련 REQ를 명시한다.
|
|
- 구현 착수 전에는 해당 문서의 open issue가 남아 있는지 확인한다.
|
|
- 운영 중 발견된 차이는 technical 문서에 먼저 반영하고, 외부 계약 변화가 있으면 SRS 업데이트 여부를 별도로 판정한다.
|