From 99e76e87220e4c6d9f8e683025a2cf2a516b10fa Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 8 Nov 2026 16:56:47 +0900 Subject: [PATCH 01/18] =?UTF-8?q?docs:=20=EA=B8=B0=EB=A1=9D=C2=B7=EC=84=A4?= =?UTF-8?q?=EA=B3=84=EC=84=9C=C2=B7=EA=B2=B0=EC=A0=95=20=EA=B8=B0=EB=A1=9D?= =?UTF-8?q?=EC=9D=84=20docs/history=C2=B7docs/design=C2=B7docs/adr?= =?UTF-8?q?=EB=A1=9C=20=EC=98=AE=EA=B8=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 프론트 docs/는 지금 동작을 설명하는 문서와 쓴 때의 기록이 한 폴더에 섞여 있다. docs/architecture/에는 현재 계약 10개와 목표 설계 14개, 결정 기록 VD 23개가 같이 있고, 설계서·계획서는 플러그인 이름 폴더(docs/superpowers/)에 있다. 문서 체계 규칙(design-docs conventions/docs-system.md v1, 2026-11-07 소유자 결정)은 수명으로 나누고 폴더 이름을 백엔드와 같게 하라고 정한다. 고른 방법: 내용 변경 없이 git mv만 담는다. git이 이름 바뀜을 알아보고 리뷰어가 이동과 내용 변경을 따로 볼 수 있게 하려는 것이다. 참조 수정과 머리 블록은 다음 커밋들이 한다. - docs/superpowers/specs → docs/design/, plans → docs/history/plans/ - docs/architecture/ 목표 설계 13개와 styling·testing의 목표 설계 2개 → docs/design/<작성일>-<이름>-design.md (2026-07-30 결정 정본은 이름 그대로) - docs/architecture/decisions/VD-* → docs/adr/ (번호 유지) 위험: 이 커밋만으로는 옮긴 문서를 가리키는 링크와 경로가 깨진다. 다음 커밋이 고친다. 게이트가 읽는 파일(review-ledger.json, review-evidence.md, adapter-remediation-ledger.md, INVENTORY.md)은 옮기지 않았다. docs/history/는 복사한 프로젝트가 지워도 된다는 약속 (tests/unit/deletable-history-documents.test.ts)이 있어서 코드가 읽는 파일을 둘 수 없다. SPEC.md는 공통 완료 기준을 매뉴얼로 옮긴 뒤 따로 옮긴다. 검증: git status가 이름 바뀜(R) 66개만 보인다. --- .../decisions => adr}/VD-01-typescript-lint-tooling.md | 0 .../decisions => adr}/VD-03-react-router-data-mode.md | 0 docs/{architecture/decisions => adr}/VD-04-native-form-facade.md | 0 .../{architecture/decisions => adr}/VD-05-icon-and-headless-ui.md | 0 .../decisions => adr}/VD-06-intl-typed-message-catalog.md | 0 .../decisions => adr}/VD-07-diagnostics-and-telemetry-exporter.md | 0 .../decisions => adr}/VD-08-storybook-and-visual-evidence.md | 0 .../decisions => adr}/VD-09-supply-chain-evidence.md | 0 .../decisions => adr}/VD-10-optional-capability-recipes.md | 0 .../decisions => adr}/VD-11-browser-file-and-origin-storage.md | 0 .../decisions => adr}/VD-12-presigned-transfer-and-image-cdn.md | 0 .../decisions => adr}/VD-13-client-cache-scope-and-persistence.md | 0 .../VD-14-resumable-download-and-background-transfer.md | 0 .../VD-15-origin-storage-lifecycle-and-migration.md | 0 .../VD-16-browser-transfer-composition-and-image-delivery.md | 0 .../VD-23-api-transport-selection-and-rest-execution.md | 0 .../decisions => adr}/VD-24-runtime-schema-and-boundary-mapper.md | 0 .../decisions => adr}/VD-25-server-state-cache-lifecycle.md | 0 .../decisions => adr}/VD-26-persisted-graphql-operation.md | 0 .../decisions => adr}/VD-27-grpc-web-unary-and-server-stream.md | 0 .../VD-28-realtime-events-web-push-and-bounded-polling.md | 0 .../VD-29-connect-web-and-browser-protobuf-runtime.md | 0 .../decisions => adr}/VD-30-protobuf-contract-and-rest-gateway.md | 0 .../2026-07-26-design-system-platform-design.md} | 0 .../2026-07-26-frontend-platform-capability-review-design.md} | 0 ...2026-07-26-frontend-platform-implementation-roadmap-design.md} | 0 .../2026-07-26-frontend-platform-testing-strategy-design.md} | 0 .../2026-07-26-frontend-ports-adapters-and-boundaries-design.md} | 0 .../2026-07-26-routing-pages-and-patterns-design.md} | 0 .../2026-07-26-typescript-state-and-data-flow-design.md} | 0 .../2026-07-27-browser-file-and-origin-storage-design.md} | 0 ...6-07-28-api-contract-schema-mapper-and-server-state-design.md} | 0 .../2026-07-28-client-cache-and-storage-design.md} | 0 ...6-07-28-protobuf-browser-transport-and-rest-gateway-design.md} | 0 .../2026-07-28-server-file-capability-infrastructure-design.md} | 0 ...026-07-30-browser-data-capability-completion-ledger-design.md} | 0 ...bility-repository-aligned-implementation-closed-deep-design.md | 0 .../2026-07-30-presigned-transfer-and-image-cdn-design.md} | 0 ...-07-30-realtime-events-web-push-and-bounded-polling-design.md} | 0 .../specs => design}/2026-07-31-platform-overview-page-design.md | 0 .../2026-08-01-refactoring-review-remediation-design.md | 0 .../2026-08-01-runtime-integrity-refactor-design.md | 0 ...026-08-02-platform-owned-frontend-assurance-delivery-design.md | 0 .../specs => design}/2026-08-02-provider-raw-guardian-design.md | 0 .../2026-08-02-v8-coverage-counter-contract-design.md | 0 .../specs => design}/2026-09-16-adapter-barrel-boundary-design.md | 0 .../2026-09-16-indexeddb-kernel-promotion-design.md | 0 .../2026-09-20-memento-frontend-template-bootstrap-design.md | 0 .../plans/2026-07-31-platform-overview-completion.md | 0 .../plans/2026-08-01-http-worker-adapter-remediation.md | 0 .../plans/2026-08-01-quality-architecture-remediation.md | 0 .../plans/2026-08-01-release-boot-integrity.md | 0 .../plans/2026-08-01-release-evidence-remediation.md | 0 .../plans/2026-08-01-runtime-correctness-remediation.md | 0 .../plans/2026-08-01-scope-owned-server-state.md | 0 .../plans/2026-08-02-cicd-frontend-assurance-delivery.md | 0 .../plans/2026-08-02-counter-bearing-coverage-provenance.md | 0 .../plans/2026-08-02-frontend-platform-consumer-migration.md | 0 .../plans/2026-08-02-promotion-security-review-fixes.md | 0 .../plans/2026-08-02-provider-raw-guardian.md | 0 .../plans/2026-08-02-security-finalizer.md | 0 .../plans/2026-08-02-test-assurance-frontend-capabilities.md | 0 .../plans/2026-08-02-v8-coverage-counter-contract.md | 0 .../plans/2026-08-13-adapter-remediation.md | 0 .../plans/2026-09-16-adapter-barrel-boundary.md | 0 .../plans/2026-09-16-indexeddb-kernel-promotion.md | 0 66 files changed, 0 insertions(+), 0 deletions(-) rename docs/{architecture/decisions => adr}/VD-01-typescript-lint-tooling.md (100%) rename docs/{architecture/decisions => adr}/VD-03-react-router-data-mode.md (100%) rename docs/{architecture/decisions => adr}/VD-04-native-form-facade.md (100%) rename docs/{architecture/decisions => adr}/VD-05-icon-and-headless-ui.md (100%) rename docs/{architecture/decisions => adr}/VD-06-intl-typed-message-catalog.md (100%) rename docs/{architecture/decisions => adr}/VD-07-diagnostics-and-telemetry-exporter.md (100%) rename docs/{architecture/decisions => adr}/VD-08-storybook-and-visual-evidence.md (100%) rename docs/{architecture/decisions => adr}/VD-09-supply-chain-evidence.md (100%) rename docs/{architecture/decisions => adr}/VD-10-optional-capability-recipes.md (100%) rename docs/{architecture/decisions => adr}/VD-11-browser-file-and-origin-storage.md (100%) rename docs/{architecture/decisions => adr}/VD-12-presigned-transfer-and-image-cdn.md (100%) rename docs/{architecture/decisions => adr}/VD-13-client-cache-scope-and-persistence.md (100%) rename docs/{architecture/decisions => adr}/VD-14-resumable-download-and-background-transfer.md (100%) rename docs/{architecture/decisions => adr}/VD-15-origin-storage-lifecycle-and-migration.md (100%) rename docs/{architecture/decisions => adr}/VD-16-browser-transfer-composition-and-image-delivery.md (100%) rename docs/{architecture/decisions => adr}/VD-23-api-transport-selection-and-rest-execution.md (100%) rename docs/{architecture/decisions => adr}/VD-24-runtime-schema-and-boundary-mapper.md (100%) rename docs/{architecture/decisions => adr}/VD-25-server-state-cache-lifecycle.md (100%) rename docs/{architecture/decisions => adr}/VD-26-persisted-graphql-operation.md (100%) rename docs/{architecture/decisions => adr}/VD-27-grpc-web-unary-and-server-stream.md (100%) rename docs/{architecture/decisions => adr}/VD-28-realtime-events-web-push-and-bounded-polling.md (100%) rename docs/{architecture/decisions => adr}/VD-29-connect-web-and-browser-protobuf-runtime.md (100%) rename docs/{architecture/decisions => adr}/VD-30-protobuf-contract-and-rest-gateway.md (100%) rename docs/{styling/design-system-platform.md => design/2026-07-26-design-system-platform-design.md} (100%) rename docs/{architecture/frontend-platform-capability-review.md => design/2026-07-26-frontend-platform-capability-review-design.md} (100%) rename docs/{architecture/frontend-platform-implementation-roadmap.md => design/2026-07-26-frontend-platform-implementation-roadmap-design.md} (100%) rename docs/{testing/frontend-platform-testing-strategy.md => design/2026-07-26-frontend-platform-testing-strategy-design.md} (100%) rename docs/{architecture/frontend-ports-adapters-and-boundaries.md => design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md} (100%) rename docs/{architecture/routing-pages-and-patterns.md => design/2026-07-26-routing-pages-and-patterns-design.md} (100%) rename docs/{architecture/typescript-state-and-data-flow.md => design/2026-07-26-typescript-state-and-data-flow-design.md} (100%) rename docs/{architecture/browser-file-and-origin-storage.md => design/2026-07-27-browser-file-and-origin-storage-design.md} (100%) rename docs/{architecture/api-contract-schema-mapper-and-server-state.md => design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md} (100%) rename docs/{architecture/client-cache-and-storage.md => design/2026-07-28-client-cache-and-storage-design.md} (100%) rename docs/{architecture/protobuf-browser-transport-and-rest-gateway.md => design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md} (100%) rename docs/{architecture/server-file-capability-infrastructure.md => design/2026-07-28-server-file-capability-infrastructure-design.md} (100%) rename docs/{architecture/browser-data-capability-completion-ledger.md => design/2026-07-30-browser-data-capability-completion-ledger-design.md} (100%) rename docs/{architecture => design}/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md (100%) rename docs/{architecture/presigned-transfer-and-image-cdn.md => design/2026-07-30-presigned-transfer-and-image-cdn-design.md} (100%) rename docs/{architecture/realtime-events-web-push-and-bounded-polling.md => design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md} (100%) rename docs/{superpowers/specs => design}/2026-07-31-platform-overview-page-design.md (100%) rename docs/{superpowers/specs => design}/2026-08-01-refactoring-review-remediation-design.md (100%) rename docs/{superpowers/specs => design}/2026-08-01-runtime-integrity-refactor-design.md (100%) rename docs/{superpowers/specs => design}/2026-08-02-platform-owned-frontend-assurance-delivery-design.md (100%) rename docs/{superpowers/specs => design}/2026-08-02-provider-raw-guardian-design.md (100%) rename docs/{superpowers/specs => design}/2026-08-02-v8-coverage-counter-contract-design.md (100%) rename docs/{superpowers/specs => design}/2026-09-16-adapter-barrel-boundary-design.md (100%) rename docs/{superpowers/specs => design}/2026-09-16-indexeddb-kernel-promotion-design.md (100%) rename docs/{superpowers/specs => design}/2026-09-20-memento-frontend-template-bootstrap-design.md (100%) rename docs/{superpowers => history}/plans/2026-07-31-platform-overview-completion.md (100%) rename docs/{superpowers => history}/plans/2026-08-01-http-worker-adapter-remediation.md (100%) rename docs/{superpowers => history}/plans/2026-08-01-quality-architecture-remediation.md (100%) rename docs/{superpowers => history}/plans/2026-08-01-release-boot-integrity.md (100%) rename docs/{superpowers => history}/plans/2026-08-01-release-evidence-remediation.md (100%) rename docs/{superpowers => history}/plans/2026-08-01-runtime-correctness-remediation.md (100%) rename docs/{superpowers => history}/plans/2026-08-01-scope-owned-server-state.md (100%) rename docs/{superpowers => history}/plans/2026-08-02-cicd-frontend-assurance-delivery.md (100%) rename docs/{superpowers => history}/plans/2026-08-02-counter-bearing-coverage-provenance.md (100%) rename docs/{superpowers => history}/plans/2026-08-02-frontend-platform-consumer-migration.md (100%) rename docs/{superpowers => history}/plans/2026-08-02-promotion-security-review-fixes.md (100%) rename docs/{superpowers => history}/plans/2026-08-02-provider-raw-guardian.md (100%) rename docs/{superpowers => history}/plans/2026-08-02-security-finalizer.md (100%) rename docs/{superpowers => history}/plans/2026-08-02-test-assurance-frontend-capabilities.md (100%) rename docs/{superpowers => history}/plans/2026-08-02-v8-coverage-counter-contract.md (100%) rename docs/{superpowers => history}/plans/2026-08-13-adapter-remediation.md (100%) rename docs/{superpowers => history}/plans/2026-09-16-adapter-barrel-boundary.md (100%) rename docs/{superpowers => history}/plans/2026-09-16-indexeddb-kernel-promotion.md (100%) diff --git a/docs/architecture/decisions/VD-01-typescript-lint-tooling.md b/docs/adr/VD-01-typescript-lint-tooling.md similarity index 100% rename from docs/architecture/decisions/VD-01-typescript-lint-tooling.md rename to docs/adr/VD-01-typescript-lint-tooling.md diff --git a/docs/architecture/decisions/VD-03-react-router-data-mode.md b/docs/adr/VD-03-react-router-data-mode.md similarity index 100% rename from docs/architecture/decisions/VD-03-react-router-data-mode.md rename to docs/adr/VD-03-react-router-data-mode.md diff --git a/docs/architecture/decisions/VD-04-native-form-facade.md b/docs/adr/VD-04-native-form-facade.md similarity index 100% rename from docs/architecture/decisions/VD-04-native-form-facade.md rename to docs/adr/VD-04-native-form-facade.md diff --git a/docs/architecture/decisions/VD-05-icon-and-headless-ui.md b/docs/adr/VD-05-icon-and-headless-ui.md similarity index 100% rename from docs/architecture/decisions/VD-05-icon-and-headless-ui.md rename to docs/adr/VD-05-icon-and-headless-ui.md diff --git a/docs/architecture/decisions/VD-06-intl-typed-message-catalog.md b/docs/adr/VD-06-intl-typed-message-catalog.md similarity index 100% rename from docs/architecture/decisions/VD-06-intl-typed-message-catalog.md rename to docs/adr/VD-06-intl-typed-message-catalog.md diff --git a/docs/architecture/decisions/VD-07-diagnostics-and-telemetry-exporter.md b/docs/adr/VD-07-diagnostics-and-telemetry-exporter.md similarity index 100% rename from docs/architecture/decisions/VD-07-diagnostics-and-telemetry-exporter.md rename to docs/adr/VD-07-diagnostics-and-telemetry-exporter.md diff --git a/docs/architecture/decisions/VD-08-storybook-and-visual-evidence.md b/docs/adr/VD-08-storybook-and-visual-evidence.md similarity index 100% rename from docs/architecture/decisions/VD-08-storybook-and-visual-evidence.md rename to docs/adr/VD-08-storybook-and-visual-evidence.md diff --git a/docs/architecture/decisions/VD-09-supply-chain-evidence.md b/docs/adr/VD-09-supply-chain-evidence.md similarity index 100% rename from docs/architecture/decisions/VD-09-supply-chain-evidence.md rename to docs/adr/VD-09-supply-chain-evidence.md diff --git a/docs/architecture/decisions/VD-10-optional-capability-recipes.md b/docs/adr/VD-10-optional-capability-recipes.md similarity index 100% rename from docs/architecture/decisions/VD-10-optional-capability-recipes.md rename to docs/adr/VD-10-optional-capability-recipes.md diff --git a/docs/architecture/decisions/VD-11-browser-file-and-origin-storage.md b/docs/adr/VD-11-browser-file-and-origin-storage.md similarity index 100% rename from docs/architecture/decisions/VD-11-browser-file-and-origin-storage.md rename to docs/adr/VD-11-browser-file-and-origin-storage.md diff --git a/docs/architecture/decisions/VD-12-presigned-transfer-and-image-cdn.md b/docs/adr/VD-12-presigned-transfer-and-image-cdn.md similarity index 100% rename from docs/architecture/decisions/VD-12-presigned-transfer-and-image-cdn.md rename to docs/adr/VD-12-presigned-transfer-and-image-cdn.md diff --git a/docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md b/docs/adr/VD-13-client-cache-scope-and-persistence.md similarity index 100% rename from docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md rename to docs/adr/VD-13-client-cache-scope-and-persistence.md diff --git a/docs/architecture/decisions/VD-14-resumable-download-and-background-transfer.md b/docs/adr/VD-14-resumable-download-and-background-transfer.md similarity index 100% rename from docs/architecture/decisions/VD-14-resumable-download-and-background-transfer.md rename to docs/adr/VD-14-resumable-download-and-background-transfer.md diff --git a/docs/architecture/decisions/VD-15-origin-storage-lifecycle-and-migration.md b/docs/adr/VD-15-origin-storage-lifecycle-and-migration.md similarity index 100% rename from docs/architecture/decisions/VD-15-origin-storage-lifecycle-and-migration.md rename to docs/adr/VD-15-origin-storage-lifecycle-and-migration.md diff --git a/docs/architecture/decisions/VD-16-browser-transfer-composition-and-image-delivery.md b/docs/adr/VD-16-browser-transfer-composition-and-image-delivery.md similarity index 100% rename from docs/architecture/decisions/VD-16-browser-transfer-composition-and-image-delivery.md rename to docs/adr/VD-16-browser-transfer-composition-and-image-delivery.md diff --git a/docs/architecture/decisions/VD-23-api-transport-selection-and-rest-execution.md b/docs/adr/VD-23-api-transport-selection-and-rest-execution.md similarity index 100% rename from docs/architecture/decisions/VD-23-api-transport-selection-and-rest-execution.md rename to docs/adr/VD-23-api-transport-selection-and-rest-execution.md diff --git a/docs/architecture/decisions/VD-24-runtime-schema-and-boundary-mapper.md b/docs/adr/VD-24-runtime-schema-and-boundary-mapper.md similarity index 100% rename from docs/architecture/decisions/VD-24-runtime-schema-and-boundary-mapper.md rename to docs/adr/VD-24-runtime-schema-and-boundary-mapper.md diff --git a/docs/architecture/decisions/VD-25-server-state-cache-lifecycle.md b/docs/adr/VD-25-server-state-cache-lifecycle.md similarity index 100% rename from docs/architecture/decisions/VD-25-server-state-cache-lifecycle.md rename to docs/adr/VD-25-server-state-cache-lifecycle.md diff --git a/docs/architecture/decisions/VD-26-persisted-graphql-operation.md b/docs/adr/VD-26-persisted-graphql-operation.md similarity index 100% rename from docs/architecture/decisions/VD-26-persisted-graphql-operation.md rename to docs/adr/VD-26-persisted-graphql-operation.md diff --git a/docs/architecture/decisions/VD-27-grpc-web-unary-and-server-stream.md b/docs/adr/VD-27-grpc-web-unary-and-server-stream.md similarity index 100% rename from docs/architecture/decisions/VD-27-grpc-web-unary-and-server-stream.md rename to docs/adr/VD-27-grpc-web-unary-and-server-stream.md diff --git a/docs/architecture/decisions/VD-28-realtime-events-web-push-and-bounded-polling.md b/docs/adr/VD-28-realtime-events-web-push-and-bounded-polling.md similarity index 100% rename from docs/architecture/decisions/VD-28-realtime-events-web-push-and-bounded-polling.md rename to docs/adr/VD-28-realtime-events-web-push-and-bounded-polling.md diff --git a/docs/architecture/decisions/VD-29-connect-web-and-browser-protobuf-runtime.md b/docs/adr/VD-29-connect-web-and-browser-protobuf-runtime.md similarity index 100% rename from docs/architecture/decisions/VD-29-connect-web-and-browser-protobuf-runtime.md rename to docs/adr/VD-29-connect-web-and-browser-protobuf-runtime.md diff --git a/docs/architecture/decisions/VD-30-protobuf-contract-and-rest-gateway.md b/docs/adr/VD-30-protobuf-contract-and-rest-gateway.md similarity index 100% rename from docs/architecture/decisions/VD-30-protobuf-contract-and-rest-gateway.md rename to docs/adr/VD-30-protobuf-contract-and-rest-gateway.md diff --git a/docs/styling/design-system-platform.md b/docs/design/2026-07-26-design-system-platform-design.md similarity index 100% rename from docs/styling/design-system-platform.md rename to docs/design/2026-07-26-design-system-platform-design.md diff --git a/docs/architecture/frontend-platform-capability-review.md b/docs/design/2026-07-26-frontend-platform-capability-review-design.md similarity index 100% rename from docs/architecture/frontend-platform-capability-review.md rename to docs/design/2026-07-26-frontend-platform-capability-review-design.md diff --git a/docs/architecture/frontend-platform-implementation-roadmap.md b/docs/design/2026-07-26-frontend-platform-implementation-roadmap-design.md similarity index 100% rename from docs/architecture/frontend-platform-implementation-roadmap.md rename to docs/design/2026-07-26-frontend-platform-implementation-roadmap-design.md diff --git a/docs/testing/frontend-platform-testing-strategy.md b/docs/design/2026-07-26-frontend-platform-testing-strategy-design.md similarity index 100% rename from docs/testing/frontend-platform-testing-strategy.md rename to docs/design/2026-07-26-frontend-platform-testing-strategy-design.md diff --git a/docs/architecture/frontend-ports-adapters-and-boundaries.md b/docs/design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md similarity index 100% rename from docs/architecture/frontend-ports-adapters-and-boundaries.md rename to docs/design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md diff --git a/docs/architecture/routing-pages-and-patterns.md b/docs/design/2026-07-26-routing-pages-and-patterns-design.md similarity index 100% rename from docs/architecture/routing-pages-and-patterns.md rename to docs/design/2026-07-26-routing-pages-and-patterns-design.md diff --git a/docs/architecture/typescript-state-and-data-flow.md b/docs/design/2026-07-26-typescript-state-and-data-flow-design.md similarity index 100% rename from docs/architecture/typescript-state-and-data-flow.md rename to docs/design/2026-07-26-typescript-state-and-data-flow-design.md diff --git a/docs/architecture/browser-file-and-origin-storage.md b/docs/design/2026-07-27-browser-file-and-origin-storage-design.md similarity index 100% rename from docs/architecture/browser-file-and-origin-storage.md rename to docs/design/2026-07-27-browser-file-and-origin-storage-design.md diff --git a/docs/architecture/api-contract-schema-mapper-and-server-state.md b/docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md similarity index 100% rename from docs/architecture/api-contract-schema-mapper-and-server-state.md rename to docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md diff --git a/docs/architecture/client-cache-and-storage.md b/docs/design/2026-07-28-client-cache-and-storage-design.md similarity index 100% rename from docs/architecture/client-cache-and-storage.md rename to docs/design/2026-07-28-client-cache-and-storage-design.md diff --git a/docs/architecture/protobuf-browser-transport-and-rest-gateway.md b/docs/design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md similarity index 100% rename from docs/architecture/protobuf-browser-transport-and-rest-gateway.md rename to docs/design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md diff --git a/docs/architecture/server-file-capability-infrastructure.md b/docs/design/2026-07-28-server-file-capability-infrastructure-design.md similarity index 100% rename from docs/architecture/server-file-capability-infrastructure.md rename to docs/design/2026-07-28-server-file-capability-infrastructure-design.md diff --git a/docs/architecture/browser-data-capability-completion-ledger.md b/docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md similarity index 100% rename from docs/architecture/browser-data-capability-completion-ledger.md rename to docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md diff --git a/docs/architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md b/docs/design/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md similarity index 100% rename from docs/architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md rename to docs/design/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md diff --git a/docs/architecture/presigned-transfer-and-image-cdn.md b/docs/design/2026-07-30-presigned-transfer-and-image-cdn-design.md similarity index 100% rename from docs/architecture/presigned-transfer-and-image-cdn.md rename to docs/design/2026-07-30-presigned-transfer-and-image-cdn-design.md diff --git a/docs/architecture/realtime-events-web-push-and-bounded-polling.md b/docs/design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md similarity index 100% rename from docs/architecture/realtime-events-web-push-and-bounded-polling.md rename to docs/design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md diff --git a/docs/superpowers/specs/2026-07-31-platform-overview-page-design.md b/docs/design/2026-07-31-platform-overview-page-design.md similarity index 100% rename from docs/superpowers/specs/2026-07-31-platform-overview-page-design.md rename to docs/design/2026-07-31-platform-overview-page-design.md diff --git a/docs/superpowers/specs/2026-08-01-refactoring-review-remediation-design.md b/docs/design/2026-08-01-refactoring-review-remediation-design.md similarity index 100% rename from docs/superpowers/specs/2026-08-01-refactoring-review-remediation-design.md rename to docs/design/2026-08-01-refactoring-review-remediation-design.md diff --git a/docs/superpowers/specs/2026-08-01-runtime-integrity-refactor-design.md b/docs/design/2026-08-01-runtime-integrity-refactor-design.md similarity index 100% rename from docs/superpowers/specs/2026-08-01-runtime-integrity-refactor-design.md rename to docs/design/2026-08-01-runtime-integrity-refactor-design.md diff --git a/docs/superpowers/specs/2026-08-02-platform-owned-frontend-assurance-delivery-design.md b/docs/design/2026-08-02-platform-owned-frontend-assurance-delivery-design.md similarity index 100% rename from docs/superpowers/specs/2026-08-02-platform-owned-frontend-assurance-delivery-design.md rename to docs/design/2026-08-02-platform-owned-frontend-assurance-delivery-design.md diff --git a/docs/superpowers/specs/2026-08-02-provider-raw-guardian-design.md b/docs/design/2026-08-02-provider-raw-guardian-design.md similarity index 100% rename from docs/superpowers/specs/2026-08-02-provider-raw-guardian-design.md rename to docs/design/2026-08-02-provider-raw-guardian-design.md diff --git a/docs/superpowers/specs/2026-08-02-v8-coverage-counter-contract-design.md b/docs/design/2026-08-02-v8-coverage-counter-contract-design.md similarity index 100% rename from docs/superpowers/specs/2026-08-02-v8-coverage-counter-contract-design.md rename to docs/design/2026-08-02-v8-coverage-counter-contract-design.md diff --git a/docs/superpowers/specs/2026-09-16-adapter-barrel-boundary-design.md b/docs/design/2026-09-16-adapter-barrel-boundary-design.md similarity index 100% rename from docs/superpowers/specs/2026-09-16-adapter-barrel-boundary-design.md rename to docs/design/2026-09-16-adapter-barrel-boundary-design.md diff --git a/docs/superpowers/specs/2026-09-16-indexeddb-kernel-promotion-design.md b/docs/design/2026-09-16-indexeddb-kernel-promotion-design.md similarity index 100% rename from docs/superpowers/specs/2026-09-16-indexeddb-kernel-promotion-design.md rename to docs/design/2026-09-16-indexeddb-kernel-promotion-design.md diff --git a/docs/superpowers/specs/2026-09-20-memento-frontend-template-bootstrap-design.md b/docs/design/2026-09-20-memento-frontend-template-bootstrap-design.md similarity index 100% rename from docs/superpowers/specs/2026-09-20-memento-frontend-template-bootstrap-design.md rename to docs/design/2026-09-20-memento-frontend-template-bootstrap-design.md diff --git a/docs/superpowers/plans/2026-07-31-platform-overview-completion.md b/docs/history/plans/2026-07-31-platform-overview-completion.md similarity index 100% rename from docs/superpowers/plans/2026-07-31-platform-overview-completion.md rename to docs/history/plans/2026-07-31-platform-overview-completion.md diff --git a/docs/superpowers/plans/2026-08-01-http-worker-adapter-remediation.md b/docs/history/plans/2026-08-01-http-worker-adapter-remediation.md similarity index 100% rename from docs/superpowers/plans/2026-08-01-http-worker-adapter-remediation.md rename to docs/history/plans/2026-08-01-http-worker-adapter-remediation.md diff --git a/docs/superpowers/plans/2026-08-01-quality-architecture-remediation.md b/docs/history/plans/2026-08-01-quality-architecture-remediation.md similarity index 100% rename from docs/superpowers/plans/2026-08-01-quality-architecture-remediation.md rename to docs/history/plans/2026-08-01-quality-architecture-remediation.md diff --git a/docs/superpowers/plans/2026-08-01-release-boot-integrity.md b/docs/history/plans/2026-08-01-release-boot-integrity.md similarity index 100% rename from docs/superpowers/plans/2026-08-01-release-boot-integrity.md rename to docs/history/plans/2026-08-01-release-boot-integrity.md diff --git a/docs/superpowers/plans/2026-08-01-release-evidence-remediation.md b/docs/history/plans/2026-08-01-release-evidence-remediation.md similarity index 100% rename from docs/superpowers/plans/2026-08-01-release-evidence-remediation.md rename to docs/history/plans/2026-08-01-release-evidence-remediation.md diff --git a/docs/superpowers/plans/2026-08-01-runtime-correctness-remediation.md b/docs/history/plans/2026-08-01-runtime-correctness-remediation.md similarity index 100% rename from docs/superpowers/plans/2026-08-01-runtime-correctness-remediation.md rename to docs/history/plans/2026-08-01-runtime-correctness-remediation.md diff --git a/docs/superpowers/plans/2026-08-01-scope-owned-server-state.md b/docs/history/plans/2026-08-01-scope-owned-server-state.md similarity index 100% rename from docs/superpowers/plans/2026-08-01-scope-owned-server-state.md rename to docs/history/plans/2026-08-01-scope-owned-server-state.md diff --git a/docs/superpowers/plans/2026-08-02-cicd-frontend-assurance-delivery.md b/docs/history/plans/2026-08-02-cicd-frontend-assurance-delivery.md similarity index 100% rename from docs/superpowers/plans/2026-08-02-cicd-frontend-assurance-delivery.md rename to docs/history/plans/2026-08-02-cicd-frontend-assurance-delivery.md diff --git a/docs/superpowers/plans/2026-08-02-counter-bearing-coverage-provenance.md b/docs/history/plans/2026-08-02-counter-bearing-coverage-provenance.md similarity index 100% rename from docs/superpowers/plans/2026-08-02-counter-bearing-coverage-provenance.md rename to docs/history/plans/2026-08-02-counter-bearing-coverage-provenance.md diff --git a/docs/superpowers/plans/2026-08-02-frontend-platform-consumer-migration.md b/docs/history/plans/2026-08-02-frontend-platform-consumer-migration.md similarity index 100% rename from docs/superpowers/plans/2026-08-02-frontend-platform-consumer-migration.md rename to docs/history/plans/2026-08-02-frontend-platform-consumer-migration.md diff --git a/docs/superpowers/plans/2026-08-02-promotion-security-review-fixes.md b/docs/history/plans/2026-08-02-promotion-security-review-fixes.md similarity index 100% rename from docs/superpowers/plans/2026-08-02-promotion-security-review-fixes.md rename to docs/history/plans/2026-08-02-promotion-security-review-fixes.md diff --git a/docs/superpowers/plans/2026-08-02-provider-raw-guardian.md b/docs/history/plans/2026-08-02-provider-raw-guardian.md similarity index 100% rename from docs/superpowers/plans/2026-08-02-provider-raw-guardian.md rename to docs/history/plans/2026-08-02-provider-raw-guardian.md diff --git a/docs/superpowers/plans/2026-08-02-security-finalizer.md b/docs/history/plans/2026-08-02-security-finalizer.md similarity index 100% rename from docs/superpowers/plans/2026-08-02-security-finalizer.md rename to docs/history/plans/2026-08-02-security-finalizer.md diff --git a/docs/superpowers/plans/2026-08-02-test-assurance-frontend-capabilities.md b/docs/history/plans/2026-08-02-test-assurance-frontend-capabilities.md similarity index 100% rename from docs/superpowers/plans/2026-08-02-test-assurance-frontend-capabilities.md rename to docs/history/plans/2026-08-02-test-assurance-frontend-capabilities.md diff --git a/docs/superpowers/plans/2026-08-02-v8-coverage-counter-contract.md b/docs/history/plans/2026-08-02-v8-coverage-counter-contract.md similarity index 100% rename from docs/superpowers/plans/2026-08-02-v8-coverage-counter-contract.md rename to docs/history/plans/2026-08-02-v8-coverage-counter-contract.md diff --git a/docs/superpowers/plans/2026-08-13-adapter-remediation.md b/docs/history/plans/2026-08-13-adapter-remediation.md similarity index 100% rename from docs/superpowers/plans/2026-08-13-adapter-remediation.md rename to docs/history/plans/2026-08-13-adapter-remediation.md diff --git a/docs/superpowers/plans/2026-09-16-adapter-barrel-boundary.md b/docs/history/plans/2026-09-16-adapter-barrel-boundary.md similarity index 100% rename from docs/superpowers/plans/2026-09-16-adapter-barrel-boundary.md rename to docs/history/plans/2026-09-16-adapter-barrel-boundary.md diff --git a/docs/superpowers/plans/2026-09-16-indexeddb-kernel-promotion.md b/docs/history/plans/2026-09-16-indexeddb-kernel-promotion.md similarity index 100% rename from docs/superpowers/plans/2026-09-16-indexeddb-kernel-promotion.md rename to docs/history/plans/2026-09-16-indexeddb-kernel-promotion.md From e632b230e3f7beafb095b2d83aa2959b585616a8 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 8 Nov 2026 16:57:58 +0900 Subject: [PATCH 02/18] =?UTF-8?q?docs:=20=EC=98=AE=EA=B8=B4=20=EB=AC=B8?= =?UTF-8?q?=EC=84=9C=EB=A5=BC=20=EA=B0=80=EB=A6=AC=ED=82=A4=EB=8A=94=20?= =?UTF-8?q?=EB=A7=81=ED=81=AC=EC=99=80=20=EA=B2=BD=EB=A1=9C=EB=A5=BC=20?= =?UTF-8?q?=EC=83=88=20=EC=9C=84=EC=B9=98=EB=A1=9C=20=EA=B3=A0=EC=B9=9C?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 앞 커밋이 기록·설계서·결정 기록을 옮겨서, 그 문서를 가리키는 상대 링크 182개와 살아 있는 문서·코드 주석의 경로 23곳이 없는 곳을 가리킨다. 고른 방법: 기계적으로 바꾼다. - 상대 링크: 모든 .md(기록 포함)에서 옮기기 전 트리로 대상을 풀고, 대상이나 문서 자신이 옮겨졌으면 새 위치 기준 상대 경로로 다시 쓴다. 옮기기 전에도 없던 대상은 건드리지 않는다. 기록 본문에서 고친 것은 링크 대상뿐이다(백엔드 1단계와 같은 예외). - 경로 글자: 살아 있는 문서와 코드·설정 주석의 `docs/architecture/…`, `docs/superpowers/…`, `decisions/VD-…`를 새 경로로 바꾼다. 기록 본문과 CHANGELOG.md는 쓴 때의 경로를 그대로 둔다. review-evidence.md와 review-ledger.json의 `docs/superpowers/specs/…`는 이 트리가 아닌 검토 작업 공간의 출처 표시라 그대로 둔다. 위험: 경로 글자를 바꾼 곳은 주석과 문서뿐이고 실행 코드의 경로 상수는 없다. 문서 지도(docs/README.md)의 옛 폴더 행은 뒤 커밋이 다시 쓴다. 검증: `git grep -n -E "docs/superpowers|architecture/decisions"`가 기록, CHANGELOG.md, 출처 표시 두 곳, docs/README.md·README.md(뒤에서 다시 쓴다) 밖에서 0건. --- .dependency-cruiser.json | 2 +- README.md | 40 +++++++++---------- docs/README.md | 18 ++++----- .../backend-api-and-server-state-contract.md | 8 ++-- docs/architecture/layers.md | 2 +- docs/architecture/optional-adapter-recipes.md | 22 +++++----- docs/architecture/overview.md | 26 ++++++------ docs/architecture/scale-architecture.md | 2 +- docs/architecture/starter-experience.md | 4 +- docs/architecture/static-delivery.md | 2 +- docs/contracts/compatibility.md | 4 +- ...ntend-platform-capability-review-design.md | 26 ++++++------ ...-platform-implementation-roadmap-design.md | 12 +++--- ...nd-ports-adapters-and-boundaries-design.md | 4 +- ...6-typescript-state-and-data-flow-design.md | 6 +-- ...-browser-file-and-origin-storage-design.md | 2 +- ...t-schema-mapper-and-server-state-design.md | 36 ++++++++--------- ...6-07-28-client-cache-and-storage-design.md | 20 +++++----- ...owser-transport-and-rest-gateway-design.md | 14 +++---- ...r-file-capability-infrastructure-design.md | 2 +- ...ata-capability-completion-ledger-design.md | 20 +++++----- ...presigned-transfer-and-image-cdn-design.md | 14 +++---- ...nts-web-push-and-bounded-polling-design.md | 26 ++++++------ docs/manual/01-add-a-feature.md | 2 +- docs/manual/02-decision-tables.md | 2 +- docs/manual/03-outside-feature-folder.md | 2 +- docs/manual/README.md | 4 +- docs/operations/adapter-remediation-ledger.md | 2 +- .../api-contract-and-server-state-recovery.md | 20 +++++----- .../browser-file-storage-recovery.md | 10 ++--- docs/operations/browser-transfer-recovery.md | 10 ++--- docs/operations/ci-quality-gates.md | 2 +- .../client-cache-and-storage-recovery.md | 10 ++--- docs/styling/design-tokens.md | 2 +- docs/testing/taxonomy.md | 2 +- tests/component/router.test.tsx | 2 +- .../resumable-upload-fetch-transport.test.ts | 2 +- 37 files changed, 192 insertions(+), 192 deletions(-) diff --git a/.dependency-cruiser.json b/.dependency-cruiser.json index e3dab6e9..81abe1f7 100644 --- a/.dependency-cruiser.json +++ b/.dependency-cruiser.json @@ -24,7 +24,7 @@ }, { "name": "presentation-does-not-know-adapters", - "comment": "§4. Presentation talks to application ports, not concrete adapters, the composition root or the TanStack runtime. Exception: src/presentation/adapters/query is the TanStack Query binding, the one place @tanstack is imported (docs/architecture/frontend-ports-adapters-and-boundaries.md). It needs @tanstack only; concrete-adapters-compose-only-in-bootstrap still keeps it off src/adapters. Owner: frontend-platform. Revisit if the binding moves out of presentation.", + "comment": "§4. Presentation talks to application ports, not concrete adapters, the composition root or the TanStack runtime. Exception: src/presentation/adapters/query is the TanStack Query binding, the one place @tanstack is imported (docs/design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md). It needs @tanstack only; concrete-adapters-compose-only-in-bootstrap still keeps it off src/adapters. Owner: frontend-platform. Revisit if the binding moves out of presentation.", "severity": "error", "from": { "path": "^src/presentation/(?!adapters/query)" diff --git a/README.md b/README.md index 8b0d536b..4d2d483e 100644 --- a/README.md +++ b/README.md @@ -111,10 +111,10 @@ design documents use; the next table maps them. | Not supported | Deliberately not selected, or browsers cannot guarantee it: SSR, app-managed background upload and download, directory selection, persistent file handles, product query persistence, exactly-once delivery between tabs | `NOT_SELECTED`, `PLATFORM_LIMITED` | The rows come from -[`docs/architecture/browser-data-capability-completion-ledger.md`](docs/architecture/browser-data-capability-completion-ledger.md), -[`docs/architecture/client-cache-and-storage.md`](docs/architecture/client-cache-and-storage.md) +[`docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md`](docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md), +[`docs/design/2026-07-28-client-cache-and-storage-design.md`](docs/design/2026-07-28-client-cache-and-storage-design.md) and -[`docs/architecture/api-contract-schema-mapper-and-server-state.md`](docs/architecture/api-contract-schema-mapper-and-server-state.md). +[`docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md`](docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md). | Status word | Where it appears | Meaning | Tier | | --- | --- | --- | --- | @@ -187,22 +187,22 @@ The starter shell is implemented, but the repository review also records the remaining work required before feature teams can use every declared contract through one end-to-end application path: -- [platform capability review](docs/architecture/frontend-platform-capability-review.md) -- [ports, adapters, and feature boundaries](docs/architecture/frontend-ports-adapters-and-boundaries.md) -- [REST, GraphQL, Connect/gRPC-Web, Schema, Mapper, and Server State](docs/architecture/api-contract-schema-mapper-and-server-state.md) -- [Protobuf browser transports and REST Gateway](docs/architecture/protobuf-browser-transport-and-rest-gateway.md) +- [platform capability review](docs/design/2026-07-26-frontend-platform-capability-review-design.md) +- [ports, adapters, and feature boundaries](docs/design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md) +- [REST, GraphQL, Connect/gRPC-Web, Schema, Mapper, and Server State](docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md) +- [Protobuf browser transports and REST Gateway](docs/design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md) - [backend API and Server State handoff contract](docs/architecture/backend-api-and-server-state-contract.md) -- [TypeScript, state ownership, and data flow](docs/architecture/typescript-state-and-data-flow.md) -- [routing, page templates, and reusable patterns](docs/architecture/routing-pages-and-patterns.md) -- [browser data capability completion ledger](docs/architecture/browser-data-capability-completion-ledger.md) -- [browser file and origin-storage platform](docs/architecture/browser-file-and-origin-storage.md) -- [client cache and storage](docs/architecture/client-cache-and-storage.md) -- [realtime events, Web Push, and bounded polling](docs/architecture/realtime-events-web-push-and-bounded-polling.md) -- [presigned transfer, resumable upload, streaming download, and Image CDN](docs/architecture/presigned-transfer-and-image-cdn.md) -- [server file capability infrastructure](docs/architecture/server-file-capability-infrastructure.md) -- [design-system platform](docs/styling/design-system-platform.md) -- [frontend platform testing strategy](docs/testing/frontend-platform-testing-strategy.md) -- [implementation roadmap](docs/architecture/frontend-platform-implementation-roadmap.md) +- [TypeScript, state ownership, and data flow](docs/design/2026-07-26-typescript-state-and-data-flow-design.md) +- [routing, page templates, and reusable patterns](docs/design/2026-07-26-routing-pages-and-patterns-design.md) +- [browser data capability completion ledger](docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md) +- [browser file and origin-storage platform](docs/design/2026-07-27-browser-file-and-origin-storage-design.md) +- [client cache and storage](docs/design/2026-07-28-client-cache-and-storage-design.md) +- [realtime events, Web Push, and bounded polling](docs/design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md) +- [presigned transfer, resumable upload, streaming download, and Image CDN](docs/design/2026-07-30-presigned-transfer-and-image-cdn-design.md) +- [server file capability infrastructure](docs/design/2026-07-28-server-file-capability-infrastructure-design.md) +- [design-system platform](docs/design/2026-07-26-design-system-platform-design.md) +- [frontend platform testing strategy](docs/design/2026-07-26-frontend-platform-testing-strategy-design.md) +- [implementation roadmap](docs/design/2026-07-26-frontend-platform-implementation-roadmap-design.md) These documents distinguish repository defaults from opt-in adapters and project-owned integrations. They are target designs and review findings; a @@ -279,7 +279,7 @@ compatible Linux assurance host described in project로 모두 검사한다. type/architecture/security/registry의 invalid fixture는 `config/ci/gates.json`에서 “실패해야 통과”하는 negative gate로 실행된다. 도구 호환성 결정은 -[VD-01](docs/architecture/decisions/VD-01-typescript-lint-tooling.md)에 기록돼 +[VD-01](docs/adr/VD-01-typescript-lint-tooling.md)에 기록돼 있다. Application feature input은 module augmentation으로 닫힌 ID와 정확한 input @@ -364,7 +364,7 @@ Run the gates one at a time in a checkout: they and the evidence checks read the fixed `dist/` and `artifacts/` paths. Two Playwright runs can share a checkout when each has its own `TEST_RUN_ID`; its build, results and report go below `.tmp/runs//`. The test servers always pick a free port. The -variables are listed in `docs/testing/frontend-platform-testing-strategy.md` +variables are listed in `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` (13.6). Operational details are in `docs/operations/`, with incident procedures in diff --git a/docs/README.md b/docs/README.md index fc22ea81..b393ddba 100644 --- a/docs/README.md +++ b/docs/README.md @@ -68,15 +68,15 @@ checkout이 없거나 그 커밋이 없으면 실패 대신 확인하지 못한 설계와 결정 기록이다. 구현된 부분과 계획이 한 문서에 섞여 있다. 행마다 상태 값을 본다. -- 런타임 capability 결정의 정본: [`architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md`](architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md) -- 상태 원장: [`architecture/browser-data-capability-completion-ledger.md`](architecture/browser-data-capability-completion-ledger.md) -- 전체 검토와 로드맵: [`architecture/frontend-platform-capability-review.md`](architecture/frontend-platform-capability-review.md), [`architecture/frontend-platform-implementation-roadmap.md`](architecture/frontend-platform-implementation-roadmap.md) -- 포트·경계·데이터 흐름: [`architecture/frontend-ports-adapters-and-boundaries.md`](architecture/frontend-ports-adapters-and-boundaries.md), [`architecture/typescript-state-and-data-flow.md`](architecture/typescript-state-and-data-flow.md), [`architecture/routing-pages-and-patterns.md`](architecture/routing-pages-and-patterns.md) -- API와 서버 상태: [`architecture/api-contract-schema-mapper-and-server-state.md`](architecture/api-contract-schema-mapper-and-server-state.md), [`architecture/backend-api-and-server-state-contract.md`](architecture/backend-api-and-server-state-contract.md), [`architecture/protobuf-browser-transport-and-rest-gateway.md`](architecture/protobuf-browser-transport-and-rest-gateway.md) -- 브라우저 데이터: [`architecture/client-cache-and-storage.md`](architecture/client-cache-and-storage.md), [`architecture/browser-file-and-origin-storage.md`](architecture/browser-file-and-origin-storage.md), [`architecture/presigned-transfer-and-image-cdn.md`](architecture/presigned-transfer-and-image-cdn.md), [`architecture/server-file-capability-infrastructure.md`](architecture/server-file-capability-infrastructure.md) -- 실시간: [`architecture/realtime-events-web-push-and-bounded-polling.md`](architecture/realtime-events-web-push-and-bounded-polling.md) -- 디자인 시스템과 테스트 전략: [`styling/design-system-platform.md`](styling/design-system-platform.md), [`testing/frontend-platform-testing-strategy.md`](testing/frontend-platform-testing-strategy.md) -- 결정 기록(ADR): [`architecture/decisions/`](architecture/decisions/) `VD-*.md` +- 런타임 capability 결정의 정본: [`architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md`](design/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md) +- 상태 원장: [`architecture/browser-data-capability-completion-ledger.md`](design/2026-07-30-browser-data-capability-completion-ledger-design.md) +- 전체 검토와 로드맵: [`architecture/frontend-platform-capability-review.md`](design/2026-07-26-frontend-platform-capability-review-design.md), [`architecture/frontend-platform-implementation-roadmap.md`](design/2026-07-26-frontend-platform-implementation-roadmap-design.md) +- 포트·경계·데이터 흐름: [`architecture/frontend-ports-adapters-and-boundaries.md`](design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md), [`architecture/typescript-state-and-data-flow.md`](design/2026-07-26-typescript-state-and-data-flow-design.md), [`architecture/routing-pages-and-patterns.md`](design/2026-07-26-routing-pages-and-patterns-design.md) +- API와 서버 상태: [`architecture/api-contract-schema-mapper-and-server-state.md`](design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md), [`architecture/backend-api-and-server-state-contract.md`](architecture/backend-api-and-server-state-contract.md), [`architecture/protobuf-browser-transport-and-rest-gateway.md`](design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md) +- 브라우저 데이터: [`architecture/client-cache-and-storage.md`](design/2026-07-28-client-cache-and-storage-design.md), [`architecture/browser-file-and-origin-storage.md`](design/2026-07-27-browser-file-and-origin-storage-design.md), [`architecture/presigned-transfer-and-image-cdn.md`](design/2026-07-30-presigned-transfer-and-image-cdn-design.md), [`architecture/server-file-capability-infrastructure.md`](design/2026-07-28-server-file-capability-infrastructure-design.md) +- 실시간: [`architecture/realtime-events-web-push-and-bounded-polling.md`](design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md) +- 디자인 시스템과 테스트 전략: [`styling/design-system-platform.md`](design/2026-07-26-design-system-platform-design.md), [`testing/frontend-platform-testing-strategy.md`](design/2026-07-26-frontend-platform-testing-strategy-design.md) +- 결정 기록(ADR): [`architecture/decisions/`](adr/) `VD-*.md` ## 3. 작업 이력·리뷰 diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index 8f267acc..77a1fe7b 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -4,7 +4,7 @@ > > Runtime Config/boot, Fetch HTTP client, Router, Query/Mutation, realtime 공통 경계, Web Worker, > Service Worker, offline command와 Background Sync의 구현 결정은 -> [프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계](./2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)가 정본이다. +> [프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계](../design/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)가 정본이다. > 본 문서의 해당 서술이 정본과 충돌하면 정본을 따른다. @@ -13,11 +13,11 @@ - 대상: Web API/BFF, application service, persistence, identity, GraphQL router, Connect/gRPC-Web gateway, Protobuf REST Gateway와 운영 owner - frontend 기준: - [API contract, Schema, Mapper와 Server State](./api-contract-schema-mapper-and-server-state.md) + [API contract, Schema, Mapper와 Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md) - browser Protobuf/gateway 기준: - [Protobuf browser transport와 REST Gateway](./protobuf-browser-transport-and-rest-gateway.md) + [Protobuf browser transport와 REST Gateway](../design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md) - 파일 전송 backend 기준: - [Server file capability infrastructure](./server-file-capability-infrastructure.md) + [Server file capability infrastructure](../design/2026-07-28-server-file-capability-infrastructure-design.md) - 복구 절차: [API contract와 server-state recovery](../operations/api-contract-and-server-state-recovery.md) diff --git a/docs/architecture/layers.md b/docs/architecture/layers.md index 131b3bfc..0b5612ff 100644 --- a/docs/architecture/layers.md +++ b/docs/architecture/layers.md @@ -155,7 +155,7 @@ realm 파일만 빼는 구조라, 배럴이 그 파일을 다시 끌어들이면 orchestration belong to `src/application` or to a feature's domain and application. -The [ports, adapters, and feature-boundary contract](./frontend-ports-adapters-and-boundaries.md) +The [ports, adapters, and feature-boundary contract](../design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md) explains how `presentation` acts as the inbound adapter and how feature application APIs augment the generic typed input registry. Concrete output ports are composed in bootstrap and stay hidden behind the application facade. diff --git a/docs/architecture/optional-adapter-recipes.md b/docs/architecture/optional-adapter-recipes.md index 69a0483b..f10d445f 100644 --- a/docs/architecture/optional-adapter-recipes.md +++ b/docs/architecture/optional-adapter-recipes.md @@ -23,15 +23,15 @@ production readiness를 뜻하지 않는다. | 심층 deterministic fake. file·storage durability·OPFS fake는 `src` port를 `implements`한다 | `recipes/frontend-capabilities/browser-file-storage-fakes.ts` | 아니오 | | 심층 contract test | `tests/recipes/browser-file-storage-contracts.test.ts` | 아니오 | | 짝 백엔드 세션 owner(JWT·Keycloak PKCE, Redis session 쿠키+CSRF). catalog 밖이고 복사해서 쓴다. src가 import하면 `PRODUCTION_IMPORTS_RECIPE` | `recipes/session-owners/`, 테스트 `tests/recipes/oidc-pkce-session-owner.test.ts`, `tests/recipes/cookie-session-owner.test.ts`, `tests/recipes/session-owners-runtime.test.ts`, 절차 `docs/manual/04-paired-backend-session.md` | 아니오 | -| browser data current-status ledger | `docs/architecture/browser-data-capability-completion-ledger.md` | 문서만 | -| 심층 설계/ADR | `docs/architecture/browser-file-and-origin-storage.md`, `decisions/VD-11-browser-file-and-origin-storage.md` | 문서만 | -| client cache scope/persistence 설계 | `docs/architecture/client-cache-and-storage.md`, `decisions/VD-13-client-cache-scope-and-persistence.md` | 문서만 | -| realtime/Web Push/Polling 설계와 reference runtime | `docs/architecture/realtime-events-web-push-and-bounded-polling.md`, `decisions/VD-28-realtime-events-web-push-and-bounded-polling.md`, `src/adapters/realtime`, `src/adapters/web-push` | composition 전에는 tree-shaken | -| transfer/CDN 설계/ADR | `docs/architecture/presigned-transfer-and-image-cdn.md`, `decisions/VD-12-presigned-transfer-and-image-cdn.md` | 문서만 | -| Range/background 결정 | `docs/architecture/decisions/VD-14-resumable-download-and-background-transfer.md` | 문서만 | -| storage lifecycle/migration 결정 | `docs/architecture/decisions/VD-15-origin-storage-lifecycle-and-migration.md` | 문서만 | -| transfer composition/Image provider 결정 | `docs/architecture/decisions/VD-16-browser-transfer-composition-and-image-delivery.md` | 문서만 | -| REST/GraphQL/Connect/gRPC-Web·Protobuf/REST Gateway·Schema·Mapper·Server State 설계 | `docs/architecture/api-contract-schema-mapper-and-server-state.md`, `docs/architecture/protobuf-browser-transport-and-rest-gateway.md`, `decisions/VD-23-api-transport-selection-and-rest-execution.md`, `decisions/VD-24-runtime-schema-and-boundary-mapper.md`, `decisions/VD-25-server-state-cache-lifecycle.md`, `decisions/VD-26-persisted-graphql-operation.md`, `decisions/VD-27-grpc-web-unary-and-server-stream.md`, `decisions/VD-29-connect-web-and-browser-protobuf-runtime.md`, `decisions/VD-30-protobuf-contract-and-rest-gateway.md` | 문서만 | +| browser data current-status ledger | `docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md` | 문서만 | +| 심층 설계/ADR | `docs/design/2026-07-27-browser-file-and-origin-storage-design.md`, `docs/adr/VD-11-browser-file-and-origin-storage.md` | 문서만 | +| client cache scope/persistence 설계 | `docs/design/2026-07-28-client-cache-and-storage-design.md`, `docs/adr/VD-13-client-cache-scope-and-persistence.md` | 문서만 | +| realtime/Web Push/Polling 설계와 reference runtime | `docs/design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md`, `docs/adr/VD-28-realtime-events-web-push-and-bounded-polling.md`, `src/adapters/realtime`, `src/adapters/web-push` | composition 전에는 tree-shaken | +| transfer/CDN 설계/ADR | `docs/design/2026-07-30-presigned-transfer-and-image-cdn-design.md`, `docs/adr/VD-12-presigned-transfer-and-image-cdn.md` | 문서만 | +| Range/background 결정 | `docs/adr/VD-14-resumable-download-and-background-transfer.md` | 문서만 | +| storage lifecycle/migration 결정 | `docs/adr/VD-15-origin-storage-lifecycle-and-migration.md` | 문서만 | +| transfer composition/Image provider 결정 | `docs/adr/VD-16-browser-transfer-composition-and-image-delivery.md` | 문서만 | +| REST/GraphQL/Connect/gRPC-Web·Protobuf/REST Gateway·Schema·Mapper·Server State 설계 | `docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md`, `docs/design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md`, `docs/adr/VD-23-api-transport-selection-and-rest-execution.md`, `docs/adr/VD-24-runtime-schema-and-boundary-mapper.md`, `docs/adr/VD-25-server-state-cache-lifecycle.md`, `docs/adr/VD-26-persisted-graphql-operation.md`, `docs/adr/VD-27-grpc-web-unary-and-server-stream.md`, `docs/adr/VD-29-connect-web-and-browser-protobuf-runtime.md`, `docs/adr/VD-30-protobuf-contract-and-rest-gateway.md` | 문서만 | | provider-neutral Browser RPC V3 계약/port/runtime | `src/contracts/browser-rpc.ts`, `src/application/ports/browser-rpc`, `src/adapters/browser-rpc`, `tests/unit/browser-rpc` | composition 전에는 tree-shaken | | API contract/server-state 복구 runbook | `docs/operations/api-contract-and-server-state-recovery.md` | 문서만 | | storage 복구 runbook template | `docs/operations/browser-file-storage-recovery.md` | 문서만 | @@ -230,12 +230,12 @@ Web Push를 함께 설치하지 않는다. - Web Push permission은 user action에서만 요청하고 subscription endpoint/key와 payload를 storage, URL, telemetry나 application state에 노출하지 않는다. - detailed status, target contract와 구현 work package는 - [Realtime events, Web Push, and bounded polling](./realtime-events-web-push-and-bounded-polling.md)을 + [Realtime events, Web Push, and bounded polling](../design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)을 따른다. 현재 concrete runtime과 product selection은 없다. - 짝 백엔드 템플릿의 실시간 출구(STOMP-over-SockJS, NDJSON)와 이 repo의 SSE· `realtime.v1` WebSocket 어댑터는 그대로 연결되지 않는다. 지금 두 템플릿만으로 되는 경로는 bounded polling이다. 대응표와 push를 고를 때의 세 길은 설계 문서 - [0.1절](./realtime-events-web-push-and-bounded-polling.md#01-짝-백엔드-템플릿과의-대응-110304-02)에 + [0.1절](../design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md#01-짝-백엔드-템플릿과의-대응-110304-02)에 있다(1103/04-02). - realtime 레지스트리(`createRealtimePolicyRegistry`)가 받는 세 바인딩의 출처 (1103/04-06). 기능 모듈에는 codec·mapper를 낼 칸이 없으므로 조합 코드가 모은다. diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index 7750dc2b..716bac86 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -84,17 +84,17 @@ selected optional capability; the repository does not fabricate that evidence. Use the following documents for implementation details and project integration work: -- [Frontend platform capability review](./frontend-platform-capability-review.md) -- [Frontend ports, adapters, and boundaries](./frontend-ports-adapters-and-boundaries.md) -- [API contract, Schema, Mapper, and Server State](./api-contract-schema-mapper-and-server-state.md) -- [Protobuf browser transports and REST Gateway](./protobuf-browser-transport-and-rest-gateway.md) +- [Frontend platform capability review](../design/2026-07-26-frontend-platform-capability-review-design.md) +- [Frontend ports, adapters, and boundaries](../design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md) +- [API contract, Schema, Mapper, and Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md) +- [Protobuf browser transports and REST Gateway](../design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md) - [Backend API and Server State handoff contract](./backend-api-and-server-state-contract.md) -- [TypeScript, state, and data flow](./typescript-state-and-data-flow.md) -- [Routing, pages, and patterns](./routing-pages-and-patterns.md) -- [Browser data capability completion ledger](./browser-data-capability-completion-ledger.md) -- [Browser file and origin storage](./browser-file-and-origin-storage.md) -- [Client cache and storage](./client-cache-and-storage.md) -- [Realtime events, Web Push, and bounded polling](./realtime-events-web-push-and-bounded-polling.md) -- [Presigned transfer and Image CDN](./presigned-transfer-and-image-cdn.md) -- [Server file capability infrastructure](./server-file-capability-infrastructure.md) -- [Frontend platform implementation roadmap](./frontend-platform-implementation-roadmap.md) +- [TypeScript, state, and data flow](../design/2026-07-26-typescript-state-and-data-flow-design.md) +- [Routing, pages, and patterns](../design/2026-07-26-routing-pages-and-patterns-design.md) +- [Browser data capability completion ledger](../design/2026-07-30-browser-data-capability-completion-ledger-design.md) +- [Browser file and origin storage](../design/2026-07-27-browser-file-and-origin-storage-design.md) +- [Client cache and storage](../design/2026-07-28-client-cache-and-storage-design.md) +- [Realtime events, Web Push, and bounded polling](../design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md) +- [Presigned transfer and Image CDN](../design/2026-07-30-presigned-transfer-and-image-cdn-design.md) +- [Server file capability infrastructure](../design/2026-07-28-server-file-capability-infrastructure-design.md) +- [Frontend platform implementation roadmap](../design/2026-07-26-frontend-platform-implementation-roadmap-design.md) diff --git a/docs/architecture/scale-architecture.md b/docs/architecture/scale-architecture.md index aa4fad13..7c554a9b 100644 --- a/docs/architecture/scale-architecture.md +++ b/docs/architecture/scale-architecture.md @@ -3,7 +3,7 @@ > **상태 머리말 (2026-11-03)** > > - **현재 계약인 범위.** 아래 표에서 상태가 "현재 계약"인 절만 지금 코드가 지키는 규칙이다. "기록만"인 절은 2026-09-23 설계 당시의 계획·목록이고, 구현되지 않았거나 바뀌었다. 문서와 코드가 다르면 코드가 맞다. -> - **출처.** 2026-09-23 설계서 "Extreme-Scale Frontend Architecture Design"을 커밋 `6f6c48e`(2026-09-24)에서 옮겼다. 원래 파일은 작업 이력 묶음 안에 있어 복사한 프로젝트가 지울 수 있다. 원문은 `git show 6f6c48e:docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/specs/2026-09-23-extreme-scale-frontend-architecture-design.md`로 볼 수 있다. +> - **출처.** 2026-09-23 설계서 "Extreme-Scale Frontend Architecture Design"을 커밋 `6f6c48e`(2026-09-24)에서 옮겼다. 원래 파일은 작업 이력 묶음 안에 있어 복사한 프로젝트가 지울 수 있다. 원문은 `git show 6f6c48e:docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/design/2026-09-23-extreme-scale-frontend-architecture-design.md`로 볼 수 있다. > - **본문.** §1~§55는 영어 원문 그대로다. 절 번호는 바꾸지 않았다. 원문 머리의 날짜·대상·상태·예정 경로 줄만 이 머리말로 바꿨다. > - **코드가 이 문서를 가리키는 방법.** 코드 주석은 `scale-architecture.md §N` 형식으로 쓴다. 문서 이름이 없는 "Spec" + 절 번호 참조는 `tests/unit/deletable-history-documents.test.ts`가 거부한다. 절 번호를 바꾸면 `git grep "scale-architecture.md §"`로 찾은 주석을 모두 함께 고친다. > - **코드와 달라진 곳을 적는 규칙.** 원문 문장은 고치지 않는다. 확인한 차이는 그 절 끝에 `> YYYY-MM-DD 현재:` 한두 줄로 적는다. 절의 상태가 바뀌면 아래 표도 고친다. diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index ef39a92c..f6224048 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -90,9 +90,9 @@ or `SessionGateway` directly must add `getSubject()` the same way. ## Extending the starter New platform work should follow -[routing, page templates, and reusable patterns](./routing-pages-and-patterns.md) +[routing, page templates, and reusable patterns](../design/2026-07-26-routing-pages-and-patterns-design.md) and the -[TypeScript, state, and data-flow target](./typescript-state-and-data-flow.md) +[TypeScript, state, and data-flow target](../design/2026-07-26-typescript-state-and-data-flow-design.md) rather than adding another independent route or data-loading convention. ### Replacing the starter screens diff --git a/docs/architecture/static-delivery.md b/docs/architecture/static-delivery.md index bcf8c6d1..7d959205 100644 --- a/docs/architecture/static-delivery.md +++ b/docs/architecture/static-delivery.md @@ -4,7 +4,7 @@ > > Runtime Config/boot, Fetch HTTP client, Router, Query/Mutation, realtime 공통 경계, Web Worker, > Service Worker, offline command와 Background Sync의 구현 결정은 -> [프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계](./2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)가 정본이다. +> [프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계](../design/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)가 정본이다. > 본 문서의 해당 서술이 정본과 충돌하면 정본을 따른다. diff --git a/docs/contracts/compatibility.md b/docs/contracts/compatibility.md index 9c481ac7..f8c13809 100644 --- a/docs/contracts/compatibility.md +++ b/docs/contracts/compatibility.md @@ -74,7 +74,7 @@ REST/OpenAPI artifacts, GraphQL schema and persisted-operation manifests, protobuf source/descriptors/codegen profiles, Connect/gRPC-Web provider profiles, ProtoJSON/HttpRule/generated OpenAPI/gateway artifacts, runtime schema/mapper registries, and server-state policy digests as defined in -[API contract, Schema, Mapper, and Server State](../architecture/api-contract-schema-mapper-and-server-state.md). +[API contract, Schema, Mapper, and Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md). Browser Protobuf and REST Gateway compatibility is further split in -[Protobuf browser transport and REST Gateway](../architecture/protobuf-browser-transport-and-rest-gateway.md); +[Protobuf browser transport and REST Gateway](../design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md); binary/JSON/HTTP-route compatibility gates are not interchangeable. diff --git a/docs/design/2026-07-26-frontend-platform-capability-review-design.md b/docs/design/2026-07-26-frontend-platform-capability-review-design.md index eaf21b76..58b85584 100644 --- a/docs/design/2026-07-26-frontend-platform-capability-review-design.md +++ b/docs/design/2026-07-26-frontend-platform-capability-review-design.md @@ -93,13 +93,13 @@ P0/P1 acceptance와 P2 recipe 기본값은 `LOCAL_TEMPLATE_READY`다. 다만 실 | 샘플 제거 | 준비됨 | feature/catalog/test 제거 후 type/architecture/registry/test/home/build 9단계 검증 | 새 contribution도 같은 제거 gate에 포함 | | registry·compatibility 집행 | 준비됨 | 10개 registry type/reference/consumer/orphan, 승인 digest와 actual semantic diff, breaking evidence | public 계약 변경 시 baseline review 유지 | | 공급망 검사 | 준비됨/프로젝트 선택 | 561개 transitive inventory/integrity/license, actual diff, CycloneDX, local provenance, secret/reproducible build gate | 실제 vulnerability scanner와 signed attestation 없이는 promotion `FAIL_UNVERIFIED` | -| realtime delivery | 참조 런타임 준비됨/프로젝트 미선택 | RT-01~04 공통 event authority, fetch-stream SSE, closed WebSocket, bounded Polling, Web Push window/worker와 handoff/reconnect 조정자는 `AVAILABLE_NOT_COMPOSED`; backend/provider/browser evidence는 없음 | [Realtime events, Web Push, and bounded polling](./realtime-events-web-push-and-bounded-polling.md)의 RT-05 제품 조립·운영 증거를 capability별로 통과 | -| offline·file·browser data | 부분 준비/프로젝트 선택 | opt-in recipe와 gate; capability별 구현·조합·미구현·미선택·platform 제한 상태가 서로 다름 | [Browser data capability completion ledger](./browser-data-capability-completion-ledger.md)의 상태와 work package를 통과한 capability만 설치 | +| realtime delivery | 참조 런타임 준비됨/프로젝트 미선택 | RT-01~04 공통 event authority, fetch-stream SSE, closed WebSocket, bounded Polling, Web Push window/worker와 handoff/reconnect 조정자는 `AVAILABLE_NOT_COMPOSED`; backend/provider/browser evidence는 없음 | [Realtime events, Web Push, and bounded polling](./2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)의 RT-05 제품 조립·운영 증거를 capability별로 통과 | +| offline·file·browser data | 부분 준비/프로젝트 선택 | opt-in recipe와 gate; capability별 구현·조합·미구현·미선택·platform 제한 상태가 서로 다름 | [Browser data capability completion ledger](./2026-07-30-browser-data-capability-completion-ledger-design.md)의 상태와 work package를 통과한 capability만 설치 | REST/GraphQL/Connect/gRPC-Web/REST Gateway, Schema/Mapper와 Server State의 상세 current/target 판정은 -[API contract, Schema, Mapper와 Server State](./api-contract-schema-mapper-and-server-state.md)를 +[API contract, Schema, Mapper와 Server State](./2026-07-28-api-contract-schema-mapper-and-server-state-design.md)를 따른다. Browser Protobuf 축의 선택 기준은 -[Protobuf browser transport와 REST Gateway](./protobuf-browser-transport-and-rest-gateway.md)를 +[Protobuf browser transport와 REST Gateway](./2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)를 따른다. 현재 REST reference 경로의 `COMPOSED` 판정을 GraphQL/Connect/gRPC-Web/ Gateway 또는 REST v2 hardening 완료 증거로 재사용하지 않는다. @@ -334,7 +334,7 @@ Web Push provider selection은 여전히 `NOT_SELECTED`이며 production bootstr worker에는 조립하지 않는다. 이 capability들을 한꺼번에 "준비됨"으로 표시하지 않는다. -[Browser data capability completion ledger](./browser-data-capability-completion-ledger.md)가 +[Browser data capability completion ledger](./2026-07-30-browser-data-capability-completion-ledger-design.md)가 `COMPOSED`, `AVAILABLE_NOT_COMPOSED`, `DESIGNED_NOT_IMPLEMENTED`, `NOT_SELECTED`, `PLATFORM_LIMITED`를 구분하는 현재 상태의 기준이다. 특히 session/account Query lifecycle, Range resumable download, cross-store quota @@ -522,11 +522,11 @@ data 같은 프로젝트별 외부 작업을 포함하지 않는다. ## 8. 관련 상세 문서 -- [API contract, Schema, Mapper와 Server State](./api-contract-schema-mapper-and-server-state.md) -- [Realtime events, Web Push, and bounded polling](./realtime-events-web-push-and-bounded-polling.md) -- [프론트 포트·어댑터와 기능 경계](./frontend-ports-adapters-and-boundaries.md) -- [TypeScript·상태·데이터 흐름](./typescript-state-and-data-flow.md) -- [라우팅·페이지·재사용 패턴](./routing-pages-and-patterns.md) -- [프론트 플랫폼 구현 로드맵](./frontend-platform-implementation-roadmap.md) -- [디자인 시스템 플랫폼](../styling/design-system-platform.md) -- [프론트 플랫폼 테스트 전략](../testing/frontend-platform-testing-strategy.md) +- [API contract, Schema, Mapper와 Server State](./2026-07-28-api-contract-schema-mapper-and-server-state-design.md) +- [Realtime events, Web Push, and bounded polling](./2026-07-30-realtime-events-web-push-and-bounded-polling-design.md) +- [프론트 포트·어댑터와 기능 경계](./2026-07-26-frontend-ports-adapters-and-boundaries-design.md) +- [TypeScript·상태·데이터 흐름](./2026-07-26-typescript-state-and-data-flow-design.md) +- [라우팅·페이지·재사용 패턴](./2026-07-26-routing-pages-and-patterns-design.md) +- [프론트 플랫폼 구현 로드맵](./2026-07-26-frontend-platform-implementation-roadmap-design.md) +- [디자인 시스템 플랫폼](2026-07-26-design-system-platform-design.md) +- [프론트 플랫폼 테스트 전략](2026-07-26-frontend-platform-testing-strategy-design.md) diff --git a/docs/design/2026-07-26-frontend-platform-implementation-roadmap-design.md b/docs/design/2026-07-26-frontend-platform-implementation-roadmap-design.md index da4d17ac..64d34b36 100644 --- a/docs/design/2026-07-26-frontend-platform-implementation-roadmap-design.md +++ b/docs/design/2026-07-26-frontend-platform-implementation-roadmap-design.md @@ -324,7 +324,7 @@ adapter로 연결한다. 동작과 production wiring을 검증한다. - 상세 상태와 남은 session/account epoch, native multi-tab evidence 및 optional IndexedDB query persistence는 - [Client cache and browser storage platform](./client-cache-and-storage.md)에 + [Client cache and browser storage platform](./2026-07-28-client-cache-and-storage-design.md)에 기록한다. **Rollback** @@ -1086,7 +1086,7 @@ revert하고 RP-11을 유지한다. 여러 vendor를 되돌릴 수 없는 한 co query state/payload를 복제하지 않고 persistence는 계속 disabled다. 기존 IndexedDB reference runtime은 이 선택 때문에 bootstrap에 조립되지 않는다. - 같은 날 VD-28과 - [Realtime events, Web Push, and bounded polling](./realtime-events-web-push-and-bounded-polling.md)을 + [Realtime events, Web Push, and bounded polling](./2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)을 추가했다. SSE, WebSocket, Web Push와 Polling을 별도 delivery capability로 분리하고 공통 delivery guarantee 없음, duplicate-tolerant CURSOR 처리, gap/snapshot checkpoint, scope generation, bounded lifecycle과 promotion 계약을 @@ -1107,7 +1107,7 @@ revert하고 RP-11을 유지한다. 여러 vendor를 되돌릴 수 없는 한 co RP-12의 reference runtime 존재는 browser data platform 전체의 구현 완료를 뜻하지 않는다. 현재 상태와 상세 exit criteria는 -[Browser data capability completion ledger](./browser-data-capability-completion-ledger.md)를 +[Browser data capability completion ledger](./2026-07-30-browser-data-capability-completion-ledger-design.md)를 단일 기준으로 사용한다. 후속 구현은 다음 독립 package로 진행한다. | 순서 | work package | 핵심 exit | @@ -1140,9 +1140,9 @@ transfer는 위 package에 암묵적으로 포함하지 않는다. 각각 `NOT_S REST reference vertical의 `COMPOSED` 판정과 multi-protocol production hardening을 구분한다. 현재/목표 상태, protocol 선택 기준과 완료 조건은 -[API contract, Schema, Mapper와 Server State](./api-contract-schema-mapper-and-server-state.md)가 +[API contract, Schema, Mapper와 Server State](./2026-07-28-api-contract-schema-mapper-and-server-state-design.md)가 소유한다. Browser Protobuf runtime과 gateway branch의 세부 기준은 -[Protobuf browser transport와 REST Gateway](./protobuf-browser-transport-and-rest-gateway.md)를 +[Protobuf browser transport와 REST Gateway](./2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)를 따른다. | 순서 | work package | 핵심 exit | @@ -1173,7 +1173,7 @@ config를 기본 bundle에 넣지 않는다. browser client/bidirectional stream copyable recipe의 교육용 `RealtimePort`와 fake는 production runtime 증거가 아니다. 현재 상태, transport 선택, event authority와 완료 기준은 -[Realtime events, Web Push, and bounded polling](./realtime-events-web-push-and-bounded-polling.md)이 +[Realtime events, Web Push, and bounded polling](./2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)이 소유한다. | 순서 | work package | 핵심 exit | diff --git a/docs/design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md b/docs/design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md index e633119f..d923318f 100644 --- a/docs/design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md +++ b/docs/design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md @@ -170,7 +170,7 @@ RP-03 구현으로 HTTP와 server-state 경계도 다음처럼 연결됐다. invariant, auth unavailable fail-close, total deadline, bounded response decoder, typed Schema/Mapper proof, complete pagination과 mutation concurrency 같은 production hardening delta는 -[API contract, Schema, Mapper와 Server State](./api-contract-schema-mapper-and-server-state.md)에 +[API contract, Schema, Mapper와 Server State](./2026-07-28-api-contract-schema-mapper-and-server-state-design.md)에 별도 `DESIGNED_NOT_IMPLEMENTED`로 기록한다. RP-04에서 route 실행 불일치는 닫혔다. route registry와 runtime map은 @@ -944,7 +944,7 @@ capability의 기본 정책, port 또는 안전한 no-op 구현과 composition 조건, 보안 영향, bundle 비용과 제거 방법이 확인된 경우에만 추가한다. SSE, WebSocket, Web Push와 bounded polling의 서로 다른 delivery 의미, inbound/outbound 분리, resume·gap·lifecycle과 현재 상태는 -[Realtime events, Web Push, and bounded polling](./realtime-events-web-push-and-bounded-polling.md)을 +[Realtime events, Web Push, and bounded polling](./2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)을 따른다. Web Push는 subscription/provider/worker delivery를, 별도 Notification 행은 permission과 user-visible rendering facade를 뜻한다. bounded polling은 inbound diff --git a/docs/design/2026-07-26-typescript-state-and-data-flow-design.md b/docs/design/2026-07-26-typescript-state-and-data-flow-design.md index e845534d..d23b9046 100644 --- a/docs/design/2026-07-26-typescript-state-and-data-flow-design.md +++ b/docs/design/2026-07-26-typescript-state-and-data-flow-design.md @@ -20,9 +20,9 @@ 이 문서는 현재 구현된 TypeScript 경계와 상태/데이터 흐름의 저장소 표준이다. 세부 역량의 구현 상태는 -[프론트엔드 플랫폼 역량 재검토](./frontend-platform-capability-review.md)를 +[프론트엔드 플랫폼 역량 재검토](./2026-07-26-frontend-platform-capability-review-design.md)를 따른다. memory query cache, Web Storage와 탭 간 invalidation의 세부 protocol은 -[Client cache and browser storage platform](./client-cache-and-storage.md)에 +[Client cache and browser storage platform](./2026-07-28-client-cache-and-storage-design.md)에 기록한다. ## 2. TypeScript 전환 원칙 @@ -94,7 +94,7 @@ Node가 직접 실행하는 script/config project는 추가로 `NodeNext`, 사용하되 저장소 내부 상대 import에 실제 `.ts/.tsx` 확장자를 기록한다. 현재 저장소의 VD-01 결정은 -[TypeScript 7과 ESLint 10의 점진적 전환 도구](./decisions/VD-01-typescript-lint-tooling.md)에 +[TypeScript 7과 ESLint 10의 점진적 전환 도구](../adr/VD-01-typescript-lint-tooling.md)에 기록돼 있다. app, Node scripts/config, tests는 각각 독립된 strict project로 typecheck한다. TypeScript 7을 아직 지원하지 않는 parser plugin을 강제 설치하지 않고 Babel parser는 lint syntax/import/security 검사, `tsc`는 type diff --git a/docs/design/2026-07-27-browser-file-and-origin-storage-design.md b/docs/design/2026-07-27-browser-file-and-origin-storage-design.md index 8a8e7846..35d6e403 100644 --- a/docs/design/2026-07-27-browser-file-and-origin-storage-design.md +++ b/docs/design/2026-07-27-browser-file-and-origin-storage-design.md @@ -40,7 +40,7 @@ receipt retention/prune가 구현되어 있으며 bootstrap에서만 분리되 ## 0. 후속 lifecycle/migration 결정과 현재 delta origin storage를 제품에 composition하기 전 남은 공통 lifecycle 설계는 -[VD-15: Origin storage lifecycle, migration, and optional file capabilities](./decisions/VD-15-origin-storage-lifecycle-and-migration.md)에 +[VD-15: Origin storage lifecycle, migration, and optional file capabilities](../adr/VD-15-origin-storage-lifecycle-and-migration.md)에 고정한다. VD-15가 Accepted됐다는 사실은 해당 runtime이 구현 또는 조립됐다는 뜻이 아니다. diff --git a/docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md b/docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md index 1a874e72..d69825d0 100644 --- a/docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md +++ b/docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md @@ -14,17 +14,17 @@ Protobuf/REST Gateway, runtime Schema, boundary Mapper, TanStack Query 기반 Server State Cache - 관련 결정: - - [VD-23 API transport selection과 REST execution](./decisions/VD-23-api-transport-selection-and-rest-execution.md) - - [VD-24 Runtime schema와 boundary mapper](./decisions/VD-24-runtime-schema-and-boundary-mapper.md) - - [VD-25 Server state cache lifecycle](./decisions/VD-25-server-state-cache-lifecycle.md) - - [VD-26 Persisted GraphQL operation](./decisions/VD-26-persisted-graphql-operation.md) - - [VD-27 gRPC-Web unary와 server stream](./decisions/VD-27-grpc-web-unary-and-server-stream.md) - - [VD-29 Connect-Web와 browser Protobuf runtime](./decisions/VD-29-connect-web-and-browser-protobuf-runtime.md) - - [VD-30 Protobuf contract와 REST Gateway](./decisions/VD-30-protobuf-contract-and-rest-gateway.md) + - [VD-23 API transport selection과 REST execution](../adr/VD-23-api-transport-selection-and-rest-execution.md) + - [VD-24 Runtime schema와 boundary mapper](../adr/VD-24-runtime-schema-and-boundary-mapper.md) + - [VD-25 Server state cache lifecycle](../adr/VD-25-server-state-cache-lifecycle.md) + - [VD-26 Persisted GraphQL operation](../adr/VD-26-persisted-graphql-operation.md) + - [VD-27 gRPC-Web unary와 server stream](../adr/VD-27-grpc-web-unary-and-server-stream.md) + - [VD-29 Connect-Web와 browser Protobuf runtime](../adr/VD-29-connect-web-and-browser-protobuf-runtime.md) + - [VD-30 Protobuf contract와 REST Gateway](../adr/VD-30-protobuf-contract-and-rest-gateway.md) - browser Protobuf/gateway 상세 설계: - [Protobuf browser transport와 REST Gateway](./protobuf-browser-transport-and-rest-gateway.md) + [Protobuf browser transport와 REST Gateway](./2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md) - backend handoff: - [Backend API와 Server State contract](./backend-api-and-server-state-contract.md) + [Backend API와 Server State contract](../architecture/backend-api-and-server-state-contract.md) - 운영 절차: [API contract와 server-state recovery](../operations/api-contract-and-server-state-recovery.md) @@ -415,7 +415,7 @@ GraphQL 상세 결정은 VD-26이 소유한다. reference target은 ## 10. Browser Protobuf RPC와 REST Gateway 설계 요약 축과 선택 기준의 상세 계약은 -[Protobuf browser transport와 REST Gateway](./protobuf-browser-transport-and-rest-gateway.md)가 +[Protobuf browser transport와 REST Gateway](./2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)가 소유한다. Protobuf는 IDL/serialization, Connect와 gRPC-Web은 browser wire protocol, Connect-Web/official grpc-web은 client runtime, REST Gateway는 HTTP 노출 방식이다. 네 이름을 하나의 대안 목록이나 하나의 auto-negotiating @@ -752,7 +752,7 @@ opening replay와 이후 resume 규칙은 VD-27이 계속 소유한다. 구현 owner, 권장 topology, 현재 reference endpoint/envelope, idempotency store, Cursor/ETag/revision과 protocol별 handoff checklist는 -[Backend API와 Server State contract](./backend-api-and-server-state-contract.md)가 +[Backend API와 Server State contract](../architecture/backend-api-and-server-state-contract.md)가 소유한다. 아래 표는 frontend 설계가 요구하는 경계 요약이다. | 경계 | backend/provider가 제공할 계약 | @@ -964,11 +964,11 @@ gRPC-Web과 REST Gateway를 “미래 대비” 목적으로 모두 기본 bundl ## 25. 관련 문서 -- [Frontend ports, adapters, and boundaries](./frontend-ports-adapters-and-boundaries.md) -- [Client cache and browser storage](./client-cache-and-storage.md) -- [VD-13 Client cache scope와 persistence](./decisions/VD-13-client-cache-scope-and-persistence.md) -- [Protobuf browser transport와 REST Gateway](./protobuf-browser-transport-and-rest-gateway.md) -- [VD-29 Connect-Web와 browser Protobuf runtime](./decisions/VD-29-connect-web-and-browser-protobuf-runtime.md) -- [VD-30 Protobuf contract와 REST Gateway](./decisions/VD-30-protobuf-contract-and-rest-gateway.md) +- [Frontend ports, adapters, and boundaries](./2026-07-26-frontend-ports-adapters-and-boundaries-design.md) +- [Client cache and browser storage](./2026-07-28-client-cache-and-storage-design.md) +- [VD-13 Client cache scope와 persistence](../adr/VD-13-client-cache-scope-and-persistence.md) +- [Protobuf browser transport와 REST Gateway](./2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md) +- [VD-29 Connect-Web와 browser Protobuf runtime](../adr/VD-29-connect-web-and-browser-protobuf-runtime.md) +- [VD-30 Protobuf contract와 REST Gateway](../adr/VD-30-protobuf-contract-and-rest-gateway.md) - [Contract compatibility](../contracts/compatibility.md) -- [Frontend platform testing strategy](../testing/frontend-platform-testing-strategy.md) +- [Frontend platform testing strategy](2026-07-26-frontend-platform-testing-strategy-design.md) diff --git a/docs/design/2026-07-28-client-cache-and-storage-design.md b/docs/design/2026-07-28-client-cache-and-storage-design.md index 95922e0e..3e712f83 100644 --- a/docs/design/2026-07-28-client-cache-and-storage-design.md +++ b/docs/design/2026-07-28-client-cache-and-storage-design.md @@ -13,7 +13,7 @@ - 범위: TanStack Query memory cache, Local/Session Storage, IndexedDB query persistence 경계, 탭 간 invalidation - 관련 결정: - [VD-13 client cache scope와 persistence](./decisions/VD-13-client-cache-scope-and-persistence.md) + [VD-13 client cache scope와 persistence](../adr/VD-13-client-cache-scope-and-persistence.md) - query persistence reference 상태: `DESIGNED_NOT_IMPLEMENTED` - query persistence product 상태: `NOT_SELECTED` @@ -405,7 +405,7 @@ locking에 사용하지 않는다. query key factory와 함께 immutable scope/persistence profile을 등록한다. freshness, GC, refetch, retry, result budget, pagination과 conditional policy는 -[VD-25](./decisions/VD-25-server-state-cache-lifecycle.md)의 +[VD-25](../adr/VD-25-server-state-cache-lifecycle.md)의 `ServerStateProfile`이 유일하게 소유한다. ```ts @@ -1682,14 +1682,14 @@ gate를 자동 충족하지 않는다. ## 21. 관련 자료 -- [API contract, Schema, Mapper와 Server State](./api-contract-schema-mapper-and-server-state.md) -- [VD-25 Server State Cache lifecycle](./decisions/VD-25-server-state-cache-lifecycle.md) -- [Browser data capability completion ledger](./browser-data-capability-completion-ledger.md) -- [TypeScript, 상태 소유권, 데이터 흐름](./typescript-state-and-data-flow.md) -- [Frontend ports, adapters and boundaries](./frontend-ports-adapters-and-boundaries.md) -- [Browser file and origin-storage platform](./browser-file-and-origin-storage.md) -- [VD-11 browser file and origin-storage 경계](./decisions/VD-11-browser-file-and-origin-storage.md) -- [VD-13 client cache scope와 persistence](./decisions/VD-13-client-cache-scope-and-persistence.md) +- [API contract, Schema, Mapper와 Server State](./2026-07-28-api-contract-schema-mapper-and-server-state-design.md) +- [VD-25 Server State Cache lifecycle](../adr/VD-25-server-state-cache-lifecycle.md) +- [Browser data capability completion ledger](./2026-07-30-browser-data-capability-completion-ledger-design.md) +- [TypeScript, 상태 소유권, 데이터 흐름](./2026-07-26-typescript-state-and-data-flow-design.md) +- [Frontend ports, adapters and boundaries](./2026-07-26-frontend-ports-adapters-and-boundaries-design.md) +- [Browser file and origin-storage platform](./2026-07-27-browser-file-and-origin-storage-design.md) +- [VD-11 browser file and origin-storage 경계](../adr/VD-11-browser-file-and-origin-storage.md) +- [VD-13 client cache scope와 persistence](../adr/VD-13-client-cache-scope-and-persistence.md) - [Client cache and Web Storage recovery](../operations/client-cache-and-storage-recovery.md) - [TanStack Query important defaults](https://tanstack.com/query/latest/docs/framework/react/guides/important-defaults) - [TanStack Query persistence](https://tanstack.com/query/v5/docs/framework/react/plugins/persistQueryClient) diff --git a/docs/design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md b/docs/design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md index 40c1efb6..fac08360 100644 --- a/docs/design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md +++ b/docs/design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md @@ -8,14 +8,14 @@ unary/server-stream lifecycle runtime은 `AVAILABLE_NOT_COMPOSED`; vendor runtime/dependency/proto/descriptor/proxy는 없음 - 관련 결정: - - [VD-23 API transport selection과 REST execution](./decisions/VD-23-api-transport-selection-and-rest-execution.md) - - [VD-24 Runtime schema와 boundary mapper](./decisions/VD-24-runtime-schema-and-boundary-mapper.md) - - [VD-25 Server state cache lifecycle](./decisions/VD-25-server-state-cache-lifecycle.md) - - [VD-27 gRPC-Web unary와 server stream](./decisions/VD-27-grpc-web-unary-and-server-stream.md) - - [VD-29 Connect-Web와 browser Protobuf runtime](./decisions/VD-29-connect-web-and-browser-protobuf-runtime.md) - - [VD-30 Protobuf contract와 REST Gateway](./decisions/VD-30-protobuf-contract-and-rest-gateway.md) + - [VD-23 API transport selection과 REST execution](../adr/VD-23-api-transport-selection-and-rest-execution.md) + - [VD-24 Runtime schema와 boundary mapper](../adr/VD-24-runtime-schema-and-boundary-mapper.md) + - [VD-25 Server state cache lifecycle](../adr/VD-25-server-state-cache-lifecycle.md) + - [VD-27 gRPC-Web unary와 server stream](../adr/VD-27-grpc-web-unary-and-server-stream.md) + - [VD-29 Connect-Web와 browser Protobuf runtime](../adr/VD-29-connect-web-and-browser-protobuf-runtime.md) + - [VD-30 Protobuf contract와 REST Gateway](../adr/VD-30-protobuf-contract-and-rest-gateway.md) - backend handoff: - [Backend API와 Server State contract](./backend-api-and-server-state-contract.md) + [Backend API와 Server State contract](../architecture/backend-api-and-server-state-contract.md) - 운영 절차: [API contract와 server-state recovery](../operations/api-contract-and-server-state-recovery.md) diff --git a/docs/design/2026-07-28-server-file-capability-infrastructure-design.md b/docs/design/2026-07-28-server-file-capability-infrastructure-design.md index c02dfa2d..d127ec6c 100644 --- a/docs/design/2026-07-28-server-file-capability-infrastructure-design.md +++ b/docs/design/2026-07-28-server-file-capability-infrastructure-design.md @@ -26,7 +26,7 @@ runtime composition을 설치하지 않는다. 브라우저 쪽 capability envelope, bounded fetch, resume checkpoint와 Image CDN descriptor 계약은 -[`presigned-transfer-and-image-cdn.md`](./presigned-transfer-and-image-cdn.md)와 +[`presigned-transfer-and-image-cdn.md`](./2026-07-30-presigned-transfer-and-image-cdn-design.md)와 VD-12가 소유한다. Range resume/background 경계는 VD-14, top-level transfer composition과 Image descriptor provider는 VD-16이 소유한다. 이 문서의 server port를 그 frontend DTO에 직접 노출하지 않고, 제품 BFF/controller가 두 경계 diff --git a/docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md b/docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md index 3ade8eae..0f98fc89 100644 --- a/docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md +++ b/docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md @@ -370,16 +370,16 @@ seekable/staging 정책, WP-04와 WP-05의 lifecycle/config 계약은 설계 단 ## 11. 상세 문서 -- [Browser file and origin storage](./browser-file-and-origin-storage.md) -- [Client cache and storage](./client-cache-and-storage.md) -- [Presigned transfer and Image CDN](./presigned-transfer-and-image-cdn.md) -- [Server file capability infrastructure](./server-file-capability-infrastructure.md) -- [VD-11 Browser file and origin-storage](./decisions/VD-11-browser-file-and-origin-storage.md) -- [VD-12 Presigned transfer and Image CDN](./decisions/VD-12-presigned-transfer-and-image-cdn.md) -- [VD-13 Client cache scope and persistence](./decisions/VD-13-client-cache-scope-and-persistence.md) -- [VD-14 Resumable download and background download](./decisions/VD-14-resumable-download-and-background-transfer.md) -- [VD-15 Origin storage lifecycle and migration](./decisions/VD-15-origin-storage-lifecycle-and-migration.md) -- [VD-16 Browser transfer composition and image delivery](./decisions/VD-16-browser-transfer-composition-and-image-delivery.md) +- [Browser file and origin storage](./2026-07-27-browser-file-and-origin-storage-design.md) +- [Client cache and storage](./2026-07-28-client-cache-and-storage-design.md) +- [Presigned transfer and Image CDN](./2026-07-30-presigned-transfer-and-image-cdn-design.md) +- [Server file capability infrastructure](./2026-07-28-server-file-capability-infrastructure-design.md) +- [VD-11 Browser file and origin-storage](../adr/VD-11-browser-file-and-origin-storage.md) +- [VD-12 Presigned transfer and Image CDN](../adr/VD-12-presigned-transfer-and-image-cdn.md) +- [VD-13 Client cache scope and persistence](../adr/VD-13-client-cache-scope-and-persistence.md) +- [VD-14 Resumable download and background download](../adr/VD-14-resumable-download-and-background-transfer.md) +- [VD-15 Origin storage lifecycle and migration](../adr/VD-15-origin-storage-lifecycle-and-migration.md) +- [VD-16 Browser transfer composition and image delivery](../adr/VD-16-browser-transfer-composition-and-image-delivery.md) - [Browser file/storage recovery](../operations/browser-file-storage-recovery.md) - [Client cache/storage recovery](../operations/client-cache-and-storage-recovery.md) - [Browser transfer recovery](../operations/browser-transfer-recovery.md) diff --git a/docs/design/2026-07-30-presigned-transfer-and-image-cdn-design.md b/docs/design/2026-07-30-presigned-transfer-and-image-cdn-design.md index bd36689b..72bd1517 100644 --- a/docs/design/2026-07-30-presigned-transfer-and-image-cdn-design.md +++ b/docs/design/2026-07-30-presigned-transfer-and-image-cdn-design.md @@ -19,7 +19,7 @@ authorization owner는 아직 조합하지 않는다. 이 개별 runtime은 > `src/adapters/http/fileserver-upload.ts`의 `createFileserverUploadClient`(`POST /v1/files`)이고, > 재개가 없다(`docs/manual/02-decision-tables.md` 「파일 업로드」). 이 문서의 경로는 제품 > backend가 같은 BFF 계약을 직접 만들 때 쓴다 -> ([`server-file-capability-infrastructure.md`](./server-file-capability-infrastructure.md)). +> ([`server-file-capability-infrastructure.md`](./2026-07-28-server-file-capability-infrastructure-design.md)). > presigned 다운로드와 private Image CDN descriptor 발급 서버도 같은 이유로 짝 백엔드에 없다. ## 0. 현재 구현과 목표 상태 @@ -46,10 +46,10 @@ admission은 이 status와 별도 축이다. `남은 목표`가 구현됐다는 뜻은 아니다. 특히 foreground whole-object streaming 증거를 Range resume나 app-managed background download 증거로 재사용하지 않는다. Range와 background download의 상세 상태 머신, destination, fallback, rollout과 완료 기준은 -[VD-14](./decisions/VD-14-resumable-download-and-background-transfer.md)가 +[VD-14](../adr/VD-14-resumable-download-and-background-transfer.md)가 소유한다. top-level runtime composition, account teardown, Image descriptor provider/refresh와 safe presentation projection은 -[VD-16](./decisions/VD-16-browser-transfer-composition-and-image-delivery.md)이 +[VD-16](../adr/VD-16-browser-transfer-composition-and-image-delivery.md)이 소유한다. ## 1. 경계와 topology @@ -526,7 +526,7 @@ partial bytes를 기존 파일 뒤에 append하지 않는다. - system picker 미지원 환경의 browser-managed handoff/server-generation fallback 상세 불변조건과 promotion gate는 -[VD-14](./decisions/VD-14-resumable-download-and-background-transfer.md)를 따른다. +[VD-14](../adr/VD-14-resumable-download-and-background-transfer.md)를 따른다. Range의 primary current status는 `DESIGNED_NOT_IMPLEMENTED`다. ### 5.1 아직 구현되지 않은 strategy selector @@ -889,12 +889,12 @@ promotion을 막는다. fake나 emulator success를 actual provider evidence로 ## 9. 표준·vendor 참고 -- [Browser data capability completion ledger](./browser-data-capability-completion-ledger.md) +- [Browser data capability completion ledger](./2026-07-30-browser-data-capability-completion-ledger-design.md) - [Fetch Standard](https://fetch.spec.whatwg.org/) - [RFC 9110 HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110.html) - [File System Standard](https://fs.spec.whatwg.org/) -- [VD-14 resumable download와 background download](./decisions/VD-14-resumable-download-and-background-transfer.md) -- [VD-16 browser transfer composition과 image delivery](./decisions/VD-16-browser-transfer-composition-and-image-delivery.md) +- [VD-14 resumable download와 background download](../adr/VD-14-resumable-download-and-background-transfer.md) +- [VD-16 browser transfer composition과 image delivery](../adr/VD-16-browser-transfer-composition-and-image-delivery.md) - [HTML responsive images](https://html.spec.whatwg.org/multipage/images.html) - [tus resumable upload protocol](https://tus.io/protocols/resumable-upload) - [Amazon S3 presigned URLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html) diff --git a/docs/design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md b/docs/design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md index a546b31c..1a97ee72 100644 --- a/docs/design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md +++ b/docs/design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md @@ -26,12 +26,12 @@ composition은 선택하지 않았다. 따라서 reference source가 있다는 capability가 설치됐거나 production-ready라는 뜻이 아니다. 상세 결정은 -[VD-28](./decisions/VD-28-realtime-events-web-push-and-bounded-polling.md)이 +[VD-28](../adr/VD-28-realtime-events-web-push-and-bounded-polling.md)이 소유한다. 공통 cache와 account scope는 -[Client cache and browser storage platform](./client-cache-and-storage.md), +[Client cache and browser storage platform](./2026-07-28-client-cache-and-storage-design.md), 선택 capability의 설치·제거 절차는 -[Optional frontend adapter recipes](./optional-adapter-recipes.md), 계층 방향은 -[Frontend ports, adapters, and boundaries](./frontend-ports-adapters-and-boundaries.md) +[Optional frontend adapter recipes](../architecture/optional-adapter-recipes.md), 계층 방향은 +[Frontend ports, adapters, and boundaries](./2026-07-26-frontend-ports-adapters-and-boundaries-design.md) 를 따른다. @@ -339,7 +339,7 @@ measured freshness/interaction requirement ### 2.3 인접 server-stream protocol과의 경계 -[API contract, Schema, Mapper와 Server State](./api-contract-schema-mapper-and-server-state.md)의 +[API contract, Schema, Mapper와 Server State](./2026-07-28-api-contract-schema-mapper-and-server-state-design.md)의 Connect/gRPC-Web server stream과 향후 GraphQL subscription은 이 문서의 SSE/WebSocket과 자동으로 같은 adapter가 아니다. @@ -2551,14 +2551,14 @@ production traffic 승인. 저장소 내부: -- [VD-28](./decisions/VD-28-realtime-events-web-push-and-bounded-polling.md) -- [VD-10 optional capability recipes](./decisions/VD-10-optional-capability-recipes.md) -- [Frontend ports, adapters, and boundaries](./frontend-ports-adapters-and-boundaries.md) -- [Optional frontend adapter recipes](./optional-adapter-recipes.md) -- [Client cache and browser storage](./client-cache-and-storage.md) -- [API contract, Schema, Mapper와 Server State](./api-contract-schema-mapper-and-server-state.md) -- [Browser file and origin-storage platform](./browser-file-and-origin-storage.md) -- [TypeScript, state, and data flow](./typescript-state-and-data-flow.md) +- [VD-28](../adr/VD-28-realtime-events-web-push-and-bounded-polling.md) +- [VD-10 optional capability recipes](../adr/VD-10-optional-capability-recipes.md) +- [Frontend ports, adapters, and boundaries](./2026-07-26-frontend-ports-adapters-and-boundaries-design.md) +- [Optional frontend adapter recipes](../architecture/optional-adapter-recipes.md) +- [Client cache and browser storage](./2026-07-28-client-cache-and-storage-design.md) +- [API contract, Schema, Mapper와 Server State](./2026-07-28-api-contract-schema-mapper-and-server-state-design.md) +- [Browser file and origin-storage platform](./2026-07-27-browser-file-and-origin-storage-design.md) +- [TypeScript, state, and data flow](./2026-07-26-typescript-state-and-data-flow-design.md) - [`RealtimePort` copyable recipe](../../recipes/frontend-capabilities/contracts.ts) - [Deterministic realtime fake](../../recipes/frontend-capabilities/fake-adapters.ts) - [Optional capability contract test](../../tests/recipes/optional-capability-contracts.test.ts) diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index 7b33b12d..cf44ae29 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -814,4 +814,4 @@ corepack pnpm test:sample-removal -- --feature=invoice-feature - 브라우저 테스트(`playwright test`)를 한 checkout에서 둘 이상 동시에 돌릴 때는 실행마다 다른 `TEST_RUN_ID`를 준다. 예: `TEST_RUN_ID=a corepack pnpm exec playwright test`. 그 실행의 빌드·결과·report는 `.tmp/runs//` 아래에 생긴다. - 서버 포트는 run ID가 없어도 빈 포트를 고른다. 같은 기계의 두 worktree도 부딪히지 않는다. 고정하려면 `TEST_E2E_PORT` 같은 포트 변수를 준다. - `ci:gate`에는 `TEST_RUN_ID`를 주지 않는다. 주면 증거가 기본 경로에 생기지 않아 게이트가 `command-generated evidence was not freshly produced`로 실패한다. - - 변수 표와 한계는 [테스트 전략 13.6절](../testing/frontend-platform-testing-strategy.md)에 있다(1105/12-04). + - 변수 표와 한계는 [테스트 전략 13.6절](../design/2026-07-26-frontend-platform-testing-strategy-design.md)에 있다(1105/12-04). diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index 991025b1..145996e6 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -425,7 +425,7 @@ export function mapInvoiceCreateProblem( - 짝 백엔드를 그대로 쓰면 Fileserver 한 번 업로드를 쓴다. - 큰 파일을 끊긴 데서 이어 올려야 하면 지금 템플릿에는 짝 경로가 없다. 짝 백엔드의 tus(`/v1/uploads`)를 부르는 프론트 client는 아직 없다. -- presigned 레시피는 제품 backend가 그 BFF 계약(`docs/architecture/server-file-capability-infrastructure.md`)을 직접 만들 때만 쓴다. +- presigned 레시피는 제품 backend가 그 BFF 계약(`docs/design/2026-07-28-server-file-capability-infrastructure-design.md`)을 직접 만들 때만 쓴다. **결과 읽기**: `upload()`는 `Result`를 돌려준다. diff --git a/docs/manual/03-outside-feature-folder.md b/docs/manual/03-outside-feature-folder.md index d96aeef6..c2b47d46 100644 --- a/docs/manual/03-outside-feature-folder.md +++ b/docs/manual/03-outside-feature-folder.md @@ -122,7 +122,7 @@ release admission refused for staging: - `label`은 `browser-files` 같은 소문자 kebab-case 토큰으로 쓴다. 다른 형식이면 조립이 `TypeError`로 멈춘다. - `close`가 던지면 scope가 `FAILED`에 머물고 모든 서버 요청이 `SCOPE_FENCED`로 막힌다. 진단 `cache.operation.failed`에 `reason: PARTICIPANT_FAILED`와 `scope_participant: