From 83d47e7185409c8da970ad38653f07070fe2fafe Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 18 Aug 2026 08:25:49 +0900 Subject: [PATCH] docs: record TechLog backend alignment completion state Task 12 of the backend-alignment plan: document the TECH_LOG_STUDIO_SOURCE switch and the generate/check:tech-log-contract scripts in README.md, and record the spec's completion status (12/12 completion conditions met, the two explicitly-out-of-scope items restated, and the gate findings from the full verification pass) in the design doc's status section. No product code changed. --- README.md | 52 +++++++++++++++++++ ...-08-17-techlog-backend-alignment-design.md | 34 ++++++++++++ 2 files changed, 86 insertions(+) diff --git a/README.md b/README.md index 4f61cf6..9e5c62f 100644 --- a/README.md +++ b/README.md @@ -55,6 +55,58 @@ TECH_LOG_TARGET_URL=http://127.0.0.1:4174 \ corepack pnpm verify:tech-log-source-parity ``` +### Studio backend source + +`TECH_LOG_STUDIO_SOURCE` (`MOCK` | `HTTP`) selects which `StudioGateway` +adapter the composition root wires up. It defaults to `MOCK` — the +session-scoped in-memory Studio described above — so the existing Studio +workflow and its test suites are unaffected unless the switch is deliberately +turned on. Setting it to `HTTP` wires the HTTP `StudioGateway` instead, which +calls the canonical `@tech-log/studio-contract` operations against +`API_BASE_URL`. With no backend reachable at that URL, Studio still boots and +its shell renders; the specific panels that need the backend show an inline +"failed to load" state rather than a blank screen or an unhandled exception. + +The switch is a field on the versioned runtime config document +(`RuntimeConfigV2`), not a build-time flag: + +- `config/runtime/{local,development,staging,production}.json` are the + deployment profiles `corepack pnpm build` (via + `scripts/generate-runtime-config.ts`) materializes into `dist/config.json` + for a real build. +- `corepack pnpm dev` does not run that step. Plain `vite` serves + `public/config.json` (and `public/release-manifest.json`) verbatim as dev + fixtures — editing `config/runtime/local.json` alone has no effect on + `pnpm dev`. To exercise `HTTP` mode under `pnpm dev`, set + `TECH_LOG_STUDIO_SOURCE` in `public/config.json` directly. Switching to + `HTTP` also requires `public/release-manifest.json`'s `contractSet` to + declare the `@tech-log/studio-contract` package the build compiled in + (`.generated/frontend-runtime/contract-set.ts` after a build), or boot fails + closed earlier, at contract-set verification (`CONTRACT_SET_PACKAGE_MISSING`) + — itself a graceful, non-blank error screen, just not the one this switch is + usually used to exercise. + +### TechLog contract generation + +The Studio HTTP contract is vendored from a canonical OpenAPI source, not +hand-written: + +- `corepack pnpm generate:tech-log-contract` regenerates + `src/features/tech-log/contracts/studio/studio-api.openapi.yaml`, + `generated.ts`, and `canonical-source.json` from the canonical + `tech-log-design-package` repository (path from `TECH_LOG_DESIGN_PACKAGE`, + default `/home/donghyeon/workspace/tech-log-design-package`). It needs that + repository checked out locally and network access, because type generation + runs in an isolated `pnpm dlx` sandbox (this repo pins TypeScript 7, which + has no classic compiler API for `openapi-typescript` to use). Run it after + the canonical contract changes, then commit the regenerated files. +- `corepack pnpm check:tech-log-contract` is the drift gate: it hashes the + vendored yaml against the recorded digest and confirms every recorded + `operationId` is present in both the yaml and the generated types. It needs + neither the canonical repository nor the network, so it runs in CI and in + this sandbox. Run it any time to confirm the vendored contract has not + drifted from what was last generated. + ## Architecture Dependencies point inward: diff --git a/docs/superpowers/specs/2026-08-17-techlog-backend-alignment-design.md b/docs/superpowers/specs/2026-08-17-techlog-backend-alignment-design.md index bb1c9ea..e35308c 100644 --- a/docs/superpowers/specs/2026-08-17-techlog-backend-alignment-design.md +++ b/docs/superpowers/specs/2026-08-17-techlog-backend-alignment-design.md @@ -11,6 +11,40 @@ - 설계 패키지 revision `0ec5582` - 결정: 현재 Public/Studio UI 기준선을 고정하고, Studio 계약·전송 경계와 Asset capability를 canonical 계약에 정합시킨다. Public 조회의 HTTP 전환은 이 사이클에서 제외한다. +### Task 12 완료 상태 (2026-08-18) + +12개 Task 전부 `feature/techlog-backend-alignment`에 커밋됐다. 아래는 §완료 조건의 12개 항목을 Task 12 게이트 실행(전체 로그는 +`.superpowers/sdd/2026-08-17-techlog-backend-alignment/task-12-report.md`)과 Task 1–11이 기록한 구현 상태를 근거로 판정한 결과다. + +| # | 완료 조건 | 판정 | 근거 | +|---|---|---|---| +| 1 | 현재 Public UI·라우트가 변경되지 않는다 | 충족 | `check:architecture`, `check:registries` PASS; Public 화면 테스트(`public-document-screens.test.tsx` 등) 무변경 통과 | +| 2 | 현재 Studio 작업 흐름이 변경되지 않는다 | 충족 | 기본 `MOCK`에서 `test:tech-log`(36 files/303 tests) 전부 PASS; `tech-log-studio-workflow.spec.ts` chromium 2/2 PASS | +| 3 | Studio 계약이 canonical에서 생성되고 digest 고정·drift 게이트 동작 | 충족 | `check:tech-log-contract`: "in sync: @tech-log/studio-contract@2.0.0 (ce2e748), 19 operations" | +| 4 | `StudioGateway` 전체 operation이 HTTP 어댑터로 구현·MSW 검증 | 충족 | `test:unit`/`test:integration`의 HTTP·MSW 계약 스위트 PASS (환경 요인 실패 1건 제외, 아래 참고) | +| 5 | WorkingCopy 저장이 Public Projection을 변경하지 않는다 | 충족 | `studio-publication-flow.test.tsx`, `public-document-screens.test.tsx` PASS | +| 6 | Validation/Preview/Publish가 version·dependency revision으로 묶인다 | 충족 | `studio-validation-preview.test.tsx` PASS | +| 7 | Publication Event/Snapshot 조회 가능, 과거 Snapshot 불변 | 충족 | `studio-publication-flow.test.tsx` PASS | +| 8 | Image/SVG 업로드 + Asset 기반 evidence 삽입 | 충족 | Task 10/11 Asset Picker·업로드 다이얼로그·Asset Library; `test:tech-log` 내 asset 관련 스위트 PASS | +| 9 | `READY` Asset만 Preview/Publish에 사용, `QUARANTINED` 미노출 | 충족 | Task 6/9가 구현; 관련 렌더러·게이트 테스트 PASS | +| 10 | 23개 오류 코드 + idempotency/version 충돌 구분 | 충족 | `error-classification.test.ts` 등 PASS | +| 11 | 프론트가 Backend 도메인 Aggregate를 복제하지 않는다 | 충족 | `check:architecture` PASS (415 modules, 전 import 해석, 12개 회귀 fixture PASS) | +| 12 | 런타임 스위치 `MOCK`/`HTTP` 전환, 기본 `MOCK`에서 기존 parity 스위트 전부 통과 | 충족 | 위 1·2 근거 + 수동 확인: `TECH_LOG_STUDIO_SOURCE=HTTP`에서 Backend 부재 시 Studio 쉘은 정상 렌더되고 패널은 "작업 흐름을 불러오지 못했습니다" 인라인 오류로 우아하게 저하됨(백지·미처리 예외 없음) | + +명시적 비완료 항목 — 계획대로 이번 사이클에 포함되지 않는다: + +- **실행 중 Backend와의 실응답 대조**: 이 환경에 Backend가 없다. Task 12 수동 확인은 "Backend 부재 시 우아한 오류 상태"까지만 검증했고, 실제 Backend 응답과의 대조는 Backend Studio 구현 완료 후 별도로 수행한다. +- **Public 조회의 HTTP 전환**: 범위에서 명시적으로 제외됐다(§범위 "제외 — Public 조회의 HTTP 전환"). `adapters/static/public-query.ts`는 이번 사이클에서 손대지 않았고, `public-v1.yaml` 기준 별도 spec/plan 사이클로 수행한다. + +완료 조건 자체는 아니지만, 게이트 실행 중 확인된 사전 존재(pre-existing) 또는 환경적(environmental) 이슈: + +- `tests/unit/ci-artifact-contract.test.ts` 16개 테스트가 `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted` 샌드박스 제약으로 실패한다. 브랜치 분기점 `9e5fbd1`에서도 동일하게 재현되는 환경 문제이며 이번 작업과 무관하다. +- `test:coverage`는 위 환경 실패 때문에 vitest가 non-zero로 종료해 `check-risk-coverage.ts`까지 도달하지 못한다(vitest 기본값 `coverage.reportOnFailure: false`). 그 파일만 제외한 진단 실행에서는 `src/application/policies/compatibility.ts`(re-export전용, 계측 가능한 statement 0개)와 `reference-http-gateway.ts`(statements 86.95%/branches 85%, 임계값 90%) 2건이 걸리는데, 둘 다 병합 지점(`9e5fbd1`) 이후 이 브랜치가 건드리지 않은 파일이다. +- `test:visual`(chromium)에서 130개 중 18개가 실패한다. Studio 문서/미리보기/게시 화면과 일부 Public Case 화면의 스냅샷 높이가 커졌다(예: 1440×2706 → 1440×2999) — evidence figure가 이제 실제 backend Asset 크기로 렌더되기 때문으로 보이며(Task 9), 골든 스냅샷 갱신 여부는 리뷰 판단이 필요해 이번 Task에서 임의로 갱신하지 않았다. +- `test:e2e`/`test:a11y`는 chromium에서 전부 통과하고, firefox/webkit 실패는 이 환경의 브라우저 의존성 문제다(firefox: Pretendard 폰트의 "name records not sorted" 경고를 strict 콘솔 검사가 실패로 잡음; webkit: 호스트에 필요한 시스템 라이브러리 없음 — `playwright install-deps` 필요). + +전체 명령·원문 출력은 `.superpowers/sdd/2026-08-17-techlog-backend-alignment/task-12-report.md`에 기록했다. + ## 목적 현재 TechLog 프론트엔드는 Studio를 세션 수명 `MockStudioGateway`로, Public을 정적 동기 catalog로 구동한다. 이 설계는 다음을 달성한다.