docyrus-app-dev

Docyrus App 开发者

使用 Docyrus 作为后端构建 React TypeScript Web 应用。通过 OAuth2 PKCE 进行身份验证，使用强大的筛选和聚合功能查询数据源，并遵循既定模式。

技术栈

• React 19 + TypeScript + Vite
• TanStack Router（基于代码），TanStack Query（服务端状态）
• Tailwind CSS v4，shadcn/ui 组件
• @docyrus/api-client（REST 客户端）+ @docyrus/signin（身份验证提供程序）
• 根据 OpenAPI 规范自动生成集合

快速开始：新应用设置

1. 使用 DocyrusAuthProvider 包装根组件：

import { DocyrusAuthProvider } from '@docyrus/signin'

<DocyrusAuthProvider
  apiUrl={import.meta.env.VITE_API_BASE_URL}
  clientId={import.meta.env.VITE_OAUTH2_CLIENT_ID}
  redirectUri={import.meta.env.VITE_OAUTH2_REDIRECT_URI}
  scopes={['offline_access', 'Read.All', 'DS.ReadWrite.All', 'Users.Read']}
  callbackPath="/auth/callback"
>
  <QueryClientProvider client={queryClient}>
    <RouterProvider router={router} />
  </QueryClientProvider>
</DocyrusAuthProvider>

2. 在 App.tsx 中检查身份验证状态并使用集合钩子：

const { status } = useDocyrusAuth()
const { getMyInfo } = useUsersCollection()

if (status === 'loading') return <Spinner />
if (status === 'unauthenticated') return <SignInButton />

3. 在组件中使用集合钩子：

const { list } = useBaseProjectCollection()

const { data: projects } = useQuery({
  queryKey: ['projects'],
  queryFn: () => list({
    columns: ['name', 'status', 'record_owner(firstname,lastname)'],
    filters: { rules: [{ field: 'status', operator: '!=', value: 'archived' }] },
    orderBy: 'created_on DESC',
    limit: 50,
  }),
})

重要规则

1. 在 .list() 和 .get() 调用中始终传入 columns。如果不传，只会返回 id。
2. 集合是 React 钩子——在 React 组件中调用 useBaseProjectCollection()、useUsersCollection() 等。它们会在内部使用 useDocyrusClient()，以通过身份验证访问 API。
3. 数据源端点是动态的——只有在租户的 OpenAPI 规范中定义的数据源才会有对应端点。
4. 计算 count 时使用 id 字段。计算 sum、avg、min、max 时使用实际的字段 slug。
5. 子查询键必须包含在 columns 中——例如，如果 childQuery 键是 orders，则在 columns 数组中包含 'orders'。
6. 公式键必须包含在 columns 中——例如，如果公式键是 total，则在 columns 数组中包含 'total'。
7. 获取当前用户资料时使用 useUsersCollection().getMyInfo()，不要直接调用 API。

架构变更后重新生成集合

通过 docyrus-architect MCP 工具创建、更新或删除数据源或字段后，应用自动生成的集合会变得过时。要重新同步：

1. 调用 regenerate_openapi_spec（architect MCP），重新构建并上传租户的 OpenAPI 规范
2. 将新规范下载到仓库，覆盖现有文件：

   curl -o openapi.json "<publicUrl returned from step 1>"
   

3. 重新生成集合：

   pnpx @docyrus/tanstack-db-generator openapi.json
   

务必连续执行这三个步骤——过时的 openapi.json 或未更新的集合会导致运行时缺少端点或端点不正确。

集合 CRUD 方法

每个生成的集合都是一个返回 CRUD 方法的 React 钩子：

const { list, get, create, update, delete: deleteOne, deleteMany } = useBaseProjectCollection()

list(params?: ICollectionListParams)   // Query with filters, sort, pagination
get(id, { columns })                    // Single record
create(data)                            // Create
update(id, data)                        // Partial update
deleteOne(id)                           // Delete one
deleteMany({ recordIds })               // Delete many

API 端点模式：/v1/apps/{appSlug}/data-sources/{slug}/items

查询功能摘要

.list() 方法支持：

功能	用途
columns	选择字段、展开关联 field(subfields)、设置别名 alias:field、展开 ...field()
filters	支持 50 多种运算符（比较、日期快捷方式、用户相关）的嵌套 AND/OR 分组
filterKeyword	全文搜索
orderBy	按字段排序并指定方向，包括关联字段
limit/offset	分页（默认 100）
fullCount	在结果旁返回总数
calculations	聚合：count、sum、avg、min、max，并支持分组
formulas	计算虚拟列（简单函数、块 AST、相关子查询）
childQueries	将相关子记录作为嵌套 JSON 数组获取
pivot	带日期范围序列的交叉表矩阵查询
expand	对关联、用户和枚举字段返回完整对象，而非 ID

查询和公式的详细信息请参阅：

• references/data-source-query-guide.md
• references/formula-design-guide-llm.md

TanStack Query 模式

// Query hook — call collection hook inside the component, pass methods to TanStack Query
function useProjects(params?: ICollectionListParams) {
  const { list } = useBaseProjectCollection()
  return useQuery({
    queryKey: ['projects', 'list', params],
    queryFn: () => list({ columns: PROJECT_COLUMNS, ...params }),
  })
}

// Mutation hook
function useCreateProject() {
  const { create } = useBaseProjectCollection()
  const qc = useQueryClient()
  return useMutation({
    mutationFn: (data: Record<string, unknown>) => create(data),
    onSuccess: () => { void qc.invalidateQueries({ queryKey: ['projects'] }) },
  })
}

参考资料

需要详细信息时，请阅读以下文件：

• references/api-client-and-auth.md — RestApiClient API、@docyrus/signin 钩子、认证提供方配置、拦截器、错误处理、SSE/流式传输、文件上传/下载
• references/data-source-query-guide.md — 最新的查询负载指南：列、筛选条件、orderBy、分页、计算、公式、子查询、透视和运算符参考
• references/formula-design-guide-llm.md — 最新的公式设计指南，用于构建和验证 formulas 负载
• references/collections-and-patterns.md — 生成的集合钩子、useUsersCollection、TanStack Query/变更钩子模式、查询键工厂、应用引导流程、路由设置、API 端点