Merge pull request #9 from MrSmart00/feature/convex-integration

feat: Convexリアルタイムバックエンド統合の完全実装

Author: MrSmart00

.github/workflows/deploy.yml

@@ -32,6 +32,8 @@ jobs:
         run: npm ci
 
       - name: Build
+        env:
+          VITE_CONVEX_URL: ${{ secrets.VITE_CONVEX_URL }}
         run: npm run build
 
       - name: Setup Pages

.gitignore

@@ -124,6 +124,9 @@ dist/
 # Documentation folder
 .docs/
 
+# Convex generated files
+convex/_generated/
+
 # OS generated files
 .DS_Store
 .DS_Store?

README.md

@@ -1,19 +1,21 @@
 # Astute Crow
 
-TypeScript + Vite を使用したモダンな Web アプリケーションです。現在は Hello World をベースとしつつ、Zenn トレンド表示機能の開発を進めています。
+TypeScript + Vite を使用したモダンな Web アプリケーションです。現在は Hello World をベースとしつつ、Zenn トレンド表示機能の開発を進めています。Convex をバックエンドとして導入し、トレンドデータのキャッシュや永続化に対応しました。
 
 ## 🚀 特徴
 
 - ⚡ **Vite**: 高速な開発サーバーとビルドツール
 - 🎯 **TypeScript**: 型安全な JavaScript 開発
 - 🎨 **モダンCSS**: CSS Variables、Grid、Flexbox を使用したレスポンシブデザイン
 - 🌙 **ダークテーマ**: 目に優しいダークモードUI
