create-fullstack-scaffold 0.4.24 → 0.5.0

package/template/src/server/module-tenant/routes/tenant-routes.ts

@@ -165,10 +165,14 @@ export const apiRoutes = new OpenAPIHono()
     if (!tenant) throw new NotFoundError('Tenant context')
     return c.json(success(tenant), 200)
   })
-  .doc('/docs', {
+  // todos 模块已占用 /docs；tenant 的 OpenAPI 文档挂独立路径避免 shadow
+  .doc('/tenant/docs', {
     openapi: '3.0.0',
     info: {
       version: '1.0.0',
       title: 'Tenant Management API',
     },
   })
+
+/** 模块级窄类型（深度 = 1 个模块）— 供 rpc-surface 门面使用，禁止再向上合并 */
+export type TenantApiType = typeof apiRoutes

package/template/src/server/module-ticket/__tests__/ticket-route.test.ts

@@ -22,7 +22,8 @@ describe('Ticket Routes', () => {
       const data = await res.json()
       expect(data.success).toBe(true)
       if (data.success) {
-        expect(Array.isArray(data.data)).toBe(true)
+        expect(data.data.tickets).toBeDefined()
+        expect(typeof data.data.total).toBe('number')
       }
     })
   })

package/template/src/server/module-ticket/__tests__/ticket-service.test.ts

