/**
 * Copyright (c) 2025 TWork Team. All rights reserved.
 * This source code is licensed under the TWork License.
 */

/**
 * engineer-dev 专属类型定义
 * 
 * 定义开发工程师模式的核心业务类型:
 * - 代码分析相关
 * - Bug诊断相关
 * - 重构相关
 * - 项目分析相关
 * - 计划执行相关
 * - 测试生成相关
 */

// ==================== 代码分析相关 ====================

/**
 * 代码分析结果
 */
export interface CodeAnalysisResult {
  /** 文件路径 */
  filePath: string
  /** 语言 */
  language: string
  /** 代码行数 */
  linesOfCode: number
  /** 复杂度评分 */
  complexityScore: number
  /** 代码质量问题 */
  issues: CodeIssue[]
  /** 依赖关系 */
  dependencies: string[]
  /** 被依赖关系 */
  dependents: string[]
  /** 技术栈检测结果 */
  techStack?: TechStackInfo
}

/**
 * 代码问题
 */
export interface CodeIssue {
  /** 问题类型 */
  type: 'bug' | 'smell' | 'vulnerability' | 'performance' | 'style'
  /** 严重程度 */
  severity: 'critical' | 'major' | 'minor' | 'info'
  /** 问题描述 */
  message: string
  /** 行号 */
  line?: number
  /** 列号 */
  column?: number
  /** 建议修复方案 */
  suggestion?: string
}

/**
 * 技术栈信息
 */
export interface TechStackInfo {
  /** 前端框架 */
  frontend?: string[]
  /** 后端框架 */
  backend?: string[]
  /** 数据库 */
  database?: string[]
  /** 构建工具 */
  buildTools?: string[]
  /** 测试框架 */
  testing?: string[]
  /** 置信度 */
  confidence: number
}

// ==================== Bug诊断相关 ====================

/**
 * Bug诊断结果
 */
export interface BugDiagnosisResult {
  /** Bug描述 */
  description: string
  /** 可能原因 */
  possibleCauses: PossibleCause[]
  /** 影响范围 */
  impactScope: string[]
  /** 修复建议 */
  fixSuggestions: FixSuggestion[]
  /** 相关代码位置 */
  relatedCode: string[]
  /** 置信度 */
  confidence: number
}

/**
 * 可能原因
 */
export interface PossibleCause {
  /** 原因描述 */
  cause: string
  /** 概率 */
  probability: 'high' | 'medium' | 'low'
  /** 验证方法 */
  verification?: string
}

/**
 * 修复建议
 */
export interface FixSuggestion {
  /** 建议描述 */
  suggestion: string
  /** 优先级 */
  priority: 'high' | 'medium' | 'low'
  /** 预估工作量 */
  estimatedEffort?: string
  /** 风险等级 */
  riskLevel?: 'low' | 'medium' | 'high'
}

// ==================== 重构相关 ====================

/**
 * 重构建议
 */
export interface RefactoringSuggestion {
  /** 重构类型 */
  type: 'extract' | 'rename' | 'move' | 'inline' | 'simplify'
  /** 重构描述 */
  description: string
  /** 目标代码位置 */
  targetLocation: string
  /** 重构前后对比 */
  beforeAfter?: {
    before: string
    after: string
  }
  /** 收益 */
  benefits: string[]
  /** 风险 */
  risks: string[]
  /** 自动修复代码 */
  autoFix?: string
}

/**
 * 重构计划
 */
export interface RefactoringPlan {
  /** 计划名称 */
  name: string
  /** 重构目标 */
  objectives: string[]
  /** 重构步骤 */
  steps: RefactoringStep[]
  /** 预估时间 */
  estimatedTime: string
  /** 风险评估 */
  riskAssessment: 'low' | 'medium' | 'high'
}

/**
 * 重构步骤
 */
export interface RefactoringStep {
  /** 步骤编号 */
  stepNumber: number
  /** 步骤描述 */
  description: string
  /** 涉及文件 */
  files: string[]
  /** 前置步骤 */
  dependencies: number[]
  /** 预估时间 */
  estimatedTime: string
}

// ==================== 项目分析相关 ====================

/**
 * 项目分析报告
 */
export interface ProjectAnalysisReport {
  /** 项目名称 */
  projectName: string
  /** 项目类型 */
  projectType: string
  /** 技术栈 */
  techStack: TechStackInfo
  /** 项目结构 */
  structure: ProjectStructure
  /** 代码统计 */
  codeStats: CodeStatistics
  /** 依赖分析 */
  dependencyAnalysis: DependencyAnalysis
  /** 质量评估 */
  qualityAssessment: QualityAssessment
  /** 建议 */
  recommendations: string[]
}

/**
 * 项目结构
 */
export interface ProjectStructure {
  /** 总文件数 */
  totalFiles: number
  /** 目录层级 */
  directoryDepth: number
  /** 主要模块 */
  mainModules: string[]
  /** 入口文件 */
  entryPoints: string[]
}

/**
 * 代码统计
 */
export interface CodeStatistics {
  /** 总代码行数 */
  totalLines: number
  /** 有效代码行数 */
  codeLines: number
  /** 注释行数 */
  commentLines: number
  /** 空行数 */
  blankLines: number
  /** 文件数 */
  fileCount: number
}

