刀豆 Console 엔지니어링 설계 문서 · 02부. 상태: 구현된 코드에 맞게 재작성됨(2026-07-16). 이 글에서는 시스템의 계층 구성, 각 데이터 유형을 소유하는 측, 양측의 통신 방식만 다룹니다. 인증은 03, 연동 구성은 05, 데이터베이스는 13, 프로젝트 계약은 18을 참조하세요.
刀豆 Console은 통합 제어 플레인이고, 각 프로젝트는 자율적인 런타임 플레인입니다. Console은 ID, 권한, 콘텐츠, 버전, 게시를 중앙에서 관리하고, 각 프로젝트는 자체 관리자 비즈니스 로직, 컴포넌트 구현, 프런트엔드 렌더링을 유지합니다. 양측은 버전이 지정된 REST, JWT/JWKS, HMAC 및 브라우저 postMessage를 통해서만 통신합니다. 프로세스나 비즈니스 데이터베이스를 공유하지 않으며, 상대측의 렌더링 코드를 중복 구현하지도 않습니다.
절대 타협할 수 없는 네 가지 원칙:
계층별 권한: 컴포넌트 fields/sample의 원본 정의는 프로젝트 코드에 있으며, Console DB에는 계약 검증을 통과한 환경별 LKG가 저장됩니다. 랜딩/블로그의 경우 Console DB가 ID, 초안 및 현재 게시된 스냅샷의 유일한 원본입니다.
렌더링은 프로젝트의 책임: 컴포넌트 구조와 데이터는 Console에 있고, 컴포넌트 스타일과 렌더러는 프로젝트에 있습니다. 미리보기와 프로덕션 모두 프로젝트 자체 렌더러를 사용합니다.
보안 영역 분리: 프로젝트의 관리자 연동과 콘텐츠/미리보기 연동은 서로 독립적으로 연결할 수 있으며, 각각 다른 구성, 자격 증명, 세션, 쿠키 및 권한 대상을 사용할 수 있습니다.
물리적 환경 분리: 제어 플레인은 platform에, 테스트 콘텐츠는 test에, 프로덕션 콘텐츠는 prod에 있습니다. 테스트/프로덕션 구성도 암시적 상속이 없는 서로 독립된 두 레코드입니다.
Console의 책임:
Better Auth 플랫폼 ID, 사용자, 프로젝트, 역할 및 3차원 RBAC.
관리자와 콘텐츠라는 두 가지 프로젝트 연동 유형의 구성, 자격 증명, 활성화, 비활성화 및 감사.
논리적 랜딩 페이지, 완전한 현지화 페이지, 공유 컴포넌트 토폴로지, 블로그, 다국어 콘텐츠, SEO, 테마 선택 및 정확한 컴포넌트 참조.
초안은 명시적으로 저장됩니다(D-95: 저장 시점은 사용자가 결정하며, 저장하지 않은 변경 사항이 있는 상태로 나갈 때 경고 표시). 랜딩에는 A/B/C 검사와 환경 적용이 있으며, 블로그 테스트/프로덕션은 초안/게시됨을 반영하고 직접 원자적으로 게시합니다.
프로젝트 기능 동기화 및 마지막 정상 상태 프로젝션.
편집 상태를 iframe 미리보기에 실시간으로 전달하고, 별도의 미리보기 창에서 초안을 읽을 수 있도록 권한을 부여합니다.
Console이 책임지지 않는 항목:
프로젝트 관리자 시스템의 비즈니스 로직과 비즈니스 데이터.
프로젝트 컴포넌트의 React/Vue/CSS 구현.
프로젝트의 프런트엔드 라우팅 프레임워크 또는 SSR/SSG/ISR 전략 선택.
프로젝트 비즈니스 데이터베이스의 비밀번호.
Redis를 실행하거나 플랫폼 상태를 저장하는 데 사용하는 일. 속도 제한, 프로젝트 SID/임대 및 재전송 방지는 모두 PostgreSQL로 통합되었습니다.
프로젝트의 책임:
자체 관리자 비즈니스 로직, 비즈니스 데이터베이스 및 서버 측 권한 검사 장치.
컴포넌트 레지스트리와 각 technicalName에 정확히 대응하는 스키마/렌더러 및 실제 스타일. 프로젝트가 componentId를 생성합니다.
언어, 테마, 색상 모드, 컴포넌트 매니페스트, 미리보기 및 재검증을 위한 기능 엔드포인트.
관리자/미리보기 브리지 JWT 검증 및 각각의 로컬 세션.
프런트엔드는 Console의 게시 API에서 게시된 콘텐츠를 읽은 다음, 프로젝트 전략에 따라 SSR/SSG/ISR을 사용해 캐시하고 렌더링합니다.
프로젝트 측의 주요 비즈니스 작업을 감사하고 requestId를 사용해 Console 레코드와 대조합니다.
프로젝트는 편집된 콘텐츠를 신뢰할 수 있는 두 번째 CMS로 별도 저장해서는 안 됩니다. 로컬 캐시는 게시된 콘텐츠의 폐기 가능한 캐시로만 사용할 수 있습니다.
┌────────────────────────── Console 控制面 :8888 ──────────────────────────┐
│ Better Auth │ 项目/RBAC │ Admin Integration │ Content Integration │
│ │ │ │ │
│ platform schema: 用户/Session、项目、接入、安全短状态、能力投影、审计 │
│ test schema: Landing Draft/Test；Blog Draft/Published；环境 taxonomy │
│ prod schema: Landing Prod C；Blog Draft A/Published B 当前槽位 │
└───────────────┬──────────────────────────────┬───────────────────────────┘
│ │
Admin 身份与复核 Content/Preview 契约
JWT/JWKS + HMAC HMAC + Preview JWT + REST
│ │
┌───────────────▼──────────────────────────────▼───────────────────────────┐
│ Project Launchpad / 其他项目运行面 │
│ /admin 业务后台 │ 项目业务库 │ component registry │ Preview renderer │
│ 项目本地 Session│ │ 前台 SSR/SSG/ISR │ revalidate/capability│
└───────────────────────────────────────────────────────────────────────────┘
프로젝트는 관리자 통합 없이 콘텐츠 통합을 사용하거나 관리자 통합만 사용할 수 있습니다. 두 통합을 같은 도메인에 배포하더라도 보안 영역을 분리한다는 원칙은 달라지지 않습니다.
Console iframe 진입점:
Console 校验平台 Session 与项目准入
→ 签发约 120 秒 Admin Bridge JWT
→ iframe 打开项目 embedded bridge
→ 项目用 Console JWKS 验签，并核对 project/env/target
→ 项目写入本地 Admin Session Cookie
→ 回到原 /admin deep link
프로젝트 관리자를 직접 열기:
项目 /admin 无本地 Session
→ 项目生成独立 state transaction
→ 跳 Console authorize
→ Console 有 Session：直接验权；无 Session：先登录
→ Console 签 standalone Bridge JWT
→ 项目核对 state + JWT，建立本地 Session
→ 回原 deep link
브리지 JWT는 일회성 ID 전달만 처리하며 장기 액세스 토큰이 아닙니다. 프로젝트 세션은 최대 7일간 유지되며, 프로젝트의 서버 측 가드는 5분마다 Console을 통해 권한을 다시 검증합니다. 프로젝트에서 로컬로 로그아웃하면 Console 세션이 아닌 프로젝트 세션만 삭제됩니다.
Console Landing Draft A
→ 强制检查后覆盖 Test B
→ 强制生产检查后覆盖 Prod C
→ 记录发布人/revision/审计
→ HMAC 通知项目 revalidate
→ 项目前台重新读取 published API / 更新本地缓存
콘텐츠는 이동하지만 구성과 자격 증명은 이동하지 않습니다. 프로덕션 프로젝트는 Console API에서 게시 상태를 읽을 수 있지만 초안 엔드포인트에는 액세스할 수 없습니다. 캐시가 무효화되면 오리진으로 대체할 수 있으며, Console은 편집 가능한 데이터베이스 사본을 프로젝트에 푸시하지 않습니다.
Console 编辑器内存态
├─ iframe：postMessage 实时覆盖项目 Preview renderer
└─ DB：有变化时 debounce 1 秒，持续输入 maxWait 30 秒
独立 Preview 窗口
→ Preview Session 鉴权
→ 读取 Console 草稿接口
→ 每 5 秒按 revision 轮询；无变化不重复渲染
미리보기와 관리자는 플랫폼 ID 루트 및 JWT/JWKS/HMAC 인프라를 공유하지만 쿠키, 세션, 대상 또는 장기 자격 증명은 공유하지 않습니다. iframe의 postMessage는 HMAC 비밀 키가 아니라 프로토콜에 정의된 편집 데이터만 전달합니다.
데이터 | 단일 진실 공급원 | 프로젝트 측 형태 |
|---|---|---|
플랫폼 사용자 및 세션 |
| 수명이 짧은 브리지 ID만 수신하며 플랫폼 세션은 복제하지 않음 |
속도 제한, 프로젝트 SID/임대 및 재전송 방지 |
| 프로젝트는 계약에 정의된 대로만 사용/재검증/로그아웃을 호출하며 Console 스토리지를 보유하지 않음 |
사용자의 최근 활동 |
| 3단계 온라인 상태가 없으며 프로젝트와 동기화되지 않음 |
프로젝트 멤버 및 권한 |
| 로컬 세션에 필요한 스냅샷을 저장하며 권한은 5분마다 다시 검증됨 |
관리자 통합 |
| 환경 변수의 관리자 자격 증명 및 프로토콜 엔드포인트 |
콘텐츠/미리보기 통합 |
| 환경 변수의 콘텐츠 자격 증명 및 프로토콜 엔드포인트 |
컴포넌트 매니페스트/스키마/샘플 | Console 동기화 프로젝션 | 프로젝트 레지스트리는 선언의 공급원이고, Console DB는 콘텐츠 오케스트레이션에 사용되는 동기화된 단일 진실 공급원임 |
페이지/블로그/초안 |
| 편집 가능한 기준 사본을 저장하지 않음 |
게시 상태 캐시 | Console 게시 API | 프로젝트는 캐시되거나 정적으로 렌더링될 수 있지만, 다시 빌드할 수 있어야 합니다. |
컴포넌트 스타일 및 렌더러 | 프로젝트 저장소 | 미리보기와 프로덕션은 동일한 프로젝트 구현을 재사용합니다. |
콘텐츠 테이블은 프로젝트 격리를 위해 project_id를 사용하며, 기존 tenant_id 용어는 사용하지 않습니다. 감사 테이블의 사용자/프로젝트 식별자는 쓰기 시점에 생성된 스냅샷이며 FK가 없습니다. 따라서 연결된 엔터티가 삭제된 후에도 기록을 읽을 수 있습니다.
환경에는 서로 혼동해서는 안 되는 두 가지 차원이 있습니다.
콘텐츠 환경: test / prod 스키마. 편집 내용은 test에만 반영되며, prod에는 승격 작업을 통해서만 쓸 수 있습니다.
프로젝트 배포 환경: 각 통합에는 테스트와 프로덕션 구성이 별도로 있으며, 오리진, 경로, 자격 증명 및 상태 값이 완전히 독립적입니다.
UI에서 “테스트 필드를 프로덕션 양식에 복사” 옵션을 제공할 수 있지만, 저장하면 독립적인 프로덕션 레코드가 되며 이후 테스트 변경 사항은 프로덕션에 영향을 주지 않습니다. 프로덕션 오리진에는 HTTPS가 필요하지만, 로컬 테스트에서는 HTTP가 허용됩니다.
프로젝트는 콘텐츠 기능을 통해 다음 항목을 선언합니다.
지원되는 로캘 및 기본 로캘.
지원되는 테마, 기본 테마 및 각 테마에 허용되는 색상 모드.
컴포넌트 매니페스트 엔드포인트 및 안정적인 미리보기 경로.
재검증 등의 프로토콜 엔드포인트.
Console은 콘텐츠 HMAC을 사용해 기능을 선제적으로 가져오고 마지막으로 정상 확인된 버전을 저장합니다. 컴포넌트의 식별 정보는 프로젝트에서 생성한 componentId + technicalName입니다. 동일한 기술 이름은 동일한 버전을 식별하며, 콘텐츠는 해당 이름을 정확히 참조합니다. 현재 라이브 프로덕션의 참조만 필드를 잠급니다. 호환성을 깨뜨리는 새 버전에는 새로운 ID와 기술 이름을 사용합니다. 해당 버전이 없으면 다른 버전을 추측하지 말고 안전하게 실패해야 합니다.
기능 동기화는 콘텐츠 폴백이 아닙니다. 프로젝트 엔드포인트를 사용할 수 없을 때 최근에 성공한 스냅샷을 표시할 수는 있지만, 모의 기능을 임의로 만들어서는 안 되며 동기화 실패를 성공으로 처리해서도 안 됩니다.
모든 요청은 다음 조건을 모두 충족해야 합니다.
有效平台身份
∩ 有效项目成员关系
∩ permission domain
∩ environment scope
∩ 资源自身状态约束
일반적인 역할 등급:
운영 담당자: 권한이 있는 프로젝트의 관리자 영역에 접근하여 콘텐츠를 편집할 수 있지만, 통합 자격 증명은 볼 수 없습니다.
개발자: 관리자/콘텐츠 통합 구성을 볼 수 있지만 수정할 수는 없습니다.
프로젝트 소유자: 자격 증명을 저장하거나 활성화 또는 비활성화하고 재발급할 수 있습니다. 자격 증명의 활성화, 비활성화 또는 재발급처럼 즉시 적용되는 작업의 경우 프런트엔드는 확인 대화 상자를 표시하고, 서버는 접근 제어를 위해 오직 3차원 RBAC에만 의존합니다(D-85).
관리자 자격 증명은 관리자 검증 요청에만 서명하며, 콘텐츠 자격 증명은 기능, 콘텐츠 및 재검증 요청에만 서명합니다. 영역 간 검증과 폴백은 엄격히 금지됩니다.
시스템 간에는 2PC를 사용하지 않습니다. 대신 멱등성, requestId, 양측 감사 및 재시도 가능한 보상 처리를 사용하도록 설계되었습니다.
미리보기 연결이 끊겨도 초안 저장에는 영향을 주지 않습니다. 초안 저장에 실패하면 시스템은 저장된 것처럼 처리하지 않습니다.
재검증 실패가 성공한 승격 작업을 롤백하지는 않지만, 실패 여부를 관찰할 수 있고 재시도할 수 있어야 합니다.
프로젝트 엔드포인트에 연결할 수 없는 경우, Admin/Preview는 Console 모의 페이지로 대체되지 않고 명시적으로 실패합니다.
활성 상태의 구성은 고정되며, 수정하거나 단일 자격 증명으로 다시 서명하려면 먼저 비활성화해야 합니다.
PostgreSQL을 사용할 수 없으면 Bridge는 일회성 사용을 차단하는 방식으로 실패합니다. 표준 HMAC 재전송 방지와 보조 요청 속도 제한은 둘 다 PG를 사용한다는 이유만으로 하나의 정책으로 통합되지 않으며, 각각 기존 장애 처리 정책을 유지합니다.
만료된 SID, 재전송 및 요청 속도 제한 행은 15분마다 정리됩니다. 정리 실패는 용량에만 영향을 미치며 요청 시점의 만료 검사를 변경하지 않습니다.
현재 프로덕션 준비 상태에서 부족한 부분은 활성화 전 준비 상태 프로브, 중요 감사용 신뢰할 수 있는 아웃박스, 동시 CAS, 여러 kid 값을 사용한 무중단 자격 증명 교체입니다. 자세한 내용은 15 §9를 참조하세요.
“모든 프로젝트 컴포넌트를 Console의 공유 렌더러로 이전”하면 다음과 같은 세 가지 새로운 문제가 생깁니다.
Console은 각 프로젝트의 UI 프레임워크 및 종속성과 함께 릴리스해야 하므로 메인 저장소와의 결합이 다시 생깁니다.
미리보기가 프로젝트의 프로덕션 배포에 실제로 사용되는 코드와 달라져 오히려 일관성이 훼손될 수 있습니다.
프로젝트별 스타일, 런타임 기능 및 데이터 소스가 플랫폼에 노출될 수밖에 없습니다.
따라서 특정 UI 렌더러가 아니라 프로토콜과 순수 타입 계약만 공유합니다. “미리보기-프로덕션 일관성”이란 Console이 렌더러를 복사한다는 의미가 아니라, 프로젝트의 Preview 및 Production 환경이 프로젝트 저장소의 동일한 렌더러를 재사용한다는 의미입니다.
/Users/edwin/coding/diaoyan/project-launchpad는 최초의 실제 참조 프로젝트입니다.
Admin iframe 및 독립형 SSO 흐름이 모두 검증되었습니다.
로컬 프로젝트에서 로그아웃한 후에도 Console 세션을 별도의 조작 없이 재사용할 수 있습니다.
콘텐츠 HMAC 기능 동기화 정보와 컴포넌트 매니페스트가 데이터베이스에 영구 저장되었습니다.
15개의 컴포넌트 계열과 변경 불가능한 16개 버전을 Console에서 개별적으로 미리 볼 수 있습니다.
테마와 light/dark/system 모드는 프로젝트 기능을 통해 선언되며, 컴포넌트 캔버스 배경은 컴포넌트 모드와 독립적입니다.
향후 프로젝트는 Project Launchpad의 비즈니스 UI나 기술 스택이 아니라 계약과 경계를 재현해야 합니다.
