【AI駆動開発】Cursorを使いこなして1ヶ月でプログラミング学習サイトを作ったのでノウハウを伝えたい

'use client';

import Prism from 'prismjs';
import 'prismjs/themes/prism-tomorrow.css';
import React, { useCallback, useEffect, useRef } from 'react';
import ReactMarkdown from 'react-markdown';
import rehypeRaw from 'rehype-raw';
import remarkGfm from 'remark-gfm';

// 必要な言語をインポート
import 'prismjs/components/prism-bash';
import 'prismjs/components/prism-css';
import 'prismjs/components/prism-java';
import 'prismjs/components/prism-javascript';
import 'prismjs/components/prism-jsx';
import 'prismjs/components/prism-python';
import 'prismjs/components/prism-ruby';
import 'prismjs/components/prism-tsx';
import 'prismjs/components/prism-typescript';

type MarkdownRendererProps = {
  content: string;
  className?: string;
};

// コード要素のprops型を定義
interface CodeProps {
  className?: string;
  children?: React.ReactNode;
  [key: string]: unknown;
}

/**
 * マークダウンデータの前処理
 * エスケープされた文字を実際の文字に変換
 */
function preprocessMarkdown(content: string): string {
  return content
    .replace(/\\n/g, '\n')
    .replace(/\\t/g, '\t')
    .replace(/\\r/g, '\r')
    .replace(/\\\\/g, '\\')
    .replace(/\\"/g, '"')
    .replace(/\\'/g, "'");
}

/**
 * 汎用的なマークダウンレンダリングコンポーネント
 * 問題文や解説文など、様々な用途で使用可能
 */
export default function MarkdownRenderer({ content, className = '' }: MarkdownRendererProps) {
  const containerRef = useRef<HTMLDivElement>(null);
  const highlightTimeoutRef = useRef<NodeJS.Timeout>();

  // マークダウンコンテンツの前処理
  const processedContent = React.useMemo(() => {
    return preprocessMarkdown(content);
  }, [content]);

  // Prism.jsでハイライトを適用する関数
  const highlightCode = useCallback(() => {
    if (containerRef.current && typeof window !== 'undefined') {
      // 既存のハイライトをクリア
      const preElements = containerRef.current.querySelectorAll('pre');
      preElements.forEach((pre) => {
        const code = pre.querySelector('code');
        if (code) {
          // Prismが追加したクラスを保持しつつ、トークンをクリア
          const className = code.className;
          const textContent = code.textContent || '';
          code.innerHTML = '';
          code.textContent = textContent;
          code.className = className;
        }
      });

      // 新しくハイライトを適用
      Prism.highlightAllUnder(containerRef.current);
    }
  }, []);

  // コンテンツ変更時とマウント時にハイライトを適用
  useEffect(() => {
    // 既存のタイムアウトをクリア
    if (highlightTimeoutRef.current) {
      clearTimeout(highlightTimeoutRef.current);
    }

    // 複数回のハイライト適用で確実性を高める
    const applyHighlight = () => {
      highlightCode();

      // 追加の保険として、少し遅れて再度適用
      highlightTimeoutRef.current = setTimeout(() => {
        highlightCode();
      }, 300);
    };

    // 初回のハイライト適用
    const initialTimeout = setTimeout(applyHighlight, 50);

    return () => {
      clearTimeout(initialTimeout);
      if (highlightTimeoutRef.current) {
        clearTimeout(highlightTimeoutRef.current);
      }
    };
  }, [processedContent, highlightCode]);

  // MutationObserverでDOM変更を監視
  useEffect(() => {
    if (!containerRef.current) return;

    const observer = new MutationObserver((mutations) => {
      // コードブロックに関する変更があった場合のみハイライトを再適用
      const hasCodeChanges = mutations.some((mutation) => {
        if (mutation.type === 'childList') {
          const addedNodes = Array.from(mutation.addedNodes);
          const removedNodes = Array.from(mutation.removedNodes);
          return [...addedNodes, ...removedNodes].some((node) => {
            if (node.nodeType === Node.ELEMENT_NODE) {
              const element = node as Element;
              return (
                element.tagName === 'PRE' ||
                element.tagName === 'CODE' ||
                element.querySelector('pre') ||
                element.querySelector('code')
              );
            }
            return false;
          });
        }
        return false;
      });

      if (hasCodeChanges) {
        highlightCode();
      }
    });

    observer.observe(containerRef.current, {
      childList: true,
      subtree: true,
    });

    return () => {
      observer.disconnect();
    };
  }, [highlightCode]);

  return (
    <div ref={containerRef} className={`prose max-w-none ${className}`}>
      <div className="markdown-content">
        <ReactMarkdown
          remarkPlugins={[remarkGfm]}
          rehypePlugins={[rehypeRaw]}
          components={{
            // コードブロックの処理
            pre: ({ children, ...props }) => {
              const childArray = React.Children.toArray(children);
              const codeElement = childArray.find((child) => React.isValidElement(child) && child.type === 'code');

              if (codeElement && React.isValidElement(codeElement)) {
                const codeProps = codeElement.props as CodeProps;
                const className = codeProps.className || '';

                // 言語とファイル名の抽出
                const languageMatch = className.match(/language-(\w+)(?::(.+))?/);
                const language = languageMatch ? languageMatch[1] : 'plaintext'; // 言語指定がない場合はplaintext
                const fileName = languageMatch && languageMatch[2] ? languageMatch[2] : '';

                // codeElementのpropsからinline-codeを削除（コードブロック内では使わない）
                const newCodeProps = { ...codeProps };
                if (newCodeProps.className === 'inline-code') {
                  newCodeProps.className = 'language-plaintext';
                }

                return (
                  <div className={`code-block ${language === 'plaintext' ? 'code-block-plaintext' : ''}`}>
                    {fileName && (
                      <div className="code-filename">
                        <span>{fileName}</span>
                      </div>
                    )}
                    <pre {...props} className={`language-${language}`} data-prism-processed="false">
                      {React.cloneElement(codeElement, {
                        className: `language-${language}`,
                        ...newCodeProps,
                      })}
                    </pre>
                  </div>
                );
              }

              // 言語指定のないpreタグは特別なクラスで扱う
              return (
                <div className="code-block code-block-plaintext">
                  <pre {...props} className="language-plaintext" data-prism-processed="false">
                    {children}
                  </pre>
                </div>
              );
            },

            // インラインコードの処理
            code: ({ className, children, ...props }) => {
              const content = String(children).replace(/\n$/, '');
              const match = className?.match(/language-(\w+)/);

              // 親要素がpreかどうかを確認する関数
              const isInsidePre = () => {
                // ブラウザ環境でのみ判定可能
                if (typeof document !== 'undefined' && props.node) {
                  // ReactMarkdownのnode型は複雑なので、より安全な方法で処理
                  type ReactMarkdownNode = {
                    parentNode?: {
                      tagName?: string;
                    };
                  };

                  // unknownを経由してキャスト
                  const node = props.node as unknown as ReactMarkdownNode;
                  if (node.parentNode?.tagName === 'PRE') {
                    return true;
                  }
                }
                // コンテンツの改行数で判断（複数行ならコードブロック内と推測）
                const textContent = String(children);
                return textContent.includes('\n') || textContent.length > 80;
              };

              // インラインコードの場合
              if (!match) {
                // 親がpreの場合はplaintextとして扱う
                if (isInsidePre()) {
                  return (
                    <code className="language-plaintext" {...props}>
                      {children}
                    </code>
                  );
                }

                // 通常のインラインコード
                return (
                  <code className="inline-code" {...props}>
                    {children}
                  </code>
                );
              }

              // コードブロック内のコード要素
              const language = match[1];
              return (
                <code className={`language-${language}`} {...props}>
                  {content}
                </code>
              );
            },

            // その他の要素のカスタマイズ（オプション）
            p: ({ children }) => <p className="mb-4 leading-relaxed text-gray-700 last:mb-0">{children}</p>,
            h1: ({ children }) => <h1 className="mb-4 text-2xl font-bold text-gray-900 sm:text-3xl">{children}</h1>,
            h2: ({ children }) => <h2 className="mb-3 text-xl font-semibold text-gray-900 sm:text-2xl">{children}</h2>,
            h3: ({ children }) => <h3 className="mb-3 text-lg font-semibold text-gray-900 sm:text-xl">{children}</h3>,
            ul: ({ children }) => <ul className="mb-4 space-y-1 pl-6">{children}</ul>,
            ol: ({ children }) => <ol className="mb-4 space-y-1 pl-6">{children}</ol>,
            li: ({ children }) => <li className="text-gray-700">{children}</li>,
            blockquote: ({ children }) => (
              <blockquote className="my-4 border-l-4 border-blue-400 bg-blue-50 py-2 pl-4 text-gray-700 italic">
                {children}
              </blockquote>
            ),
            a: ({ children, href }) => (
              <a
                href={href}
                className="text-blue-600 underline hover:text-blue-800 hover:no-underline"
                target="_blank"
                rel="noopener noreferrer"
              >
                {children}
              </a>
            ),
          }}
        >
          {processedContent}
        </ReactMarkdown>
      </div>
    </div>
  );
}

# Next.js + TypeScript プロジェクトのコーディング規約

## 前提条件

- このプロジェクトは以下の技術スタックを使用しています：
  - Next.js 15 (App Router)
  - TypeScript 5.4+
  - Tailwind CSS (スタイリング)
  - Lucide Icons (アイコン)
  - Devicon (開発技術アイコン)

## ディレクトリ構造

- `src/app`: Next.js App Router のページ構造
- `src/components`: React コンポーネント
- `src/lib`: 外部ライブラリとの統合コード
- `src/hooks`: カスタム React Hooks
- `src/types`: グローバルな型定義
- `src/styles`: グローバルスタイルシート
- `src/utils`: ユーティリティ関数

## 基本コーディング規約

### 型安全性

- 厳格な型付けを行って
- 必要に応じて型ガードを使用
- `any`型の使用は原則として避けて
- すべてのコンポーネントの props には型定義を行って
- 外部データの型は`src/types`ディレクトリに定義

### 命名規則

- コンポーネント: `PascalCase.tsx`
- ユーティリティ関数: `camelCase.ts`
- 定数: `UPPER_SNAKE_CASE`
- App Router のページ: `page.tsx`
- ディレクトリ名: `kebab-case`

### コーディングスタイル

- ES2015 以降のモダンな構文を使用
- 関数はアロー関数で作成
  - 推奨: `const sample = (value: string): string => value.toUpperCase();`
  - 非推奨: `function sample(value: string) { return value.toUpperCase(); }`
- コンポーネントは関数コンポーネントとして実装
- 公開関数やコンポーネントには JSDoc を記述
- クラスの代わりに関数を使用

### Next.js 固有のガイドライン

- 可能な限り Server Components を使用
- クライアントでの状態管理が必要な場合のみ`'use client'`ディレクティブを使用
- メタデータは export functions を使って定義
- 画像最適化には必ず`next/image`の`Image`コンポーネントを使用
- リンクには必ず`next/link`の`Link`コンポーネントを使用
- Server Actions はサーバーコンポーネントのみで Form で使用
- Next.js 15 では`params`と`searchParams`が`Promise`型になったため、ページコンポーネントで使用する際は必ず`await`
  - 例: `const resolvedParams = await params`
  - 型定義では`params: Promise<{ id: string }>`、`searchParams: Promise<{ page?: string }>`のように記述

### スタイリング

- `docs-copilot/design-rules/LN_DESIGN_GUIDE.md` のデザインガイドラインに従う
- スタイリングには Tailwind CSS を使用
- カラーは Tailwind のデフォルトカラーパレットを使用
- レスポンシブデザインには Tailwind のブレークポイントを使用

### パフォーマンス最適化

- 不要な再レンダリングを防ぐために`useMemo`と`useCallback`を適切に使用
- 大きなコンポーネントは`React.lazy`と`Suspense`を使用して動的インポート
- クライアントコンポーネントは必要な場合のみに限定

### データ処理とエラーハンドリング

#### Supabase クエリのベストプラクティス

- データの整合性を保つため、不正な値を事前にフィルタリング
- 統計データ取得時は`null`値を適切に除外
- エラーハンドリングは必ず実装し、フォールバック値を提供

```typescript
// 推奨：不正データを除外するクエリ
const { data, error } = await supabase
  .from('table_name')
  .select('columns')
  .not('important_field', 'is', null)
  .order('created_at', { ascending: false });

if (error) {
  console.error('データ取得エラー:', error);
  return fallbackValue; // 必ずフォールバック値を返す
}
```

#### UI の堅牢性

- データの状態に応じた適切な表示分岐を実装
- ローディング状態、エラー状態、空状態を考慮
- データ不整合があっても適切なメッセージを表示

```typescript
// 推奨：3段階の表示ロジック
{
  data?.validField ? (
    <NormalDisplay data={data} />
  ) : data?.partialField ? (
    <PartialDisplay message="データ準備中" />
  ) : (
    <EmptyDisplay message="データがありません" />
  );
}
```

#### 統計データの処理

- 集計処理はフロントエンドで行う際も型安全性を確保
- `Number()`を使用した型変換では`|| 0`でフォールバック値を設定
- 日付計算では`Date`オブジェクトの妥当性を検証

```typescript
// 推奨：安全な統計データ処理
data.forEach((session) => {
  const techRate = Number(session.tech_rate) || 0;
  const attempts = Number(session.total_attempts) || 0;

  if (techRate > 0) {
    // 有効な値のみ処理
    // 統計処理
  }
});
```

## テストガイドライン

### 基本方針

- 基本的なユニットテストを実装
- React Testing Library を使用してコンポーネントをテスト
- 外部サービスの呼び出しはモックを使用

### Supabase のテスト

#### モック化の基本構造

```typescript
// Supabaseクライアントのモック化
jest.mock('@/lib/supabase', () => ({
  supabase: {
    from: jest.fn(),
  },
}));
```

#### クエリチェーンのモック化

Supabase のクエリは`.select().eq().order()`のようにチェーンするため、各メソッドで`mockReturnThis()`を使用：

```typescript
const mockSelect = jest.fn().mockReturnThis();
const mockEq = jest.fn().mockReturnThis();
const mockNot = jest.fn().mockReturnThis();
const mockOrder = jest.fn().mockResolvedValue({
  data: mockData,
  error: null,
});

(supabase.from as jest.Mock).mockReturnValue({
  select: mockSelect,
  eq: mockEq,
  not: mockNot,
  order: mockOrder,
});
```

#### エラーハンドリングのテスト

正常系だけでなく、以下のエラーケースも必ずテスト：

- データが存在しない場合（`data: []`）
- データが null の場合（`data: null`）
- Supabase エラーの場合（`error: { message: 'Database error' }`）
- 例外が発生した場合（`throw new Error()`）

#### 日付処理のテスト

固定日時でのテストには`jest.useFakeTimers()`を使用：

```typescript
beforeEach(() => {
  jest.useFakeTimers();
  jest.setSystemTime(new Date('2024-01-20T12:00:00Z'));
});

afterEach(() => {
  jest.useRealTimers();
});
```

### データ不整合への対応

#### 表示ロジックの堅牢性

データベースに不整合データ（例：`tech_rate`が null のセッション）があっても、UI が適切に動作するよう 3 段階の表示ロジックを実装：

```typescript
// 例：タイムアタック統計の表示
{
  courseStats?.bestTechRate ? (
    // 1. ベストスコアあり → 正常な表示
    <BestScoreDisplay />
  ) : courseStats?.totalSessions > 0 ? (
    // 2. セッションはあるがスコアなし → 「記録更新中」表示
    <InProgressDisplay />
  ) : (
    // 3. セッションなし → 「初回挑戦」表示
    <FirstTimeDisplay />
  );
}
```

#### データフィルタリング

統計関数では不正なデータを事前に除外：

```typescript
// tech_rateがnullでないレコードのみ取得
const { data, error } = await supabase
  .from('time_attack_sessions')
  .select('course, tech_rate, created_at')
  .eq('user_id', userId)
  .not('tech_rate', 'is', null) // 重要：不正データを除外
  .order('created_at', { ascending: false });
```

### テストファイルの命名と配置

- テストファイル：`src/lib/__tests__/ファイル名.test.ts`
- コンポーネントテスト：`src/components/__tests__/コンポーネント名.test.tsx`
- 統合テスト：`src/__tests__/integration/`

## 有料機能・認証に関する情報

プログラミング学習のための有料サブスクリプションコンテンツを提供するウェブサイトを構築します。Next.js と Clerk Billing を組み合わせ、シンプルな認証とサブスクリプション管理を実現します。

### システム構成

- フロントエンド＆バックエンド: Next.js (App Router)
- ホスティング: Vercel
- 認証＆サブスクリプション管理: Clerk Billing

### 基本コンセプト

- シンプルな実装を優先
- 可能な限り外部サービスのデフォルト機能を活用
- TypeScript による型安全性の確保
- 設定ベースのアクセス制御

### 実装における重要な教訓

#### データ不整合への対応

実際の運用では、以下のようなデータ不整合が発生する可能性がある：

- タイムアタック途中での離脱（`tech_rate`が`null`のセッション）
- エラーによる不完全なデータ保存
- 異なるバージョン間でのデータ構造の違い

**対策：**

- データベースクエリレベルでの不正データ除外
- UI 表示ロジックでの多段階フォールバック
- 統計計算での安全な型変換とバリデーション

#### ユーザー体験の向上

```typescript
// ❌ 悪い例：バイナリな表示判定
{
  hasData ? <Content /> : <EmptyState />;
}

// ✅ 良い例：段階的な状態表示
{
  hasValidData ? (
    <FullContent />
  ) : hasPartialData ? (
    <PartialContent message="データ準備中" />
  ) : (
    <EmptyContent message="まだデータがありません" />
  );
}
```