100 lines
4.7 KiB
Markdown
100 lines
4.7 KiB
Markdown
 
|
## ADDED Requirements
|
||
|
|
|
||
|
|
### Requirement: Provider-agnostic data interface
|
||
|
|
|
||
|
|
The system SHALL define a `DataProvider` interface that all market-data access
|
||
|
|
goes through. Evaluation and UI code MUST depend only on this interface and its
|
||
|
|
normalized data models, never on a concrete provider SDK or response shape. The
|
||
|
|
active provider SHALL be selectable via configuration without code changes in
|
||
|
|
consumers.
|
||
|
|
|
||
|
|
#### Scenario: Default free provider is used when none configured
|
||
|
|
- **WHEN** the app starts with no market-data provider explicitly configured
|
||
|
|
- **THEN** a default free-tier provider implementation is selected
|
||
|
|
- **AND** all normalized data models are populated from that provider
|
||
|
|
|
||
|
|
#### Scenario: Provider can be swapped via configuration
|
||
|
|
- **WHEN** an operator sets the provider configuration to a different implementation
|
||
|
|
- **THEN** the system routes all data requests through the new provider
|
||
|
|
- **AND** no changes to evaluation or UI code are required
|
||
|
|
|
||
|
|
### Requirement: Ticker resolution for NYSE and Nasdaq
|
||
|
|
|
||
|
|
The system SHALL accept a ticker symbol, validate that it resolves to an
|
||
|
|
NYSE- or Nasdaq-listed equity, and return a normalized company profile
|
||
|
|
(name, exchange, sector/industry, currency, shares outstanding).
|
||
|
|
|
||
|
|
#### Scenario: Valid listed ticker resolves
|
||
|
|
- **WHEN** a user submits a ticker listed on NYSE or Nasdaq (e.g. `DE`)
|
||
|
|
- **THEN** the system returns a company profile with name, exchange, and sector
|
||
|
|
|
||
|
|
#### Scenario: Unknown or unlisted ticker is rejected
|
||
|
|
- **WHEN** a user submits a symbol that does not resolve to an NYSE/Nasdaq equity
|
||
|
|
- **THEN** the system returns a not-found result with a clear message
|
||
|
|
- **AND** no evaluation is attempted
|
||
|
|
|
||
|
|
### Requirement: Company fundamentals and financial statements
|
||
|
|
|
||
|
|
The system SHALL provide normalized fundamentals sufficient for valuation and
|
||
|
|
earnings analysis: TTM and per-fiscal-year revenue, operating profit, margins,
|
||
|
|
net income, diluted EPS, operating cash flow, free cash flow, dividend per share,
|
||
|
|
and total/net debt. Where the provider exposes it, per-segment revenue and
|
||
|
|
operating profit SHALL be included.
|
||
|
|
|
||
|
|
#### Scenario: Fundamentals returned for a resolved ticker
|
||
|
|
- **WHEN** fundamentals are requested for a resolved ticker
|
||
|
|
- **THEN** the system returns TTM and at least the last three fiscal years of the
|
||
|
|
listed metrics
|
||
|
|
- **AND** each metric carries the fiscal period it belongs to
|
||
|
|
|
||
|
|
#### Scenario: Missing metric is represented explicitly
|
||
|
|
- **WHEN** the provider does not supply a given metric
|
||
|
|
- **THEN** the normalized model marks that metric as unavailable rather than zero
|
||
|
|
|
||
|
|
### Requirement: Price history and computed technical indicators
|
||
|
|
|
||
|
|
The system SHALL provide daily OHLCV price history and compute technical context
|
||
|
|
used for timing: 20/50/200-day moving averages, recent swing highs and lows,
|
||
|
|
distance from 52-week high and low, average daily volume and today's volume as a
|
||
|
|
multiple of it, and realized volatility (e.g. 60-day annualized).
|
||
|
|
|
||
|
|
#### Scenario: Technical context computed from price history
|
||
|
|
- **WHEN** price history is requested for a resolved ticker
|
||
|
|
- **THEN** the system returns the moving averages, 52-week high/low, volume ratio,
|
||
|
|
and realized volatility computed from that history
|
||
|
|
|
||
|
|
#### Scenario: Insufficient history degrades gracefully
|
||
|
|
- **WHEN** fewer than 200 trading days of history are available
|
||
|
|
- **THEN** longer-window indicators (e.g. 200-day average) are marked unavailable
|
||
|
|
- **AND** shorter-window indicators are still returned
|
||
|
|
|
||
|
|
### Requirement: Analyst coverage and consensus estimates
|
||
|
|
|
||
|
|
The system SHALL provide, where available, analyst rating counts (bullish /
|
||
|
|
neutral / bearish), average and median price targets, target range, and forward
|
||
|
|
consensus estimates (next fiscal-year EPS and revenue).
|
||
|
|
|
||
|
|
#### Scenario: Analyst data returned when available
|
||
|
|
- **WHEN** analyst coverage exists for a ticker
|
||
|
|
- **THEN** the system returns rating counts, average/median/target range, and
|
||
|
|
forward EPS/revenue estimates
|
||
|
|
|
||
|
|
#### Scenario: No coverage is handled
|
||
|
|
- **WHEN** no analyst coverage exists for a ticker
|
||
|
|
- **THEN** the system returns an empty coverage result the evaluation can note
|
||
|
|
|
||
|
|
### Requirement: Rate limiting, caching, and data-freshness disclosure
|
||
|
|
|
||
|
|
The system SHALL respect provider rate limits, cache responses to reduce calls,
|
||
|
|
and expose each dataset's freshness (as-of timestamp and whether it is delayed
|
||
|
|
or real-time) so downstream output can disclose it.
|
||
|
|
|
||
|
|
#### Scenario: Rate-limit and transient errors are handled
|
||
|
|
- **WHEN** the provider returns a rate-limit or transient error
|
||
|
|
- **THEN** the system retries within limits and, if still failing, returns a typed
|
||
|
|
error rather than throwing an unhandled exception
|
||
|
|
|
||
|
|
#### Scenario: Data freshness is surfaced
|
||
|
|
- **WHEN** any dataset is returned
|
||
|
|
- **THEN** it includes an as-of timestamp and a delayed/real-time flag
|