-- 📈 **Zennトレンド表示**: [非公式API](https://github.com/kaisugi/zenn-trend-api)を利用したZennの人気記事情報の取得・表示（開発中）
+- 📈 **Convex バックエンド連携**: Convex によるトレンドデータの取得・キャッシュ・永続化
+- 🌐 **フォールバックAPI**: Convex が利用できない環境でも Zenn 非公式 API 経由でデータを取得
 
 ## 📋 必要な環境
 
 - Node.js 18.0.0 以上
 - npm または yarn
+- Convex アカウント（バックエンドを稼働させる場合）
 
 ## 🛠️ セットアップ
 
@@ -25,13 +27,28 @@ cd astute-crow
 # 依存関係をインストール
 npm install
 
+# Convex の型定義を生成（初回のみ）
+npm run convex:codegen
+
+# .env.local を作成して Convex の URL を設定
+cat <<'EOF' > .env.local
+VITE_CONVEX_URL=https://your-project.convex.cloud
+EOF
+# 既存の .env.local がある場合は上書きしないよう注意し、URL を自身のものに変更してください
+
 # 開発サーバーを起動
 npm run dev
 ```
 
+Convex の開発サーバーをローカルで起動する場合は別ターミナルで以下を実行します。
+
+```bash
+npm run convex:dev
+```
+
 ## 📱 使用方法
 
-開発サーバーを起動すると、自動的にブラウザが開きます。ポートが使用中の場合は、利用可能なポート（通常は3001など）で起動します。
+開発サーバーを起動すると、自動的にブラウザが開きます。ポートが使用中の場合は、利用可能なポート（通常は3001など）で起動します。Convex が利用可能であれば Convex 経由で、利用できない場合は自動的に Zenn API にフォールバックします。
 
 ## 🔧 利用可能なコマンド
 
@@ -40,6 +57,8 @@ npm run dev
 | `npm run dev` | 開発サーバーを起動 |
 | `npm run build` | プロダクション用ビルドを作成 |
 | `npm run preview` | ビルド結果をプレビュー |
+| `npm run convex:dev` | Convex の開発サーバー（ローカル）を起動 |
+| `npm run convex:codegen` | Convex の型定義を生成 |
 
 ## 📁 プロジェクト構造
 
@@ -50,14 +69,22 @@ npm run dev
 │   ├── components/
 │   │   └── ZennTrends.ts    # Zennトレンド表示コンポーネント
 │   ├── services/
-│   │   └── zennService.ts   # Zenn API連携サービス
+│   │   ├── convexZennService.ts # Convex 連携とフォールバックロジック
+│   │   └── zennService.ts       # フォールバックAPI用サービス（開発検証用）
 │   └── types/
 │       └── zenn.ts          # Zenn関連の型定義
-├── frontend/                # フロントエンド用ディレクトリ（将来の拡張予定）
+├── convex/                  # Convex 関連のサーバーコード
+│   ├── schema.ts            # Convex データモデル
+│   ├── trends.ts            # トレンド取得アクション/クエリ
+│   ├── zennApi.ts           # Zenn 非公式API呼び出しアクション
+│   └── zennData.ts          # DB とのやり取り（クエリ/ミューテーション）
 ├── backend/                 # バックエンド用ディレクトリ（将来の拡張予定）
+├── frontend/                # フロントエンド用ディレクトリ（将来の拡張予定）
 ├── index.html               # HTMLテンプレート
 ├── tsconfig.json            # TypeScript設定
 ├── vite.config.ts           # Vite設定
+├── convex.json              # Convex CLI 設定
+├── .env.local               # Convex URL などの環境変数（各自作成、Git未追跡）
 └── package.json             # パッケージ設定
 ```
 
@@ -67,6 +94,7 @@ npm run dev
 - Hello World アプリケーションのベース
 - TypeScript + Vite の開発環境
 - ダークテーマ対応のモダンUI
+- Convex バックエンドとの統合とフォールバックロジック
 
 ### 開発中
 - Zenn トレンド表示機能
@@ -82,6 +110,7 @@ npm run dev
 
 - **TypeScript 5.9+**: 型安全性とモダンな開発体験
 - **Vite 7.1+**: 高速なバンドラーと開発ツール
+- **Convex 1.27+**: サーバーレスなリアルタイムバックエンド
 - **ES2020**: モダンな JavaScript 機能
 - **CSS3**: フレキシブルレイアウトとアニメーション
 
@@ -98,4 +127,4 @@ MIT License - 詳細は [LICENSE](LICENSE) ファイルをご確認ください
 
 ## 👨‍💻 作者
 
-**Hiroya Hinomori** - [@MrSmart00](https://github.com/MrSmart00)
+**Hiroya Hinomori** - [@MrSmart00](https://github.com/MrSmart00)

convex.json

@@ -0,0 +1,3 @@
+{
+  "functions": "./convex/"
+}

convex/schema.ts

@@ -0,0 +1,49 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  // Zennユーザー情報
+  zennUsers: defineTable({
+    username: v.string(),
+    name: v.string(),
+    avatarSmallUrl: v.string(),
+  }).index("by_username", ["username"]),
+
+  // Zenn記事・本の投稿データ
+  zennPosts: defineTable({
+    externalId: v.string(), // ZennのAPI上のID
+    title: v.string(),
+    slug: v.string(),
+    likedCount: v.number(),
+    publishedAt: v.string(),
+    emoji: v.string(),
+    postType: v.union(v.literal("Article"), v.literal("Book")),
+
+    // 記事の場合
+    articleType: v.optional(v.union(v.literal("tech"), v.literal("idea"))),
+
+    // 本の場合
+    price: v.optional(v.number()),
+    isFree: v.optional(v.boolean()),
+    summary: v.optional(v.string()),
+
+    // ユーザー情報への参照
+    userId: v.id("zennUsers"),
+
+    // メタデータ
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_external_id", ["externalId"])
+    .index("by_post_type", ["postType"])
+    .index("by_likes", ["likedCount"])
+    .index("by_published", ["publishedAt"]),
+
+  // トレンドデータのキャッシュ情報
+  trendCache: defineTable({
+    cacheKey: v.string(), // "trends_all", "trends_tech", "trends_idea", "trends_books"
+    expiresAt: v.number(),
+    lastFetched: v.number(),
+    isValid: v.boolean(),
+  }).index("by_cache_key", ["cacheKey"]),
+});

convex/trends.ts

@@ -0,0 +1,136 @@
+import { action, query, mutation, type ActionCtx } from "./_generated/server";
+import { v } from "convex/values";
+
+const CACHE_DURATION = 5 * 60 * 1000; // 5分
+
+type TrendsArgs = {
+  forceRefresh?: boolean;
+  postType?: "Article" | "Book";
+  articleType?: "tech" | "idea";
+};
+
+type TrendsResult = Promise<any[]>;
+
+const getTrendsHandler = async (ctx: ActionCtx, args: TrendsArgs): TrendsResult => {
+  const cacheKey = `trends_${args.postType || "all"}_${args.articleType || "all"}`;
+  const now = Date.now();
+
+  if (!args.forceRefresh) {
+    const cacheInfo = await ctx.runQuery("zennData:getCacheInfo" as any, { cacheKey });
+    if (cacheInfo && cacheInfo.isValid && cacheInfo.expiresAt > now) {
+      return await ctx.runQuery("zennData:getTrendPosts" as any, {
+        postType: args.postType,
+        articleType: args.articleType,
+      });
+    }
+  }
+
+  const freshData = await ctx.runAction("zennApi:fetchAllTrends" as any, {});
+
+  await ctx.runMutation("trends:syncPostsToDatabase" as any, { posts: freshData });
+
+  await ctx.runMutation("zennData:updateCacheInfo" as any, {
+    cacheKey,
+    expiresAt: now + CACHE_DURATION,
+  });
+
+  return await ctx.runQuery("zennData:getTrendPosts" as any, {
+    postType: args.postType,
+    articleType: args.articleType,
+  });
+};
+
+// メイン関数：トレンドデータを取得または更新
+export const getTrends = action({
+  args: {
+    forceRefresh: v.optional(v.boolean()),
+    postType: v.optional(v.union(v.literal("Article"), v.literal("Book"))),
+    articleType: v.optional(v.union(v.literal("tech"), v.literal("idea"))),
+  },
+  handler: getTrendsHandler,
+});
+
+// データベースに投稿データを同期
+export const syncPostsToDatabase = mutation({
+  args: {
+    posts: v.array(v.any()),
+  },
+  handler: async (ctx, args) => {
+    for (const post of args.posts) {
+      const userId = await ctx.runMutation("zennData:upsertUser" as any, {
+        username: post.user.username,
+        name: post.user.name,
+        avatarSmallUrl: post.user.avatarSmallUrl,
+      });
+
+      await ctx.runMutation("zennData:upsertPost" as any, {
+        externalId: post.id,
+        title: post.title,
+        slug: post.slug,
+        likedCount: post.likedCount,
+        publishedAt: post.publishedAt,
+        emoji: post.emoji,
+        postType: post.postType,
+        articleType: post.articleType,
+        price: post.price,
+        isFree: post.isFree,
+        summary: post.summary,
+        userId,
+      });
+    }
+  },
+});
+
+// すべてのトレンドを取得（フロントエンド用）
+export const getAllTrends = query({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.runQuery("zennData:getTrendPosts" as any, {});
+  },
+});
+
+// 技術記事のトレンドを取得
+export const getTechTrends = query({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.runQuery("zennData:getTrendPosts" as any, {
+      postType: "Article",
+      articleType: "tech",
+    });
+  },
+});
+
+// アイデア記事のトレンドを取得
+export const getIdeaTrends = query({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.runQuery("zennData:getTrendPosts" as any, {
+      postType: "Article",
+      articleType: "idea",
+    });
+  },
+});
+
+// 本のトレンドを取得
+export const getBookTrends = query({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.runQuery("zennData:getTrendPosts" as any, {
+      postType: "Book",
+    });
+  },
+});
+
+// 手動でデータを更新
+export const refreshTrends = action({
+  args: {},
+  handler: async (ctx) => getTrendsHandler(ctx, { forceRefresh: true }),
+});
+
+// キャッシュをクリア
+export const clearCache = mutation({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.runMutation("zennData:clearAllCache" as any, {});
+  },
+});

