chore: add docs sync guardrails and spec documents

2026-04-03 07:53:20 +00:00
parent 3e3acbd13d
commit 3eae90a9ab
8 changed files with 1063 additions and 0 deletions
@@ -0,0 +1,380 @@
+# PortfolioHub Specification
+
+## 1. Overview
+
+PortfolioHub is a FastAPI-based portfolio lifecycle service with a Typer CLI.
+
+- Runtime: Python 3.11+
+- API framework: FastAPI
+- CLI framework: Typer
+- DB driver: Psycopg v3
+- Migration: Alembic
+
+Primary goals:
+
+- Manage portfolio lifecycle (create/update/delete/reset)
+- Record trade and balance-affecting actions (buy/sell/invest/transfer)
+- Expose status and ledger snapshots through API and CLI
+- Keep API and CLI behavior aligned through a shared service/repository layer
+
+## 2. Scope and Non-Goals
+
+In scope:
+
+- Authenticated portfolio read and write operations
+- Role-based access control (read, trade-write, admin)
+- Optional PostgreSQL/Timescale-backed repository via feature flag
+- Operational commands for DB bootstrap and migration
+
+Current non-goals / limitations:
+
+- In-memory fallback repository is not implemented for production usage
+- External broker execution is not handled here (service focuses on portfolio state)
+- Advanced observability wiring for Redis/Loki is not yet implemented in runtime paths
+
+## 3. Architecture
+
+Layered components:
+
+- API layer: HTTP routes and request validation
+- CLI layer: command parsing and output rendering
+- Service layer: orchestration and response shaping
+- Domain layer: business logic rules
+- Repository layer: persistence abstraction and concrete Postgres implementation
+
+Key design principle:
+
+- API and CLI call the same `PortfolioService`, so behavior is consistent regardless of entrypoint.
+
+## 4. Entrypoints
+
+HTTP service:
+
+- App factory: `app.main:create_app`
+- ASGI app: `app.main:app`
+- OpenAPI docs: `/docs`
+- ReDoc: `/redoc`
+
+CLI:
+
+- Console script: `portfoliohub`
+- Entry function: `app.cli.main:main`
+
+## 5. Configuration Specification
+
+Configuration precedence (high to low):
+
+1. Environment variables
+2. `.env` file (loaded at startup if present)
+3. Code defaults
+
+Core settings:
+
+- `PORTFOLIOHUB_ALLOWED_ORIGINS`: comma-separated CORS origins
+- `PORTFOLIOHUB_READ_TOKENS`: comma-separated read tokens
+- `PORTFOLIOHUB_TRADE_WRITE_TOKENS`: comma-separated write tokens
+- `PORTFOLIOHUB_ADMIN_TOKENS`: comma-separated admin tokens
+- `PORTFOLIOHUB_DB_ENABLED`: enables DB repository selection when `true`
+
+Database settings (active source):
+
+- `TIMESCALEDB_HOST`
+- `TIMESCALEDB_PORT`
+- `TIMESCALEDB_NAME`
+- `TIMESCALEDB_USER`
+- `TIMESCALEDB_PASSWORD`
+- `TIMESCALEDB_SSLMODE`
+- `TIMESCALEDB_CONNECT_TIMEOUT_SEC`
+- `TIMESCALEDB_APPLICATION_NAME`
+
+Derived setting:
+
+- `active_database_url` uses PostgreSQL psycopg URL format with encoded credentials and query options.
+
+## 6. Authentication and Authorization
+
+Auth scheme:
+
+- `Authorization: Bearer <token>` required for protected API routes
+
+Permission levels:
+
+- `read`
+- `trade-write`
+- `admin`
+
+Authorization hierarchy:
+
+- `admin` can access all endpoints
+- `trade-write` can access `trade-write` + `read`
+- `read` can access only read endpoints
+
+Failure responses:
+
+- Missing/invalid bearer header: `401`
+- Unknown token: `401`
+- Insufficient permission: `403`
+
+## 7. HTTP API Specification
+
+Base routes:
+
+- Health: `/health`
+- Portfolio: `/portfolios`
+
+### 7.1 Health Endpoint
+
+- `GET /health`
+- Auth: none
+- Response `200`:
+
+```json
+{"status": "ok"}
+```
+
+### 7.2 Portfolio Endpoints
+
+#### List Portfolios
+
+- `GET /portfolios`
+- Auth: `read`
+- Query params:
+  - `broker` (optional string)
+  - `status_filter` (optional string)
+- Response `200`: array of `PortfolioListItem`
+
+#### Get Portfolio Status
+
+- `GET /portfolios/{portfolio_id}`
+- Auth: `read`
+- Query params:
+  - `recent_trades` (int, default `5`)
+- Response `200`: `PortfolioDetailResponse`
+
+#### Create Portfolio
+
+- `POST /portfolios`
+- Auth: `trade-write`
+- Body: `CreatePortfolioRequest`
+- Response `201`: `PortfolioDetailResponse`
+
+#### Update Portfolio
+
+- `PATCH /portfolios/{portfolio_id}`
+- Auth: `trade-write`
+- Body: `UpdatePortfolioRequest`
+- Response `200`: `PortfolioDetailResponse`
+
+#### Buy
+
+- `POST /portfolios/{portfolio_id}/buy`
+- Auth: `trade-write`
+- Body: `BuyRequest`
+- Response `200`: `PortfolioDetailResponse`
+
+#### Sell
+
+- `POST /portfolios/{portfolio_id}/sell`
+- Auth: `trade-write`
+- Body: `SellRequest`
+- Response `200`: `PortfolioDetailResponse`
+
+#### Invest
+
+- `POST /portfolios/{portfolio_id}/invest`
+- Auth: `trade-write`
+- Body: `InvestRequest`
+- Response `200`: `PortfolioDetailResponse`
+
+#### Transfer
+
+- `POST /portfolios/{portfolio_id}/transfer`
+- Auth: `trade-write`
+- Body: `TransferRequest`
+- Response `200`: `PortfolioDetailResponse`
+
+#### Reset
+
+- `POST /portfolios/{portfolio_id}/reset`
+- Auth: `trade-write`
+- Body: `ResetPortfolioRequest`
+- Response `200`: `PortfolioDetailResponse`
+
+#### Delete
+
+- `DELETE /portfolios/{portfolio_id}`
+- Auth: `admin`
+- Query params:
+  - `keep_ledger` (bool, default `false`)
+- Response `204`: no content
+
+### 7.3 Example Requests and Responses
+
+- See `docs/api-examples.md` for maintained request/response examples.
+
+## 8. Schema Specification
+
+### 8.1 Request Models
+
+`CreatePortfolioRequest`
+
+- `portfolio_id: str`
+- `broker: str = "kis"`
+- `status: str = "enabled"`
+- `symbol: str`
+- `strategy_name: str = "target_value"`
+- `strategy_params: object = {}`
+- `cash_balance: float >= 0`
+- `asset_quantity: float >= 0`
+- `asset_price: float >= 0`
+- `profit_buffer: float >= 0`
+
+`UpdatePortfolioRequest` (all fields optional)
+
+- `broker: str | null`
+- `status: str | null`
+- `symbol: str | null`
+- `strategy_name: str | null`
+- `strategy_params: object | null`
+- `asset_price: float >= 0 | null`
+
+`BuyRequest` / `SellRequest`
+
+- `quantity: float > 0`
+- `price: float > 0`
+- `fee: float >= 0`
+- `tax: float >= 0`
+- `note: str = ""`
+
+`InvestRequest`
+
+- `movement_type: "deposit" | "profit" | "withdraw"`
+- `amount: float > 0`
+- `note: str = ""`
+
+`TransferRequest`
+
+- `direction: "to-buffer" | "from-buffer"`
+- `amount: float > 0`
+- `note: str = ""`
+
+`ResetPortfolioRequest`
+
+- `infer_symbol: str | null`
+
+### 8.2 Response Models
+
+`PortfolioListItem`
+
+- Includes portfolio summary fields and computed `total_value`
+
+`PortfolioDetailResponse`
+
+- `portfolio: PortfolioSummary`
+- `recent_entries: LedgerEntryResponse[]`
+- `strategy_set: StrategySetResponse | null`
+- `live_quantity: float | null`
+
+`LedgerEntryResponse`
+
+- Snapshot-oriented ledger response including balances after each action
+
+`ErrorResponse`
+
+- `detail: str`
+
+## 9. CLI Specification
+
+Global option:
+
+- `--format [table|json]` (default: `table`)
+
+Commands:
+
+- `portfoliohub init-db [--maintenance-db postgres]`
+- `portfoliohub migrate-db`
+- `portfoliohub health-check`
+
+Portfolio subcommands:
+
+- `portfoliohub portfolio list [--broker ...] [--status ...]`
+- `portfoliohub portfolio status <portfolio_id> [--recent 5]`
+- `portfoliohub portfolio create <portfolio_id> --symbol ... [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]`
+
+Confirmation behavior:
+
+- Mutating portfolio commands request confirmation by default.
+- `--force` bypasses confirmation prompts.
+
+## 10. Persistence and Migration Specification
+
+Repository selection:
+
+- If `PORTFOLIOHUB_DB_ENABLED=false`: an unimplemented placeholder repository raises `FeatureNotReadyError` on access.
+- If `PORTFOLIOHUB_DB_ENABLED=true`: `PostgresPortfolioRepository` is used.
+
+Migration commands:
+
+- `init-db`: create target DB if missing, then apply Alembic `head`
+- `migrate-db`: apply Alembic `head` to existing target DB
+
+Migration source of truth:
+
+- `migrations/versions`
+
+DB schema specification:
+
+- Detailed table/column/index constraints are documented in `docs/db-schema-spec.md`.
+- The documentation is generated from and must stay consistent with Alembic revisions under `migrations/versions`.
+
+## 11. Error Handling
+
+Application-level errors are translated through registered exception handlers.
+
+Typical error classes include:
+
+- authorization failures (`401`, `403`)
+- domain/repository-level failures surfaced by service operations
+- feature-not-ready errors when DB mode is disabled but persistence is required
+
+## 12. CORS Policy
+
+CORS middleware is enabled with:
+
+- `allow_origins` from configured origins list
+- `allow_credentials = true`
+- `allow_methods = ["GET", "POST", "PATCH", "DELETE", "OPTIONS"]`
+- `allow_headers = ["Authorization", "Content-Type"]`
+
+## 13. Testing Specification
+
+Test framework:
+
+- `pytest`
+
+Configured behavior:
+
+- test paths: `tests`
+- recursion excluded: `temp`, `.git`, `.venv`
+
+Current test modules include API, auth, CLI, and domain service coverage.
+
+## 14. Versioning and Compatibility
+
+- Current package version: `0.1.0`
+- API version exposure follows application version setting (`app_version`)
+- Minimum Python version: `3.11`
+
+## 15. Future Extension Points
+
+- Redis-backed cache/session integration
+- Loki logging pipeline integration
+- Additional brokers and order-execution adapters
+- Enhanced operational/admin endpoints