@designfever/web-review-kit 0.1.0

package/docs/df-sheet-adapter.md

@@ -0,0 +1,336 @@
+# df-sheet adapter implementation plan
+
+## Goal
+
+`dfSheetAdapter` connects df-web-review-kit QA items to df-sheet issues.
+
+The first production pilot is Lexus. Keep the adapter local and project-tested
+before exposing it as a package export.
+
+## Current decision
+
+- Use `issues.id` as the canonical QA item id.
+- Add only one df-sheet field: `issues.review_metadata jsonb null`.
+- Store human-readable QA content in `description`.
+- Store restore data in `review_metadata`.
+- Store screenshots through df-sheet `/api/upload`, then attach the returned URL
+  to `issues.attachments`.
+- Use a project/page scoped integration token, not an open unauthenticated API.
+- Publish the adapter only after the Lexus pilot validates create, list, update,
+  delete, upload, and deep-link restore.
+
+## Required df-sheet changes
+
+### Database
+
+Add a nullable JSON field to `issues`.
+
+```sql
+alter table issues
+add column if not exists review_metadata jsonb null;
+```
+
+### API
+
+Pass `review_metadata` through the existing issue APIs.
+
+- `POST /api/issues`
+  - accept `body.review_metadata`
+  - insert it into `issues.review_metadata`
+- `PATCH /api/issues/:id`
+  - accept `body.review_metadata`
+  - update `issues.review_metadata`
+- `GET /api/issues`
+  - include `review_metadata` in list responses
+- `GET /api/issues/:id`
+  - include `review_metadata` in detail responses
+
+Do not hide adapter metadata in `description`. df-sheet uses Tiptap JSON there,
+so a hidden JSON block would be fragile.
+
+### Auth
+
+Add an integration token path for adapter calls.
+
+Recommended rules:
+
+- token is sent with `Authorization: Bearer <token>`
+- token is scoped to one `project_id`
+- token is scoped to one `page_id`
+- token can only create/list/read/update/delete issues in that scope
+- token can upload attachments for those issues
+
+Do not expose issue CRUD without auth.
+
+## Adapter config
+
+```ts
+type DfSheetAdapterOptions = {
+  baseUrl: string;
+  projectId: string;
+  pageId: string;
+  token: string;
+  issueType?: string;
+  issuePriority?: "low" | "medium" | "high" | "urgent";
+};
+```
+
+Example usage during the Lexus pilot:
+
+```ts
+createWebReviewKit({
+  projectId: "lexus-official-v2026",
+  adapter: createDfSheetAdapter({
+    baseUrl: "https://df-sheet.vercel.app",
+    projectId: "<df-sheet-project-id>",
+    pageId: "<df-sheet-page-id>",
+    token: "<integration-token>",
+    issueType: "task",
+    issuePriority: "medium",
+  }),
+});
+```
+
+If the target project has no backend proxy, assume the browser can see this
+token. Keep the token project/page scoped so leakage impact is limited.
+
+## Adapter contract changes
+
+Current adapter contract:
+
+```ts
+interface WebReviewKitAdapter {
+  list(query: ReviewItemQuery): Promise<ReviewItem[]>;
+  create(item: ReviewItem): Promise<ReviewItem>;
+  update(id: string, patch: Partial<Omit<ReviewItem, "id" | "createdAt">>): Promise<ReviewItem>;
+  remove(id: string): Promise<void>;
+}
+```
+
+Add `get(id)` for deep-link restore:
+
+```ts
+interface WebReviewKitAdapter {
+  get(id: string): Promise<ReviewItem | null>;
+  list(query: ReviewItemQuery): Promise<ReviewItem[]>;
+  create(item: ReviewItem): Promise<ReviewItem>;
+  update(id: string, patch: Partial<Omit<ReviewItem, "id" | "createdAt">>): Promise<ReviewItem>;
+  remove(id: string): Promise<void>;
+}
+```
+
+`localAdapter` should implement `get(id)` from local storage.
+
+## Status mapping
+
+df-web-review-kit:
+
+- `todo`
+- `doing`
+- `review`
+- `hold`
+- `done`
+
+df-sheet:
+
+- `todo`
+- `in_progress`
+- `review`
+- `on_hold`
+- `done`
+
+Mapping:
+
+```ts
+const toDfSheetStatus = {
+  todo: "todo",
+  doing: "in_progress",
+  review: "review",
+  hold: "on_hold",
+  done: "done",
+} as const;
+
+const fromDfSheetStatus = {
+  todo: "todo",
+  in_progress: "doing",
+  review: "review",
+  on_hold: "hold",
+  done: "done",
+} as const;
+```
+
+## Review metadata shape
+
+The metadata must be enough to rebuild a `ReviewItem` from a df-sheet issue.
+
+```ts
+type DfSheetReviewMetadata = {
+  schema: "df-web-review-kit";
+  version: 1;
+  reviewProjectId: string;
+  routeKey: string;
+  pageUrl: string;
+  originalUrl?: string;
+  normalizedPath: string;
+  scope?: ReviewItemScope;
+  kind: ReviewItemKind;
+  viewport: ViewportSize;
+  devicePixelRatio?: number;
+  scroll?: {
+    x: number;
+    y: number;
+  };
+  anchor?: DomAnchor;
+  marker?: ReviewMarker;
+  selection?: ReviewSelection;
+  reviewUrl?: string;
+};
+```
+
+Avoid storing screenshot data URLs in metadata. Use `attachments`.
+
+## Issue mapping
+
+### ReviewItem to Issue
+
+```ts
+{
+  project_id: options.projectId,
+  page_id: options.pageId,
+  title: item.title || makeIssueTitle(item),
+  description: makeIssueDescription(item),
+  status: toDfSheetStatus[normalizeReviewItemStatus(item.status)],
+  priority: options.issuePriority ?? "medium",
+  type: options.issueType ?? "task",
+  attachments: item.screenshot ? [uploadedScreenshot] : [],
+  links: makeReviewUrl(item),
+  review_metadata: makeReviewMetadata(item),
+}
+```
+
+### Issue to ReviewItem
+
+```ts
+{
+  id: issue.id,
+  externalIssueId: issue.id,
+  projectId: metadata.reviewProjectId,
+  routeKey: metadata.routeKey,
+  pageUrl: metadata.pageUrl,
+  originalUrl: metadata.originalUrl,
+  normalizedPath: metadata.normalizedPath,
+  scope: metadata.scope,
+  kind: metadata.kind,
+  title: issue.title,
+  comment: extractComment(issue.description),
+  status: fromDfSheetStatus[issue.status],
+  viewport: metadata.viewport,
+  devicePixelRatio: metadata.devicePixelRatio,
+  scroll: metadata.scroll,
+  anchor: metadata.anchor,
+  marker: metadata.marker,
+  selection: metadata.selection,
+  screenshot: undefined,
+  createdAt: issue.created_at,
+  updatedAt: issue.updated_at ?? issue.created_at,
+}
+```
+
+## Deep link flow
+
+Target URL:
+
+```txt
+/review?target=/path&w=390&h=720&item=<issue.id>
+```
+
+Flow:
+
+1. `ReviewShell` reads `item` from the query string.
+2. It calls `adapter.get(itemId)`.
+3. The adapter fetches `GET /api/issues/:id`.
+4. It maps the df-sheet issue to `ReviewItem`.
+5. `ReviewShell` restores target route and viewport from the item metadata.
+6. It reloads the target iframe.
+7. It highlights the restored item after the target document is ready.
+
+The query params `target`, `w`, and `h` are hints for early shell rendering.
+`adapter.get(item)` is the source of truth.
+
+## List sync
+
+MVP behavior:
+
+- load list on review shell mount
+- reload after create/update/delete
+- reload when target route changes
+- reload on manual refresh
+- optionally reload when the window regains focus
+
+Do not start with realtime sync. Add Supabase realtime later only if the Lexus
+pilot shows that multiple reviewers need live updates.
+
+## Delete behavior
+
+Use the existing df-sheet delete API for the pilot:
+
+```txt
+DELETE /api/issues/:id
+```
+
+If teams want QA history preserved later, add an archive/hidden status in
+df-sheet instead of hard delete.
+
+## Implementation phases
+
+### Phase 1: contract
+
+- add `adapter.get(id)`
+- update `localAdapter`
+- update review shell deep-link restore to use adapter data instead of local
+  storage only
+
+### Phase 2: df-sheet adapter
+
+- add `src/adapters/df-sheet.ts`
+- implement `createDfSheetAdapter(options)`
+- implement issue/status/metadata mapping helpers
+- implement screenshot upload helper
+- keep the adapter unexported or internally linked during Lexus pilot
+
+### Phase 3: Lexus pilot
+
+- configure Lexus review shell with df-sheet adapter options
+- test create/list/update/delete
+- test screenshot attachment upload
+- test `/review?...&item=<issue.id>` restore
+- test status changes from both review-kit and df-sheet
+
+### Phase 4: package export
+
+After the Lexus pilot is stable:
+
+- export as `@designfever/web-review-kit/adapters/df-sheet`
+- include adapter files in package build
+- update README with installation/config examples
+- publish npm package
+
+## Verification checklist
+
+- `pnpm typecheck`
+- `pnpm build`
+- create text QA from Lexus review page
+- create capture QA with screenshot
+- list reload shows created issues
+- status update maps both directions
+- delete removes item from list
+- deep link restores route, viewport, and highlighted QA
+- df-sheet issue detail shows title, description, status, attachment, and link
+
+## Open questions
+
+- Lexus df-sheet `project_id`
+- Lexus df-sheet `page_id`
+- integration token creation and rotation flow
+- whether df-sheet should expose an issue type dedicated to QA
+- whether delete should become archive after the pilot

