# Settings and Env Loading

- Related REQ: N/A

## 목표
설정값 로딩 경로를 단일화하여 로컬/운영 간 동작 차이를 최소화하고, 보안 민감 값을 안전하게 주입한다.

## 설정 로딩 우선순위
1. 환경 변수
2. `.env` 파일
3. 코드 기본값

## 핵심 설정 그룹

| 그룹 | 예시 키 | 목적 |
| --- | --- | --- |
| API/CORS | `PORTFOLIOHUB_ALLOWED_ORIGINS` | 브라우저 호출 허용 오리진 제어 |
| 인증/권한 | `PORTFOLIOHUB_READ_TOKENS`, `PORTFOLIOHUB_TRADE_WRITE_TOKENS`, `PORTFOLIOHUB_ADMIN_TOKENS` | 정적 토큰 기반 접근 제어 |
| 세션/토큰 TTL | `PORTFOLIOHUB_SESSION_TOKEN_TTL_HOURS` 등 | DB 발급 토큰 만료 정책 |
| Bootstrap User | `PORTFOLIOHUB_BOOTSTRAP_USERNAME`, `PORTFOLIOHUB_BOOTSTRAP_PASSWORD` | 초기 admin 사용자 생성 |
| DB 연결 | `TIMESCALEDB_*` | Postgres/Timescale 접속 정보 |
| Observability | `LOKI_*`, `REDIS_*` | 중앙 로그/캐시 운영 확장 포인트 |

## 상세 설정 명세

핵심 설정:

- `PORTFOLIOHUB_ALLOWED_ORIGINS`: comma-separated CORS origins
- `PORTFOLIOHUB_BOOTSTRAP_USERNAME`: users 테이블이 비어 있을 때 생성할 초기 username
- `PORTFOLIOHUB_BOOTSTRAP_EMAIL`: bootstrap user의 선택적 email
- `PORTFOLIOHUB_BOOTSTRAP_PASSWORD`: 초기 admin password
- `PORTFOLIOHUB_READ_TOKENS`: comma-separated read tokens
- `PORTFOLIOHUB_TRADE_WRITE_TOKENS`: comma-separated trade-write tokens
- `PORTFOLIOHUB_ADMIN_TOKENS`: comma-separated admin tokens
- `PORTFOLIOHUB_DB_ENABLED`: `true`일 때 DB repository 활성화
- `PORTFOLIOHUB_SESSION_TOKEN_TTL_HOURS`: login session token TTL(hours)
- `PORTFOLIOHUB_CLIENT_TOKEN_DEFAULT_TTL_DAYS`: client token 기본 TTL(days)
- `PORTFOLIOHUB_BOT_TOKEN_DEFAULT_TTL_DAYS`: bot token 기본 TTL(days)

DB 활성 설정:

- `TIMESCALEDB_HOST`
- `TIMESCALEDB_PORT`
- `TIMESCALEDB_NAME`
- `TIMESCALEDB_USER`
- `TIMESCALEDB_PASSWORD`
- `TIMESCALEDB_SSLMODE`
- `TIMESCALEDB_CONNECT_TIMEOUT_SEC`
- `TIMESCALEDB_APPLICATION_NAME`

파생 설정:

- `active_database_url`은 psycopg PostgreSQL URL 포맷으로 credentials와 query options를 인코딩해 구성한다.

## CORS 정책

CORS middleware는 다음 기준으로 동작한다.

- `allow_origins`: 구성된 origins 목록 사용
- `allow_credentials = true`
- `allow_methods = ["GET", "POST", "PATCH", "DELETE", "OPTIONS"]`
- `allow_headers = ["Authorization", "Content-Type"]`

브라우저 기반 frontend가 HTTPS로 접근하면 `PORTFOLIOHUB_ALLOWED_ORIGINS`에는 정확한 HTTPS origin만 명시한다.

예시:

```bash
PORTFOLIOHUB_ALLOWED_ORIGINS=https://app.example.com,https://www.example.com
```

## 운영 규칙
- 운영 환경에서는 `.env` 대신 배포 플랫폼의 환경 변수 주입을 우선한다.
- `PORTFOLIOHUB_DB_ENABLED=true`일 때 `TIMESCALEDB_*` 필수 키 누락 여부를 시작 시 검증한다.
- 민감 값은 문서/샘플에 실제 비밀 값을 기록하지 않는다.

## Validation Notes
- 필수 키 누락 시 명확한 예외 메시지로 기동 실패해야 한다.
- CORS 오리진 파싱은 공백/쉼표 변형 입력에도 안정적으로 동작해야 한다.
- 부트스트랩 계정 자동 생성은 `users` 테이블이 비어 있을 때만 수행되어야 한다.

## Open Implementation Points
- 설정 스키마를 strict mode로 고정할지(미정의 키 거부) 여부를 확정한다.
- Redis/Loki 활성화 플래그와 실패 시 동작(무시/실패)을 명시적으로 분리할지 결정한다.