Portal.C 開発者向けオンボーディングガイド

Portal.Cプロジェクトへようこそ！このガイドでは、新しい開発メンバーがスムーズにプロジェクトに参加できるよう、必要な情報をまとめています。

プロジェクト概要

Portal.Cは、Tech.C Ventureのメンバー管理とイベント管理を行うWebアプリケーションです。技育プロジェクトVol.16で開発される、Tech.C Venture初の基盤システムです。

主要機能

認証・ログイン機能: ZITADEL認証基盤を使用した認証システム
メンバープロフィール機能: 学年自動計算、24時間限定ステータス、スキルタグ管理
時間割閲覧機能: 学年・専攻でフィルタリング可能なメンバー時間割
イベント管理機能: イベント一覧表示と参加表明
管理者画面: イベント登録、参加者管理

技術スタック

フロントエンド: Next.js 15 (App Router), React 19, TypeScript 5.6+
バックエンド: TypeScript
データベース: Supabase (PostgreSQL)
認証基盤: ZITADEL (NextAuth.js経由)
スタイリング: Tailwind CSS
UIコンポーネント: @openameba/spindle-ui
ホスティング: Vercel

前提知識

開発に参加する前に、以下の技術についての基礎知識があることが望ましいです：

必須

TypeScript: プロジェクト全体がTypeScriptで書かれています
React: React 19の基本的な理解
Next.js: App Routerの基本（Server Components / Client Components）
Git: バージョン管理の基本操作

あると良い

Clean Architecture: プロジェクトのアーキテクチャパターン
PostgreSQL: データベース設計とクエリ
Tailwind CSS: ユーティリティファーストCSSフレームワーク
Supabase: BaaS（Backend as a Service）の概念

学習リソース

開発環境のセットアップ

1. 前提条件

以下のツールをインストールしてください：

Node.js 18+: nvmの使用を推奨
npm: Node.jsに同梱（プロジェクトではnpmを使用）
Git: バージョン管理
エディタ: VSCode推奨（プロジェクトには設定ファイルが含まれています）

2. リポジトリのクローン

git clone https://github.com/Tech-C-Venture/Portal.C.git
cd Portal.C

3. 依存関係のインストール

npm install

4. 環境変数の設定

.env.exampleをコピーして.envファイルを作成：

cp .env.example .env

.envファイルを編集し、以下の値を設定してください：

# ZITADEL認証
ZITADEL_ISSUER=https://your-zitadel-instance.zitadel.cloud
ZITADEL_CLIENT_ID=your_client_id

# NextAuth
NEXTAUTH_SECRET=your_secret_key_here  # openssl rand -base64 32 で生成
NEXTAUTH_URL=http://localhost:3000

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

注意: 環境変数の実際の値は、プロジェクトリードまたは運営メンバーから入手してください。

5. Supabaseのセットアップ

Supabase ダッシュボードにアクセス
プロジェクトを作成または既存のプロジェクトに接続
SQL Editorでsupabase/migrations/内のマイグレーションファイルを順番に実行：
- 20241216000001_create_members_table.sql
- 20241216000002_create_tags_table.sql
- 20241216000003_create_events_table.sql
- 20241216000004_create_timetables_table.sql

6. 開発サーバーの起動

npm run dev

ブラウザで http://localhost:3000 を開いて動作を確認してください。

7. ビルドとリントの確認

# ビルド確認
npm run build

# リント実行
npm run lint

# テスト実行
npm run test

プロジェクト構造の理解

Portal.CはClean Architectureパターンを採用しています。以下の4層構造で設計されています。

ディレクトリ構造

Portal.C/
├── src/                      # Clean Architecture実装
│   ├── domain/              # ドメイン層（ビジネスロジック）
│   │   ├── entities/       # エンティティ（Member, Event, Timetable）
│   │   └── value-objects/  # 値オブジェクト（Email, StudentId等）
│   ├── application/         # アプリケーション層（ユースケース）
│   │   ├── use-cases/      # ビジネスロジック実行単位
│   │   ├── ports/          # インターフェース定義（リポジトリ等）
│   │   ├── dtos/           # データ転送オブジェクト
│   │   └── mappers/        # Entity ↔ DTO変換
│   └── infrastructure/      # インフラストラクチャ層
│       ├── repositories/   # データアクセス実装
│       ├── database/       # Supabaseクライアント
│       └── di/             # 依存性注入コンテナ
├── app/                     # プレゼンテーション層（Next.js App Router）
│   ├── events/             # イベント関連ページ
│   ├── members/            # メンバー関連ページ
│   ├── profile/            # プロフィールページ
│   ├── timetable/          # 時間割ページ
│   ├── admin/              # 管理画面
│   └── api/                # API Routes
├── components/              # Reactコンポーネント
│   ├── layout/             # レイアウトコンポーネント
│   └── ui/                 # UIコンポーネント
├── lib/                     # ユーティリティ関数
├── types/                   # TypeScript型定義
├── supabase/                # Supabase設定とマイグレーション
└── .kiro/                   # Kiro開発フレームワーク
    ├── steering/           # プロジェクト全体のガイドライン
    └── specs/              # 機能仕様書

Clean Architectureの層構造

┌─────────────────────────────────────────────┐
│          Presentation Layer                 │
│  (app/, components/ - Next.js App Router)   │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│         Application Layer                   │
│   (use-cases/, ports/, dtos/, mappers/)     │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│          Infrastructure Layer               │
│ (repositories/, database/, auth/, di/)      │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│            Domain Layer                     │
│       (entities/, value-objects/)           │
└─────────────────────────────────────────────┘

依存性ルール: 内側の層は外側の層に依存しません。