@@ -17,7 +17,8 @@ describe('Ticket Service', () => {
   describe('getTickets', () => {
     it('should return all tickets', async () => {
       const result = await service.getTickets()
-      expect(Array.isArray(result)).toBe(true)
+      expect(result.tickets).toBeDefined()
+      expect(typeof result.total).toBe('number')
     })
 
     it('should filter tickets by status', async () => {
@@ -33,8 +34,8 @@ describe('Ticket Service', () => {
       createdTicketIds.push(created.id)
 
       const result = await service.getTickets({ status: 'open' })
-      expect(Array.isArray(result)).toBe(true)
-      result.forEach(ticket => {
+      expect(Array.isArray(result.tickets)).toBe(true)
+      result.tickets.forEach(ticket => {
         expect(ticket.status).toBe('open')
       })
     })

package/template/src/server/module-ticket/routes/ticket-routes.ts

@@ -1,4 +1,4 @@
-import { createRoute, z } from '@hono/zod-openapi'
+import { createRoute } from '@hono/zod-openapi'
 import { OpenAPIHono } from '@hono/zod-openapi'
 import * as ticketService from '../services/ticket-service'
 import { successResponse, errorResponse, success, created } from '@server/utils/route-helpers'
@@ -9,7 +9,8 @@ import {
   TicketSchema,
   CreateTicketSchema,
   UpdateTicketSchema,
-  TicketListSchema,
+  TicketListResponseSchema,
+  TicketListQuerySchema,
   TicketDeleteResultSchema,
   ReplyTicketSchema,
 } from '@shared/modules/ticket'
@@ -21,13 +22,10 @@ const listRoute = createRoute({
   security: [{ Bearer: [] }],
   middleware: [authMiddleware({ requiredPermissions: [Permission.TICKET_VIEW] })],
   request: {
-    query: z.object({
-      limit: z.coerce.number().int().positive().max(100).default(20),
-      offset: z.coerce.number().int().min(0).default(0),
-    }),
+    query: TicketListQuerySchema,
   },
   responses: {
-    200: successResponse(TicketListSchema, 'List all tickets'),
+    200: successResponse(TicketListResponseSchema, 'List all tickets'),
     401: errorResponse('Unauthorized'),
     403: errorResponse('Forbidden'),
     500: errorResponse('Internal server error'),
@@ -167,9 +165,9 @@ const closeRoute = createRoute({
 
 export const ticketRoutes = new OpenAPIHono()
   .openapi(listRoute, async c => {
-    const { limit, offset } = c.req.valid('query')
-    const result = await ticketService.getTickets()
-    return c.json(success(result.slice(offset, offset + limit)), 200)
+    const { page, limit } = c.req.valid('query')
+    const result = await ticketService.getTickets({ page, limit })
+    return c.json(success(result), 200)
   })
   .openapi(getRoute, async c => {
     const { id } = c.req.valid('param')
@@ -208,3 +206,6 @@ export const ticketRoutes = new OpenAPIHono()
     if (!result) throw new NotFoundError('Ticket', id)
     return c.json(success(result), 200)
   })
+
+/** 模块级窄类型（深度 = 1 个模块）— 供 rpc-surface 门面使用，禁止再向上合并 */
+export type TicketsApiType = typeof ticketRoutes

package/template/src/server/module-ticket/services/ticket-service.ts

@@ -154,8 +154,13 @@ export async function getTickets(filters?: {
   status?: TicketStatus
   priority?: TicketPriority
   category?: TicketCategory
-}): Promise<Ticket[]> {
+  page?: number
+  limit?: number
+}): Promise<{ tickets: Ticket[]; total: number; page: number; limit: number }> {
   const db = await getDb()
+  const page = filters?.page ?? 1
+  const limit = filters?.limit ?? 20
+  const offset = (page - 1) * limit
   const conditions = []
 
   if (filters?.status) {
@@ -169,7 +174,7 @@ export async function getTickets(filters?: {
   }
 
   const priorityOrder = { urgent: 0, high: 1, medium: 2, low: 3 }
-  const rows =
+  const allRows =
     conditions.length > 0
       ? await db
           .select()
@@ -177,14 +182,20 @@ export async function getTickets(filters?: {
           .where(and(...conditions))
       : await db.select().from(tickets)
 
-  const sorted = rows.sort((a, b) => priorityOrder[a.priority] - priorityOrder[b.priority])
+  const sorted = allRows.sort((a, b) => priorityOrder[a.priority] - priorityOrder[b.priority])
+  const rows = sorted.slice(offset, offset + limit)
 
   const result: Ticket[] = []
-  for (const row of sorted) {
+  for (const row of rows) {
     result.push(await loadTicketWithReplies(row))
   }
 
-  return result
+  return {
+    tickets: result,
+    total: sorted.length,
+    page,
+    limit,
+  }
 }
 
 export async function getTicketById(id: string): Promise<Ticket | null> {

package/template/src/server/module-todos/__tests__/isr.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+// Mock the todo service BEFORE importing isr.ts
+vi.mock('@server/module-todos/services/todo-service', () => ({
+  listTodos: vi.fn(),
+}))
+
+import { listTodos } from '@server/module-todos/services/todo-service'
+import type { MockTodo } from '@server/test-utils/test-isr-helper'
+
+// Side-effect: register ISR routes into global registry
+import '@server/module-todos/isr'
+
+const mockTodosData: MockTodo[] = [
+  {
+    id: 1,
+    title: 'Task A',
+    status: 'completed',
+    createdAt: '2024-01-01T00:00:00.000Z',
+    updatedAt: '2024-01-01T00:00:00.000Z',
+  },
+  {
+    id: 2,
+    title: 'Task B',
+    status: 'pending',
+    createdAt: '2024-01-02T00:00:00.000Z',
+    updatedAt: '2024-01-02T00:00:00.000Z',
+  },
+  {
+    id: 3,
+    title: 'Task C',
+    status: 'in_progress',
+    createdAt: '2024-01-03T00:00:00.000Z',
+    updatedAt: '2024-01-03T00:00:00.000Z',
+  },
+]
+
+describe('Todos Module ISR', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('route registration', () => {
+    it('should register /todos route', async () => {
+      vi.mocked(listTodos).mockResolvedValue({ todos: mockTodosData, total: 3, page: 1, limit: 20 })
+
+      // Dynamic import to trigger registration into fresh registry
+      // Since isr.ts registers into the global registry, we test the global one
+      const { isrRegistry } = await import('@server/core/isr-registry')
+      // The global registry already has todos from the side-effect import
+      expect(isrRegistry.match('/todos')).not.toBeNull()
+      expect(isrRegistry.match('/todos')!.module).toBe('todos')
+    })
+
+    it('should register / route', async () => {
+      const { isrRegistry } = await import('@server/core/isr-registry')
+      const entry = isrRegistry.match('/')
+      expect(entry).not.toBeNull()
+      expect(entry!.module).toBe('todos')
+    })
+  })
+
+  describe('data fetching', () => {
+    it('should fetch todos from service', async () => {
+      vi.mocked(listTodos).mockResolvedValue({ todos: mockTodosData, total: 3, page: 1, limit: 20 })
+
+      const { isrRegistry } = await import('@server/core/isr-registry')
+      const entry = isrRegistry.match('/todos')!
+      const data = (await entry.fetch('/todos', {})) as { todos: MockTodo[] }
+
+      expect(data.todos).toHaveLength(3)
+      expect(data.todos[0].title).toBe('Task A')
+    })
+
+    it('should handle empty todos', async () => {
+      vi.mocked(listTodos).mockResolvedValue({ todos: [], total: 0, page: 1, limit: 20 })
+
+      const { isrRegistry } = await import('@server/core/isr-registry')
+      const entry = isrRegistry.match('/todos')!
+      const data = (await entry.fetch('/todos', {})) as { todos: MockTodo[] }
+
+      expect(data.todos).toHaveLength(0)
+    })
+
+    it('should handle DB error gracefully', async () => {
+      vi.mocked(listTodos).mockRejectedValue(new Error('DB connection failed'))
+
+      const { isrRegistry } = await import('@server/core/isr-registry')
+      const entry = isrRegistry.match('/todos')!
+
+      await expect(entry.fetch('/todos', {})).rejects.toThrow('DB connection failed')
+    })
+  })
+
+  describe('meta tags', () => {
+    it('should return correct meta', async () => {
+      const { isrRegistry } = await import('@server/core/isr-registry')
+      const entry = isrRegistry.match('/todos')!
+      const meta = entry.meta({}, '/todos')
+
+      expect(meta.title).toContain('Todo List')
+      expect(meta.description).toContain('todos')
+    })
+  })
+})

package/template/src/server/module-todos/__tests__/todo-service.test.ts

@@ -33,9 +33,12 @@ describe('Todo Service', () => {
     it('should return empty array when no todos exist', async () => {
       const result = await todoService.listTodos()
 
-      expect(result).toEqual([])
-      expect(Array.isArray(result)).toBe(true)
-      expect(result.length).toBe(0)
+      expect(result.todos).toEqual([])
+      expect(Array.isArray(result.todos)).toBe(true)
+      expect(result.todos.length).toBe(0)
+      expect(result.total).toBe(0)
+      expect(result.page).toBe(1)
+      expect(result.limit).toBe(20)
     })
 
     it('should return all todos ordered by created_at DESC', async () => {
@@ -55,11 +58,11 @@ describe('Todo Service', () => {
 
       const result = await todoService.listTodos()
 
-      expect(result).toHaveLength(2)
-      expect(result[0].title).toBe('Todo 2')
-      expect(result[0].status).toBe('completed')
-      expect(result[1].title).toBe('Todo 1')
-      expect(result[1].status).toBe('pending')
+      expect(result.todos).toHaveLength(2)
+      expect(result.todos[0].title).toBe('Todo 2')
+      expect(result.todos[0].status).toBe('completed')
+      expect(result.todos[1].title).toBe('Todo 1')
+      expect(result.todos[1].status).toBe('pending')
     })
   })
 
@@ -183,7 +186,7 @@ describe('Todo Service', () => {
         expect(checkResult.rows.length).toBe(0)
 
         const allTodos = await todoService.listTodos()
-        expect(allTodos.length).toBe(0)
+        expect(allTodos.total).toBe(0)
       }
     })
 

package/template/src/server/module-todos/__tests__/todos-route-rpc.test.ts

@@ -438,13 +438,13 @@ describe('Todo Routes - Business Logic Tests', () => {
       await createMultipleTodos(3)
       const client = createTestClient(undefined, { headers: authHeaders })
 
-      const res = await client.api.todos.$get({ headers: authHeaders })
+      const res = await client.api.todos.$get({ query: {} })
       const data = await res.json()
 
       expect(data.success).toBe(true)
-      if (data.success && Array.isArray(data.data)) {
-        expect(data.data).toHaveLength(3)
-        const timestamps = data.data.map((t: { createdAt: string }) =>
+      if (data.success && 'data' in data) {
+        expect(data.data.todos).toHaveLength(3)
+        const timestamps = data.data.todos.map((t: { createdAt: string }) =>
           new Date(t.createdAt).getTime()
         )
         for (let i = 0; i < timestamps.length - 1; i++) {
@@ -456,12 +456,12 @@ describe('Todo Routes - Business Logic Tests', () => {
     it('should return empty array when no todos exist', async () => {
       const client = createTestClient(undefined, { headers: authHeaders })
 
-      const res = await client.api.todos.$get({ headers: authHeaders })
+      const res = await client.api.todos.$get({ query: {} })
       const data = await res.json()
 
       expect(data.success).toBe(true)
       if (data.success) {
-        expect(data.data).toEqual([])
+        expect(data.data.todos).toEqual([])
       }
     })
   })

package/template/src/server/module-todos/isr.ts

@@ -0,0 +1,41 @@
+/**
+ * Todos module ISR routes (meta-only).
+ * Registered into isrRegistry at import time.
+ * Fetches data for SEO meta tags — body rendering handled by React SPA.
+ */
+
+import { isrRegistry, type ISRRouteEntry } from '@server/core/isr-registry'
+import { listTodos } from './services/todo-service'
+
+interface TodoData {
+  todos: Array<{ id: number; title: string; status: string }>
+}
+
+async function fetchTodos(_pathname: string): Promise<TodoData> {
+  const { todos } = await listTodos({ limit: 20 })
+  return { todos }
+}
+
+function todoMeta(): { title: string; description: string } {
+  return {
+    title: 'Todo List - Biomimic App',
+    description: 'Manage your todos with real-time updates',
+  }
+}
+
+const todosEntries: ISRRouteEntry[] = [
+  {
+    module: 'todos',
+    match: '/todos',
+    fetch: fetchTodos,
+    meta: () => todoMeta(),
+  },
+  {
+    module: 'todos',
+    match: '/',
+    fetch: fetchTodos,
+    meta: () => todoMeta(),
+  },
+]
+
+isrRegistry.registerMany(todosEntries)

package/template/src/server/module-todos/routes/todos-routes.ts

@@ -11,20 +11,23 @@ import {
   TodoWithAttachmentsSchema,
   UploadFileSchema,
   AttachmentIdResponseSchema,
+  TodoListResponseSchema,
+  TodoListQuerySchema,
 } from '@shared/schemas'
 import { successResponse, errorResponse, success, created } from '@server/utils/route-helpers'
 import { getAuthUser } from '@server/utils/auth'
 import { NotFoundError, ValidationError } from '@server/utils/app-error'
 import { authMiddleware } from '@server/middleware/auth'
 
-const TodoListSchema = z.array(TodoSchema)
-
 const listRoute = createRoute({
   method: 'get',
   path: '/todos',
   tags: ['todos'],
+  request: {
+    query: TodoListQuerySchema,
+  },
   responses: {
-    200: successResponse(TodoListSchema, 'List all todos'),
+    200: successResponse(TodoListResponseSchema, 'List all todos'),
     500: errorResponse('Internal server error'),
   },
 })
@@ -166,8 +169,9 @@ const deleteAttachmentRoute = createRoute({
 
 export const apiRoutes = new OpenAPIHono()
   .openapi(listRoute, async c => {
-    const todos = await todoService.listTodos()
-    return c.json(success(todos), 200)
+    const { page, limit } = c.req.valid('query')
+    const result = await todoService.listTodos({ page, limit })
+    return c.json(success(result), 200)
   })
   .openapi(getRoute, async c => {
     const { id } = c.req.valid('param')
@@ -254,3 +258,6 @@ export const apiRoutes = new OpenAPIHono()
       title: 'Todo API',
     },
   })
+
+/** 模块级窄类型（深度 = 1 个模块）— 供 rpc-surface 门面使用，禁止再向上合并 */
+export type TodosApiType = typeof apiRoutes

package/template/src/server/module-todos/services/todo-service.ts

@@ -58,17 +58,38 @@ export async function seedTodosIfEmpty(): Promise<void> {
   }
 }
 
-export async function listTodos(): Promise<Todo[]> {
+export async function listTodos(options?: {
+  page?: number
+  limit?: number
+}): Promise<{ todos: Todo[]; total: number; page: number; limit: number }> {
   const db = await getDb()
-  const rows = await db.select().from(todos).orderBy(desc(todos.createdAt))
-  return rows.map((row: TodoTable) => ({
-    id: row.id,
-    title: row.title,
-    description: row.description ?? undefined,
-    status: row.status,
-    createdAt: toISOString(row.createdAt),
-    updatedAt: toISOString(row.updatedAt),
-  }))
+  const page = options?.page ?? 1
+  const limit = options?.limit ?? 20
+  const offset = (page - 1) * limit
+
+  // SQL 分页（全表扫 + 内存 slice 在数据量增长后是性能反模式）
+  const rows = await db
+    .select()
+    .from(todos)
+    .orderBy(desc(todos.createdAt))
+    .limit(limit)
+    .offset(offset)
+  // db 为 LibSQL|D1 联合类型：select(config) 会重载坍缩，$count 两驱动同签名
+  const total = await db.$count(todos)
+
+  return {
+    todos: rows.map((row: TodoTable) => ({
+      id: row.id,
+      title: row.title,
+      description: row.description ?? undefined,
+      status: row.status,
+      createdAt: toISOString(row.createdAt),
+      updatedAt: toISOString(row.updatedAt),
+    })),
+    total,
+    page,
+    limit,
+  }
 }
 
 export async function getTodo(id: number): Promise<Todo | null> {

package/template/src/server/route-registry.ts

@@ -60,7 +60,3 @@ export const adminApiRoutes = new OpenAPIHono()
   .route('/api', pluginAdminRoutes)
   .route('/api', dashboardRoutes)
   .route('/api', tenantRoutes)
-
-// 导出类型
-export type ClientApiRoutes = typeof clientApiRoutes
-export type AdminApiRoutes = typeof adminApiRoutes

package/template/src/server/rpc-merge.ts

@@ -0,0 +1,27 @@
+/**
+ * RPC 客户端对象合并（get-fallback Proxy）
+ *
+ * 用途：当同一路径段（如 'admin'）由多个模块路由文件共同提供时，
+ * 把两个窄客户端的子对象合并成一个类型交集，避免在类型层面重新
+ * 链式 merge 触发 TS2589。
+ *
+ * 语义：primary 优先，secondary 兜底。两个来源的子路径约定互不重叠
+ * （重叠时取 primary 的），因此 get-fallback 足够且无需枚举键。
+ */
+
+export function mergeRpcObjects<T extends object, U extends object>(
+  primary: T,
+  secondary: U
+): T & U {
+  return new Proxy({} as T & U, {
+    get(_target, prop) {
+      if (prop in primary) {
+        return Reflect.get(primary as object, prop, primary)
+      }
+      return Reflect.get(secondary as object, prop, secondary)
+    },
+    has(_target, prop) {
+      return prop in primary || prop in secondary
+    },
+  })
+}

package/template/src/server/rpc-surface.ts

@@ -0,0 +1,117 @@
+/**
+ * @framework-baseline rpc-surface-v1
+ *
+ * 按模块拆分的类型安全 RPC 门面（generator 管理文件）。
+ *
+ * 背景：此前客户端通过 `hc<ClientApiType>`（route-registry 里 11-13 个模块
+ * 链式 merge 后的类型）调用 API，类型实例化深度随模块数线性增长，触发
+ * TS2589，历史上甚至 patch 过 TypeScript 编译器（已被 no-ts-patch validator
+ * 禁止）。
+ *
+ * 本文件是替代方案：每个模块单独实例化一个窄客户端（深度 = 1 个模块），
+ * 组装成与旧 `apiClient.api.<segment>` 完全同形的门面对象。调用方
+ * （client / admin / test-utils / CLI）全部通过 createApiFacade() 获取实例，
+ * 运行时 URL 与旧实现一字不差（baseUrl + '/api' + 模块内部路径）。
+ *
+ * preset 裁剪时由 CLI generator 重新生成本文件（见 src/generators/rpc-surface.ts），
+ * 只包含所选模块的导入与门面条目。
+ */
+
+import { hc } from 'hono/client'
+import { mergeRpcObjects } from './rpc-merge'
+import type { AuthApiType } from './module-auth/routes/auth-routes'
+import type { ChatApiType } from './module-chat/routes/chat-routes'
+import type { NotificationsApiType } from './module-notifications/routes/notification-routes'
+import type { TodosApiType } from './module-todos/routes/todos-routes'
+import type { PluginsApiType } from './module-plugin/routes/plugin-routes'
+import type { PublicContentApiType } from './module-content/routes/public-content-routes'
+import type { CartApiType } from './module-order/routes/cart-routes'
+import type { OrdersMockApiType } from './module-order/routes/orders-mock-routes'
+import type { TopicsApiType } from './module-content/routes/topics-routes'
+import type { MerchantApiType } from './module-merchant/routes/merchant-routes'
+import type { OrdersApiType } from './module-order/routes/order-routes'
+import type { TicketsApiType } from './module-ticket/routes/ticket-routes'
+import type { DisputesApiType } from './module-dispute/routes/dispute-routes'
+import type { ContentsApiType } from './module-content/routes/content-routes'
+import type { CaptchaApiType } from './module-captcha/routes/captcha-routes'
+import type { PermissionsApiType } from './module-permission/routes/permission-routes'
+import type { RolesApiType } from './module-permission/routes/role-routes'
+import type { AuditLogsApiType } from './module-permission/routes/audit-log-routes'
+import type { AdminRoutesApiType } from './module-admin/routes/admin-routes'
+import type { DashboardApiType } from './module-admin/routes/dashboard-routes'
+import type { TenantApiType } from './module-tenant/routes/tenant-routes'
+import type { PluginAdminApiType } from './module-plugin/routes/plugin-admin-routes'
+import type { FilesApiType } from './module-file/routes/file-routes'
+
+/** hono hc 的选项类型（fetch / webSocket / sse / headers 等） */
+export type RpcClientOptions = NonNullable<Parameters<typeof hc>[1]>
+
+/**
+ * 创建按模块拆分的 RPC 门面。
+ * 返回对象与旧 `hc<MergedApiType>(baseUrl)` 的调用形态完全兼容：
+ * `facade.api.todos.$get()` 等价于旧的 `apiClient.api.todos.$get()`。
+ */
+export function createApiFacade(baseUrl: string, options: RpcClientOptions = {}) {
+  const api = `${baseUrl.replace(/\/$/, '')}/api`
+
+  const authClient = hc<AuthApiType>(api, options)
+  const chatClient = hc<ChatApiType>(api, options)
+  const notificationsClient = hc<NotificationsApiType>(api, options)
+  const todosClient = hc<TodosApiType>(api, options)
+  const pluginsClient = hc<PluginsApiType>(api, options)
+  const publicContentClient = hc<PublicContentApiType>(api, options)
+  const cartClient = hc<CartApiType>(api, options)
+  const ordersMockClient = hc<OrdersMockApiType>(api, options)
+  const topicsClient = hc<TopicsApiType>(api, options)
+  const merchantClient = hc<MerchantApiType>(api, options)
+  const ordersClient = hc<OrdersApiType>(api, options)
+  const ticketsClient = hc<TicketsApiType>(api, options)
+  const disputesClient = hc<DisputesApiType>(api, options)
+  const contentsClient = hc<ContentsApiType>(api, options)
+  const captchaClient = hc<CaptchaApiType>(api, options)
+  const permissionsClient = hc<PermissionsApiType>(api, options)
+  const rolesClient = hc<RolesApiType>(api, options)
+  const auditLogsClient = hc<AuditLogsApiType>(api, options)
+  const adminRoutesClient = hc<AdminRoutesApiType>(api, options)
+  const dashboardClient = hc<DashboardApiType>(api, options)
+  const tenantClient = hc<TenantApiType>(api, options)
+  const pluginAdminClient = hc<PluginAdminApiType>(api, options)
+  const filesClient = hc<FilesApiType>(api, options)
+
+  return {
+    api: {
+      auth: authClient.auth,
+      chat: chatClient.chat,
+      notifications: notificationsClient.notifications,
+      todos: todosClient.todos,
+      plugins: mergeRpcObjects(pluginsClient.plugins, pluginAdminClient.plugins),
+      categories: mergeRpcObjects(pluginsClient.categories, pluginAdminClient.categories),
+      stats: mergeRpcObjects(pluginsClient.stats, pluginAdminClient.stats),
+      public: mergeRpcObjects(publicContentClient.public, filesClient.public),
+      'generate-url': filesClient['generate-url'],
+      upload: filesClient['upload'],
+      private: filesClient['private'],
+      cart: cartClient.cart,
+      'orders-mock': ordersMockClient['orders-mock'],
+      profile: topicsClient.profile,
+      topics: topicsClient.topics,
+      merchant: merchantClient.merchant,
+      orders: ordersClient.orders,
+      tickets: ticketsClient.tickets,
+      disputes: disputesClient.disputes,
+      contents: contentsClient.contents,
+      captcha: captchaClient.captcha,
+      'verify-captcha': captchaClient['verify-captcha'],
+      permissions: permissionsClient.permissions,
+      roles: rolesClient.roles,
+      'audit-logs': auditLogsClient['audit-logs'],
+      // 'admin' 段由 dashboard-routes 与 admin-routes（内部再嵌 6 个子路由）共同提供，
+      // 用运行时合并避免类型层 merge
+      admin: mergeRpcObjects(dashboardClient.admin, adminRoutesClient.admin),
+      tenants: tenantClient.tenants,
+      tenant: tenantClient.tenant,
+    },
+  }
+}
+
+export type ApiFacade = ReturnType<typeof createApiFacade>