# dcalc backend

## Run

```bash
uv sync
python main.py
```

## Test

```bash
uv run pytest -v
```

## Quality

```bash
uv run ruff check .
```

## Runtime Entry

- `main.py`: FastAPI application and uvicorn entry.
- `api/routes/calc.py`: `/api/calc` HTTP route.
- `services/calc_service.py`: calculation orchestration.
- `core/basic/character/`: character calculation implementation.
- `core/basic/equipment.py`: equipment data models and compatibility access.
- `core/basic/equipment_registry.py`: equipment version registry and cache.
- `database/connect.py`: SQLite and Redis connections.

## Gold Cache and Notifications

- Application startup checks both realtime and official gold caches, then checks
  them every minute. Data older than 30 minutes refreshes without HTTP traffic.
  Redis locks prevent duplicate work across workers. Realtime region pages stay
  8 seconds apart. Failures retain the last successful data for up to 24 hours.
- Official authentication uses `HELPER_TOKEN` and `HELPER_ID`. Authentication
  failures (`returnCode=-30003`, explicit token-expiry messages or HTTP 401) can
  notify via Bark. Network errors do not trigger token-expiry notifications.
- Set optional `BARK_URL` in `config/.env`, `.env.dev`, `.env.prod` or the process
  environment to your full Bark push URL, including its device key. There is no
  default destination; unset/blank means no Bark request. Restart after changing
  credentials. A successful alert is deduplicated per token for 24 hours; a new
  token permits a new alert. Failed pushes remain retryable. No credentials are
  included in notification text or logged push errors.
- Official gold responses also contain `max` and `min`: the largest/smallest
  values of `10000 / price` across both rank arrays, in 万金币 per 100点券,
  rounded to 4 decimals. Nonpositive/invalid prices are excluded; absent valid
  quotes yield `null`. Existing rank arrays retain their 点券 per 100万金币 unit.

## Compatibility Rules

- Do not change `/calc` request and response contract without frontend migration approval.
- Do not change frontendNew result data shape during backend refactors.
- Keep Skill and Forge business formulas behavior-compatible unless a dedicated formula task says otherwise.