analyze-yii2-project

Yii2 プロジェクトのワークフローを分析する

目的

レガシーな Yii2 プロジェクトを分析し、ビジネスロジックを抽出してアーキテクチャを理解し、モダナイゼーションを計画するための包括的なワークフローです。

使用するタイミング

• ✅ ユーザーから Yii2 コードベースの分析を依頼された場合
• ✅ Yii2 から NestJS／モダンなフレームワークへの移行を計画する場合
• ✅ ドキュメント化されていない Yii2 プロジェクトを理解する必要がある場合
• ✅ Yii2 のコードからビジネス要件を抽出する場合
• ✅ Yii2 アプリケーションの技術的負債を評価する場合

前提条件

インフラストラクチャの確認

codecompass health

確認項目：

• ✅ Weaviate が稼働している（localhost:8081）
• ✅ Ollama が稼働している（localhost:11434）
• ✅ PostgreSQL が稼働している（localhost:5433）

プロジェクト要件

• Yii2 プロジェクトのディレクトリにアクセスできる
• vendor/ ディレクトリが存在する（ない場合は composer install を実行）
• すべてのファイルに対する読み取り権限がある

ステップごとのワークフロー

フェーズ 1：初期スキャン（概要の把握）

ステップ 1.1：Yii2 アナライザーを実行する

codecompass analyze:yii2 <path-to-yii2-project>

実行内容：

• ディレクトリ構造をスキャンする
• Yii2 のバージョンを検出する
• 規約（コントローラー、モデル、ビュー）を特定する
• ルーティングパターンを抽出する
• データベースのマイグレーションをマッピングする

想定される出力：

• フレームワークのバージョン
• ディレクトリ構造の検証結果
• コントローラー／モデルの数
• マイグレーション履歴

ステップ 1.2：結果を検証する 以下を確認します：

• ❌ vendor/ がない → composer install を実行する
• ❌ Yii2 のバージョンが古い（<2.0.40）→ docs/YII2_QUICK_REFERENCE.md の互換性に関する注意事項を確認する
• ❌ 標準的でない構造 → 手動で設定する必要がある場合があります

フェーズ 2：ビジネス機能の抽出

ステップ 2.1：コントローラーから機能を抽出する

# Analyzer automatically extracts business capabilities from controllers

マッピング内容：

Controller → Business Capability
├── UserController → User Management
├── OrderController → Order Processing
├── PaymentController → Payment Handling
└── ReportController → Reporting & Analytics

ステップ 2.2：モデルからドメインエンティティを抽出する 特定する項目：

• ActiveRecord モデル → データベースエンティティ
• バリデーションルール → ビジネスルール
• リレーションシップ → ドメインモデルの関連

ステップ 2.3：マイグレーションからデータモデルの変遷を抽出する 追跡する項目：

• 時系列でのスキーマ変更
• マイグレーションに埋め込まれたビジネスロジック
• データ変換パターン

フェーズ 3：依存関係の分析

ステップ 3.1：クラスの依存関係を分析する 使用するもの：PHP の解析に AstAnalyzerService

マッピングする項目：

• 密結合（多くのクラスに依存しているクラス）
• 循環依存（リファクタリングが必要な兆候）
• 継承階層
• サービスの依存関係

ステップ 3.2：コアロジックと補助ロジックを特定する 分類項目：

• コアドメイン：ビジネス上重要なロジック（慎重に維持する）
• 補助：インフラストラクチャ、ユーティリティ（置き換え可能）
• 汎用：フレームワークの定型コード（移行時に破棄する）

フェーズ 4：要件の抽出

ステップ 4.1：要件抽出ツールを実行する

codecompass requirements:extract --project-id <yii2-project-id>

抽出項目：

• モデルのバリデーションルール → ビジネス制約
• コントローラーのアクション → ユースケース
• RBAC ルール（存在する場合） → 認可要件
• データベースの制約 → データ整合性ルール

ステップ 4.2：ドキュメントを生成する 出力内容：

• ビジネス機能マップ（Markdown）
• ドメインモデル図（Mermaid）
• ユースケースカタログ
• データディクショナリ

フェーズ 5：セマンティックインデックス作成（任意ですが推奨）

ステップ 5.1：コードベースをインデックス化する

codecompass batch:index <path-to-yii2-project>

理由：

• 「決済処理のビジネスロジック」のようなセマンティック検索が可能になる
• ファイルをまたいだパターンの発見
• 類似コードの検出
• 自然言語でのクエリ

ステップ 5.2：インデックス作成を確認する

curl http://localhost:8081/v1/schema
# Check for CodeContext or AtlasCode collection

ステップ 5.3：セマンティック検索をテストする

codecompass search:semantic "validation rules for customer registration"

返される内容：User モデルのバリデーター、コントローラーのロジック、関連コード

フェーズ 6：移行計画

ステップ 6.1：移行の複雑さを特定する 評価項目：

• 複雑さ：低：CRUD 操作、標準的なパターン
• 複雑さ：中：カスタムワークフロー、ビジネスルール
• 複雑さ：高：レガシー統合、ドキュメント化されていないロジック

ステップ 6.2：ビジネス価値に基づいて優先順位を付ける マッピング内容：

