# Management CLI Operations

- Related REQ: N/A

## 목표
`portfoliohub` CLI를 운영 자동화와 수동 점검 모두에 안전하게 사용할 수 있도록 명령 책임과 사용 규칙을 정의한다.

## 명령 그룹

| 그룹 | 주요 명령 | 목적 |
| --- | --- | --- |
| DB 운영 | `init-db`, `migrate-db`, `health-check` | 스키마 적용 및 연결 상태 점검 |
| 사용자 관리 | `user list/get/create/update/delete` | 운영 계정 라이프사이클 |
| 포트폴리오 조회 | `portfolio list`, `portfolio status` | 상태 확인 |
| 포트폴리오 변경 | `portfolio create/update/buy/sell/invest/transfer/reset/delete` | 거래/자금/상태 변경 |

## 인터페이스 명세

전역 옵션:

- `--format [table|json]` (기본값: `table`)

공통 명령:

- `portfoliohub init-db [--maintenance-db postgres]`
- `portfoliohub migrate-db`
- `portfoliohub health-check`

포트폴리오 하위 명령:

- `portfoliohub portfolio list [--broker ...] [--status ...]`
- `portfoliohub portfolio status <portfolio_id> [--recent 5]`
- `portfoliohub portfolio create <portfolio_id> --symbol ... [--name ...] [options] [--force]`
- `portfoliohub portfolio update <portfolio_id> [options] [--force]`
- `portfoliohub portfolio buy <portfolio_id> --quantity ... --price ... [options] [--force]`
- `portfoliohub portfolio sell <portfolio_id> --quantity ... --price ... [options] [--force]`
- `portfoliohub portfolio invest <portfolio_id> --type <deposit|profit|withdraw> --amount ... [options] [--force]`
- `portfoliohub portfolio transfer <portfolio_id> --direction <to-buffer|from-buffer> --amount ... [options] [--force]`
- `portfoliohub portfolio reset <portfolio_id> [--infer-symbol ...] [--force]`
- `portfoliohub portfolio delete <portfolio_id> [--keep-ledger] [--force]`

포트폴리오 댓글 하위 명령:

- `portfoliohub portfolio comment add <portfolio_id> --content <text>`
- `portfoliohub portfolio comment list <portfolio_id>`
- `portfoliohub portfolio comment update <portfolio_id> <comment_id> --content <text> [--force]`
- `portfoliohub portfolio comment delete <portfolio_id> <comment_id> [--force]`

전략셋 하위 명령:

- `portfoliohub strategy list`
- `portfoliohub strategy create --name ... --config ...`
- `portfoliohub strategy update <strategy_set_id> [--name ...] [--config ...]`
- `portfoliohub strategy delete <strategy_set_id> [--force]`

## 실행 원칙
- 쓰기 명령은 기본적으로 확인 프롬프트를 띄운다.
- 자동화 스크립트에서는 `--force`를 사용해 비대화식 실행을 보장한다.
- DB 타깃 실행 시 `PORTFOLIOHUB_DB_ENABLED=true`와 `TIMESCALEDB_*`를 명시한다.

## 예시 시나리오
1. 신규 환경 준비
   - `portfoliohub init-db`
   - `portfoliohub health-check`
2. 일상 운영
   - `portfoliohub portfolio list`
   - `portfoliohub portfolio status <portfolio_id>`
3. 배포 후 검증
   - `portfoliohub user list`
   - 주요 API smoke test와 결과 비교

## 오류/종료코드 가이드
- `0`: 정상 종료
- `1`: 입력/검증/런타임 오류
- 재시도 가능 오류(예: 일시적 DB 연결 실패)는 메시지에 원인을 명확히 표기한다.

확인 동작:

- 변경 명령은 기본적으로 확인 프롬프트를 요청한다.
- `--force`를 지정하면 확인 프롬프트를 생략한다.

## Open Implementation Points
- JSON 출력 모드(`--json`)를 도입해 자동화 친화성을 높일지 결정한다.
- 대량 작업(batch) 명령 추가 시 실패 항목 보고 포맷을 표준화한다.