chore(docs): remove retired delivery artifacts
Remove retired StagePilot commands, templates, lifecycle records, and historical delivery documents, and record the current uv dependency lock.
This commit is contained in:
@@ -1,119 +0,0 @@
|
||||
# [REQ] `GET /v1/portfolios` 응답에 종목 코드(`symbol`) 포함
|
||||
|
||||
## 요약
|
||||
|
||||
`GET /v1/portfolios` 응답의 `PortfolioItem` 에 종목 코드(`symbol`) 필드를 추가해주세요. 현재는 `asset_id` (UUID) 만 반환되어, 종목 코드가 필요한 클라이언트가 별도 카탈로그 조회로 매핑해야 합니다.
|
||||
|
||||
## 배경
|
||||
|
||||
trex-orbit 자동매매 데몬은 매 사이클마다 `GET /v1/portfolios` 로 daemon-scoped portfolio 리스트를 받아 운용 대상 종목을 결정합니다. 이후 외부 데이터 서비스 (`kis-data-hub`) 에 시세 / 분봉을 요청하려면 종목 코드 (예: `"005930"`) 가 필요한데, 현재 `PortfolioItem` 에는 `asset_id` (UUID) 만 있고 `symbol` 이 빠져 있어 다음 우회가 필요합니다.
|
||||
|
||||
1. trex-orbit 부팅 시 asset 카탈로그를 별도로 조회해 `asset_id → symbol` 캐시 구성
|
||||
2. 사이클 중 `asset_id` 마다 캐시 lookup
|
||||
3. 캐시 미스 시 portfolio-hub 에 추가 조회
|
||||
|
||||
이 과정에서 캐시 stale / 신규 asset 등록 후 동기화 지연 / 클라이언트마다 캐시 로직 중복 같은 운영 부담이 발생합니다.
|
||||
|
||||
## 현재 상태
|
||||
|
||||
**Endpoint**: `GET /v1/portfolios` ([`app/api/v1_portfolios.py:224`](app/api/v1_portfolios.py#L224))
|
||||
|
||||
**응답 스키마**: [`PortfolioItem`](app/schemas/v1.py#L165)
|
||||
|
||||
```python
|
||||
class PortfolioItem(BaseModel):
|
||||
portfolio_id: str
|
||||
asset_id: str | None = None # UUID
|
||||
owner_user_id: str | None = None
|
||||
broker: str
|
||||
status: str
|
||||
name: str
|
||||
cash_balance: float = 0.0
|
||||
asset_quantity: float = 0.0
|
||||
price: float = 0.0
|
||||
profit_buffer: float = 0.0
|
||||
tag_ids: list[str] = Field(default_factory=list)
|
||||
managed_by_daemon_id: str | None = None
|
||||
created_at: datetime | None = None
|
||||
updated_at: datetime | None = None
|
||||
# symbol 없음
|
||||
```
|
||||
|
||||
종목 코드는 별도 `AssetItem` 에만 존재 ([`app/schemas/v1.py:55`](app/schemas/v1.py#L55)):
|
||||
|
||||
```python
|
||||
class AssetItem(BaseModel):
|
||||
asset_id: str
|
||||
symbol: str # ← 여기 있음
|
||||
status: str
|
||||
...
|
||||
```
|
||||
|
||||
## 요청 변경
|
||||
|
||||
### 1. 스키마
|
||||
|
||||
`PortfolioItem` 에 `symbol` 필드 추가:
|
||||
|
||||
```python
|
||||
class PortfolioItem(BaseModel):
|
||||
portfolio_id: str
|
||||
asset_id: str | None = None
|
||||
symbol: str | None = None # ← 추가 요청
|
||||
owner_user_id: str | None = None
|
||||
...
|
||||
```
|
||||
|
||||
### 2. 응답 채움 로직
|
||||
|
||||
`GET /v1/portfolios` 의 `_portfolio_to_item` 빌더가 `portfolios.asset_id → assets.symbol` join 결과를 활용해 `symbol` 을 채워주세요. 이미 repository 단계에서 join 되어 있다면 변환 로직만 추가하면 됩니다.
|
||||
|
||||
### 3. 단건 / 관련 엔드포인트도 동일 적용
|
||||
|
||||
다음 엔드포인트의 응답에도 `symbol` 포함:
|
||||
|
||||
- `POST /v1/portfolios` (생성 후 반환)
|
||||
- `PATCH /v1/portfolios/{portfolio_id}`
|
||||
- `DELETE /v1/portfolios/{portfolio_id}` (soft delete 응답)
|
||||
- 기타 `PortfolioItem` 을 반환하는 모든 경로
|
||||
|
||||
## 정당성
|
||||
|
||||
1. **클라이언트 단순화**: daemon 클라이언트 (trex-orbit 등) 가 portfolio 정보만 받으면 즉시 외부 시세 API 호출 가능. 추가 카탈로그 조회 / 캐시 관리 불필요.
|
||||
2. **일관성**: `cash_balance`, `asset_quantity`, `price` 등 자산 관련 필드는 이미 PortfolioItem 에 포함됨. `symbol` 도 자산 식별의 핵심이므로 같이 포함되는 것이 자연스러움.
|
||||
3. **stale cache 위험 제거**: 클라이언트 캐시 + miss fallback 패턴은 카탈로그 변경 시 일시적 불일치 가능. server 측 join 으로 항상 최신 매핑 제공.
|
||||
4. **운영 부담 감소**: 캐시 무효화 / 갱신 / 재로드 로직이 클라이언트마다 중복 구현되는 것을 회피.
|
||||
|
||||
## 호환성
|
||||
|
||||
`symbol` 은 신규 필드이며 `Optional[str]` 로 추가하면 기존 클라이언트에 영향 없음 (additive change).
|
||||
|
||||
## 영향 범위
|
||||
|
||||
- [`app/api/v1_portfolios.py`](app/api/v1_portfolios.py) — `_portfolio_to_item` 에 symbol 채움
|
||||
- [`app/schemas/v1.py`](app/schemas/v1.py#L165) — `PortfolioItem` 에 `symbol` 필드 추가
|
||||
- [`app/repositories/`](app/repositories/) — `list_portfolios` / `get_portfolio` 가 asset join 결과를 들고 오도록 보강 (이미 그렇다면 변경 없음)
|
||||
- [`docs/interface-contract.md`](docs/interface-contract.md#L321) — `GET /v1/portfolios` 응답 예시 갱신
|
||||
- 테스트 — `PortfolioItem` 응답 형식 검증 케이스 추가
|
||||
|
||||
## 검수 기준
|
||||
|
||||
1. `GET /v1/portfolios` 호출 시 각 item 에 `symbol` 필드가 포함됨
|
||||
2. `symbol` 값은 해당 `asset_id` 의 `AssetItem.symbol` 과 일치 (server side join)
|
||||
3. 단건 조회 / 생성 / 수정 / 삭제 응답도 동일하게 `symbol` 포함
|
||||
4. `interface-contract.md` 의 `GET /v1/portfolios` 응답 예시에 `symbol` 명시
|
||||
5. 기존 테스트 회귀 없음 + 신규 케이스 추가
|
||||
|
||||
## 우선순위
|
||||
|
||||
**Medium** — trex-orbit 사이드에서 캐시 기반 우회가 가능해 즉시 차단 이슈는 아니지만, 운영 본격 시작 전 정리하면 lifecycle 비용을 크게 줄임.
|
||||
|
||||
## 관련 문서
|
||||
|
||||
- trex-orbit `temp/plan.md` 8.4.1 step 3 (asset_id → symbol resolve) — 본 이슈의 우회 구현 단계
|
||||
- trex-orbit `temp/plan.md` 8.6.4.1 전제 시점 — universe 결정 과정에서 symbol resolve 가 필요한 이유
|
||||
|
||||
## 작성자 / 일자
|
||||
|
||||
- 요청자: trex-orbit 팀 (genichin@gmail.com)
|
||||
- 작성일: 2026-05-24
|
||||
Reference in New Issue
Block a user