cleanup phases 0 done

2026-07-29 23:20:46 +03:30
parent c99e3f4a6e
commit d3ec723119
13 changed files with 24889 additions and 4 deletions
@@ -0,0 +1,34 @@
+# Integration — the client↔server seam
+
+> **Populated by phase 2 — not yet written**, except the OpenAPI snapshot, which phase 0 refreshed.
+> Until then the contract lives in [dev/contracts/](../../dev/contracts/README.md) (frozen 2026-07-13)
+> and the deployment shape in [DEPLOY.md](../../DEPLOY.md).
+
+The two projects have no shared build. Everything that crosses between them — envelope shape, casing,
+pagination, idempotency, cookies and refresh, CORS, `NEXT_PUBLIC_API_URL`, three containers behind Caddy,
+a remote SQL Server and the OTP relay — is described **here, as one thing**. Today it is described
+nowhere as one thing, which is the gap this section closes.
+
+## Planned contents
+
+| File | Covers |
+| --- | --- |
+| `api-contract.md` | Envelope, casing, pagination, error shape, idempotency, auth headers/cookies |
+| `domains/` | One file per service domain, refreshed against the live swagger |
+| [`openapi/`](openapi/README.md) | The machine contract — **snapshot is current as of 2026-07-29** |
+| `config-matrix.md` | Every env var and appsettings key: client, server, docker, the bot |
+| `topology.md` | The runtime dependency graph — 3 containers + Caddy + remote SQL + OTP relay |
+
+## What phase 0 already established
+
+The machine contract barely drifted. Between the 2026-07-13 snapshot and the live server on 2026-07-29:
+**one endpoint added** (`POST /api/v1/webhooks/payouts/{provider}`), **one schema changed**
+(`GeneratePayoutBatchCommand`), nothing removed. Full diff in
+[_plan/open-contradictions.md § OpenAPI drift](../_plan/open-contradictions.md#openapi-drift).
+
+So phase 2's real work is the **17 hand-written** `dev/contracts/domains/*.md` files, which were frozen
+the same day and have never been checked against anything mechanically — not the JSON.
+
+Also open for this section: **C-2** (`SET_VIA_USER_SECRETS_OR_ENV` names a store that was removed),
+**C-3** (`https://localhost:5002` in 18 places vs `http://` in `launchSettings.json`), **C-8** (two
+contract files for messaging), **C-9** (a `v1.1` OpenAPI document that may not exist).
@@ -0,0 +1,56 @@
+# OpenAPI snapshot
+
+The **machine contract**. The server generates it with NSwag; this folder holds the published snapshot
+so the client can generate or verify types without booting the backend.
+
+> Last verified: 2026-07-29 against commit `c99e3f4` (server code last changed in `5885280`, 2026-07-28).
+
+| | |
+| --- | --- |
+| File | [`swagger.v1.json`](swagger.v1.json) |
+| Taken | 2026-07-29 |
+| Commit | `c99e3f4` |
+| **Paths** | **178** |
+| **Operations** | **186** |
+| Component schemas | 339 |
+| Generator | NSwag v14.7.1.0 · OpenAPI 3.0.0 |
+| Size | 612 K |
+
+## How to regenerate
+
+The API binds **plain HTTP** on port 5002 (`launchSettings.json`), despite what most prose in this repo
+says — see contradiction C-3. Use whatever port you bind; the document is the same.
+
+```bash
+cd server
+ASPNETCORE_ENVIRONMENT=Development dotnet run \
+  --project src/API/Baya.Web.Api/Baya.Web.Api.csproj
+
+# from another shell, once "Now listening" appears:
+curl -s --noproxy '*' http://127.0.0.1:5002/swagger/v1/swagger.json \
+  -o docs/integration/openapi/swagger.v1.json
+```
+
+Two things that cost time the first run:
+
+- Booting in `Development` **migrates and seeds** against the DB in `appsettings.Development.json` —
+  currently a *remote* SQL Server. First boot takes ~40 s and logs
+  `Demo world already seeded — no-op.` when the world is present.
+- `--noproxy '*'` matters. With a proxy configured in the environment, `curl` to `localhost` returns
+  **502** rather than the document.
+
+Then update the table above — date, commit, and endpoint count — in the same change. A snapshot whose
+provenance is unrecorded is what this chain exists to stop.
+
+## Scope
+
+`v1` only. [The old README](../../../dev/contracts/openapi/README.md) claimed the server publishes
+documents `v1` **and** `v1.1`, but only `v1` has ever been committed and `v1.1` was not fetched during
+the phase 0 survey. `UNVERIFIED:` check `/swagger/v1.1/swagger.json` when the server is next up
+(contradiction C-9).
+
+## The human contract
+
+The prose half — one file per domain — lands in [`../domains/`](../index.md) in phase 2. **The two must
+agree**: this JSON is the wire truth, the markdown explains it. When they disagree, the JSON wins and
+the markdown is wrong.