@designfever/web-review-kit 0.1.0

package/docs/supabase-presence.md

@@ -0,0 +1,198 @@
+# Supabase presence adapter
+
+## 목적
+
+`df-web-review-kit`의 `ReviewPresenceAdapter` contract를 Supabase Realtime Presence로 구현하고 운영하기 위한 문서다.
+
+Lexus pilot Supabase project:
+
+```txt
+name: bb-qa
+url: https://vhqnvfkamnpgyqclohso.supabase.co
+```
+
+공식 문서 기준:
+
+- Presence는 접속자/활성 문서 같은 느리게 변하는 상태 공유에 맞다: https://supabase.com/docs/guides/realtime/presence
+- Realtime은 Broadcast, Presence, Postgres Changes를 제공한다: https://supabase.com/docs/guides/realtime
+- DB 변경 fan-out은 Broadcast가 scalability/security 측면에서 권장되고, Postgres Changes는 단순하지만 scale이 약하다: https://supabase.com/docs/guides/realtime/subscribing-to-database-changes
+- private Broadcast/Presence는 `realtime.messages` RLS policy와 `private: true` channel 설정이 필요하다: https://supabase.com/docs/guides/realtime/authorization
+
+## 현재 결론
+
+이번 presence 요구사항은 Supabase Presence가 맞다.
+
+목표는 "QA item이 바뀌면 실시간으로 동기화"가 아니라 "현재 누가 어떤 page/viewport/source를 보고 있는지"다. 따라서 Postgres Changes나 Broadcast보다 Presence가 먼저다.
+
+현재 shell UI는 두 단계로 보여준다.
+
+- 우측 QA panel: 현재 page에 있는 user id만 표시
+- sitemap: page별 user id 표시
+
+## Channel 전략
+
+권장 channel topic:
+
+```txt
+review-presence-<projectId>
+```
+
+page별 channel이 아니라 project 단위 channel을 쓴다. 그래야 `/review`를 열어 둔 사람이 서로 다른 page를 보고 있어도 sitemap에서 "누가 어느 페이지에 있는지"를 볼 수 있다.
+
+Payload의 `target`/`routeKey`로 page를 구분한다.
+
+topic은 Supabase Realtime 호환성을 위해 `:` 같은 구분자를 쓰지 않고, adapter에서 `channelPrefix`와 `projectId`를 alphanumeric/`_`/`-` slug로 normalize한다.
+
+## Adapter implementation
+
+현재 구현 위치:
+
+```txt
+packages/df-web-review-kit/src/react-shell/supabase-presence.ts
+```
+
+현재 package adapter는 Supabase client를 직접 생성하지 않고 `client`를 주입받는다. Host page 쪽에서 `@supabase/supabase-js`의 `createClient()`를 호출해 넘긴다. 이렇게 하면 package 본체가 Supabase dependency에 강하게 묶이지 않는다.
+
+현재 구현 특징:
+
+- channel topic은 `review-presence-<projectId>`로 생성한다.
+- `projectId`, `sessionId`, `userId`, `routeKey`, `target`, `source`, `viewport`, `mode`, `selectedItemId`, `selectedReviewNumber`를 track한다.
+- StrictMode/HMR에서 같은 topic channel이 중복으로 남지 않도록 bridge/refCount를 둔다.
+- `presenceState()` 결과는 `sessionId` 기준으로 dedupe한다.
+- primary Supabase presence 연결이 실패하면 `createFallbackPresenceAdapter()`로 local BroadcastChannel presence를 쓸 수 있다.
+
+## Public dev mode
+
+초기 연결 검증은 public channel로도 가능하다.
+
+```ts
+const presence = createSupabasePresenceAdapter({
+  client: supabase,
+  private: false,
+});
+```
+
+주의:
+
+- public channel은 같은 Supabase project key를 가진 사용자가 topic을 알면 subscribe 가능하다.
+- dev smoke test까지만 허용한다.
+
+## Private production mode
+
+production은 private channel을 권장한다.
+
+```ts
+const presence = createSupabasePresenceAdapter({
+  client: supabase,
+  private: true,
+});
+```
+
+client는 인증 세션을 가진 Supabase client여야 한다. private channel은 Realtime Authorization policy가 필요하다.
+
+## RLS sketch
+
+Supabase Realtime Authorization은 `realtime.messages`에 대한 RLS policy로 Broadcast/Presence 권한을 계산한다.
+
+project membership table을 둔다고 가정한다.
+
+```sql
+create table if not exists public.review_project_members (
+  project_id text not null,
+  user_id uuid not null references auth.users(id) on delete cascade,
+  created_at timestamptz not null default now(),
+  primary key (project_id, user_id)
+);
+
+alter table public.review_project_members enable row level security;
+
+create policy review_project_members_read_own
+  on public.review_project_members
+  for select
+  to authenticated
+  using ((select auth.uid()) = user_id);
+
+create index if not exists review_project_members_user_project_idx
+  on public.review_project_members (user_id, project_id);
+```
+
+Presence topic은 `review-presence-<projectId>` 형식이므로 RLS에서 topic을 project id로 해석한다.
+
+```sql
+create or replace function public.review_presence_project_id(topic text)
+returns text
+language sql
+immutable
+as $$
+  select nullif(regexp_replace(topic, '^review-presence-', ''), topic);
+$$;
+```
+
+Presence read/write policy:
+
+```sql
+create policy "authenticated can listen to review presence"
+on realtime.messages
+for select
+to authenticated
+using (
+  realtime.messages.extension = 'presence'
+  and exists (
+    select 1
+    from public.review_project_members member
+    where member.user_id = (select auth.uid())
+      and member.project_id = public.review_presence_project_id((select realtime.topic()))
+  )
+);
+
+create policy "authenticated can track review presence"
+on realtime.messages
+for insert
+to authenticated
+with check (
+  realtime.messages.extension = 'presence'
+  and exists (
+    select 1
+    from public.review_project_members member
+    where member.user_id = (select auth.uid())
+      and member.project_id = public.review_presence_project_id((select realtime.topic()))
+  )
+);
+```
+
+RLS performance notes:
+
+- `auth.uid()`는 `(select auth.uid())` 형태로 감싸서 per-row 호출을 줄인다.
+- RLS 조건에서 조회하는 `(user_id, project_id)`는 composite index를 둔다.
+- policy가 복잡해질수록 channel join latency가 늘 수 있다.
+
+## Env
+
+Lexus pilot에 붙일 때 후보 env:
+
+```txt
+VITE_REVIEW_SUPABASE_URL=https://vhqnvfkamnpgyqclohso.supabase.co
+VITE_REVIEW_SUPABASE_ANON_KEY=
+VITE_REVIEW_SUPABASE_PRESENCE_PRIVATE=false
+```
+
+브라우저에는 anon key만 둔다. service role key는 절대 넣지 않는다.
+
+`VITE_REVIEW_SUPABASE_ANON_KEY`가 비어 있으면 shell은 local BroadcastChannel presence로 fallback한다.
+
+## QA checklist
+
+1. Settings에서 각 브라우저에 다른 `User ID` 입력
+2. Browser A/B: 같은 target page로 `/review?target=/&w=540&h=1080`
+3. A/B 양쪽 우측 QA panel에서 서로의 user id 확인
+4. Browser B를 다른 target page로 이동
+5. A의 우측 QA panel에서는 B가 사라지고, sitemap에서는 B가 이동한 page에 표시되는지 확인
+6. B에서 viewport 변경 후 presence payload의 viewport가 바뀌는지 devtools로 확인
+7. B에서 다른 QA item 선택 후 `selectedReviewNumber`가 payload에 들어가는지 devtools로 확인
+8. B tab close 후 A에서 B가 사라지는지 확인
+
+## Open decisions
+
+- public dev mode를 package에 남길지.
+- private presence를 실제 production에서 쓸 때 auth/member policy를 어디까지 package 문서화할지.
+- sitemap presence를 별도 dashboard로 키울지.

