requirements-analysis/src/steps/step3.ts

简化的需求分析MCP服务 - 基于AI软件工程（优化版）6步流程

/**
 * Step 3: 生成需求分析文档初版
 */

import { StepResult, STEP_DEFINITIONS, AnalysisSession } from '../types';
import { DocumentReferenceManager } from '../utils/document-reference-manager';
import { DocumentContentExtractor } from '../utils/document-content-extractor';

export class Step3 {
  
  /**
   * 生成第3步提示词（精简版）
   */


  static async generatePrompt(session: AnalysisSession): Promise<string> {
    const projectInfo = session.projectInfo;

    // 使用文档引用管理器获取前序步骤内容
    const docManager = new DocumentReferenceManager(projectInfo.projectName);
    const contentExtractor = new DocumentContentExtractor();

    let step1Content = '';
    let step2Content = '';

    try {
      const step1Doc = await docManager.getStepDocument(1);
      step1Content = contentExtractor.extractKeyContent(step1Doc, 'conclusions');
    } catch (error) {
      console.warn('Step 1 document not available');
      step1Content = '第1步验证结果暂未生成';
    }

    try {
      const step2Doc = await docManager.getStepDocument(2);
      step2Content = contentExtractor.extractKeyContent(step2Doc, 'key_points');
    } catch (error) {
      console.warn('Step 2 document not available');
      step2Content = '第2步分析结果暂未生成';
    }

    return `你正在为开发团队编写详细的需求规格说明书，这份文档将成为整个项目开发的核心指导文件。作为经验丰富的需求分析师，你需要确保文档既专业规范又实用易懂，能够有效指导后续的设计和开发工作。

请以严谨的态度和清晰的逻辑，将前期的分析成果转化为一份高质量的需求分析文档。

**项目背景**
- **项目名称**: ${projectInfo.projectName}
- **所属行业**: ${projectInfo.industry}
- **核心价值**: 基于前期分析，这个项目将为${projectInfo.industry}行业带来显著价值

**前期分析精华**
- **项目验证结果**: ${step1Content}
- **战略分析要点**: ${step2Content}

**文档编写指南**

请按照以下结构编写完整的需求分析文档，每个章节都要内容充实、逻辑清晰：

**1. 文档信息** - 项目名称、版本号(v1.0)、编写日期、文档状态

**2. 项目概述**
- **项目背景**: 详细描述现状问题和解决必要性
- **项目目标**: 明确的业务目标、技术目标、用户目标
- **项目范围**: 清晰的边界定义，包含和不包含的功能
- **利益相关者**: 识别所有相关方及其关注点

**3. 功能需求** - 使用以下示例格式：
\`\`\`
#### REQ-USER-001: 用户登录认证 (P0)
**功能描述**: 系统应提供安全的用户身份认证机制
**输入**: 用户名、密码、验证码
**处理**: 验证用户凭据，生成会话令牌
**输出**: 登录成功/失败状态，用户信息
**业务规则**: 密码错误3次锁定账户30分钟，会话超时2小时
**验收标准**:
- 给定有效的用户凭据，当用户点击登录，那么系统应在2秒内完成认证并跳转到主页
- 给定无效的密码，当用户尝试登录，那么系统应显示错误提示并记录日志
\`\`\`

**4. 非功能需求** - 性能、安全、可用性、扩展性的具体指标

**5. 系统集成需求** - 外部系统集成和数据集成的详细要求

**6. 约束条件** - 技术、业务、资源约束的明确说明

**7. 验收标准** - 使用BDD格式编写清晰的验收标准

**8. 附录** - 术语表、需求追溯矩阵

**质量标准**
- **完整性**: 覆盖所有必要的功能和非功能需求
- **准确性**: 需求描述准确无歧义，技术可行
- **可测试性**: 每个需求都有明确的验收标准
- **可追溯性**: 需求与业务目标有清晰的对应关系

**格式规范**
- 需求ID: REQ-[模块缩写]-[三位数字]
- 优先级: P0(必须有)、P1(应该有)、P2(可以有)
- 验收标准: 严格使用"给定...当...那么..."的BDD格式

请确保文档内容详实、结构清晰、格式规范，总篇幅控制在7000字以内。`;
  }

  /**
   * 创建第3步结果
   */
  static async createStepResult(session: AnalysisSession, result: string): Promise<StepResult> {
    const stepDef = STEP_DEFINITIONS[2]; // 第3步

    return {
      stepNumber: stepDef.number,
      stepName: stepDef.name,
      prompt: await this.generatePrompt(session),
      result,
      timestamp: new Date(),
      filePath: stepDef.fileName,
      status: 'completed'
    };
  }

  /**
   * 验证第3步结果质量
   */
  static validateResult(result: string): { isValid: boolean; score: number; issues: string[] } {
    const issues: string[] = [];
    let score = 100;

    // 检查文档结构完整性
    const requiredSections = [
      '文档信息',
      '项目概述',
      '功能需求',
      '非功能需求',
      '验收标准'
    ];

    const missingSections = requiredSections.filter(section => !result.includes(section));
    if (missingSections.length > 0) {
      issues.push(`缺少必要章节：${missingSections.join(', ')}`);
      score -= missingSections.length * 15;
    }

    // 检查需求ID格式
    if (!result.includes('REQ-')) {
      issues.push('缺少标准的需求ID格式');
      score -= 10;
    }

    // 检查优先级标记
    if (!result.includes('P0') && !result.includes('P1') && !result.includes('P2')) {
      issues.push('缺少优先级标记');
      score -= 10;
    }

    // 检查验收标准格式
    if (!result.includes('给定') && !result.includes('当') && !result.includes('那么')) {
      issues.push('验收标准未使用BDD格式');
      score -= 15;
    }

    // 检查内容长度
    if (result.length < 4000) {
      issues.push('文档内容过于简单');
      score -= 20;
    }

    return {
      isValid: score >= 70,
      score: Math.max(0, score),
      issues
    };
  }
}