# 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 at wall-clock minute boundaries. Each half-hour batch starts 5 minutes
  early: 01:25 collects the 01:30 batch, 01:55 collects the 02:00 batch, without
  HTTP traffic. All regions in a refresh share the batch timestamp selected at
  the start, even if the work crosses a half-hour boundary. Existing public
  `updataTime` types remain number for realtime and string for official.
  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.
- Realtime uses the arithmetic mean of displayed unit prices from rows 4–10
  (`i.item1`, slice `[3:10]`), in 元/万金币, rounded to 2 decimals. This replaces
  the earlier 万金币/元 average and uses a new Redis namespace so old units are
  never returned as new prices. No BeautifulSoup or browser dependency is added.
- 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 2 decimals. Nonpositive/invalid prices are excluded; absent valid
  quotes yield `null`. Rank arrays retain their 点券 per 100万金币 unit and are
  also rounded to 2 decimals. JSON numbers do not force trailing zeroes.

## 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.