301 lines
14 KiB
Markdown
301 lines
14 KiB
Markdown
# Portfolio Hub Interface Contract
|
|
|
|
- Baseline Mode: observed
|
|
- Baseline Seed: .stagepilot/bootstrap/baseline.yaml
|
|
- Status: confirmed
|
|
- Owner: repository-maintainers
|
|
- Last Updated (KST): 2026-05-13 00:00
|
|
- Source Discovery / Batch: bootstrap-baseline, bat-001, bat-006, bat-008, bat-010
|
|
- Primary Runtime: mixed
|
|
|
|
## Project Summary
|
|
- PortfolioHub exposes portfolio management and trading ledger workflows through a FastAPI service and a companion CLI.
|
|
|
|
## Primary Domain
|
|
- Portfolio management and trading ledger services.
|
|
|
|
## Purpose
|
|
- This document captures the approved external and cross-boundary interface contracts for the project.
|
|
- It is a cross-cutting reference for REQ drafting, batch design, implementation, verification, and handoff.
|
|
|
|
## Scope
|
|
- Covers externally visible APIs, CLI surfaces, events, files, or batch I/O contracts.
|
|
- Does not duplicate full business requirements already owned by REQ documents.
|
|
- Does not replace low-level code references or generated API artifacts.
|
|
|
|
## Interface Summary
|
|
|
|
- Primary HTTP API :: manage authentication, portfolios, strategy sets, and users over JSON HTTP endpoints
|
|
- PortfolioHub CLI :: provide command-line access to health checks, database setup, users, portfolios, strategies, and service tokens
|
|
|
|
## Interface: `Primary HTTP API`
|
|
|
|
- Type: http-api
|
|
- Consumers / Producers: authenticated clients, operators, and downstream services
|
|
- Purpose: manage authentication, portfolios, strategy sets, and users over JSON HTTP endpoints
|
|
- Stability: internal
|
|
|
|
### Inputs
|
|
|
|
- Authorization: Bearer <token> :: required for protected routes and mapped to read, trade-write, or admin permissions
|
|
- JSON request bodies :: carry login, token issuance, user CRUD, strategy-set CRUD, portfolio mutations, comments, and tags
|
|
- Route and query parameters :: select users, tokens, portfolios, filters, recent history windows, comments, and tags
|
|
|
|
### Outputs
|
|
|
|
- JSON response models :: responses are shaped by app/schemas/auth.py, app/schemas/user.py, and app/schemas/portfolio.py
|
|
- HTTP 201, 200, and 204 status codes :: create, read or update, and delete semantics respectively
|
|
- GET /health payload :: returns `{"status": "ok", "service": "portfolio-hub", "version": "<semver>", "checked_at": "<ISO8601 KST>"}` for readiness checks
|
|
|
|
### Error Contract
|
|
|
|
- 401 Unauthorized :: invalid credentials, invalid token, or missing token on protected routes
|
|
- 403 Forbidden :: insufficient permission or token issuance policy violation
|
|
- 404 Not Found :: missing user, token, portfolio, comment, tag, or strategy set
|
|
- 422 Unprocessable Entity :: FastAPI or Pydantic request validation failure
|
|
|
|
### Compatibility Rules
|
|
|
|
- Route prefixes /health, /auth, /users, /strategy-sets, and /portfolios define the current internal API surface.
|
|
- Permission semantics read, trade-write, and admin must stay aligned across auth guards and token metadata.
|
|
- Breaking route or schema changes require REQ and Batch documentation updates before release.
|
|
|
|
## Interface: `PortfolioHub CLI`
|
|
|
|
- Type: cli
|
|
- Consumers / Producers: operators and automation
|
|
- Purpose: provide command-line access to health checks, database setup, users, portfolios, strategies, and service tokens
|
|
- Stability: internal
|
|
|
|
### Inputs
|
|
|
|
- pfhub subcommands :: include user, portfolio, strategy, service-token, daemon, credential, health-check, init-db, and migrate-db command families
|
|
- Flags and options :: include --format table|json, --force confirmations, and operation-specific mutation arguments
|
|
- Environment configuration :: app/core/config.py resolves PORTFOLIOHUB_* and TIMESCALEDB_* values before command execution
|
|
- Portfolio identification (bat-006) :: all portfolio mutation commands accept `<name>` (positional) + `--user <username>` instead of raw portfolio_id; `comment` and `tag` sub-commands still accept portfolio_id (UUID) directly
|
|
|
|
### Outputs
|
|
|
|
- Table or JSON console rendering :: read flows emit structured operator output suitable for manual review or automation
|
|
- One-time token reveal :: issued client or service tokens are shown once and then only masked metadata remains
|
|
- Process exit status :: command success or failure is communicated through standard CLI exit behavior
|
|
|
|
### Error Contract
|
|
|
|
- Typer validation errors :: invalid arguments or missing required options stop the command before execution
|
|
- Confirmation refusal :: write commands abort unless the operator confirms or passes --force
|
|
- Persistence and auth failures :: disabled DB mode, connectivity issues, or permission problems surface as command errors
|
|
|
|
### Compatibility Rules
|
|
|
|
- Command names and primary flags should remain stable for internal automation.
|
|
- Write commands require explicit confirmation unless --force is present.
|
|
- JSON output should remain machine-readable across additive command evolution.
|
|
|
|
## Interface: `v1 Consumer API (trex-basic)`
|
|
|
|
- Type: http-api
|
|
- Consumers / Producers: trex-basic service (Consumer-Driven Contract, dcy-002, dcy-006)
|
|
- Purpose: provide daemon-scoped asset listing, user info with daemon_id diagnostic, and daemon-assignment-authorized trade ledger recording
|
|
- Stability: internal (versioned under /v1)
|
|
|
|
### Authentication
|
|
|
|
- All /v1 endpoints require `Authorization: Bearer <token>` header.
|
|
- Token must be DB-issued (`token_source="db"`); env tokens are rejected with HTTP 403.
|
|
- Admin catalog endpoints (`POST /v1/assets`, `PATCH /v1/assets/{id}`, `PATCH /v1/assets/{id}/deactivate`) require admin permission.
|
|
- POST /v1/assets/{asset_id}/ledger/trades additionally requires `trade-write` permission.
|
|
|
|
### Token Type Branching
|
|
|
|
- `token_type="service"`: daemon-scoped endpoints. `daemon_id` must be non-NULL (NULL → HTTP 403 fail-closed).
|
|
- `token_type="user"`: user-scoped. Endpoints return owner's own data.
|
|
- `token_type="admin"`: admin-scoped. May query other users' data via `?user_id=<id>` param.
|
|
|
|
### Daemon Authorization Model
|
|
|
|
- Service tokens are bound to a daemon at issuance via `daemon_id` field. Legacy/unbound tokens have `daemon_id=NULL`.
|
|
- GET /v1/assets (service token) and POST /v1/assets/{asset_id}/ledger/trades are daemon-scoped. NULL token `daemon_id` → HTTP 403 (fail-closed).
|
|
- GET /v1/user_info is available to any service token; returns `daemon_id: null` as diagnostic for unbound tokens.
|
|
- Each asset (portfolio) may be assigned to exactly one daemon via `portfolios.managed_by_daemon_id`. Mismatch or unassigned asset → HTTP 403 on ledger writes.
|
|
|
|
### Endpoint: `GET /v1/assets`
|
|
|
|
- Auth: DB token required; behavior branches by `token_type`
|
|
- `service`: returns portfolios where `managed_by_daemon_id = token.daemon_id`; NULL daemon_id → 403
|
|
- `user`: returns caller's own portfolios (`owner_user_id = token.user_id`)
|
|
- `admin`: returns caller's own portfolios; `?user_id=<id>` overrides to specified user
|
|
- Query Params: `?status=<value>` (optional portfolio status filter), `?market=<code>` (optional market code filter), `?user_id=<id>` (admin only)
|
|
- Response: HTTP 200
|
|
|
|
```
|
|
{
|
|
"total": <int>,
|
|
"assets": [
|
|
{
|
|
"asset_id": "<UUID>", // portfolio.portfolio_id
|
|
"symbol": "<str>",
|
|
"status": "<str>",
|
|
"cash": <float>,
|
|
"quantity": <float>,
|
|
"broker_type": "<str>",
|
|
"strategy_id": "<str|null>",
|
|
"strategy_type": "<str|null>",
|
|
"strategy_params": {<dict>},
|
|
"updated_at": "<ISO8601|null>",
|
|
"name": "<str|null>",
|
|
"price": <float|null>,
|
|
"profit_buffer": <float|null>,
|
|
"tags": [<str>]|null,
|
|
"owner_user_id": "<str|null>",
|
|
"created_at": "<ISO8601|null>",
|
|
"last_trade_at": "<ISO8601|null>"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
- Error: HTTP 401 if no token; HTTP 403 if env token or (service token with daemon_id NULL)
|
|
|
|
### Endpoint: `POST /v1/assets` (Admin Catalog)
|
|
|
|
- Auth: admin token required
|
|
- Body: `{"symbol": "<str>", "markets": [<str>], "display_name": "<str|null>", "status": "active"}`
|
|
- Response: HTTP 201 `AssetCatalogResponse`
|
|
|
|
```
|
|
{
|
|
"asset_id": "<UUID>",
|
|
"symbol": "<str>",
|
|
"markets": [<str>],
|
|
"display_name": "<str|null>",
|
|
"status": "<str>",
|
|
"created_at": "<ISO8601|null>",
|
|
"updated_at": "<ISO8601|null>"
|
|
}
|
|
```
|
|
|
|
- Error: HTTP 403 if not admin
|
|
|
|
### Endpoint: `PATCH /v1/assets/{asset_id}` (Admin Catalog Update)
|
|
|
|
- Auth: admin token required
|
|
- Body: `{"markets": [<str>]|null, "display_name": "<str|null>", "status": "<str|null>"}`
|
|
- Response: HTTP 200 `AssetCatalogResponse`
|
|
- Error: HTTP 403 if not admin
|
|
|
|
### Endpoint: `PATCH /v1/assets/{asset_id}/deactivate` (Admin Catalog Deactivate)
|
|
|
|
- Auth: admin token required
|
|
- Body: none
|
|
- Response: HTTP 200 `AssetCatalogResponse` with `status="inactive"`
|
|
- Error: HTTP 403 if not admin
|
|
|
|
### Endpoint: `GET /v1/user_info`
|
|
|
|
- Auth: service-token bearer (read); available to all service tokens including unbound (daemon_id=NULL)
|
|
- Response: HTTP 200
|
|
|
|
```
|
|
{
|
|
"runtime_id": "<str|null>", // null for tokens without runtime_id (diagnostic)
|
|
"daemon_id": "<str|null>", // null for unbound/legacy tokens (diagnostic)
|
|
"trading_enabled": <bool>, // mapped from users.is_active
|
|
"disabled_reason": "<str|null>", // "account_inactive" when trading_enabled=false
|
|
"brokers": [
|
|
{
|
|
"broker": "<str>",
|
|
"account_ref": "<str>",
|
|
"credential_payload": {<dict>}|null, // Fernet-decrypted {app_key, app_secret}
|
|
"credential_version": <int>,
|
|
"last_rotated_at": "<ISO8601|null>"
|
|
}
|
|
],
|
|
"user_id": "<str>",
|
|
"username": "<str>",
|
|
"email": "<str|null>",
|
|
"permission": "<str>"
|
|
}
|
|
```
|
|
|
|
- Error: HTTP 401 if no token; HTTP 403 if not a service token
|
|
|
|
### Endpoint: `POST /v1/assets/{asset_id}/ledger/trades`
|
|
|
|
- Auth: service-token bearer (trade-write); token must have `daemon_id` bound; asset must be assigned to that daemon
|
|
- Path Param: `asset_id` — must be a valid UUID portfolio_id
|
|
- Authorization: `portfolios.managed_by_daemon_id` must equal `token.daemon_id`; NULL token → 403; unassigned asset → 403; mismatch → 403
|
|
- Request Body:
|
|
|
|
```
|
|
{
|
|
"order_id": "<str>", // required, min_length=1
|
|
"execution_id": "<str>", // required, min_length=1
|
|
"side": "buy"|"sell",
|
|
"quantity": <decimal>, // > 0
|
|
"price": <decimal>, // > 0
|
|
"fee_amount": <decimal>, // >= 0, default 0
|
|
"tax_amount": <decimal>, // >= 0, default 0
|
|
"executed_at": "<ISO8601>"
|
|
}
|
|
```
|
|
|
|
- Response HTTP 201 (new record):
|
|
|
|
```
|
|
{
|
|
"ledger_entry_id": <int>,
|
|
"asset_id": "<str>",
|
|
"order_id": "<str>",
|
|
"execution_id": "<str>",
|
|
"side": "<str>",
|
|
"quantity": <float>,
|
|
"price": <float>,
|
|
"fee_amount": <float>,
|
|
"tax_amount": <float>,
|
|
"executed_at": "<ISO8601>",
|
|
"recorded_at": "<ISO8601|null>",
|
|
"status": "new"
|
|
}
|
|
```
|
|
|
|
- Response HTTP 200 (idempotent duplicate with identical payload): same body with `"status": "duplicate"`
|
|
- Error: HTTP 401 if no token; HTTP 403 if not service token, daemon_id NULL, asset unassigned, or daemon mismatch; HTTP 404 if asset_id not found; HTTP 409 if duplicate key with different payload
|
|
|
|
### Idempotency Contract
|
|
|
|
- Deduplication key: `(asset_id, order_id, execution_id)` — enforced by `uq_ledger_trades_idempotency` DB unique constraint
|
|
- Identical payload re-send → HTTP 200 + `status="duplicate"`, no new row created
|
|
- Same key, different payload → HTTP 409 Conflict
|
|
|
|
### Deployment Constraint (bat-006)
|
|
|
|
- trex-basic and portfolio-hub must be deployed simultaneously when BAT-006 is released.
|
|
- After BAT-006, all `asset_id` values in GET /v1/assets responses change from TEXT to UUID format.
|
|
- trex-basic consumers must handle UUID-format asset_id before the coordinated deployment is completed.
|
|
|
|
## Shared Constraints
|
|
|
|
- Token permission levels gate both HTTP and CLI mutations consistently.
|
|
- DB-backed endpoints and commands require PORTFOLIOHUB_DB_ENABLED=true plus valid TimescaleDB settings.
|
|
- Secret and token values are only revealed once at issuance time and are masked afterwards.
|
|
|
|
## Current Gaps / Planned Changes
|
|
|
|
- External consumer versioning policy is still implicit and not published as a separate contract artifact.
|
|
- Service-token lifecycle and ownership rules may continue to evolve as authorization requirements mature.
|
|
- OpenAPI publication and CLI reference generation are not yet automated.
|
|
|
|
## Update Triggers
|
|
|
|
- Update this document when an externally visible API, event, CLI, or file contract changes.
|
|
- Update this document when a batch changes compatibility, validation, or error behavior.
|
|
- Update this document when a new external consumer or producer is introduced.
|
|
|
|
## Change Log
|
|
|
|
- 2026-05-19 KST: bat-002 — REQ-010/012/013/015: added admin catalog endpoints (POST/PATCH /v1/assets, PATCH /v1/assets/{id}/deactivate); rewrote GET /v1/assets authentication to support service/user/admin token branching; added market filter param; removed market field from AssetItem; added AssetCatalogResponse schema.
|
|
- 2026-05-13 KST: bat-010 — REQ-006/007/008/011/023: added daemon authorization model section; updated GET /v1/assets (daemon-scoped filter, NULL 403); updated GET /v1/user_info (daemon_id field, NULL runtime_id → 200+null diagnostic); updated POST /v1/assets/{asset_id}/ledger/trades (daemon assignment authorization, fail-closed policy); added daemon CLI subcommand to CLI surface; updated v1 purpose and source discovery.
|
|
- 2026-05-11 KST: bat-008 — REQ-011 AC-1: expanded v1 Consumer API section with authentication contract, detailed request/response schemas for GET /v1/assets, GET /v1/user_info, POST /v1/assets/{asset_id}/ledger/trades; updated GET /health response schema (REQ-004); added idempotency contract.
|
|
- 2026-05-11 KST: bat-006 — Added v1 consumer API interface section (trex-basic); noted asset_id UUID change and simultaneous deployment constraint; updated CLI portfolio inputs to reflect name+user identification.
|
|
- 2026-04-30 KST: Bootstrap baseline created from repository observation for initial StagePilot adoption. |