docyrus-app-dev

Docyrus App Developer

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 には実際のフィールドスラッグを使ってください。
5. 子クエリのキーは columns に含める必要があります — たとえば、childQuery のキーが orders の場合、columns 配列に 'orders' を含めてください。
6. 数式のキーは columns に含める必要があります — たとえば、数式のキーが total の場合、columns 配列に 'total' を含めてください。
7. 現在のユーザープロフィールには、直接 API を呼び出すのではなく、useUsersCollection().getMyInfo() を使ってください。

スキーマ変更後のコレクション再生成

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
   

必ず3つの手順をまとめて実行してください。古い 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 エンドポイント