54 lines
2.2 KiB
Markdown
54 lines
2.2 KiB
Markdown
# 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.
|