package/docs/supabase-review-items.md

@@ -0,0 +1,365 @@
+# Supabase review item adapter
+
+## Purpose
+
+`df-web-review-kit`의 remote QA 저장소를 Supabase table로 검증하기 위한 문서다.
+
+Lexus pilot:
+
+```txt
+project: bb-qa
+url: https://vhqnvfkamnpgyqclohso.supabase.co
+table: review_items
+source: supabase
+```
+
+## Environment
+
+```env
+VITE_REVIEW_SUPABASE_URL=https://vhqnvfkamnpgyqclohso.supabase.co
+VITE_REVIEW_SUPABASE_ANON_KEY=
+VITE_REVIEW_SUPABASE_TABLE=review_items
+VITE_REVIEW_SUPABASE_PRESENCE_PRIVATE=false
+```
+
+`anon` key만 browser env에 넣는다. `service_role` key는 browser env에 넣지 않는다.
+
+## Schema
+
+Supabase SQL editor에서 실행한다.
+
+```sql
+create table if not exists public.review_items (
+  id text primary key,
+  project_id text not null,
+  route_key text not null,
+  source text not null default 'supabase',
+  review_number integer,
+  status text not null default 'todo',
+  item jsonb not null,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+
+create unique index if not exists review_items_project_review_number_idx
+  on public.review_items (project_id, source, review_number)
+  where review_number is not null;
+
+create index if not exists review_items_project_route_updated_idx
+  on public.review_items (project_id, source, route_key, updated_at desc);
+
+create index if not exists review_items_project_status_idx
+  on public.review_items (project_id, source, status);
+
+create table if not exists public.review_project_counters (
+  project_id text not null,
+  source text not null default 'supabase',
+  next_review_number integer not null default 1,
+  updated_at timestamptz not null default now(),
+  primary key (project_id, source),
+  constraint review_project_counters_next_review_number_check
+    check (next_review_number > 0)
+);
+
+create or replace function public.create_review_item(
+  p_id text,
+  p_project_id text,
+  p_route_key text,
+  p_source text,
+  p_status text,
+  p_item jsonb
+)
+returns public.review_items
+language plpgsql
+security invoker
+set search_path = public
+as $$
+declare
+  v_review_number integer;
+  v_now timestamptz := now();
+  v_row public.review_items;
+begin
+  insert into public.review_project_counters (
+    project_id,
+    source,
+    next_review_number,
+    updated_at
+  )
+  select
+    p_project_id,
+    p_source,
+    coalesce(max(review_number), 0) + 2,
+    v_now
+  from public.review_items
+  where project_id = p_project_id
+    and source = p_source
+  on conflict (project_id, source) do update
+    set next_review_number = greatest(
+          public.review_project_counters.next_review_number + 1,
+          excluded.next_review_number
+        ),
+        updated_at = excluded.updated_at
+  returning next_review_number - 1 into v_review_number;
+
+  insert into public.review_items (
+    id,
+    project_id,
+    route_key,
+    source,
+    review_number,
+    status,
+    item,
+    created_at,
+    updated_at
+  )
+  values (
+    p_id,
+    p_project_id,
+    p_route_key,
+    p_source,
+    v_review_number,
+    p_status,
+    p_item || jsonb_build_object(
+      'id', p_id,
+      'reviewNumber', v_review_number,
+      'projectId', p_project_id,
+      'routeKey', p_route_key,
+      'normalizedPath', coalesce(nullif(p_item->>'normalizedPath', ''), p_route_key),
+      'status', p_status,
+      'externalIssueId', p_id,
+      'submittedAt', coalesce(p_item->>'submittedAt', v_now::text),
+      'submitStatus', coalesce(p_item->>'submitStatus', 'submitted'),
+      'createdAt', v_now::text,
+      'updatedAt', v_now::text
+    ),
+    v_now,
+    v_now
+  )
+  returning * into v_row;
+
+  return v_row;
+end;
+$$;
+
+grant execute on function public.create_review_item(
+  text,
+  text,
+  text,
+  text,
+  text,
+  jsonb
+) to anon;
+
+grant select, insert, update, delete on public.review_items to anon;
+grant select, insert, update on public.review_project_counters to anon;
+
+alter table public.review_items enable row level security;
+alter table public.review_project_counters enable row level security;
+
+drop policy if exists review_items_lexus_read on public.review_items;
+create policy review_items_lexus_read
+  on public.review_items
+  for select
+  to anon
+  using (project_id = 'lexus-official-v2026');
+
+drop policy if exists review_items_lexus_insert on public.review_items;
+create policy review_items_lexus_insert
+  on public.review_items
+  for insert
+  to anon
+  with check (project_id = 'lexus-official-v2026');
+
+drop policy if exists review_items_lexus_update on public.review_items;
+create policy review_items_lexus_update
+  on public.review_items
+  for update
+  to anon
+  using (project_id = 'lexus-official-v2026')
+  with check (project_id = 'lexus-official-v2026');
+
+drop policy if exists review_items_lexus_delete on public.review_items;
+create policy review_items_lexus_delete
+  on public.review_items
+  for delete
+  to anon
+  using (project_id = 'lexus-official-v2026');
+
+drop policy if exists review_project_counters_lexus_read on public.review_project_counters;
+create policy review_project_counters_lexus_read
+  on public.review_project_counters
+  for select
+  to anon
+  using (project_id = 'lexus-official-v2026');
+
+drop policy if exists review_project_counters_lexus_insert on public.review_project_counters;
+create policy review_project_counters_lexus_insert
+  on public.review_project_counters
+  for insert
+  to anon
+  with check (project_id = 'lexus-official-v2026');
+
+drop policy if exists review_project_counters_lexus_update on public.review_project_counters;
+create policy review_project_counters_lexus_update
+  on public.review_project_counters
+  for update
+  to anon
+  using (project_id = 'lexus-official-v2026')
+  with check (project_id = 'lexus-official-v2026');
+```
+
+## Migration from max+1 RPC
+
+이미 `review_items`와 이전 `create_review_item` RPC를 만든 DB에서는 아래 블록만 실행한다.
+
+```sql
+create table if not exists public.review_project_counters (
+  project_id text not null,
+  source text not null default 'supabase',
+  next_review_number integer not null default 1,
+  updated_at timestamptz not null default now(),
+  primary key (project_id, source),
+  constraint review_project_counters_next_review_number_check
+    check (next_review_number > 0)
+);
+
+create or replace function public.create_review_item(
+  p_id text,
+  p_project_id text,
+  p_route_key text,
+  p_source text,
+  p_status text,
+  p_item jsonb
+)
+returns public.review_items
+language plpgsql
+security invoker
+set search_path = public
+as $$
+declare
+  v_review_number integer;
+  v_now timestamptz := now();
+  v_row public.review_items;
+begin
+  insert into public.review_project_counters (
+    project_id,
+    source,
+    next_review_number,
+    updated_at
+  )
+  select
+    p_project_id,
+    p_source,
+    coalesce(max(review_number), 0) + 2,
+    v_now
+  from public.review_items
+  where project_id = p_project_id
+    and source = p_source
+  on conflict (project_id, source) do update
+    set next_review_number = greatest(
+          public.review_project_counters.next_review_number + 1,
+          excluded.next_review_number
+        ),
+        updated_at = excluded.updated_at
+  returning next_review_number - 1 into v_review_number;
+
+  insert into public.review_items (
+    id,
+    project_id,
+    route_key,
+    source,
+    review_number,
+    status,
+    item,
+    created_at,
+    updated_at
+  )
+  values (
+    p_id,
+    p_project_id,
+    p_route_key,
+    p_source,
+    v_review_number,
+    p_status,
+    p_item || jsonb_build_object(
+      'id', p_id,
+      'reviewNumber', v_review_number,
+      'projectId', p_project_id,
+      'routeKey', p_route_key,
+      'normalizedPath', coalesce(nullif(p_item->>'normalizedPath', ''), p_route_key),
+      'status', p_status,
+      'externalIssueId', p_id,
+      'submittedAt', coalesce(p_item->>'submittedAt', v_now::text),
+      'submitStatus', coalesce(p_item->>'submitStatus', 'submitted'),
+      'createdAt', v_now::text,
+      'updatedAt', v_now::text
+    ),
+    v_now,
+    v_now
+  )
+  returning * into v_row;
+
+  return v_row;
+end;
+$$;
+
+grant execute on function public.create_review_item(
+  text,
+  text,
+  text,
+  text,
+  text,
+  jsonb
+) to anon;
+
+grant select, insert, update on public.review_project_counters to anon;
+
+alter table public.review_project_counters enable row level security;
+
+drop policy if exists review_project_counters_lexus_read on public.review_project_counters;
+create policy review_project_counters_lexus_read
+  on public.review_project_counters
+  for select
+  to anon
+  using (project_id = 'lexus-official-v2026');
+
+drop policy if exists review_project_counters_lexus_insert on public.review_project_counters;
+create policy review_project_counters_lexus_insert
+  on public.review_project_counters
+  for insert
+  to anon
+  with check (project_id = 'lexus-official-v2026');
+
+drop policy if exists review_project_counters_lexus_update on public.review_project_counters;
+create policy review_project_counters_lexus_update
+  on public.review_project_counters
+  for update
+  to anon
+  using (project_id = 'lexus-official-v2026')
+  with check (project_id = 'lexus-official-v2026');
+```
+
+## Current adapter behavior
+
+- `list`: `project_id`, `source`, optional `route_key`, optional `status`로 조회한다.
+- `create`: local draft id/number를 버리고 새 `id`를 만든 뒤 `create_review_item` RPC로 canonical `review_number`를 발급하고 insert한다.
+- `update`: status 포함 item patch를 JSONB와 query 컬럼에 반영한다.
+- `remove`: row를 삭제한다.
+
+## Security note
+
+위 RLS는 dev 검증용이다. 누구든 anon key와 project id를 알면 QA row를 만들고 수정할 수 있다.
+
+package 배포 전에는 다음 중 하나로 좁히는 것을 권장한다.
+
+- authenticated user + project member table 기반 RLS
+- Supabase Edge Function 또는 project backend proxy
+- private deployment 내부에서만 노출되는 service endpoint
+
+## Numbering note
+
+local item의 `#id`는 개인 draft 번호라 여러 사용자가 동시에 작업하면 겹칠 수 있다.
+
+remote source에 등록될 때는 Supabase adapter가 local 번호를 버리고 새 canonical `review_number`를 받는다. 기본 create 경로는 `create_review_item` RPC를 사용한다. RPC는 `review_project_counters` row를 `insert ... on conflict ... do update returning`으로 증가시켜 같은 project/source 번호 발급만 짧게 직렬화한다. 삭제된 번호도 재사용하지 않는다.
+
+`unsafeClientReviewNumberFallback: true`를 adapter option에 넣으면 예전 client-side `max(review_number) + 1` fallback을 사용할 수 있지만, 동시 등록에서 충돌 가능성이 있으므로 dev 임시 용도 외에는 쓰지 않는다.