[AZ-485] [AZ-486] Cycle 1 docs refresh (Step 13)
ci/woodpecker/push/build-arm Pipeline was successful

Phase B cycle 1 was a structural refactor only: F4 (barrel imports +
STC-ARCH-01) and F7 (endpoint builders + STC-ARCH-02). This commit
brings docs in line with source after the cycle, no code changes.

Module docs (12 consumers): swap every /api/<service>/... literal in
code snippets and integration tables for the matching endpoints.*
builder; note the barrel import migration in Dependencies.

New module doc: src__api__endpoints.md (public surface, F4 barrel
re-export note, STC-ARCH-02 enforcement, contract-test reference).

Architecture compliance baseline: mark F4 + F7 CLOSED with commit
hashes (23746ec, 8a461a2).

01_api-transport component description: add endpoints.ts + barrel to
Internal Interfaces, close the F7 caveat, extend Module Inventory.

ripple_log_cycle1.md: Task Step 0.5 reverse-dep analysis records the
import-graph closure (no extra docs needed beyond the direct set).

Carry-over reports landed alongside the docs:
- test_run_report_phase_b_cycle1.md (Step 11 outcome)
- implementation_report_refactor_phase_b_cycle1.md (cycle summary)

State file: trimmed to the autodev <30-line target; Steps 14 + 15
recorded as SKIPPED with rationale (no security or perf surface
changed in this cycle); pointer moved to Step 16 (Deploy).

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-12 00:01:04 +03:00
parent 8a461a2051
commit 17d5bb45e7
17 changed files with 456 additions and 172 deletions
@@ -29,18 +29,20 @@ No props.
- **State**:
- `system: SystemSettings | null` — loaded from
`GET /api/annotations/settings/system`. `null` until the GET
resolves; the panel does not render until then (`{system && (...)}`).
`GET endpoints.annotations.settingsSystem()` (= `/api/annotations/settings/system`).
`null` until the GET resolves; the panel does not render until
then (`{system && (...)}`).
- `dirs: DirectorySettings | null` — analogous, from
`GET /api/annotations/settings/directories`.
- `aircrafts: Aircraft[]` — from `GET /api/flights/aircrafts`.
`GET endpoints.annotations.settingsDirectories()` (= `/api/annotations/settings/directories`).
- `aircrafts: Aircraft[]` — from `GET endpoints.flights.aircrafts()`
(= `/api/flights/aircrafts`).
- `saving: boolean` — disables the two Save buttons during a PUT.
- **Bootstrap effect** (`useEffect([])`):
```ts
api.get<SystemSettings>('/api/annotations/settings/system').then(setSystem).catch(() => {})
api.get<DirectorySettings>('/api/annotations/settings/directories').then(setDirs).catch(() => {})
api.get<Aircraft[]>('/api/flights/aircrafts').then(setAircrafts).catch(() => {})
api.get<SystemSettings>(endpoints.annotations.settingsSystem()).then(setSystem).catch(() => {})
api.get<DirectorySettings>(endpoints.annotations.settingsDirectories()).then(setDirs).catch(() => {})
api.get<Aircraft[]>(endpoints.flights.aircrafts()).then(setAircrafts).catch(() => {})
```
Three independent calls, all silently swallowed on error. Empty UI
@@ -48,7 +50,7 @@ No props.
- **`saveSystem()`**:
1. Guard: `if (!system) return`.
2. `setSaving(true)`.
3. `await api.put('/api/annotations/settings/system', system)`.
3. `await api.put(endpoints.annotations.settingsSystem(), system)`.
4. `setSaving(false)`.
No optimistic update needed (the PUT body **is** the local state).
@@ -56,10 +58,10 @@ No props.
path is missing**: a thrown PUT leaves `saving: true` permanently
(no `try/finally`). Flag for Step 4.
- **`saveDirs()`** — analogous against
`PUT /api/annotations/settings/directories`. Same missing
`PUT endpoints.annotations.settingsDirectories()`. Same missing
`try/finally` issue.
- **`handleToggleDefault(a)`** — duplicate of the same handler in
`AdminPage`: `PATCH /api/flights/aircrafts/${a.id}` with
`AdminPage`: `PATCH endpoints.flights.aircraft(a.id)` with
`{ isDefault: !a.isDefault }` then optimistic local flip. Two copies
of the same logic in two pages — extract to a shared helper or to
`FlightContext` in Step 8 (the legacy WPF had a single
@@ -79,7 +81,7 @@ No props.
## Dependencies
- **Internal**:
- `../../api/client` — `api`.
- `../../api` (barrel) — `api`, `endpoints`. (Since AZ-485 / F4 + AZ-486 / F7.)
- `../../types` — `SystemSettings`, `DirectorySettings`, `Aircraft`.
- **External**: `react` (`useState`, `useEffect`),
`react-i18next` (`useTranslation`).
@@ -117,16 +119,16 @@ No props.
## External integrations
| Method | Path | Purpose |
| Method | Builder → Path | Purpose |
|---|---|---|
| `GET` | `/api/annotations/settings/system` | Load tenant config |
| `PUT` | `/api/annotations/settings/system` | Save tenant config |
| `GET` | `/api/annotations/settings/directories` | Load directory paths |
| `PUT` | `/api/annotations/settings/directories` | Save directory paths |
| `GET` | `/api/flights/aircrafts` | Load aircraft list |
| `PATCH` | `/api/flights/aircrafts/{id}` | Toggle `isDefault` |
| `GET` | `endpoints.annotations.settingsSystem()` → `/api/annotations/settings/system` | Load tenant config |
| `PUT` | `endpoints.annotations.settingsSystem()` → `/api/annotations/settings/system` | Save tenant config |
| `GET` | `endpoints.annotations.settingsDirectories()` → `/api/annotations/settings/directories` | Load directory paths |
| `PUT` | `endpoints.annotations.settingsDirectories()` → `/api/annotations/settings/directories` | Save directory paths |
| `GET` | `endpoints.flights.aircrafts()` → `/api/flights/aircrafts` | Load aircraft list |
| `PATCH` | `endpoints.flights.aircraft(id)` → `/api/flights/aircrafts/{id}` | Toggle `isDefault` |
Routed by `nginx.conf` to `annotations/` and `flights/` backends.
Path builders live in `src/api/endpoints.ts` (since AZ-486 / F7). Routed by `nginx.conf` to `annotations/` and `flights/` backends.
## Security