refactor(admin): migrate data layer to V2 API response contract (#1045)

* fix(admin): smoke-test driven API alignment for v2 migration

- posts/notes/drafts: switch list sort params to wire-format
  sort_by/sort_order (snake_case enums) to match server's
  createPagerSchema; previous camelCase + numeric -1/1 was rejected
- manage-posts/notes list views: pass the new sort keys through
- webhook create: always send `secret: ''` when the form leaves it
  blank; server's WebhookSchema requires `z.string()` and the admin
  form intentionally treats the field as optional
- docs/superpowers: capture in-progress React migration specs (status,
  layout shell, data flow, datatable, list filter bar, recovery banner,
  rightpane quick edit) so they survive across machines

* feat(admin): opt out of implicit response translation via x-skip-translation

Admin always edits/manages original records; no admin endpoint consumes translated payloads. Send `x-skip-translation: 1` on every outbound request (shared $api instance plus the raw agent-chat SSE fetch) so the backend ignores browser-implicit Accept-Language and NEXT_LOCALE cookie. Explicit `?lang=xx` query and `x-lang` header remain respected for business filters (enrichment per-locale rows, search index).

Author: Innei

apps/admin/src/api/drafts.ts

@@ -8,13 +8,15 @@ import type {
 
 import { request } from '~/utils/request'
 
+export type DraftSortOrder = 'asc' | 'desc'
+
 export interface GetDraftsParams {
   page?: number
   size?: number
   refType?: DraftRefType
   hasRef?: boolean
-  sortBy?: string
-  sortOrder?: 1 | -1
+  sort_by?: string
+  sort_order?: DraftSortOrder
 }
 
 export interface CreateDraftData {

apps/admin/src/api/notes.ts

@@ -3,11 +3,22 @@ import type { NoteModel } from '~/models/note'
 
 import { request } from '~/utils/request'
 
+export type NoteSortKey =
+  | 'title'
+  | 'createdAt'
+  | 'modifiedAt'
+  | 'weather'
+  | 'mood'
+export type SortOrder = 'asc' | 'desc'
+
 export interface GetNotesParams {
   page?: number
   size?: number
-  sortBy?: string
-  sortOrder?: number
+  sort_by?: NoteSortKey
+  sort_order?: SortOrder
+  /**
+   * @deprecated backend dropped db_query in v12.10.x pager refactor; param is silently ignored
+   */
   db_query?: Record<string, boolean>
 }
 

apps/admin/src/api/posts.ts

@@ -3,11 +3,14 @@ import type { PostModel } from '~/models/post'
 
 import { request } from '~/utils/request'
 
+export type PostSortKey = 'createdAt' | 'modifiedAt' | 'pinAt'
+export type SortOrder = 'asc' | 'desc'
+
 export interface GetPostsParams {
   page?: number
   size?: number
-  sortBy?: string
-  sortOrder?: number
+  sort_by?: PostSortKey
+  sort_order?: SortOrder
   categoryIds?: string[]
 }
 

apps/admin/src/components/editor/rich/agent-chat/composables/use-agent-loop.ts

@@ -46,7 +46,10 @@ function createAdminTransport(providerId: string): TransportAdapter {
   return async (messages, tools, model, signal) => {
     const response = await fetch(`${API_URL}/ai/agent/chat`, {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
+      headers: {
+        'Content-Type': 'application/json',
+        'x-skip-translation': '1',
+      },
       credentials: 'include',
       body: JSON.stringify({ model, messages, tools, providerId }),
       signal,

apps/admin/src/utils/request.ts

@@ -40,6 +40,7 @@ export const $api = ofetch.create({
   onRequest({ options }) {
     const headers = new Headers(options.headers)
     headers.set('x-uuid', _uuid)
+    headers.set('x-skip-translation', '1')
 
     // GET 请求添加时间戳防缓存
     if (options.method?.toUpperCase() === 'GET') {

apps/admin/src/views/extra-features/webhook/index.tsx

@@ -160,7 +160,13 @@ export default defineComponent({
           data: submitData,
         })
       } else {
-        createMutation.mutate(data as any)
+        // Server requires `secret` as a string; admin form leaves it optional.
+        // Default to "" when the user did not provide one so creation succeeds.
+        const createPayload: Partial<WebhookModel> = {
+          ...data,
+          secret: data.secret ?? '',
+        }
+        createMutation.mutate(createPayload as any)
       }
     }
 

apps/admin/src/views/manage-notes/list.tsx

@@ -14,6 +14,7 @@ import { NButton, NEllipsis, NInput, NPopconfirm, NSpace } from 'naive-ui'
 import { computed, defineComponent, reactive, ref, watchEffect } from 'vue'
 import { RouterLink } from 'vue-router'
 import { toast } from 'vue-sonner'
+import type { NoteSortKey } from '~/api/notes'
 import type { NoteModel } from '~/models/note'
 import type { TableColumns } from 'naive-ui/lib/data-table/src/interface'
 import type { PropType } from 'vue'
@@ -225,8 +226,12 @@ export const ManageNoteListView = defineComponent({
         return notesApi.getList({
           page: params.page,
           size: params.size,
-          sortBy: params.sortBy || undefined,
-          sortOrder: params.sortOrder || undefined,
+          ...(params.sortBy
+            ? {
+                sort_by: params.sortBy as NoteSortKey,
+                sort_order: params.sortOrder === 1 ? 'asc' : 'desc',
+              }
+            : {}),
           db_query: params.filters?.dbQuery,
         }) as Promise<any>
       },

apps/admin/src/views/manage-posts/list.tsx

@@ -19,6 +19,7 @@ import {
 } from 'vue'
 import { RouterLink } from 'vue-router'
 import { toast } from 'vue-sonner'
+import type { PostSortKey } from '~/api/posts'
 import type {
   FilterOption,
   FilterState,
@@ -206,8 +207,8 @@ export const ManagePostListView = defineComponent({
           categoryIds: params.filters?.categoryIds,
           ...(params.sortBy
             ? {
-                sortBy: params.sortBy,
-                sortOrder: params.sortOrder,
+                sort_by: params.sortBy as PostSortKey,
+                sort_order: params.sortOrder === 1 ? 'asc' : 'desc',
               }
             : {}),
         })

docs/superpowers/specs/2026-05-06-react-migration/00-roadmap.md

@@ -20,7 +20,7 @@ docs/superpowers/specs/2026-05-06-react-migration/
 ├── 05-data-layer.md        ← request.ts port, TanStack Query patterns, socket.io hook
 ├── 06-routing-auth.md      ← react-router tree, ProtectedRoute, better-auth + passkey
 ├── 07-layouts-patterns.md  ← AppShell, Sidebar, MasterDetailLayout, header-action injection
-├── 08-form-system.md       ← react-hook-form + zod, ConfigForm DSL port
+├── 08-form-system.md       ← @tanstack/react-form + zod (Standard Schema), ConfigForm DSL port
 ├── 09-editors.md           ← haklex direct-mount, monaco, codemirror, xterm, draft system
 ├── 10-charts-misc.md       ← G2 hook, kbar swap, shiki/marked, diffs, excalidraw, confetti
 ├── 11-views-migration.md   ← 21 views in batches; preconditions + acceptance per batch
@@ -43,7 +43,7 @@ docs/superpowers/specs/2026-05-06-react-migration/
 | UI primitives | Base UI (`@base-ui-components/react`) | headless; pairs with css.ts |
 | Styling | css.ts (`@vanilla-extract/css` + vite plugin) | Compile-time CSS; tokens live as TS exports |
 | Design system | Linear dark-canvas (per pasted DESIGN.md) | Lavender accent, four-step surface ladder, no second chromatic accent |
-| Forms | `react-hook-form` + `zod` | `zod` already in source repo |
+| Forms | `@tanstack/react-form` + `zod` (Standard Schema) | aligns with TanStack Query/Table; zod already in source repo; library swap landed 2026-05-10 |
 | Animation | `motion` | User-specified |
 | Icons | `lucide-react` | 1:1 swap from `lucide-vue-next` |
 | Toast | `sonner` | 1:1 swap from `vue-sonner` |

docs/superpowers/specs/2026-05-06-react-migration/01-repo-skeleton.md

@@ -143,8 +143,7 @@ admin-react/
     "lucide-react": "latest",
     "sonner": "^1.7.0",
     "kbar": "^0.1.0",
-    "react-hook-form": "^7.53.0",
-    "@hookform/resolvers": "^3.9.0",
+    "@tanstack/react-form": "^1.29.3",
     "zod": "4.3.6",
     "ofetch": "1.5.1",
     "better-auth": "1.4.18",