/**
 * 依赖分析
 */
export interface DependencyAnalysis {
  /** 外部依赖 */
  externalDependencies: string[]
  /** 内部模块依赖 */
  internalDependencies: DependencyEdge[]
  /** 循环依赖 */
  circularDependencies: string[][]
  /** 核心模块 */
  coreModules: string[]
}

/**
 * 依赖边
 */
export interface DependencyEdge {
  /** 源模块 */
  from: string
  /** 目标模块 */
  to: string
  /** 依赖类型 */
  type: 'import' | 'require' | 'dynamic'
}

/**
 * 质量评估
 */
export interface QualityAssessment {
  /** 整体评分 */
  overallScore: number
  /** 可维护性 */
  maintainability: number
  /** 可读性 */
  readability: number
  /** 测试覆盖率 */
  testCoverage?: number
  /** 技术债务 */
  technicalDebt: 'low' | 'medium' | 'high'
}

// ==================== 计划执行相关 ====================

/**
 * 执行计划
 */
export interface ExecutionPlan {
  /** 计划ID */
  planId: string
  /** 计划名称 */
  planName: string
  /** 计划描述 */
  description: string
  /** 执行步骤 */
  steps: PlanStep[]
  /** 验收标准 */
  acceptanceCriteria: string[]
  /** 预估时间 */
  estimatedTime: string
  /** 状态 */
  status: 'pending' | 'executing' | 'completed' | 'failed'
}

/**
 * 计划步骤
 */
export interface PlanStep {
  /** 步骤编号 */
  stepNumber: number
  /** 步骤标题 */
  title: string
  /** 步骤描述 */
  description: string
  /** 执行文件 */
  files: string[]
  /** 依赖步骤 */
  dependencies: number[]
  /** 预估时间 */
  estimatedTime: string
  /** 成功标准 */
  successCriteria: string
}

// ==================== 测试生成相关 ====================

/**
 * 测试计划
 */
export interface TestPlan {
  /** 计划名称 */
  name: string
  /** 测试范围 */
  scope: string
  /** 测试策略 */
  strategy: TestStrategy
  /** 执行计划 */
  executionPlan: TestExecutionStep[]
  /** 验收标准 */
  acceptanceCriteria: {
    minimumCoverage: number
    passRate: number
    performanceRequirements?: string
  }
}

/**
 * 测试策略
 */
export interface TestStrategy {
  /** 单元测试比例 */
  unitTestRatio: number
  /** 集成测试比例 */
  integrationTestRatio: number
  /** API测试比例 */
  apiTestRatio: number
  /** 目标覆盖率 */
  targetCoverage: number
  /** 策略描述 */
  description: string
}

/**
 * 测试执行步骤
 */
export interface TestExecutionStep {
  /** 步骤编号 */
  stepNumber: number
  /** 步骤标题 */
  title: string
  /** 步骤描述 */
  description: string
  /** 测试文件 */
  testFiles: string[]
  /** 依赖步骤 */
  dependencies: number[]
  /** 预估时间 */
  estimatedTime: string
  /** 成功标准 */
  successCriteria: string
}

// ==================== 指令类型相关 ====================

/**
 * 工程师指令类型
 */
export type EngineerInstructionType =
  | 'module_development'    // 模块开发
  | 'code_refactoring'      // 代码重构
  | 'bug_diagnosis'         // Bug诊断
  | 'performance_optimization'  // 性能优化
  | 'test_generation'       // 测试生成
  | 'project_analysis'      // 项目分析
  | 'lsp_query'             // LSP查询
  | 'code_search'           // 代码搜索
  | 'workflow_integration'  // 工作流集成

/**
 * 指令元数据
 */
export interface InstructionMetadata {
  /** 指令类型 */
  type: EngineerInstructionType
  /** 指令描述 */
  description: string
  /** 关键词 */
  keywords: string[]
  /** 所需工具 */
  requiredTools: string[]
  /** 输出类型 */
  outputType: string
}

// ==================== 工作流相关 ====================

/**
 * 工作流定义
 */
export interface WorkflowDefinition {
  /** 工作流ID */
  workflowId: string
  /** 工作流名称 */
  name: string
  /** 工作流描述 */
  description: string
  /** 工作流步骤 */
  steps: WorkflowStep[]
  /** 触发条件 */
  triggerCondition: string
  /** 超时时间 */
  timeout?: number
}

/**
 * 工作流步骤
 */
export interface WorkflowStep {
  /** 步骤ID */
  stepId: string
  /** 步骤名称 */
  name: string
  /** 工具名称 */
  toolName: string
  /** 工具参数 */
  toolArgs: Record<string, unknown>
  /** 下一步 */
  nextStep?: string
  /** 错误处理 */
  onError?: 'stop' | 'continue' | 'retry'
}

/**
 * 工作流执行结果
 */
export interface WorkflowExecutionResult {
  /** 工作流ID */
  workflowId: string
  /** 执行状态 */
  status: 'success' | 'failed' | 'partial'
  /** 步骤结果 */
  stepResults: Array<{
    stepId: string
    success: boolean
    data?: unknown
    error?: string
  }>
  /** 执行时间 */
  executionTime: number
  /** 错误信息 */
  error?: string
}
