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：分析类依赖关系 使用 AstAnalyzerService 解析 PHP

映射内容：

• 紧密耦合（依赖许多其他类的类）
• 循环依赖（重构风险信号）
• 继承层次结构
• 服务依赖关系

步骤 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 队列）
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 - 能力映射

---

请记住：目标不仅是理解代码，还要保留其中蕴含的业务知识。