---
name: existing-system-gap-analysis-workflow
type: procedure
when: '现有项目, 新需求, 已有系统, 现有系统, 差距分析, gap analysis, existing system, 现有源码'
scope:
  - backend
  - frontend
  - infrastructure
products:
  - '*'
owner_mechanism_id: mc-existing-system-analysis
consumed_contracts:
  - existing_system_analysis_contract_entry
  - architecture_design_contract_entry
  - technology_decision_contract
  - brainstorm_contract
  - detail_discipline_contract
  - first_principles_contract
required_sections:
  - 项目上下文检测
  - 现有系统分析
  - 需求差距分析
  - 主线集成计划
  - 验证计划
hard_rules:
  - >-
    existing_system + new_requirement 必须先生成 ExistingSystemAnalysisContract 和
    RequirementGapAnalysis
  - new_system / empty_project 不得强制执行 ExistingSystemAnalysis
  - unknown 必须 manual_required，不能猜测继续
  - 现有系统分析必须读取真实代码和相关文档，不能只读需求文档
  - >-
    分析结论必须区分 fact / inference / assumption / unknown，并带 confidence 和
    evidence_refs
  - 差距分析必须列出现有能力、缺失能力、复用模块、required_changes、兼容/数据/权限/集成风险
  - 实现前必须有 MainlineIntegrationPlan
  - VerificationPlan 必须从 RequirementGapAnalysis 生成
acceptance_checks:
  - project_context_type 已检测且非 unknown
  - ExistingSystemAnalysisContract 已创建
  - RequirementGapAnalysis 已创建
  - 现有项目已有技术栈和项目约定优先于 SoloForge 默认
  - 分析结论包含 fact/inference/assumption/unknown 分类
id: ka-procedure-现有系统差距分析工作流
asset_kind: procedure
lifecycle_status: active
authority: supporting
routes:
  - code_change
primary_triggers:
  - 现有系统差距分析工作流
secondary_triggers: []
negative_triggers: []
priority: P1
specificity: 5
consumes:
  - mc-existing-system-analysis
emits:
  - existing_system_analysis
  - requirement_gap_analysis
  - mainline_integration_plan
  - verification_plan
required_evidence:
  - workflow_id
  - required_mechanisms
version: 1.1.0
last_reviewed: '2026-06-01'
stages: ["现有系统分析"]
---

## 适用场景
已有源码、路由、API、前端页面、权限模型和测试脚本的项目中开发新需求。必须先分析现有系统、再做差距分析、最后才进入设计或编码。

## 步骤
1. **项目上下文检测**: detectProjectContext 判断 project_context_type
2. **现有系统分析**:
   - 读取真实代码和相关文档
   - 识别技术栈、路由、API、前端页面、权限模型、测试脚本
   - 区分 fact / inference / assumption / unknown
3. **需求差距分析**:
   - 列出现有能力、缺失能力、复用模块
   - 列出 required_changes、optional_changes、out_of_scope
   - 列出兼容/数据/权限/集成风险、前后端影响、测试回归范围
4. **主线集成计划**: 新增文件、组件、API、service、DTO/model、配置必须被真实消费
5. **验证计划**: VerificationPlan 从 RequirementGapAnalysis 生成

## 检查点
- [ ] project_context_type 已检测
- [ ] 现有系统分析读取了真实代码
- [ ] 差距分析包含完整风险列表
- [ ] MainlineIntegrationPlan 已创建
- [ ] VerificationPlan 已从差距分析生成

## 禁止退化
- existing_system 未分析不得进入设计或编码
- unknown 类型不得猜测继续，必须 manual_required
- 不能只读需求文档，必须读代码
- 缺差距分析不得 coding
