trex/portfolio-hub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
829629fa8fe5af3d01a3edeeccb55b028093bb0c
portfolio-hub/docs/srs/Interface/req-008_v1-ledger-trades-endpoint.md
T
genichin 829629fa8f feat: implement portfolio UUID migration and v1 API finalization (BAT-006, BAT-001 re-verified) 
Core Changes:
- Migrate portfolio_id from string to UUID in schema and repository layer
- Update portfolio CLI commands to use name+user combination for identification
- Update HTTP API to accept portfolio_id as UUID path parameter
- Implement portfolio ownership validation in repository queries

Requirements Completed (REQ-016 to REQ-019):
- REQ-016: portfolios table UUID schema migration with data migration script
- REQ-017: CLI portfolio commands with name+user identification
- REQ-018: HTTP API portfolio path parameters and v1 asset_id UUID returns
- REQ-019: Portfolio UUID baseline documentation updates

BAT-001 Re-verification:
- REQ-004~010 marked as Implemented after verification evidence validation
- All v1 API endpoints verified with comprehensive test coverage

Documentation Updates:
- Update data-model.md with portfolio UUID structure
- Update interface-contract.md with UUID path parameters
- Update runtime-flows.md with ownership-based resolution flows
- Update project-structure.md with database layer changes
- Add migration script for portfolio UUID transition

Testing:
- Add test_portfolio_uuid.py for migration validation
- Update test_cli.py and test_portfolio_ownership.py for ownership checks
2026-05-11 09:27:57 +00:00

5.2 KiB
Raw Blame History

req-008: POST /v1/assets/{asset_id}/ledger/trades 엔드포인트 구현

  • Status: Implemented
  • Type: Interface
  • Priority: High
  • Owner: repository-maintainers

Intent

  • trex-basic이 체결 내역을 portfolio-hub에 idempotent하게 전송할 수 있도록 한다.
  • 동일 (asset_id, order_id, execution_id) 조합의 중복 수신은 DB unique constraint로 감지하고 status=duplicate를 반환한다(NFR-2).
  • 동일 키에 다른 payload가 오면 충돌로 처리한다.

Requirement

  • POST /v1/assets/{asset_id}/ledger/trades는 service-token bearer 인증으로 체결 내역(execution_id, order_id, side, quantity, price, fee_amount, tax_amount, executed_at)을 ledger_trades 테이블에 저장하고 HTTP 201을 반환해야 한다.
  • 동일 (asset_id, order_id, execution_id) 재수신은 신규 행 생성 없이 status=duplicate와 기존 ledger_entry_id를 HTTP 200으로 반환해야 한다.
  • 동일 키에 payload가 다른 경우 HTTP 409를 반환해야 한다.
  • idempotency는 DB unique constraint로 보장하며, 애플리케이션 로직만으로 보장하지 않는다.

Acceptance Criteria

  1. Given 유효한 service-token과 신규 체결 데이터로 POST /v1/assets/{asset_id}/ledger/trades 요청 시, Then HTTP 201과 생성된 ledger_entry_id가 반환되어야 한다.
  2. Given 동일 (asset_id, order_id, execution_id)와 동일 payload로 두 번째 요청 시, Then HTTP 200과 status="duplicate", 기존 ledger_entry_id가 반환되어야 하며 DB에 단일 행만 존재해야 한다.
  3. Given 동일 (asset_id, order_id, execution_id)에 다른 payload로 요청 시, Then HTTP 409가 반환되어야 한다.
  4. Given asset_id가 존재하지 않는 portfolio_id인 경우, Then HTTP 404가 반환되어야 한다.
  5. Given 인증 없이 요청 시, Then HTTP 401이 반환되어야 한다.

Impacted Area

  • Docs: docs/interface-contract.md (REQ-011에서 갱신 예정), docs/data-model.md (REQ-011에서 갱신 예정)
  • Modules: app/api/v1_ledger.py (신규), app/domain/models.py (LedgerTrade 모델 추가), app/services/ (ledger 저장 서비스 메서드 추가), app/schemas/ (v1 ledger 요청/응답 스키마 추가), app/repositories/postgres.py (ledger_trades 저장 및 중복 감지 쿼리 추가), app/main.py (/v1 라우터 등록)
  • Tests: tests/test_v1_ledger.py (신규)

Notes

  • NFR-2(idempotency DB unique constraint): (asset_id, order_id, execution_id) unique constraint는 REQ-009 migration에서 정의한다.
  • ledger_trades 테이블과 기존 portfolio_ledger 테이블은 별개다. portfolio_ledger는 내부 원장이고 ledger_trades는 trex-basic이 외부에서 기록하는 체결 내역이다.
  • 중복 감지 구현: DB unique constraint 위반(psycopg UniqueViolation) 캐치 → 기존 행 조회 → payload 동일 여부 비교 → duplicate 또는 409 응답.
  • Source Discovery: dcy-002 (FR-5, NFR-2)

Change Log

CHG-20260511-01

  • Date: 2026-05-11
  • Author: repository-maintainers

Change Summary

  • Implemented 전환 — BAT-001 re-verified verification passed, confirm-req-implemented 게이트 통과

Intent

  • BAT-001 verification.md (re-verified, 2026-05-03) AC-1~5 모두 PASS. Blocking Issues 없음.

Acceptance Criteria Delta

  • none

Impacted Area Delta

  • none

Delivery Trace Delta

  • Batches: BAT-001 (release-candidate)
  • Releases: none

Revalidation Impact

  • Reverification Needed: no
  • Existing Implementation Invalidated: no
  • Status Recommendation: implemented
  • Follow-up Action: draft-release (BAT-001)

Validation Plan

  • BAT-001 verification.md (re-verified) AC-1~5 evidence 연결 확인 완료

CHG-20260502-02

  • Date: 2026-05-02
  • Author: repository-maintainers

Change Summary

  • REQ-008 confirm-req 승인 전환 (Status: Proposed → Approved)

Intent

  • 필수 필드(Status, Type, Priority, Owner, Intent, Requirement, Acceptance Criteria 5개, Impacted Area, Change Log) 모두 충족 확인 후 승인

Acceptance Criteria Delta

  • No change

Impacted Area Delta

  • No change

Delivery Trace Delta

  • Batches:
    • none
  • Releases:
    • none

Revalidation Impact

  • Reverification Needed: no
  • Existing Implementation Invalidated: no
  • Status Recommendation: keep-current
  • Follow-up Action: suggest-batch-reqs → draft-batch

CHG-20260502-01

  • Date: 2026-05-02
  • Author: repository-maintainers

Change Summary

  • REQ-008 최초 생성 (source Discovery: dcy-002 FR-5)

Intent

  • trex-basic Consumer-Driven Contract의 POST /v1/assets/{asset_id}/ledger/trades 요구사항을 REQ backlog로 정규화

Acceptance Criteria Delta

  • Added:
    • 전체 Acceptance Criteria 신규 작성

Impacted Area Delta

  • Docs:
    • docs/interface-contract.md (REQ-011에서 갱신 예정)
  • Modules:
    • app/api/v1_ledger.py 신규
    • app/domain/models.py LedgerTrade 추가
  • Tests:
    • tests/test_v1_ledger.py 신규

Delivery Trace Delta

  • Batches:
    • none
  • Releases:
    • none

Revalidation Impact

  • Reverification Needed: no
  • Existing Implementation Invalidated: no
  • Status Recommendation: keep-current
  • Follow-up Action: confirm-req 후 batch 배정. REQ-009(ledger_trades 테이블 + unique constraint)와 함께 delivery 단위 구성 필수.
Reference in New Issue View Git Blame Copy Permalink