# Polaris Backend

FastAPI + SQLAlchemy 2.0 + Pydantic v2 + Celery/Redis backend for the Polaris
reseller platform. PostgreSQL schema is canonical in `/opt/polaris/db/schema.sql`
(not managed by this service).

## Run (CT host, no Docker)

```sh
cd /opt/polaris/backend
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
# .env at /opt/polaris/.env provides POSTGRES_PASSWORD (auto-loaded)
.venv/bin/python scripts/seed.py                      # sample supplier + 27 products
DATABASE_URL=postgresql+psycopg2://reseller:${POSTGRES_PASSWORD}@127.0.0.1:5432/reseller \
  .venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
```

## Run (Docker, via OPS compose)

The OPS agent adds `api` + `worker` services. Inside the Docker network:
- `DATABASE_URL=postgresql+psycopg2://reseller:${POSTGRES_PASSWORD}@postgres:5432/reseller`
- `REDIS_URL=redis://redis:6379/0`
- worker command: `scripts/celery_worker.sh` (worker + beat; beat schedule in `app/tasks.py`)

## Env vars

| var | purpose |
|---|---|
| `DATABASE_URL` | SQLAlchemy URL (default: local 127.0.0.1:5432 w/ `POSTGRES_PASSWORD`) |
| `REDIS_URL` | Celery broker (default `redis://redis:6379/0`) |
| `SECRET_KEY` | JWT signing key (dev default — set in prod) |
| `ADMIN_EMAIL` / `ADMIN_PASSWORD` | admin login (plain compare — TODO: hash `ADMIN_PASSWORD_HASH` with bcrypt/argon2) |

## API

All under `/api` (see CONTRACT.md for the full list). Interactive docs at `/docs`.

Key notes:
- Importer NEVER auto-publishes: new products enter as `status='imported'`;
  `POST /api/products/{id}/publish` requires a calculated `retail_price`.
- Pricing: active `price_rules` bands (cost → markup), floor at
  cost+shipping+fees, `min_price` respected; `estimate_net_profit` =
  retail − cost − shipping − fees.
- Orders: `POST /api/orders` routes each item to the highest-scoring eligible
  supplier (40% price / 20% inventory / 15% speed / 10% fulfillment / 10%
  returns / 5% history) and records profit.
- Analytics `conversion` is 0.0 until a traffic/visitor source exists.

## Seed

`scripts/seed.py` — idempotent. Creates the sample supplier, imports 27
products (home/gadgets/office, $50–$500 retail), prices via the pricing engine,
and publishes the valid ones.