generic-fullstack-feature-developer

フルスタック機能開発者

Next.js／NestJS のフルスタックアプリケーションで機能を開発するためのガイドです。

拡張元： 汎用機能開発者 - 開発ワークフロー、意思決定のフレームワーク、データフローパターン、エラー処理については、基本スキルをお読みください。

フルスタックのデータフロー

User Action → Event Handler → API Call → NestJS Controller
                                              ↓
UI Update ← Response ← Service ← Prisma ← Database

リクエスト／レスポンスサイクル

// Frontend: Call API
const response = await fetch('/api/users', {
  method: 'POST',
  body: JSON.stringify(userData),
});

// Backend: Handle request
@Post()
@UseGuards(JwtAuthGuard)
async createUser(@Body() dto: CreateUserDto) {
  return this.userService.create(dto);
}

Next.js App Router のパターン

ファイル規約

ファイル	目的
page.tsx	ルート UI（デフォルトではサーバーコンポーネント）
layout.tsx	共通 UI ラッパー
loading.tsx	Suspense ローディング UI
error.tsx	エラーバウンダリー
route.ts	API エンドポイント

サーバーコンポーネントとクライアントコンポーネント

// Server Component (default) - can fetch data
export default async function Page() {
  const data = await getData(); // Direct DB/API call
  return <div>{data.title}</div>;
}

// Client Component - needs 'use client'
'use client';
export default function Interactive() {
  const [state, setState] = useState();
  return <button onClick={() => setState(...)}>Click</button>;
}

NestJS モジュールパターン

Module → Controller → Service → Prisma

機能モジュールの追加

// 1. Module definition
@Module({
  controllers: [UsersController],
  providers: [UsersService],
  exports: [UsersService],
})
export class UsersModule {}

// 2. Controller with guards
@Controller("users")
@UseGuards(JwtAuthGuard)
export class UsersController {
  @Post()
  create(@Body() dto: CreateUserDto) {
    return this.usersService.create(dto);
  }
}

// 3. Service with Prisma
@Injectable()
export class UsersService {
  constructor(private prisma: PrismaService) {}

  create(dto: CreateUserDto) {
    return this.prisma.user.create({ data: dto });
  }
}

Prisma ワークフロー

スキーマの変更

# 1. Edit schema.prisma
# 2. Create migration
npx prisma migrate dev --name add_user_role

# 3. Regenerate client
npx prisma generate

# 4. Update services to use new fields

型安全なクエリ

// ✓ Type-safe with generated types
const user = await this.prisma.user.findUnique({
  where: { id },
  include: { posts: true },
});

// ✗ Avoid raw SQL
await this.prisma.$queryRaw`SELECT * FROM users`; // No type safety

認証フロー

Login Request → Validate Credentials → Generate JWT → Set Cookie
      ↓
Protected Route → JwtAuthGuard → Extract User → Inject to Controller

認証の統合ポイント

// Frontend: Include credentials
fetch('/api/protected', { credentials: 'include' });

// Backend: Guard + decorator
@UseGuards(JwtAuthGuard)
@Get('profile')
getProfile(@CurrentUser() user: User) {
  return user;
}

機能チェックリスト（フルスタック）

開始前

• データモデル（Prisma スキーマ）を計画する
• API コントラクト（DTO）を定義する
• 認証要件を特定する

開発中

• Prisma スキーマを作成／更新する
• マイグレーションを実行する
• NestJS モジュール（コントローラー＋サービス）を実装する
• フロントエンドコンポーネントを作成する
• ローディング状態／エラー状態を追加する

完了前

• DTO バリデーションデコレーターを追加する
• DTO と呼び出し元に照らして、サービスと API のエラー処理経路を確認する
• バックエンドのユニットテストと API E2E テストは、ユーザーから依頼された場合にのみ行う
• TypeScript の型が一致していることを確認する

関連項目

• 汎用機能開発者 - 基本的な手法
• コードレビュー標準 - 品質要件
• デザインパターン - UI パターン