70 lines
3.2 KiB
Markdown
70 lines
3.2 KiB
Markdown
# 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.
|
||
Before all realtime regions are available, the response body has `code=202`
|
||
and `data=[]`; progress appears only in `message`. A successful response never
|
||
substitutes a partially populated region list for the complete dataset.
|
||
- Realtime selects rows 4–10 (slice `[3:10]`), converts each original unit price
|
||
with `1 / Price`, then averages those ratios in 万金币/元. Rounding to 2 decimals
|
||
happens only after averaging; prices are not rounded before conversion. A new
|
||
Redis namespace excludes the earlier 元/万金币 cache, whose rounded prices
|
||
cannot recover the original ratios. No new 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.
|