Business Capability → Migration Priority
├── Core Revenue Generating → HIGH (do first, carefully)
├── Customer-Facing → MEDIUM (visible impact)
└── Internal Tools → LOW (can defer)

ステップ 6.3：移行ロードマップを作成する 構成：

1. インフラストラクチャのセットアップ（NestJS、TypeORM など）
2. ドメインモデル（ActiveRecord を TypeORM エンティティに移行）
3. コアビジネスロジック（慎重に維持する）
4. API レイヤー（REST／GraphQL エンドポイント）
5. バックグラウンドジョブ（Yii2 queue を使用している場合）
6. テストと検証

確認する一般的なパターン

Yii2 コントローラーのパターン

// CRUD pattern
public function actionIndex() // → LIST endpoint
public function actionView($id) // → GET/:id endpoint
public function actionCreate() // → POST endpoint
public function actionUpdate($id) // → PUT/:id endpoint
public function actionDelete($id) // → DELETE/:id endpoint

NestJS との対応：

@Controller('users')
export class UsersController {
  @Get() findAll()
  @Get(':id') findOne()
  @Post() create()
  @Put(':id') update()
  @Delete(':id') remove()
}

Yii2 モデルのパターン

// Validation rules
public function rules() {
  return [
    [['email'], 'required'],
    [['email'], 'email'],
  ];
}

NestJS DTO との対応：

export class CreateUserDto {
  @IsNotEmpty()
  @IsEmail()
  email: string;
}

Yii2 データベースのパターン

// ActiveRecord query
$users = User::find()
  ->where(['status' => User::STATUS_ACTIVE])
  ->orderBy('created_at DESC')
  ->all();

TypeORM との対応：

const users = await this.userRepository.find({
  where: { status: UserStatus.ACTIVE },
  order: { createdAt: 'DESC' },
});

出力成果物

1. アーキテクチャ図（Mermaid）

graph TD
  Controller[Controllers] --> Service[Business Logic]
  Service --> Model[ActiveRecord Models]
  Model --> DB[(Database)]
  Controller --> View[Views]

2. ビジネス機能マップ

## Core Capabilities
- User Management (UserController, User model)
- Order Processing (OrderController, Order/OrderItem models)
- Payment Handling (PaymentController, Payment model)

## Supporting Capabilities
- Reporting (ReportController)
- Notifications (EmailService)

3. 移行チェックリスト

• NestJS プロジェクトの構成をセットアップする
• データベーススキーマを移行する（Yii2 migrations → TypeORM migrations）
• モデルを移植する（ActiveRecord → TypeORM entities）
• ビジネスロジックを再実装する（ルールを維持すること！）
• API エンドポイントを作成する（REST/GraphQL）
• 認証／認可を移植する
• バックグラウンドジョブを移行する
• 統合テストを実施する
• パフォーマンステストを実施する
• 段階的にロールアウトする

よくある問題と解決策

問題 1：コントローラーが見つからない

症状：アナライザーがコントローラーを 0 件と報告する 原因：標準とは異なるディレクトリ構成 解決策：Yii2 の @app エイリアス設定を確認し、パスを調整する

問題 2：データベーススキーマが見つからない

症状：モデルを適切に抽出できない 原因：データベースにアクセスできない、またはマイグレーションが実行されていない 解決策：データベース接続が設定されていることを確認し、未適用のマイグレーションを実行する

問題 3：循環依存が検出された

症状：依存関係グラフに循環参照が表示される 意味：コードの問題点。モジュール間の結合度が高い状態です 対応：移行中に循環を解消するリファクタリングを計画する

問題 4：ビジネスルールが文書化されていない

症状：コントローラーにコメントのない複雑なロジックがある 対応：

1. セマンティック検索を使って類似パターンを探す
2. 可能であれば、元の開発者に話を聞く
3. 移行前に動作をテストで記録する
4. 要件ドキュメントに前提事項を記載する

ベストプラクティス

✅ 推奨事項

• 移行を計画する前に、分析をすべて実行する
• ビジネスルールをすべて抽出する（暗黙のルールも含む）
• 前提事項と不明点を文書化する
• セマンティック検索をテストして、インデックス作成を検証する
• 包括的な機能マップを作成する
• 技術的な容易さではなく、ビジネス価値に基づいて優先順位を付ける

❌ 避けること

• 依存関係の分析を省略する（後で問題になります）
• Yii2 の標準的なパターンがどこでも使われていると思い込む
• バリデーションルールを無視する（これらもビジネス要件です！）
• アーキテクチャ全体を理解する前にコーディングを始める
• すべてを一度に移行する（代わりにストラングラーフィグパターンを採用する）

関連スキル

• extract-requirements.md - 詳細な要件抽出
• semantic-search.md - コードの調査
• software-architect.md - アーキテクチャの観点

関連モジュール

.ai/capabilities.json より：

• yii2-analyzer - 主な分析モジュール
• ast-analyzer - PHP の解析
• database-analyzer - スキーマの抽出
• requirements - ビジネスルールの抽出
• business-analyzer - 機能のマッピング

---

重要：目標はコードを理解するだけではなく、コードに埋め込まれたビジネス知識を維持することです。