협재 · 첫날 오후



애월 · 늦은 오후



제주시 · 마지막 저녁

diff --git a/config/contracts/registry-change-evidence.json b/config/contracts/registry-change-evidence.json index b039daa..008c74b 100644 --- a/config/contracts/registry-change-evidence.json +++ b/config/contracts/registry-change-evidence.json @@ -96,6 +96,30 @@ "compatibilityWindow": "Existing valid envelopes continue to decode; invalid values fail closed.", "rollback": "Remove the required codec field and runtime codec dispatch together.", "owner": "frontend-platform" + }, + { + "changeId": "FE-REG-ROUTE:APP_HOME:chunkId:field-changed", + "versionBump": "Memento product composition takes ownership of the root route and its lazy chunk identity.", + "migration": "The compiled product manifest installs Memento APP_HOME at / and the route runtime resolves it to the Memento home page while preserving the root URL.", + "compatibilityWindow": "Each release owns its route/chunk manifest and cache epoch, so old and new chunk identities are not mixed within one admitted release.", + "rollback": "Remove the Memento feature from the compiled product manifest and restore the platform APP_HOME route/runtime pair together.", + "owner": "memento-web" + }, + { + "changeId": "FE-REG-ROUTE-RUNTIME:APP_HOME:moduleId:field-changed", + "versionBump": "The root route runtime module changes from the template home module to the Memento home module.", + "migration": "Memento contributes the root route contract and matching lazy runtime module through the installed feature composition.", + "compatibilityWindow": "Release-manifest chunk verification keeps module/chunk identities release-scoped; no cross-release runtime module lookup is accepted.", + "rollback": "Remove the Memento feature contribution and restore the platform APP_HOME route/runtime pair in the same release.", + "owner": "memento-web" + }, + { + "changeId": "FE-REG-ROUTE:$contract:allowedValues:contract-field-changed", + "versionBump": "The route registry governance contract admits the Memento feature's typed route schemas and loading surfaces.", + "migration": "Memento route/search schema IDs and loading-surface IDs are installed through the product feature contract and validated by the same registry/runtime composition as platform and reference routes.", + "compatibilityWindow": "The new allowed values are additive; existing route definitions and their runtime codecs remain valid during the transition.", + "rollback": "Remove the Memento product feature contribution and then remove the additive Memento schema/loading-surface values from registry governance.", + "owner": "memento-web" } ] } diff --git a/config/contracts/registry-governance.json b/config/contracts/registry-governance.json index a19036d..1c86cc4 100644 --- a/config/contracts/registry-governance.json +++ b/config/contracts/registry-governance.json @@ -41,8 +41,22 @@ "uniqueFields": ["routeId", "path", "chunkId"], "allowedValues": { "access": ["public", "session-required"], - "paramsSchema": [null, "NotFoundSplat", "ReferenceResourceParams"], - "searchSchema": [null, "ReferenceResourceListQuery"], + "paramsSchema": [ + null, + "NotFoundSplat", + "ReferenceResourceParams", + "MementoMemoryParams", + "MementoAlbumParams", + "MementoPersonParams", + "MementoPlaceParams" + ], + "searchSchema": [ + null, + "ReferenceResourceListQuery", + "MementoLibrarySearch", + "MementoDetailSearch", + "MementoSettingsSearch" + ], "loadingSurface": [ "app-shell", "example-page", @@ -50,6 +64,20 @@ "reference-resource-detail", "reference-resource-form", "reference-resource-status", + "memento-home", + "memento-library", + "memento-memories", + "memento-memory-detail", + "memento-albums", + "memento-album-detail", + "memento-search", + "memento-people", + "memento-person-detail", + "memento-places", + "memento-place-detail", + "memento-login", + "memento-register", + "memento-settings", "none" ], "errorSurface": [ @@ -235,7 +263,9 @@ "consumerDirectories": [ "src/presentation/routes", "src/features/reference-feature/presentation", - "src/features/reference-feature/contracts" + "src/features/reference-feature/contracts", + "src/features/memento-web/contracts", + "src/features/memento-web/presentation" ], "breakingFields": ["schemaId", "boundary", "runtime"] }, diff --git a/docs/reviews/2026-09-20-memento-template-integration-followup-review.md b/docs/reviews/2026-09-20-memento-template-integration-followup-review.md new file mode 100644 index 0000000..c9eb960 --- /dev/null +++ b/docs/reviews/2026-09-20-memento-template-integration-followup-review.md @@ -0,0 +1,1153 @@ +# Memento Frontend — Follow-up Review for Remaining Work + +> 검토일: 2026-09-20 +> 대상: `/shared/codebase/memento-frontend` +> 선행 리뷰: `docs/reviews/2026-09-20-memento-template-integration-visual-parity-review.md` +> 현재 판정: **아직 더 봐야댐** +> 범위: 1차 리뷰 반영 후 남은 미완료 항목만 다룬다. + +--- + +# 1. 이번 재검수 결론 + +1차 리뷰에서 요구한 큰 구조 전환은 대부분 제대로 반영되었다. + +현재 확인된 완료 항목: + +- Static prototype이 실제 UI를 소유하던 구조 제거 +- `index.html`을 React root만 남기는 구조로 변경 +- `beta.js`, `beta.css`, static login/register 제거 +- `MementoRuntimeBridge` / prototype DOM integration 제거 +- Memento page를 TS/TSX component로 분해 +- React Router 및 feature route runtime으로 전환 +- Memento feature contract/runtime 등록 +- local -> mock, development/staging/production -> API 구조 유지 +- template의 Application Feature Input 사용 +- template의 Query / Mutation bridge 사용 +- template의 reusable HTTP capability 사용 +- feature 내부 direct `fetch` 제거 +- feature presentation direct DOM query 제거 +- Storybook 추가 +- Memento assurance gate 추가 +- Visual regression test 추가 +- E2E 추가 + +검증 결과: + +```text +check:memento-assurance PASS +check:architecture PASS +check:design-system PASS +check:types:app PASS + +Memento unit/component 7 / 7 PASS +Memento visual 26 / 26 PASS +Memento E2E 9 / 9 PASS + Chromium / Firefox / WebKit +``` + +하지만 현재 상태를 **완료**로 판정하지 않은 이유는 세 가지다. + +1. Memento Design System이 아직 완전히 token contract 안으로 들어오지 않았다. +2. Visual regression baseline이 원본 prototype과의 동일성을 공식적으로 보장하지 않는다. +3. E2E가 1차 리뷰에서 요구했던 핵심 사용자 흐름을 전부 검증하지 않는다. + +추가로, 전체 공식 component suite는 현재 Coka host의 Node.js 버전 때문에 실행하지 못했다. + +--- + +# 2. P1 — Memento Design System tokenization 미완료 + +## 2.1 현재 상태 + +현재 Memento presentation은 template design-system public barrel을 사용하도록 개선되었다. + +예: + +```ts +import { + MementoButton, + MementoChip, + MementoBadge, + MementoIconButton, +} from "../../../../presentation/design-system/index.ts"; +``` + +그리고 Memento wrapper는 template primitive를 실제로 감싼다. + +```text +MementoButton -> Button +MementoIconButton -> IconButton +MementoBadge -> Badge +MementoChip -> Button +``` + +이 방향은 맞다. + +또 다음 Memento token도 기존 token contract에 추가되어 있다. + +```text +--memento-background +--memento-surface +--memento-surface-muted +--memento-content +--memento-content-muted +--memento-border +--memento-action +--memento-action-muted +--memento-danger +--memento-sidebar-width +--memento-shadow +``` + +문제는 여기서 끝나 있다는 점이다. + +--- + +## 2.2 현재 `memento.css`는 여전히 Beta CSS의 상당 부분을 직접 보유한다 + +현재 파일: + +```text +src/presentation/design-system/memento/memento.css +``` + +측정 결과: + +```text +416 lines +39,544 bytes + +raw color occurrences: 152 +unique raw color values: 84 +``` + +예를 들면 다음 값들이 여전히 component stylesheet에 직접 존재한다. + +```css +background:#e6e7e2; +color:#161715; +background:#e8e9e4; + +background:linear-gradient(135deg,#9db0a4,#d7c5a9); +background:#5e8b6c; + +color:#d6d9d5; +border-color:#c8d8cd; +color:#2f4c3d; + +background:#1d211e; +color:#f8f8f6; +color:#bdc9c1; +color:#c8cbc6; + +background:#94633d; + +background:#e7ebe7; +color:#8a8d87; +``` + +즉 현재 상태는: + +```text +기존 beta.css + ↓ +memento.css 안으로 이동 + + +핵심 색상/폭/그림자 일부만 token contract 등록 +``` + +에 가깝다. + +1차 리뷰에서 요구한 최종 상태는 이보다 한 단계 더 나가야 한다. + +```text +Primitive Token + ↓ +Semantic Token + ↓ +Component / Product Token + ↓ +Memento Design Component + ↓ +Feature Component + ↓ +Page +``` + +--- + +# 3. P1 해결 방향 — 기존 디자인 값은 유지하면서 token contract에 편입 + +중요한 제약은 그대로다. + +> **디자인 값을 바꾸면 안 된다.** + +따라서 현재 raw value를 새로운 값으로 개선하는 것이 아니다. + +현재 값을 그대로 token 이름 아래로 이동해야 한다. + +--- + +## 3.1 Primitive token 후보 + +반복되는 물리 값을 primitive로 먼저 분류한다. + +예: + +```css +--memento-palette-ink-950: #161715; +--memento-palette-forest-950: #1d211e; +--memento-palette-forest-700: #31433a; +--memento-palette-forest-600: #496356; +--memento-palette-forest-500: #5e8b6c; + +--memento-palette-stone-100: #f4f4f1; +--memento-palette-stone-150: #ecece7; +--memento-palette-stone-200: #e6e7e2; +--memento-palette-stone-300: #dddeda; + +--memento-radius-sm: 9px; +--memento-radius-md: 12px; +--memento-radius-lg: 18px; +--memento-radius-xl: 22px; +--memento-radius-2xl: 26px; +``` + +단 실제 이름은 repository의 기존 naming convention에 맞춰 조정한다. + +--- + +## 3.2 Semantic token 후보 + +화면 의미 단위로 재매핑한다. + +예: + +```css +--memento-color-page-background +--memento-color-panel +--memento-color-panel-muted + +--memento-color-text-primary +--memento-color-text-secondary +--memento-color-text-inverse + +--memento-color-border +--memento-color-action +--memento-color-action-muted +--memento-color-action-content + +--memento-color-success +--memento-color-warning +--memento-color-danger + +--memento-color-overlay +--memento-color-dark-surface +``` + +현재 존재하는 token과 중복된다면 새로 만들지 말고 기존 이름에 매핑한다. + +--- + +## 3.3 Component token 후보 + +Component에서 반복되는 값을 product component token으로 올린다. + +예: + +```css +--memento-sidebar-background +--memento-sidebar-border +--memento-sidebar-active-background + +--memento-button-background +--memento-button-border +--memento-button-primary-background +--memento-button-primary-content +--memento-button-radius + +--memento-chip-active-background +--memento-chip-active-border +--memento-chip-active-content + +--memento-dialog-radius +--memento-dialog-shadow +--memento-drawer-width + +--memento-selection-bar-background +--memento-selection-bar-shadow + +--memento-card-radius +--memento-media-tile-radius + +--memento-auth-visual-background +``` + +모든 CSS 수치를 억지로 token으로 만드는 것은 목적이 아니다. + +반복되거나 제품 시각 정체성을 구성하는 값, 테마/variant에서 의미를 갖는 값을 우선 대상으로 한다. + +--- + +# 4. P1 — `check:design-system` blind spot도 반드시 수정 + +현재 `scripts/check-design-system.ts`의 CSS 검사 범위는 다음에 국한된다. + +```text +primitive.css +semantic.css +component.css +theme.css +``` + +실제 코드는 현재 다음과 같다. + +```ts +const cssSources = await Promise.all( + [...Object.values(tokenFiles), "src/presentation/styles/theme.css"].map(...) +); +``` + +따라서: + +```text +src/presentation/design-system/memento/memento.css +``` + +는 검사하지 않는다. + +결과적으로 Memento CSS에 raw color가 152회 있어도: + +```text +Design system contract: 59 tokens and vendor boundaries PASS +``` + +가 나온다. + +이는 design-system gate가 Memento product design을 실제로 보호하지 못하고 있다는 뜻이다. + +--- + +## 4.1 Gate 개선안 + +방법은 두 가지가 가능하다. + +### 방법 A — 기존 `check:design-system`에 product stylesheet 포함 + +권장. + +예: + +```ts +const productDesignSources = [ + "src/presentation/design-system/memento/memento.css", +]; + +const cssSources = await Promise.all( + [ + ...Object.values(tokenFiles), + "src/presentation/styles/theme.css", + ...productDesignSources, + ].map(...) +); +``` + +그리고 product stylesheet에서 허용되지 않는 raw palette를 탐지한다. + +### 방법 B — Memento assurance에 별도 CSS gate 추가 + +예: + +```text +FE-MEMENTO-008 MEMENTO_RAW_DESIGN_VALUE +``` + +단 design-system 자체의 책임이라는 점을 고려하면 A가 더 자연스럽다. + +--- + +## 4.2 Raw value 허용 정책 + +무조건 모든 `#fff`, rgba까지 금지하면 실용성이 떨어질 수 있다. + +명시적인 정책을 둔다. + +예: + +허용: + +- transparent +- currentColor +- CSS keyword +- gradient 안에서 기술적으로 1회만 쓰이는 overlay 값 +- Story/demo 전용 fixture + +금지: + +- 제품 palette의 반복 raw hex +- 동일한 의미를 가진 반복 rgba +- 이미 token이 존재하는 값을 raw value로 다시 사용하는 것 + +가능하면 allowlist는 파일 단위가 아니라 **값 + 이유** 단위로 최소화한다. + +--- + +# 5. P1 완료 조건 + +다음 조건이 모두 만족되어야 한다. + +- [ ] Memento 핵심 palette가 token contract 아래에 있다. +- [ ] 반복되는 raw color가 product stylesheet에 직접 남아 있지 않다. +- [ ] Memento component visual value가 token을 통해 전달된다. +- [ ] `memento.css`가 design-system gate 검사 범위에 포함된다. +- [ ] raw palette를 다시 추가하면 gate가 실패한다. +- [ ] 기존 screenshot 결과는 변경되지 않는다. +- [ ] `check:design-system` PASS +- [ ] `check:memento-assurance` PASS + +--- + +# 6. P2 — Visual baseline provenance 미완료 + +## 6.1 현재 Visual Test 자체는 잘 구성되어 있다 + +현재: + +```text +tests/visual/memento-prototype.visual.spec.ts +``` + +와 26개의 snapshot이 존재한다. + +범위: + +- Desktop 12개 주요 surface +- Mobile 4개 주요 surface +- Profile Drawer +- Upload Dialog +- Create Album Dialog +- Share Dialog +- Edit Memory Dialog +- Library Selection +- Media Viewer +- Login +- Register +- Action Modal + +실제 실행 결과: + +```text +26 / 26 PASS +``` + +여기까지는 좋다. + +--- + +# 7. 문제 — 이 snapshot이 원래 Beta prototype의 golden baseline이라는 증거가 없다 + +현재 snapshot은 이번 React migration과 함께 새로 생성된 파일이다. + +즉 CI가 지금 증명하는 것은 기본적으로: + +```text +현재 React 렌더링 + vs +현재 저장된 React snapshot +``` + +이다. + +하지만 요구사항은: + +> 기존 디자인을 1도 바꾸지 않는다. + +이므로 더 중요한 비교는: + +```text +Legacy approved Beta prototype + vs +New React implementation +``` + +이다. + +현재 repository 안에는 이 provenance가 명확하게 남아 있지 않다. + +--- + +# 8. 실제 재검수에서 원본 prototype과 비교한 결과 + +이번 검수에서는 Git `HEAD`에 남아 있는 기존: + +```text +index.html +public/beta.css +public/beta.js +``` + +를 별도 임시 디렉터리에 복원했다. + +그리고 legacy prototype과 현재 React implementation을 각각 별도 HTTP server로 띄운 뒤 Chromium에서 동일 viewport로 직접 screenshot을 비교했다. + +조건: + +```text +Viewport: 1600 x 1100 +Browser: Chromium +iframe: 비교 시 동일하게 hidden +assets: 동일 public/assets 사용 +``` + +결과: + +| Surface | Render Size | Changed Pixels | +| --- | --- | ---: | +| Home | 1600 x 1505 / 동일 | 425 | +| Library | 1600 x 1619 / 동일 | 1,946 | +| Memories | 1600 x 1872 / 동일 | 314 | +| Memory Detail | 1600 x 3346 / 동일 | 8,580 | +| Albums | 1600 x 1100 / 동일 | 1,114 | +| People | 1600 x 1100 / 동일 | 296 | +| Places Map | 1600 x 1100 / 동일 | 1,416 | +| Search | 1600 x 1100 / 동일 | 2,473 | +| Settings | 1600 x 1100 / 동일 | 296 | + +해석: + +- 전체 layout dimension은 모두 동일했다. +- 구조가 무너진 수준의 변경은 없다. +- 대부분 화면은 매우 작은 차이만 존재한다. +- 현재 migration은 시각적으로 상당히 정확하게 수행되었다. + +하지만 **pixel-identical은 아니다.** + +--- + +# 9. P2 해결 방향 — Golden Visual Migration Evidence 추가 + +권장 방식은 legacy prototype을 production source로 되살리는 것이 아니다. + +Legacy 화면을 **visual migration fixture/evidence**로만 보존한다. + +예: + +```text +tests/ +└── fixtures/ + └── memento-visual-baseline/ + ├── README.md + ├── legacy/ + │ ├── index.html + │ ├── beta.css + │ ├── beta.js + │ └── ... + └── baseline/ + ├── desktop-home.png + ├── desktop-library.png + └── ... +``` + +또는 source fixture를 보존하기 싫다면 승인된 screenshot만 저장한다. + +핵심은: + +> snapshot의 출처가 “React 구현 자체”가 아니라 “승인된 기존 prototype”이라는 사실을 repository가 설명할 수 있어야 한다. + +--- + +## 9.1 권장 evidence 문서 + +예: + +```text +tests/visual/MEMENTO_VISUAL_BASELINE.md +``` + +내용: + +- baseline 생성 기준 commit +- legacy source +- browser version +- viewport +- font condition +- iframe/map masking rule +- screenshot 생성 명령 +- 승인된 변경 허용 정책 +- snapshot update 절차 + +--- + +## 9.2 Snapshot update 규칙도 강화 + +현재처럼: + +```bash +pnpm test:visual:update +``` + +만 실행하면 디자인 변경이 쉽게 baseline으로 흡수될 수 있다. + +Memento에 대해서는 다음 정책이 필요하다. + +```text +Visual diff 발생 + ↓ +원인 확인 + ↓ +구조 변경 때문에 발생한 미세 차이인지 확인 + ↓ +디자인 변경 여부 확인 + ↓ +승인된 경우에만 snapshot update +``` + +즉 visual update는 실패를 없애는 명령이 아니라 **승인 절차의 마지막 단계**여야 한다. + +--- + +# 10. 남은 pixel difference 처리 + +현재 차이가 매우 작다고 해서 자동으로 무시하면 안 된다. + +특히 Memory Detail의 8,580 changed pixels는 다른 화면보다 상대적으로 크다. + +우선 diff image를 생성해서 영역을 확인한다. + +예: + +```bash +compare legacy-memory.png react-memory.png memory-diff.png +``` + +확인 대상: + +- native button rendering +- font anti-aliasing +- line-height +- heading default style +- focus normalization +- image decode timing +- responsive rounding +- primitive wrapper가 삽입한 style +- route/React DOM 차이로 발생한 cascade + +실제 디자인 값 차이라면 수정한다. + +브라우저 rasterization 차이처럼 구조상 불가피하다면 이유와 허용 기준을 baseline 문서에 기록한다. + +--- + +# 11. P2 완료 조건 + +- [ ] Legacy approved prototype이 baseline의 출처라는 evidence가 있다. +- [ ] desktop 주요 화면 legacy ↔ React 비교가 자동화되어 있다. +- [ ] mobile 주요 화면 legacy ↔ React 비교가 있다. +- [ ] overlay/dialog/drawer도 legacy ↔ React 기준을 갖는다. +- [ ] visual snapshot update 절차가 문서화되어 있다. +- [ ] Memory Detail 등 남은 diff의 원인이 확인되어 있다. +- [ ] 의도하지 않은 실제 visual change는 0이다. +- [ ] 현재 26 visual regression test가 계속 PASS한다. + +--- + +# 12. P3 — E2E coverage 미완료 + +## 12.1 현재 상태 + +현재: + +```text +tests/e2e/memento-flow.spec.ts +``` + +에는 3개의 logical scenario가 있다. + +1. Router navigation / browser history +2. Local mock + Create Album / Upload overlay +3. Settings deep link + Login/Register + +3 browser: + +```text +Chromium +Firefox +WebKit +``` + +에서 실행되어 총: + +```text +9 / 9 PASS +``` + +했다. + +현재 작성된 테스트는 의미가 있고 정상 동작한다. + +문제는 1차 리뷰의 최소 E2E 요구 범위보다 좁다는 점이다. + +--- + +# 13. 추가해야 할 E2E 흐름 + +## E2E-1 — Library interaction + +반드시 검증할 것: + +```text +/library + ↓ +filter 변경 + ↓ +search 입력 + ↓ +media select + ↓ +selection bar 표시 + ↓ +selection clear / action +``` + +검증 예: + +- URL search param 또는 state가 의도대로 변경되는지 +- 결과 filtering이 적용되는지 +- 선택 개수가 표시되는지 +- browser navigation 시 상태 정책이 의도대로인지 + +--- + +## E2E-2 — Home -> Memory Detail + +```text +Home + ↓ +Memory Card + ↓ +/memories/:memoryId + ↓ +detail data render + ↓ +tab 전환 +``` + +검증: + +- hard-coded page toggle이 아닌 실제 route navigation +- deep link reload +- story/photos/info tab +- 뒤로 가기 + +--- + +## E2E-3 — Memory candidate save + +```text +/memories + ↓ +suggested candidate + ↓ +save command + ↓ +mutation + ↓ +UI feedback / destination state +``` + +Local mock에서 mutation이 실제 application input을 통과하는지 검증한다. + +--- + +## E2E-4 — Search -> Person + +```text +/search + ↓ +person result + ↓ +/people/:personId +``` + +검증: + +- search interaction +- person detail deep link +- detail render + +--- + +## E2E-5 — Search -> Place + +```text +/search + ↓ +place result + ↓ +/places/:placeId +``` + +검증: + +- route +- detail render +- back navigation + +--- + +## E2E-6 — Share flow + +```text +Memory Detail + ↓ +Share + ↓ +Dialog + ↓ +createShare mutation + ↓ +result state +``` + +단순히 dialog가 열리는 것만이 아니라 command까지 통과하도록 한다. + +--- + +## E2E-7 — API mode boot + +현재 local mock은 잘 검증되고 있다. + +추가로: + +```text +APP_PROFILE=development +``` + +에서 Memento가 mock이 아니라 HTTP capability를 사용하는지 검증해야 한다. + +실제 backend가 필요하지 않도록 MSW 또는 test server를 사용해도 된다. + +검증해야 하는 것은 네트워크 성공 자체보다 **composition 선택**이다. + +예: + +```text +local -> mock +development -> API +production -> API +``` + +그리고 development E2E에서 예상 endpoint request가 발생하는지 확인한다. + +--- + +# 14. E2E 완료 조건 + +최소 다음 user journey가 browser test로 존재해야 한다. + +- [ ] Home -> Library +- [ ] Library filter +- [ ] Library search +- [ ] Library select +- [ ] Home -> Memory Detail +- [ ] Memory Detail tabs +- [ ] Memories -> Candidate Save +- [ ] Albums -> Create Album +- [ ] Search -> Person +- [ ] Search -> Place +- [ ] Profile -> Settings +- [ ] Upload +- [ ] Share +- [ ] Login -> Register +- [ ] Browser back/forward +- [ ] Deep link reload +- [ ] Local mock boot +- [ ] Development API boot + +모든 flow를 모든 브라우저에서 동일하게 돌릴 필요는 없다. + +권장: + +```text +Critical navigation/state: + Chromium + Firefox + WebKit + +Long mutation scenarios: + Chromium 중심 + 필요 시 cross-browser smoke 추가 +``` + +테스트 시간만 늘어나고 의미가 없는 중복은 피한다. + +--- + +# 15. P4 — 공식 전체 component suite 환경 검증 + +이번 검수에서는 Memento에 직접 관련된 test를 Vitest로 실행했다. + +결과: + +```text +tests/unit/memento-environment-gateway.test.ts +tests/component/memento-design-system.test.tsx + +7 / 7 PASS +``` + +하지만 공식: + +```bash +pnpm test:component +``` + +는 실행되지 않았다. + +이유: + +```text +Current Node.js: 22.23.2 +Required: >=24.11.0 <25.0.0 +``` + +repository의 runtime guard가 정상적으로 차단했다. + +즉 이는 코드 failure는 아니다. + +그러나 완료 판정 전에는 지원 runtime에서 공식 command를 한 번 통과시키는 것이 맞다. + +--- + +## 15.1 지원 Node에서 최종 실행할 명령 + +최소: + +```bash +corepack pnpm check:memento-assurance +corepack pnpm check:architecture +corepack pnpm check:design-system +corepack pnpm check:types + +corepack pnpm test:unit +corepack pnpm test:component +corepack pnpm test:integration + +corepack pnpm test:e2e +corepack pnpm test:visual +corepack pnpm test:storybook + +corepack pnpm build +``` + +Memento 변경이 template의 공용 HTTP/design-system/runtime을 수정했기 때문에 Memento 전용 테스트만으로 끝내면 안 된다. + +특히 현재 변경에는 다음 공용 영역도 포함된다. + +```text +src/adapters/http/* +src/contracts/* +src/features/installed-* +src/presentation/design-system/* +src/presentation/routes/* +src/bootstrap/* +``` + +따라서 full regression이 필요하다. + +--- + +# 16. 추가 권장 정리 — Application type ownership + +현재: + +```text +src/features/memento-web/presentation/hooks/use-memento.ts +``` + +가 다음 타입을: + +```ts +../../application/memento-gateway.ts +``` + +에서 import 한다. + +예: + +```text +AlbumQuery +CreateAlbumInput +CreateShareInput +LibraryQuery +MemoryQuery +ShareTarget +UpdateAlbumInput +UpdateMemoryInput +``` + +런타임 Gateway를 presentation에서 호출하는 것은 아니기 때문에 현재 architecture violation은 아니다. + +다만 presentation -> application input이라는 경계를 더 명확히 하려면 이 type들도 application public API 또는 command/query contract 쪽에서 export하는 것이 낫다. + +권장: + +```text +memento-application.ts +또는 +application/contracts/ +``` + +에서 presentation이 필요한 query/command type을 export한다. + +최종 의존 방향: + +```text +Presentation + ↓ +Application Public Contract + ↓ +Port + ↓ +Adapter +``` + +를 명확하게 만든다. + +이 항목은 P1~P3를 막는 blocker는 아니지만 이번 정리 시 같이 처리하는 편이 좋다. + +--- + +# 17. 구현 권장 순서 + +남은 작업은 다음 순서가 가장 안전하다. + +## Step 1 — Design token 정리 + +먼저 visual value의 이름과 위치만 바꾼다. + +디자인 수치는 바꾸지 않는다. + +완료 후: + +```bash +pnpm check:design-system +pnpm test:visual +``` + +## Step 2 — Design-system gate 강화 + +`memento.css`를 gate 범위에 포함한다. + +고의로 raw palette 하나를 fixture에 넣었을 때 실패하는 regression fixture도 추가한다. + +## Step 3 — Legacy visual baseline evidence 구축 + +현재 Git HEAD prototype을 기준으로 approved baseline을 만든다. + +기존 production prototype source는 fixture/evidence 용도로만 다룬다. + +## Step 4 — Pixel diff 분석 + +특히: + +- Memory Detail +- Search +- Library +- Places + +의 차이가 실제 디자인 변경인지 확인한다. + +## Step 5 — E2E user journey 확대 + +우선 mutation + search/detail 흐름부터 추가한다. + +## Step 6 — Supported Node에서 full regression + +마지막에 전체 suite/build를 실행한다. + +--- + +# 18. 이번 후속 리뷰의 완료 Definition of Done + +다음이 전부 충족될 때 이번 1차 template integration 작업을 **완료**로 판정한다. + +## Design System + +- [ ] Memento 핵심 visual palette가 token contract로 편입됨 +- [ ] 반복 raw product color가 제거됨 +- [ ] `memento.css`가 design-system 검사 범위에 포함됨 +- [ ] raw design value regression fixture 존재 +- [ ] Memento component가 template primitive를 계속 사용함 + +## Visual Parity + +- [ ] 승인된 legacy prototype이 golden baseline의 출처로 기록됨 +- [ ] desktop legacy ↔ React comparison 존재 +- [ ] mobile legacy ↔ React comparison 존재 +- [ ] overlay legacy ↔ React comparison 존재 +- [ ] 남은 pixel diff 원인이 분석됨 +- [ ] 의도하지 않은 visual design change가 없음 +- [ ] Visual regression 26개 이상 PASS + +## Architecture + +- [ ] direct DOM query 없음 +- [ ] feature direct fetch 없음 +- [ ] prototype bridge 없음 +- [ ] static product markup 없음 +- [ ] route runtime 사용 +- [ ] application input 사용 +- [ ] reusable HTTP binding 사용 +- [ ] local mock / dev-prod API composition 유지 + +## E2E + +- [ ] Library filter/search/select +- [ ] Memory detail +- [ ] Memory candidate save +- [ ] Create Album +- [ ] Person navigation +- [ ] Place navigation +- [ ] Settings +- [ ] Upload +- [ ] Share mutation +- [ ] Auth route +- [ ] Browser history +- [ ] Local mock +- [ ] Development API mode + +## Full Verification + +지원 Node `>=24.11 <25` 환경에서: + +- [ ] `check:memento-assurance` +- [ ] `check:architecture` +- [ ] `check:design-system` +- [ ] `check:types` +- [ ] `test:unit` +- [ ] `test:component` +- [ ] `test:integration` +- [ ] `test:e2e` +- [ ] `test:visual` +- [ ] `test:storybook` +- [ ] `build` + +전부 PASS. + +--- + +# 19. 최종 작업 지시 + +현재 구조를 다시 뒤엎을 필요는 없다. + +React ownership, Router, feature contract/runtime, application/query boundary, HTTP capability 도입은 현재 방향을 유지한다. + +이번 후속 작업의 핵심은 다음 세 문장으로 정리된다. + +> **1. `memento.css`를 단순한 Beta CSS 보관소로 두지 말고 실제 Design System contract 아래로 끝까지 편입한다.** + +> **2. 현재 React snapshot을 기준으로 삼는 데서 끝내지 말고, 기존 승인 prototype이 visual baseline의 원본이라는 증거를 repository에 남긴다.** + +> **3. 화면이 보인다는 수준의 E2E가 아니라 주요 사용자 command/navigation flow가 application boundary를 실제로 통과하는지 검증한다.** + +이 세 항목과 supported Node에서의 full regression까지 끝나면 이번 template integration 작업은 **완료**로 판정할 수 있다. diff --git a/docs/reviews/2026-09-20-memento-template-integration-visual-parity-review.md b/docs/reviews/2026-09-20-memento-template-integration-visual-parity-review.md new file mode 100644 index 0000000..79ff5ea --- /dev/null +++ b/docs/reviews/2026-09-20-memento-template-integration-visual-parity-review.md @@ -0,0 +1,1653 @@ +# Memento Frontend — Template Integration & Visual-Parity Refactoring Review + +> 검토일: 2026-09-20 +> 대상: `/shared/codebase/memento-frontend` +> 기준: 현재 `main` / `85c804b feat: memento-frontend 디자인 구성 및 셋팅` +> 최우선 제약: **현재 디자인은 시각적으로 변경하지 않는다.** +> 목표: 현재 Memento 디자인 시안을 제품 디자인 시스템으로 편입하고, 화면을 TypeScript/TSX 컴포넌트로 분해한 뒤 기존 frontend template이 제공하는 routing, provider, design-system, application boundary, reusable capability, test/assurance 구조를 실제 제품 코드가 사용하도록 재구성한다. + +--- + +## 1. 결론 + +현재 `memento-frontend`는 **template을 기반으로 만들어진 프로젝트이지만, 실제 Memento 화면은 template 위에서 렌더링되는 React 제품이 아니다.** + +실제 사용자에게 보이는 UI의 소유권은 다음 세 파일에 있다. + +- `index.html` — 전체 화면 DOM을 정적으로 보유 +- `public/beta.css` — 실제 Memento 디자인을 보유 +- `public/beta.js` — 화면 전환, modal, drawer, selection, filtering 등 UI 동작을 imperative DOM 조작으로 보유 + +반면 React는 다음과 같이 동작한다. + +- `#root`는 `hidden aria-hidden="true"` 상태다. +- `RuntimeApplication`은 화면을 렌더링하지 않는다. +- `MementoRuntimeBridge`는 `useEffect`에서 `document.body`를 넘겨받아 기존 정적 DOM을 조작한다. +- `memento-prototype-integration.ts`는 1,124 LOC이며 `querySelector` 계열 접근을 대량으로 사용한다. +- Memento feature에서 template design-system import는 현재 0건이다. +- Memento route는 template의 feature route registry/runtime에 등록되어 있지 않다. + +즉 현재 구조는 아래에 가깝다. + +```text +Clean Architecture Frontend Template +├── bootstrap / provider / router / design-system / HTTP capability / tests +│ +└── React root (hidden) + └── MementoRuntimeBridge + └── document.body의 정적 prototype DOM을 찾아서 조작 + +실제 화면 +├── index.html +├── beta.css +└── beta.js +``` + +원하는 구조는 반대가 되어야 한다. + +```text +bootstrap + -> RuntimeApplication + -> template providers + -> AppRouter + -> MementoAppShell + -> Memento routes/pages + -> Memento design-system components + -> feature hooks / application input + -> MementoGateway port + -> local: mock adapter + -> dev/staging/prod: reusable HTTP capability binding +``` + +따라서 이번 리팩터링의 핵심은 **디자인을 새로 만드는 것이 아니라, 현재 디자인의 소유권을 static prototype에서 React + template architecture로 옮기는 것**이다. + +--- + +## 2. 현재 상태에서 확인된 근거 + +### 2.1 화면 소유권이 React가 아니다 + +현재 `index.html`은 213 LOC / 약 31 KB이며 다음을 직접 포함한다. + +- Sidebar +- Mobile top navigation +- Home +- Library +- Memories +- Search +- Place detail +- Memory detail +- Albums +- Album detail +- People +- Person detail +- Places map +- Settings +- Selection bar +- Profile drawer +- Upload modal +- Create Album modal +- Share modal +- Edit Memory modal +- Action modal +- Media viewer + +정적으로 포함된 `.page` surface만 12개, modal은 5개다. + +그리고 마지막 부분이 다음 구조다. + +```html + + +
+ +``` + +React가 페이지를 렌더링하는 것이 아니라 **이미 완성된 DOM 뒤에서 부수 기능만 연결하고 있다.** + +### 2.2 `beta.js`가 사실상 UI framework 역할을 한다 + +`public/beta.js`는 353 LOC이며 다음 책임을 직접 가진다. + +- 페이지 전환 +- active class 관리 +- 뒤로 가기 상태 +- modal / drawer open-close +- filter 상태 +- library selection +- album filter/search/sort +- detail tab +- person/place navigation +- image viewer +- settings surface 교체 +- toast +- logout redirect +- action modal의 동적 HTML 생성 + +실제 코드도 다음 패턴이다. + +```text +document.querySelector(...) +document.querySelectorAll(...) +document.getElementById(...) +element.classList.toggle(...) +element.onclick = ... +document.addEventListener(...) +``` + +확인 시 `beta.js` 내부에는: + +- `getElementById`: 67회 +- `querySelector` 계열 문자열: 약 70회 +- `addEventListener`: 6회 + +가 존재한다. + +이는 React 상태/라우팅/컴포넌트 lifecycle을 사용하지 않는 별도 UI runtime이다. + +### 2.3 React integration 역시 DOM adapter에 가깝다 + +`src/features/memento-web/presentation/memento-runtime-bridge.tsx`는 시각적 React component가 아니다. + +```ts +useEffect(() => { + document.documentElement.dataset.mementoDataMode = gateway.mode; + const cleanup = installMementoPrototypeIntegration(document.body, gateway); + ... +}, [gateway]); + +return null; +``` + +그리고 `memento-prototype-integration.ts`가 정적 DOM을 찾아 데이터를 주입한다. + +이 파일은 1,124 LOC이고 `querySelector` 계열 접근이 약 60회 존재한다. + +결과적으로 UI에 두 개의 imperative owner가 생겼다. + +```text +beta.js + + +memento-prototype-integration.ts + ↓ +동일한 static DOM +``` + +이 구조는 장기적으로 이벤트 중복, 상태 불일치, cleanup 누락, DOM selector coupling을 만들 가능성이 높다. + +--- + +## 3. 가장 큰 구조적 문제 + +## P0-1. Template의 React render tree가 실제 제품 화면을 소유하지 않는다 + +Template에는 이미 다음 기반이 있다. + +- `RuntimeApplication` +- `ApplicationProvider` +- server-state provider +- `AppRouter` +- `AppShell` +- route registry/runtime +- render/chunk/error boundary +- locale provider +- session provider +- theme provider + +하지만 현재 `RuntimeApplication`은 `MementoRuntimeBridge`만 mount한다. + +즉 template이 가진 렌더링 구조가 준비되어 있지만 **Memento가 그 구조에 들어오지 않았다.** + +### 교정 방향 + +최종적으로 `RuntimeApplication`은 Memento가 포함된 Router를 렌더링해야 한다. + +```tsx +


7월 12일부터 15일까지 촬영한 84장의 사진과 영상을 시간과 장소의 흐름으로 정리했습니다.
- - -


아직 어떤 Memory나 Album에도 포함되지 않았습니다.
시각적으로 거의 같은 사진을 검토할 수 있습니다.
1 TB 중 42% 사용 · 원본 3,184개
사진을 추가하면 자동으로 갱신됩니다.
직접 만든 컬렉션은 자동 Memory와 구분해서 관리합니다.



GPS 메타데이터가 제주도로 분류된 168장의 사진과 영상 · 사진이 추가되면 자동으로 갱신됩니다.
Memory84
방문 묶음37
2026.07.12 — 07.15 · 제주 · 84개의 사진과 영상







촬영 시간, GPS, 사진 간 시간 간격을 기준으로 자동 구성되었습니다. 사용자는 커버·제목·구간 합치기/나누기만 수정하면 됩니다.

124개의 사진과 영상 · 최근 수정 9월 14일




자주 함께 등장한 얼굴부터 보여줍니다.
381장의 사진 · 12개의 Memory
84
67업로드 전에 checksum을 비교해 이미 있는 원본은 건너뜁니다.


