docs(aar): append 2026-08-14 findings (German locale, timezone, fork patch)

Capture the follow-up work in the Wiki.js AAR: locale migration mechanics
(migrateToLocale only patches pages; rebuild tree+index; nav must move to the
new locale), the new-user timezone source (DB column default), API-only wiki
editing, and the standing upstream deviation (startup sed on users.js) with its
upgrade-check anchor. Stumbles 11-13 + a dated Nachtrag section.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Thore Cimbal
2026-08-14 12:00:00 +00:00
co-authored by Claude Opus 4.8
parent c6ea585643
commit 168fccc235
+31 -1
View File
@@ -37,6 +37,9 @@ sonst teuer neu lernt.
| 8 | **Git-Storage braucht den Remote-Branch vorab.** Wiki.js: „Invalid branch! Make sure it exists on the remote first." Ziel-Repo mit leerem Initial-Commit auf `main` bootstrappen. Nach fehlgeschlagenem Init sitzt der lokale Klon fest → `purge`-Action + re-init. | tool | ADR-0015 | | 8 | **Git-Storage braucht den Remote-Branch vorab.** Wiki.js: „Invalid branch! Make sure it exists on the remote first." Ziel-Repo mit leerem Initial-Commit auf `main` bootstrappen. Nach fehlgeschlagenem Init sitzt der lokale Klon fest → `purge`-Action + re-init. | tool | ADR-0015 |
| 9 | **Cluster erreicht git.lab nicht (Absicht).** Wiki.js pusht nach Gitea, ein CI-Job kanonisiert Gitea→git.lab (Muster `canonize_rotation`, umgekehrte Richtung). | infra | ADR-0015 | | 9 | **Cluster erreicht git.lab nicht (Absicht).** Wiki.js pusht nach Gitea, ein CI-Job kanonisiert Gitea→git.lab (Muster `canonize_rotation`, umgekehrte Richtung). | infra | ADR-0015 |
| 10 | **Nav-Sidebar rendert `target` wortwörtlich als `href`** (Default-Theme: `href: item.target`, keine `targetType`- oder Slash-Behandlung). Page-Targets ohne führenden Slash lösen **relativ** auf → von `/betrieb/x` aus wird `betrieb/y` zu `/betrieb/betrieb/y` → 404 (von `/` aus geht es zufällig, daher lange unbemerkt). `home` mit leerem Target ist ebenfalls tot. Fix: Targets absolut speichern (`/<path>`; `home``/`) — Wiki.js' eigener Editor nutzt `/<locale>/<path>`. | tool | `wikijs-config.py` (`set_navigation`) | | 10 | **Nav-Sidebar rendert `target` wortwörtlich als `href`** (Default-Theme: `href: item.target`, keine `targetType`- oder Slash-Behandlung). Page-Targets ohne führenden Slash lösen **relativ** auf → von `/betrieb/x` aus wird `betrieb/y` zu `/betrieb/betrieb/y` → 404 (von `/` aus geht es zufällig, daher lange unbemerkt). `home` mit leerem Target ist ebenfalls tot. Fix: Targets absolut speichern (`/<path>`; `home``/`) — Wiki.js' eigener Editor nutzt `/<locale>/<path>`. | tool | `wikijs-config.py` (`set_navigation`) |
| 11 | **Locale-Wechsel migriert nur `pages`.** Default en→de via `localization.updateLocale` (lädt live, KEIN Neustart) + `pages.migrateToLocale`; letzteres patcht NUR die `pages`-Tabelle (Kollisions-Guard). `pageTree`/`pageLinks`/`pageHistory`/Suchindex bleiben auf der alten Locale → danach `pages.rebuildTree` + `search.rebuildIndex`, die Restzeilen in `pageLinks`/`pageHistory` einmalig nachziehen. **Nav-Baum muss unter der NEUEN Locale liegen** (getTree nutzt die Seiten-Locale), sonst leere Sidebar. `namespacing:false` → saubere `/<pfad>`-URLs. | tool | `wikijs-config.py` (`ensure_locale`) |
| 12 | **New-User-Zeitzone kommt aus dem DB-Spalten-Default** (`users.timezone` = `America/New_York`), NICHT aus Config: SSO-`processProfile` legt Nutzer ohne `timezone` an (`localeCode` dagegen aus `WIKI.config.lang.code`). Bestehende Konten per `users.update` korrigieren (patcht nur übergebene Felder, kein Nulling). Neue Nutzer brauchen den **Fork-Patch** (s. Nachtrag). | tool | `wikijs-config.py` (`ensure_timezones`) |
| 13 | **Wiki-Inhalt nur über die Wiki.js-API editieren** — git-storage ist bidirektional, **nie** direkt nach Gitea schreiben (würde beim nächsten Sync kollidieren/überschrieben). Reproduzierbar via kurzlebigem In-Cluster-Job mit gemountetem Admin-Secret (Creds bleiben im Cluster; Pod-Label `app.kubernetes.io/name: wikijs-config` matcht die NetworkPolicy zu Wiki.js). | tool | dieser AAR |
## 3. Learnings (knapp) ## 3. Learnings (knapp)
@@ -54,6 +57,33 @@ sonst teuer neu lernt.
- In-place dokumentiert: Kommentare in `wikijs-config.py`, `wikijs.yaml`, `.sourceignore` - In-place dokumentiert: Kommentare in `wikijs-config.py`, `wikijs.yaml`, `.sourceignore`
(gitops); Notizen in #0048/#0050; Architektur in ADR-0015. (gitops); Notizen in #0048/#0050; Architektur in ADR-0015.
- **Offen (Harvest):** Befunde 110 in eine `docs/wiki/stolpersteine/wikijs.md` ziehen - **Offen (Harvest):** Befunde 113 in eine `docs/wiki/stolpersteine/wikijs.md` ziehen
(Wiki.js-Betriebswissen an einem Ort), dann `status: harvested`. Die Refinement-Session (Wiki.js-Betriebswissen an einem Ort), dann `status: harvested`. Die Refinement-Session
geht diesen AAR durch. geht diesen AAR durch.
## 5. Nachtrag 2026-08-14 — Deutsch-Locale, Zeitzone & stehende Fork-Abweichung
Nach dem Umzug fielen drei Dinge auf (sorb): die deutschen Inhalte hingen an der Locale
`en`, die Default-Sprache war Englisch, die Systemkonten standen auf `America/New_York`.
Alles behoben und reproduzierbar im Konfig-Job verankert:
- **Default-Sprache `de` + 25 Seiten en→de migriert** (`ensure_locale`) — Mechanik siehe
Stolperstein #11.
- **Zeitzone `Europe/Berlin`** für die Systemkonten (`ensure_timezones`, #12); der
Nav-`href`-Bug (#10) wurde im selben Zug gefixt.
**⚠️ Stehende Upstream-Abweichung (Fork-Patch) — framework-relevant:**
Wiki.js läuft als Upstream-Image (`ghcr.io/requarks/wiki:2.5`), es gibt **keine**
Build-Pipeline. Damit **neue** OIDC-Nutzer `Europe/Berlin` statt des im DB-Spalten-Default
verankerten `America/New_York` bekommen, patcht der Container beim Start
`server/models/users.js` (`processProfile`) per `sed` (idempotent, fail-open). Das ist eine
**dauerhafte Abweichung vom Upstream**, hängt am Anker `localeCode: WIKI.config.lang.code,`
und **muss bei jedem Wiki.js-Upgrade gegengeprüft** werden.
- Dokumentiert: ⚠️-Kommentar in `apps/production/wikijs.yaml` **und** in der Upgrade-Doku
`/betrieb/upgrades` (Abschnitt „Wiki.js: Startup-Patch"), neben den Element-Fork-Einträgen.
- **ADR m.E. nicht nötig** (kleine operative Abweichung, kein Architektur-/Regel-Grundsatz);
Nachverfolgung läuft über die Upgrade-Doku + diesen AAR. Wer das anders sieht, hebt es per
ADR nach.
gitops-Commits: Locale/Nav/Zeitzone `2250969`, Nav-Slash-Fix `9f8eed3`, Fork-Patch `5f54fbe`.