portfolio-hub/docs/technical/index.md

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 업데이트 여부를 별도로 판정한다.