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