From 2c3ee8271db3fa812a48e40d582e2edfaf12dd1c Mon Sep 17 00:00:00 2001 From: "dong.nguyen" Date: Thu, 22 Oct 2026 19:00:01 +0700 Subject: [PATCH] =?UTF-8?q?docs(spec-v4):=20record=20dictionary-boundary?= =?UTF-8?q?=20audit=20=E2=80=94=203=20person-content=20keys=20in=20ui.json?= =?UTF-8?q?=20(row=2018),=20structure-assigned=20string=20localization=20d?= =?UTF-8?q?ecision=20(row=2019)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/design/specs/v4/spec-v4-live-edit.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/design/specs/v4/spec-v4-live-edit.md b/docs/design/specs/v4/spec-v4-live-edit.md index d0a0160..904a3c5 100644 --- a/docs/design/specs/v4/spec-v4-live-edit.md +++ b/docs/design/specs/v4/spec-v4-live-edit.md @@ -538,6 +538,20 @@ Resolved by owner decision during the 2026-10-22 review: - **`profile.tagline`** → Decision D9 (segment the value; markup moves to `Hero.tsx`). - Display name (rev.1 Q3) → Decision D6. `ui.json` editability (rev.1 Q4) → §5.1 editable surface: read-only in v4. +Open — recorded by the 2026-10-22 dictionary-boundary audit (owner decision: record now, fix later): + +An audit of every key in `ui.{vi,en}.json` against the D1/D2 boundary (language-neutral structure / per-language text / chrome) found exactly three keys that hold person content inside the chrome document — and because §3.3/§5.1 keep `ui.json` read-only in edit mode, the owner cannot edit these own texts through `?edit`: + +- `ui.about.subtitle` (`ui.{vi,en}.json:55`) — a short variant of `profile.bio` rendered as the `/about` heading subtitle (`AboutPage.tsx:26`). A duplicated fact with two sources. +- `ui.experience.tldrText` (`ui.{vi,en}.json:67`) — career facts in personal voice ("15 years of experience, more than 8 companies…"), rendered at `Experience.tsx:64` and `ExperiencePage.tsx:61`. +- `ui.philosophy.quotes` (`ui.{vi,en}.json:100-109`) — the owner's own essays ("Time is priceless"), rendered at `PhilosophyPage.tsx:24`. + +Everything else in `ui.json` is chrome (nav/aria/CTA labels, section headings, category labels, resume and edit-mode strings); conversely nothing in `content.json` belongs in the structure documents — `profile.name` is localized by D6, `experience.*.title` is language-dependent by nature. + +Fix when scheduled (Plan A, row 18): move the three values into the `profile` record of the text documents — `profile.subtitle`, `profile.tldr`, `profile.philosophyQuotes: [{ title, details: [string] }]` — a fixed record, not id-keyed, so §3.6 rule 2 is untouched; extend `ProfileText` in `dict-types.ts` (vi required, en optional per-field); repoint the four call sites; wrap them with `EditableText` (`SectionHeading`'s `subtitle` prop becomes `ReactNode`); update the JsonPanel content-tab shape hint; delete the keys from both `ui` documents — `UIDict = typeof uiViJson` makes `tsc` the migration net. + +Owner decision still open (row 19 — not a rule violation, §4 assigns these to structure deliberately): language-dependent strings rendered untranslated on Vietnamese pages — `experience.company` of the two non-company entries ("Open to new opportunities", "Career break"), `duration` month names, `profile.currentInterests` / `roles` / `philosophy[].keywords`, `projects.role` / `metrics`. Localizing them reverses §4 (types, loaders, validator, resume generator): data would keep machine-readable dates (`start`/`end`) with the display string moved to the text documents. + Deferred (not v4): - **Media editing** (profile photo, QR images): the Contents API handles base64 fine, but `public/profile-photo.webp` is a fixed path served with 30-day immutable caching (`nginx.conf:25-30`) — replacing the file at the same URL serves the stale image until cache expiry. Correct media editing needs URL versioning (filename or `?v=`) plus a data reference update — its own small design. Binary git diffs also make review opaque, and edit frequency is low. Revisit in v4.1. @@ -563,3 +577,5 @@ Deferred (not v4): | 15 | Edit mode 3c: save bar, conflicts, failure recovery | 3 | ✅ Done 2026-10-22 (automated) — `EditBar.tsx`: changed-path diff with per-path revert and per-document discard, validate-before-save, sequential-PUT progress lines (written / conflict / failed), resume after partial failure, conflict actions (rebase / take-theirs / hand-merge), exit confirm when dirty. Verified via the same (now deleted) SSR smoke — vi markup carried the conflict controls, save statuses, and the resume button. ⬜ Browser + Gitea: save → commit → queued CI deploy → live change; full 412 flow against a real stale sha | | 16 | Layout designer research (WYSIWYG / layout config) | deferred | ⬜ Out of v4 scope | | 17 | Target-branch editing (D10): `?edit=`, `?ref=` on GET, `branch` on PUT, branch chip + merge hint | 3 | ✅ Done 2026-10-22 (automated) — tri-state URL parsing with git-ref validation (`edit-mode.ts`), `?ref=` on every document GET and `branch` in every PUT body (`draft.ts`, incl. the 412-refresh and id-union legs), branch persisted beside the session flag, EditBar branch chip + merge hint on non-default branches (`ui.json` `branchLabel`/`mergeHint`). Verified: `pnpm build`, `pnpm lint` (no new warnings), `scripts/smoke-draft.ts` 7/7, throwaway wiring smoke (URL tri-state, ref/branch transport, EditBar render for branch vs master) — deleted after the run. ⬜ Browser + Gitea: edit on a non-master branch → commits land there; merge → deploy | +| 18 | Move the three person-content keys out of `ui.json` (§11 Open item): `about.subtitle` → `profile.subtitle`, `experience.tldrText` → `profile.tldr`, `philosophy.quotes` → `profile.philosophyQuotes`; extend `ProfileText`, repoint 4 call sites, `EditableText` wrap + `SectionHeading` `subtitle: ReactNode`, JsonPanel hint update; `tsc` is the migration net | post-v4 | ⬜ TODO — recorded 2026-10-22 by the dictionary-boundary audit; owner chose record-only | +| 19 | Owner decision: localize the §4 structure-assigned strings (`experience.company` of non-company entries, `duration`, `currentInterests`, `roles`, `keywords`, `projects.role`/`metrics`) or keep them EN-only like `technologies` | open question | ⬜ Open — recorded 2026-10-22; reverses §4 if adopted |