quant-trader-service/README.md

# quant-trader-service

Trader V4 P0 decision service.

## Scope

The service follows the V4 Trader documents under `/Users/zach/Desktop/app/trader`.
P0 only allows `REPLAY_SIM` and `SHADOW`; `PAPER`, `REAL`, real fills, and old
strategy-service contracts are rejected.

## Implemented Surface

- Spring Boot service under `com.quantai.trader`
- strict P0 runtime guard for run mode, execution mode, and trading switch
- JSON artifact loader for model bundle manifest, PM config manifest, and model output policy
- five-model output contract: Direction, Entry, Continue, Exit, Risk
- dynamic PM sizing with side-aware stop/target price calculation
- Risk Gate for hard blockers and forced close decisions
- JDBC persistence for run, cycle, model output, PM decision, risk decision, action, evidence, and outbox
- Flyway V1 schema for the V4 P0 tables
- health, replay-cycle, and feedback endpoints
- JaCoCo line coverage gate at 90%

## Local Database

Default configuration:

```text
jdbc:mysql://127.0.0.1:3306/quant_trader
username: quant_trader
password: quant_trader
```

Override with `TRADER_DB_URL`, `TRADER_DB_USERNAME`, and `TRADER_DB_PASSWORD`.

## Artifact Root

Default artifact root:

```text
/Users/zach/Desktop/quant-strategy-training-data/trader-v4/artifact_bundle
```

Required files:

```text
manifests/model_bundle_manifest.json
manifests/position_manager_manifest.json
model_output_policy.json
```

The loader requires the configured model/calibration/PM version triple to match
the manifests, all five model families to be present, and the model/PM manifests
to be `ACTIVE`.

## Commands

```bash
mvn clean test
TRADER_DB_USERNAME=quant_trader TRADER_DB_PASSWORD=quant_trader SERVER_PORT=18080 mvn spring-boot:run
```

## HTTP

```text
GET  /api/trader/health
POST /api/trader/replay/cycles
POST /api/trader/feedback
```

`/api/trader/feedback` is disabled by default in P0 and still rejects
`PAPER_APP`, `REAL_APP`, and any real fill when explicitly enabled for tests.