chore: initialize StagePilot baseline documentation and discovery/SRS/batches/releases structure

2026-04-30 13:19:48 +00:00
parent 7e9fbc1418
commit e362de205f
10 changed files with 723 additions and 0 deletions
@@ -0,0 +1,114 @@
+# Portfolio Hub Interface Contract
+
+- Baseline Mode: observed
+- Baseline Seed: .stagepilot/bootstrap/baseline.yaml
+- Status: confirmed
+- Owner: repository-maintainers
+- Last Updated (KST): 2026-04-30 22:13
+- Source Discovery / Batch: bootstrap-baseline
+- 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"} 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, 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
+
+### 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.
+
+## 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-04-30 KST: Bootstrap baseline created from repository observation for initial StagePilot adoption.