From 20a6f22ec39aefbb8bf9b82b0daa72fca537130e Mon Sep 17 00:00:00 2001
From: Paul Schneider <paul@pschneider.fr>
Date: Mon, 6 Jul 2026 21:03:10 +0100
Subject: [PATCH] PostIt: document the BaseAddress / pathPrefix URL convention
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous "PostIt: fix blog API double-prefix" commit changed
DefaultPathPrefix from "api/blog" to "blog" without spelling out
the convention. Future-me (or anyone else touching ApiUrl) needs
to know that BaseAddress already terminates in /api/v1/ and that
pathPrefix is relative to that.

* BlogApiClient: add a <para> in the class summary that names the
  convention, points at the matching controller route, and
  cross-references the fix commit.
* postit-oidc.md: add a row in the "Composants partagés" table
  with the same warning, in the architectural-doc voice.
---
 doc/architecture/postit-oidc.md             |  1 +
 src/PostIt/PostIt/Services/BlogApiClient.cs | 10 ++++++++++
 2 files changed, 11 insertions(+)

diff --git a/doc/architecture/postit-oidc.md b/doc/architecture/postit-oidc.md
index ee003b41..ddedbfde 100644
--- a/doc/architecture/postit-oidc.md
+++ b/doc/architecture/postit-oidc.md
@@ -56,6 +56,7 @@ pas vers un serveur HTTP.
 |---------------------------------|-------------------------------------------------------------------|
 | `Services/OidcLoginPhase`       | Enum des étapes du flow : `Idle / Discovering / OpeningBrowser / AwaitingCallback / ExchangingCode / Success / Error` |
 | `Services/YavscApiClient`       | Client HTTP de l'API Yavsc. Porte `LoginInteractiveAsync(IProgress<OidcLoginPhase>)` et `TrySilentLoginAsync`. Refresh silencieux sur 401 et sur access-token bientôt expiré. |
+| `Services/BlogApiClient`        | Mapper DTO↔path pour la sous-API blog. **Note** : `pathPrefix` est *relatif* à `/api/v1/` (que porte déjà `BaseAddress`) — ex. `"blog"` pour matcher `[Route(APIPrefix + "/blog")]`. Ne pas ré-inclure `api/`. |
 | `Services/SingleInstance`       | Named-pipe helper. `TryHandOffAsync` côté 2ᵉ instance, `StartServerAsync` côté instance vivante. |
 | `Services/CustomSchemeBrowser`  | `IBrowser` OidcClient qui ouvre le système + attend le pipe.      |
 | `Services/SchemeUrlDetector`    | Détection pure, testable, du `postit://callback` dans argv.       |
diff --git a/src/PostIt/PostIt/Services/BlogApiClient.cs b/src/PostIt/PostIt/Services/BlogApiClient.cs
index 5ebfe264..d489be60 100644
--- a/src/PostIt/PostIt/Services/BlogApiClient.cs
+++ b/src/PostIt/PostIt/Services/BlogApiClient.cs
@@ -15,6 +15,16 @@ namespace PostIt.Services;
 /// <see cref="YavscApiClient"/>. This class is a thin DTO↔path
 /// mapper, nothing more.
 ///
+/// <para><b>URL convention.</b> <see cref="YavscApiClient"/>'s
+/// <c>BaseAddress</c> already terminates with <c>/api/v1/</c>
+/// (see <c>Settings.ApiUrl</c>). The path prefix below is
+/// therefore <i>relative</i> to that version segment: a prefix of
+/// <c>"blog"</c> resolves to <c>…/api/v1/blog</c>, which matches
+/// the <c>[Route(APIPrefix + "/blog")]</c> attribute on
+/// <c>Yavsc.Blogs.Controllers.BlogApiController</c>. Do not
+/// re-include the <c>api/</c> segment here — that produced 404s
+/// in the past (see commit "PostIt: fix blog API double-prefix").</para>
+///
 /// The class is intentionally non-IDisposable: it does not own the
 /// <see cref="YavscApiClient"/> it depends on. Lifetimes are managed
 /// by the consumer (typically a singleton service registered with