dcalc/backend/README.md

dcalc backend

Run

uv sync
python main.py

Test

uv run pytest -v

Quality

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.