mirror of
https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer.git
synced 2026-10-09 20:37:37 +02:00
david-spacil
4c2558399e
Úkol 4.3 (ruční běh po merge do main) splněn: běh 37059874538 skončil podle návrhu červeně kvůli rozbitému oai_dc na api.aiscr.cz/2.2/oai a založil issue #89. Změna přesunuta do archivu (--skip-specs). Připraveno s pomocí AI (Claude).
79 lines
3.6 KiB
Markdown
79 lines
3.6 KiB
Markdown
# Proposal
|
||
|
||
## Why
|
||
|
||
Digiarchiv changes its API without notice to clients. Issue #67 showed the
|
||
cost: digiarchiv v4.1.0 (Solr 10) changed the facet item shape from
|
||
`{"name": …}` to `[value, count]`, the plugin swallowed the resulting
|
||
exception and the person codelists (`vedouci`, `nalezce`) came out empty –
|
||
found by hand, after users were already affected. Today nothing in the
|
||
repository talks to the live API: `tests/smoke_test.py` is deliberately
|
||
offline and CI runs only on pull requests and pushes, so an API change is
|
||
noticed only when a user hits it.
|
||
|
||
## What Changes
|
||
|
||
- New scheduled GitHub Actions workflow `.github/workflows/api_monitor.yml`
|
||
that runs once a day (and on manual dispatch) against the production
|
||
digiarchiv and `api.aiscr.cz` OAI, without credentials.
|
||
- New **contract test** `tests/api_contract.py` (plain `requests`, no QGIS):
|
||
sends the same requests the plugin sends and checks the shape of every
|
||
response the plugin reads – endpoints, keys, value types, facet item
|
||
shape, OAI sets, pagination, bbox restriction, PIAN geometry, filters,
|
||
login error path. Says *what* changed in the API.
|
||
- New **live plugin test** `tests/api_plugin_live.py`, run in
|
||
`qgis/qgis:ltr`: calls the plugin's own functions (`fetch_set` for every
|
||
codelist set, `load_translations`, `load_amcr_data` per data type) against
|
||
the live API and checks that they produce non-empty, well-formed results.
|
||
Says *whether* the change breaks users.
|
||
- Every run records the deployed digiarchiv version (git-describe string
|
||
from the web bundle) in its summary.
|
||
- Outages (timeouts, HTTP 5xx, connection errors after retries) are
|
||
reported as *unavailable*, separately from contract breaks, and do not
|
||
open an issue.
|
||
- A failing or drifting run opens **one** tracking issue (label
|
||
`api-monitor`) or updates the open one; the next clean run closes it.
|
||
- `AGENTS.md` documents the monitor (what it runs, how to run it locally,
|
||
how to read the issue).
|
||
|
||
What changes for a plugin user: nothing directly – no file under
|
||
`amcr_viewer/` changes and the plugin version is not bumped. Indirectly,
|
||
API breaks like #67 are found within a day of a digiarchiv release instead
|
||
of by users.
|
||
|
||
Out of scope:
|
||
|
||
- Logged-in checks (variant D): no account secret is stored in the repo;
|
||
anonymous runs cover only `pristupnost=A` records.
|
||
- Testing version branches on schedule: GitHub runs `schedule` only on the
|
||
default branch; other refs can be run by manual dispatch.
|
||
- Availability monitoring of digiarchiv as a service.
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `api-monitoring`: periodic verification that the digiarchiv / AMČR OAI
|
||
API still satisfies the contract the plugin depends on, and reporting of
|
||
breaks through a tracking issue.
|
||
|
||
### Modified Capabilities
|
||
|
||
<!-- none – openspec/specs/ is not maintained (change-tracked) -->
|
||
|
||
## Impact
|
||
|
||
- New files: `.github/workflows/api_monitor.yml`, `tests/api_contract.py`,
|
||
`tests/api_plugin_live.py`; edited `AGENTS.md`.
|
||
- Affected plugin modules (read, not changed): `amcr_viewer/amcr_tools.py`
|
||
(`load_translations`, `load_amcr_data`, `login_to_api`),
|
||
`amcr_viewer/amcr_codelists.py` (`slovnicek`, `fetch_set`).
|
||
- API: one run ≈ a few dozen anonymous requests to
|
||
`digiarchiv.aiscr.cz/api/*` and `api.aiscr.cz/2.2/oai`, restricted to a
|
||
small bbox – negligible load for digiarchiv.
|
||
- GitHub: scheduled workflow minutes (two short jobs per day), the
|
||
`api-monitor` label, `issues: write` permission for the reporting job
|
||
only. Depends on the digiarchiv repository
|
||
(`ARUP-CAS/aiscr-digiarchiv-2`) only as the source of the API under test.
|
||
- PR targets `main` (repository tooling, no plugin behaviour change).
|