Domain Layer: ビジネスロジック、外部依存なし
Application Layer: ユースケース、Domainのみに依存
Infrastructure Layer: 外部サービス統合（DB、認証等）
Presentation Layer: UI、Application/Domainに依存

重要なファイル

ファイル	説明
`README.md`	プロジェクト概要とセットアップ手順
`CLAUDE.md`	AI開発支援用の指示（Kiro Spec-Driven Development）
`docs/ARCHITECTURE.md`	Clean Architectureの詳細設計
`.kiro/steering/`	プロジェクト全体のガイドライン（product.md, tech.md, structure.md）
`package.json`	依存関係とスクリプト定義
`tsconfig.json`	TypeScript設定（パスエイリアス含む）

開発ワークフロー

Kiro Spec-Driven Development

Portal.CではKiroスタイルのSpec-Driven Developmentを採用しています。これにより、要件定義→設計→実装の流れが明確になり、AI支援開発が効率化されます。

基本フロー

Phase 0（オプション）: プロジェクトガイドラインの準備
- /kiro:steering: ガイドライン管理
- /kiro:steering-custom: カスタムガイドライン作成

Phase 1（仕様策定）:

# 1. 仕様初期化
/kiro:spec-init "新機能の説明"

# 2. 要件定義
/kiro:spec-requirements {feature-name}

# 3. ギャップ分析（オプション、既存コードベースとの整合性確認）
/kiro:validate-gap {feature-name}

# 4. 設計
/kiro:spec-design {feature-name} [-y]

# 5. 設計レビュー（オプション）
/kiro:validate-design {feature-name}

# 6. タスク生成
/kiro:spec-tasks {feature-name} [-y]

Phase 2（実装）:

# タスク実装
/kiro:spec-impl {feature-name} [task-numbers]

# 実装検証（オプション）
/kiro:validate-impl {feature-name}

進捗確認:
```
/kiro:spec-status {feature-name}
```

実例：新機能追加の流れ

# 例：通知機能の追加
/kiro:spec-init "メンバーへのプッシュ通知機能"
/kiro:spec-requirements notification-feature
/kiro:spec-design notification-feature -y
/kiro:spec-tasks notification-feature -y
/kiro:spec-impl notification-feature 1-3

Gitワークフロー

ブランチ作成:

git checkout -b feature/your-feature-name

開発とコミット:

git add .
git commit -m "feat: 機能の説明"

プッシュ:

git push -u origin feature/your-feature-name

プルリクエスト作成:
- GitHubでPRを作成
- レビューを依頼
- CI/CDが通ることを確認

コミットメッセージ規約

Conventional Commitsに準拠：

feat: 新機能の追加
fix: バグ修正
docs: ドキュメント更新
style: コードフォーマット変更
refactor: リファクタリング
test: テスト追加・修正
chore: ビルドプロセス・ツール変更

コーディング規約

TypeScript

型安全性: any型は使用禁止、適切な型定義を使用
strict mode: TypeScript strict modeを有効化
命名規則:
- ファイル名: PascalCase（コンポーネント）、camelCase（ユーティリティ）
- 関数/変数: camelCase
- 型/インターフェース: PascalCase
- 定数: UPPER_SNAKE_CASE

React / Next.js

Server Components優先: デフォルトでServer Componentsを使用
Client Components: 'use client'が必要な場合のみ使用
コンポーネント設計: 単一責任の原則に従う
Hooks: カスタムフックはuseプレフィックスを付ける

Clean Architectureルール

依存性の方向:
- Domain → (依存なし)
- Application → Domain
- Infrastructure → Application, Domain
- Presentation → Application, Domain
レイヤー間通信:
- Use Caseを通じてビジネスロジックを実行
- Repositoryインターフェース（ports）を定義し、実装（Infrastructure）を注入

データフロー:

// NG: Presentationから直接Repository実装を参照
import { SupabaseMemberRepository } from '@/infrastructure/repositories/SupabaseMemberRepository';

// OK: DIコンテナ経由でインターフェースを取得
import { container } from '@/infrastructure/di/setup';
import { REPOSITORY_KEYS } from '@/infrastructure/di/keys';
const repository = container.resolve<IMemberRepository>(REPOSITORY_KEYS.MEMBER);

コードレビューチェックリスト

型安全性が保たれているか（anyを使っていないか）
Clean Architectureの依存性ルールに違反していないか
テストが追加されているか
ESLintエラーがないか
コミットメッセージが規約に従っているか

よくある問題とトラブルシューティング

1. `npm install`でエラーが出る

原因: Node.jsのバージョンが古い

解決方法:

# Node.jsバージョン確認
node -v

# nvmでNode.js 18+をインストール
nvm install 18
nvm use 18

2. 環境変数が読み込まれない

原因: .envファイルが正しく設定されていない

解決方法:

.envファイルがプロジェクトルートに存在するか確認
サーバーを再起動（npm run dev）
ブラウザのキャッシュをクリア

3. Supabaseへの接続エラー

原因: Supabase認証情報が間違っている、またはマイグレーションが未実行

解決方法:

# 環境変数を確認
echo $NEXT_PUBLIC_SUPABASE_URL
echo $NEXT_PUBLIC_SUPABASE_ANON_KEY

# Supabaseダッシュボードでマイグレーションが実行されているか確認
# SQL Editorでテーブルの存在を確認
SELECT * FROM members LIMIT 1;

4. 型エラーが出る

原因: 型定義が古い、または間違った型を使用している

解決方法:

# 型定義を再生成（Supabaseの場合）
npx supabase gen types typescript --project-id YOUR_PROJECT_ID > types/database.types.ts

# TypeScriptキャッシュをクリア
rm -rf .next
npm run build