convex/zennApi.ts

@@ -0,0 +1,75 @@
+import { action } from "./_generated/server";
+
+const fetchTechArticlesRaw = async () => {
+  const response = await fetch("https://zenn-api.vercel.app/api/trendTech");
+  if (!response.ok) {
+    throw new Error(`Tech API request failed: ${response.status}`);
+  }
+  const data: any[] = await response.json();
+  return data.map(article => ({
+    ...article,
+    id: String(article.id ?? article.slug ?? `tech-${Math.random().toString(36).slice(2)}`),
+    postType: "Article" as const,
+    articleType: "tech" as const
+  }));
+};
+
+const fetchIdeaArticlesRaw = async () => {
+  const response = await fetch("https://zenn-api.vercel.app/api/trendIdea");
+  if (!response.ok) {
+    throw new Error(`Idea API request failed: ${response.status}`);
+  }
+  const data: any[] = await response.json();
+  return data.map(article => ({
+    ...article,
+    id: String(article.id ?? article.slug ?? `idea-${Math.random().toString(36).slice(2)}`),
+    postType: "Article" as const,
+    articleType: "idea" as const
+  }));
+};
+
+const fetchBooksRaw = async () => {
+  const response = await fetch("https://zenn-api.vercel.app/api/trendBook");
+  if (!response.ok) {
+    throw new Error(`Book API request failed: ${response.status}`);
+  }
+  const data: any[] = await response.json();
+  return data.map(book => ({
+    ...book,
+    id: String(book.id ?? book.slug ?? `book-${Math.random().toString(36).slice(2)}`),
+    emoji: book.emoji || "📚",
+    postType: "Book" as const,
+    price: typeof book.price === "number" ? book.price : Number(book.price ?? 0),
+    isFree: book.isFree || book.price === 0,
+    summary: book.summary || ""
+  }));
+};
+
+// Zenn APIからデータを取得するアクション関数
+export const fetchTechArticles = action({
+  args: {},
+  handler: fetchTechArticlesRaw,
+});
+
+export const fetchIdeaArticles = action({
+  args: {},
+  handler: fetchIdeaArticlesRaw,
+});
+
+export const fetchBooks = action({
+  args: {},
+  handler: fetchBooksRaw,
+});
+
+export const fetchAllTrends = action({
+  args: {},
+  handler: async () => {
+    const [techArticles, ideaArticles, books] = await Promise.all([
+      fetchTechArticlesRaw(),
+      fetchIdeaArticlesRaw(),
+      fetchBooksRaw(),
+    ]);
+
+    return [...techArticles, ...ideaArticles, ...books];
+  },
+});