package/docs/df-sheet-next.md

@@ -0,0 +1,222 @@
+# df-sheet adapter next plan
+
+## 목적
+
+df-sheet를 `df-web-review-kit`의 remote destination으로 계속 사용할 때의 역할과 필요한 df-sheet 쪽 변경을 분리해서 정리한다.
+
+Supabase 실험 문서는 adapter 구조 검증용이고, 이 문서는 df-sheet 제품/운영 흐름 기준이다.
+
+## 현재 위치
+
+현재 `dfSheetAdapter`는 review-kit item을 df-sheet issue로 보낸다.
+
+현재 동작:
+
+- `create`: local QA item을 df-sheet issue로 등록
+- `list`: df-sheet issue 목록을 review item으로 변환
+- `get`: issue detail을 review item으로 변환
+- `update/remove`: review-kit 안에서는 read-only로 막음
+- restore data: `issues.review_metadata`
+- review link: issue metadata/link에 `/review?...&item=<issueId>` 저장
+
+현재 shell adapter에서는 df-sheet config에 `updateStatus`와 `remove`를 넣지 않는다. 따라서 df-sheet source에서는 상태 변경 dropdown은 readonly badge로만 둘 수 있고, 삭제 버튼도 숨긴다.
+
+## 권장 역할
+
+df-sheet는 source of record가 되어야 한다. review-kit은 다음 역할까지만 한다.
+
+- local에서 만든 QA를 df-sheet issue로 등록
+- df-sheet issue를 현재 page/viewport에서 restore
+- issue status를 표시
+- 필요 시 status update만 좁게 허용
+
+review-kit이 df-sheet의 전체 issue editor가 되면 안 된다.
+
+## 상태 변경 정책
+
+generic `update`는 넣지 않는다.
+
+df-sheet 상태를 review-kit에서 바꾸고 싶다면 `updateStatus`만 추가한다.
+
+```ts
+{
+  label: 'df-sheet',
+  get,
+  list,
+  create,
+  statusOptions: DF_SHEET_STATUS_OPTIONS,
+  updateStatus: async ({ id, status, statusOption, statusIndex }) => {
+    return dfSheet.updateIssueStatus(id, {
+      status,
+      statusIndex,
+      statusLabel: statusOption.label,
+    });
+  },
+}
+```
+
+상태 기준:
+
+- 저장 identity: `statusOption.value`
+- 표시명: `statusOption.label`
+- 외부 매핑 보조값: `statusIndex`
+
+df-sheet의 실제 status vocabulary가 다르면 adapter에서 mapping한다.
+
+```ts
+const DF_SHEET_STATUS_OPTIONS = [
+  { value: 'todo', label: '작업전' },
+  { value: 'doing', label: '작업중' },
+  { value: 'review', label: '검토 필요' },
+  { value: 'hold', label: '보류' },
+  { value: 'done', label: '완료' },
+] as const;
+```
+
+## df-sheet API 제안
+
+현재 issue CRUD API를 그대로 넓히기보다 review-kit 전용 endpoint를 두는 쪽이 안전하다.
+
+추천 endpoint:
+
+```txt
+GET    /api/review-kit/issues
+GET    /api/review-kit/issues/:id
+POST   /api/review-kit/issues
+PATCH  /api/review-kit/issues/:id/status
+```
+
+선택 endpoint:
+
+```txt
+DELETE /api/review-kit/issues/:id
+```
+
+요청은 integration token 기준으로 project/page scope를 제한한다.
+
+```http
+Authorization: Bearer <review-kit-token>
+```
+
+Token scope:
+
+- `project_id`
+- `page_id`
+- allowed actions: `create`, `read`, optional `update_status`, optional `delete`
+
+브라우저에서 직접 token을 쓰는 경우 누출을 전제로 작게 scope를 잡는다. production에서는 backend proxy 또는 df-sheet domain cookie auth를 우선 검토한다.
+
+## DB 필드
+
+`issues.review_metadata jsonb`는 유지한다.
+
+```sql
+alter table issues
+add column if not exists review_metadata jsonb null;
+```
+
+`review_metadata`에 들어가는 값:
+
+- review item id
+- review number
+- route/normalized path
+- viewport
+- scroll
+- anchor
+- marker
+- selection
+- original comment
+- review link
+- schema/source/version
+
+사람이 읽어야 하는 내용은 `title`/`description`에 둔다. restore에 필요한 구조 데이터는 `review_metadata`에 둔다.
+
+## create flow
+
+1. local item 선택
+2. review-kit이 df-sheet `POST /api/review-kit/issues` 호출
+3. df-sheet가 issue 생성
+4. df-sheet가 issue id/url 반환
+5. remote 등록 성공 시 local item은 삭제하고, 실패 시에만 `syncSubmission`으로 실패 상태를 기록
+
+remote issue id를 local id로 덮어쓰지 않는다. 대신 remote 등록 payload에서는 사람이 볼 번호로 `reviewNumber`를 보낸다.
+
+## list/get flow
+
+`list`는 route 기준으로 좁게 가져온다.
+
+```txt
+project_id=<df-sheet-project-id>
+page_id=<df-sheet-page-id>
+review_source=df-web-review-kit
+review_route_key=<target route>
+```
+
+응답에는 `review_metadata`가 반드시 포함되어야 한다. metadata가 없거나 source/schema가 맞지 않으면 adapter는 review item으로 변환하지 않는다.
+
+## status update flow
+
+df-sheet에서 status 변경을 허용하려면 issue 전체 patch가 아니라 status-only endpoint를 쓴다.
+
+```txt
+PATCH /api/review-kit/issues/:id/status
+```
+
+Body:
+
+```json
+{
+  "status": "doing"
+}
+```
+
+Response는 updated issue와 `review_metadata`를 포함한다.
+
+review-kit adapter는 이 응답을 `ReviewItem`으로 변환한다.
+
+## delete policy
+
+초기에는 df-sheet delete를 review-kit에서 열지 않는 편이 낫다.
+
+이유:
+
+- remote issue 삭제는 팀 공유 데이터에 직접 영향이 크다.
+- review-kit list에서 실수 클릭으로 삭제될 수 있다.
+- df-sheet 내부 권한/감사 로그와 맞춰야 한다.
+
+필요하면 `remove`를 adapter에 넣고, UI는 확인 modal을 추가한다. 현재 shell의 local 삭제 UX와 같은 즉시 삭제 방식으로 remote delete를 열면 안 된다.
+
+## package 관점
+
+df-sheet adapter를 package에 포함할 때도 df-sheet 전용 타입/설정은 adapter 내부에 묶는다.
+
+`ReviewShellAdapter`는 계속 storage-agnostic이어야 한다.
+
+좋은 방향:
+
+- `dfSheetAdapter(options)`는 core `WebReviewKitAdapter` 구현
+- `dfSheetShellAdapter(options)` 또는 helper는 shell-facing adapter config 생성
+- page/review에서는 helper를 조립해서 넘김
+
+예시:
+
+```ts
+const dfSheet = dfSheetAdapter(options);
+
+const REVIEW_ADAPTERS = [
+  localReviewShellAdapter(local),
+  dfSheetReviewShellAdapter(dfSheet, {
+    pageId: options.pageId,
+    statusOptions: DF_SHEET_STATUS_OPTIONS,
+    canUpdateStatus: false,
+  }),
+];
+```
+
+## 남은 결정
+
+- df-sheet에서 review-kit 전용 endpoint를 새로 만들지, 기존 `/api/issues`를 확장할지.
+- status update를 review-kit에서 허용할지.
+- integration token을 cookie auth와 병행할지.
+- df-sheet issue status vocabulary와 review-kit status value를 1:1로 맞출지.
+- remote delete를 허용할지.