genichin
e6b6a8715b
Core Implementation (BAT-010):
- Add daemon registry schema and CRUD operations (req-023)
- Implement single-daemon asset assignment constraint (one asset per daemon)
- Add daemon_id field to service_token for daemon identification
- Add daemon.py CLI module for daemon management commands
- Add 20260513_0016_daemon_model.py migration for daemon tables
API Changes:
- GET /v1/assets: include daemon_id in AssetResponse
- POST /v1/assets/{asset_id}/ledger/trades: require daemon token binding
- GET /v1/user_info: include daemon metadata
- Enhanced service-token rotate to preserve daemon bindings
CLI Commands:
- pfhub daemon register --name <name> --runtime-id <runtime-id>
- pfhub daemon list
- pfhub daemon get <daemon-id>
- pfhub daemon revoke <daemon-id>
Requirements (REQ-023, REQ-028):
- REQ-023: Daemon Registry and Service Token Daemon Binding (Interface, Approved)
* AC-1: daemon CRUD operations
* AC-2: service token daemon binding for POST /v1/assets/{asset_id}/ledger/trades
* AC-3: single daemon per asset (exact-one assignment model)
- REQ-028: README.md Daemon Provisioning Runbook update (Documentation, Approved)
Documentation:
- Add dcy-006 Discovery for daemon-id and single-daemon asset assignment
- Update README.md with Daemon Provisioning Runbook section
- Add BAT-010 batch documentation with planning, implementation, verification
- Update rel-006 release document (daemon model implementation)
- Update data-model.md with daemon and daemon_asset_assignment tables
- Update interface-contract.md with daemon registry APIs
- Update runtime-flows.md with daemon lifecycle flows
Breaking Changes:
- REQ-005~009, REQ-011~012 status reverted to Approved due to revised contract
* daemon_id field addition and exact-one asset assignment requirement
* Existing Implemented evidence invalidated by contract revision
* BAT-001/002/008 re-verification required
Testing:
- Add test_daemon_registry.py for daemon CRUD operations
- Add test_daemon_assignment.py for single-asset assignment constraints
- Update test_auth.py, test_cli.py, test_v1.py for daemon support
- Verify daemon token binding in trade endpoint authorization
Impact:
- Database: 2 new tables (daemons, daemon_asset_assignments)
- Migration: 20260513_0016 creates daemon model schema
- CLI: 4 new daemon subcommands
- API: daemon_id propagation through v1 endpoints
- Verification: BAT-001/002/008 re-verification gates next release
177 lines
7.8 KiB
Markdown
177 lines
7.8 KiB
Markdown
# req-008: POST /v1/assets/{asset_id}/ledger/trades 엔드포인트 구현
|
|
|
|
- Status: Approved
|
|
- 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가 오면 충돌로 처리하며, daemon assignment mismatch 또는 미배정 asset write는 저장 전에 거부한다.
|
|
|
|
## Requirement
|
|
- POST /v1/assets/{asset_id}/ledger/trades는 service-token bearer 인증으로, 인증된 token의 `daemon_id`에 배정된 asset에 대해서만 체결 내역(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로 보장하며, 애플리케이션 로직만으로 보장하지 않는다.
|
|
- daemon assignment mismatch, 미배정 asset, `daemon_id = NULL` legacy token은 모두 HTTP 403으로 fail-closed 처리해야 하며 ledger row가 생성되면 안 된다.
|
|
|
|
## Acceptance Criteria
|
|
1. Given 유효한 daemon-bound service-token과 해당 daemon에 배정된 asset의 신규 체결 데이터로 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이 반환되어야 한다.
|
|
6. Given asset이 다른 daemon에 배정되어 있는 경우, When 요청 daemon이 asset owner daemon과 다르면, Then HTTP 403이 반환되어야 하고 ledger row는 생성되지 않아야 한다.
|
|
7. Given asset이 아직 daemon에 배정되지 않았거나 토큰의 `daemon_id`가 NULL인 경우, Then HTTP 403이 반환되어야 하고 ledger row는 생성되지 않아야 한다.
|
|
|
|
## 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, app/services/, app/schemas/, app/repositories/portfolio_repository.py, app/repositories/postgres.py, app/main.py
|
|
- Tests: tests/test_v1.py 또는 신규 daemon assignment / ledger authorization 회귀 테스트
|
|
|
|
## 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 응답.
|
|
- daemon authorization은 기존 permission(`trade-write`) 위에 추가되는 두 번째 authorization 축이다.
|
|
- Source Discovery: dcy-002 (FR-5, NFR-2), dcy-006 (FR-2, FR-4, NFR-2)
|
|
|
|
## Change Log
|
|
|
|
### CHG-20260513-01
|
|
- Date: 2026-05-13
|
|
- Author: repository-maintainers
|
|
|
|
#### Change Summary
|
|
- ledger write REQ에 daemon assignment authorization과 403 fail-closed 규칙을 추가하고, 기존 Implemented 상태를 Approved로 되돌림
|
|
|
|
#### Intent
|
|
- dcy-006은 `trade-write` permission만으로는 충분하지 않고, asset이 인증 daemon에 배정됐는지까지 검증하도록 요구한다. 현재 구현은 asset 존재성만 확인하므로 revised authorization contract를 충족하지 못한다.
|
|
|
|
#### Acceptance Criteria Delta
|
|
- Added:
|
|
- AC-6: daemon mismatch 403
|
|
- AC-7: 미배정 asset 또는 daemon-less token 403
|
|
- Updated:
|
|
- AC-1: 성공 조건을 daemon-assigned asset으로 제한
|
|
- Removed:
|
|
- none
|
|
|
|
#### Impacted Area Delta
|
|
- Docs:
|
|
- `docs/interface-contract.md`, `docs/runtime-flows.md`, `docs/data-model.md`
|
|
- Modules:
|
|
- `app/api/v1_ledger.py`, `app/repositories/portfolio_repository.py`, `app/repositories/postgres.py`
|
|
- Tests:
|
|
- `tests/test_v1.py` 또는 신규 daemon assignment ledger authorization 테스트
|
|
|
|
#### Delivery Trace Delta
|
|
- Batches:
|
|
- BAT-001 (release-candidate; REL-001 released input) — ledger verification evidence는 404/409/idempotency 중심이라 daemon authz 케이스를 추가해 재검증해야 함
|
|
- Releases:
|
|
- REL-001 (released) — released trade-write contract는 daemon mismatch 403 정책을 포함하지 않음
|
|
|
|
#### Revalidation Impact
|
|
- Reverification Needed: yes
|
|
- Existing Implementation Invalidated: yes
|
|
- Status Recommendation: rollback-to-approved
|
|
- Follow-up Action: dcy-006 후속 batch에서 asset assignment lookup과 ledger authorization guard를 구현하고 duplicate/conflict 회귀와 함께 재검증한다.
|
|
|
|
#### Validation Plan
|
|
- `app/api/v1_ledger.py`가 현재 asset 존재성만 확인하는지 코드 리뷰로 확인한다.
|
|
- 구현 후 success/duplicate/conflict/404와 daemon mismatch·unassigned 403 시나리오를 함께 검증한다.
|
|
|
|
### 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 단위 구성 필수.
|