cc-devflow 1.0.1

package/.claude/docs/design/consistency-conflict-detection-algorithms.md

@@ -0,0 +1,658 @@
+# 一致性检查冲突检测算法设计
+
+> **设计目标**: 建立智能的冲突检测和解决机制
+> **创建时间**: 2025-01-20
+> **版本**: v1.0
+
+## 📋 概述
+
+为 cc-devflow 的一致性检查系统设计高效的冲突检测算法，能够自动识别文档间的冲突、需求的矛盾以及实现的偏差，并提供智能的解决建议。
+
+## 🎯 核心目标
+
+### 检测能力
+1. **语义冲突检测**: 识别表达不同但含义冲突的需求
+2. **逻辑矛盾发现**: 发现业务规则和技术约束间的矛盾
+3. **实现偏差识别**: 检测代码实现与规格说明的偏差
+4. **版本不一致性**: 发现文档间的版本同步问题
+
+### 算法特性
+- **准确性**: 减少误报，提高检测精度
+- **效率性**: 支持大规模项目的快速检查
+- **可扩展性**: 支持自定义规则和新的检测维度
+- **智能性**: 基于上下文理解进行智能判断
+
+## 🏗 算法架构
+
+### 整体框架
+```yaml
+冲突检测流水线:
+  1. 数据预处理: 文档解析和结构化
+  2. 特征提取: 关键信息识别和抽取
+  3. 冲突分析: 多维度冲突检测
+  4. 结果评分: 冲突严重程度评估
+  5. 解决建议: 智能修复方案生成
+
+算法分层:
+  语法层: 格式和结构冲突
+  语义层: 含义和逻辑冲突
+  实现层: 代码和规格冲突
+  业务层: 需求和约束冲突
+```
+
+## 🔍 核心检测算法
+
+### 1. 语义冲突检测算法
+
+#### 1.1 需求描述矛盾检测
+```python
+class RequirementConflictDetector:
+    def __init__(self):
+        self.semantic_analyzer = SemanticAnalyzer()
+        self.conflict_patterns = ConflictPatternLibrary()
+
+    def detect_semantic_conflicts(self, requirements: List[Requirement]) -> List[Conflict]:
+        """
+        检测需求间的语义冲突
+        """
+        conflicts = []
+
+        # 1. 构建语义向量空间
+        semantic_vectors = self.build_semantic_vectors(requirements)
+
+        # 2. 识别相似但矛盾的需求
+        for i, req_a in enumerate(requirements):
+            for j, req_b in enumerate(requirements[i+1:], i+1):
+                similarity = self.calculate_semantic_similarity(
+                    semantic_vectors[i], semantic_vectors[j]
+                )
+
+                # 高相似度但逻辑矛盾
+                if similarity > 0.7 and self.is_logically_contradictory(req_a, req_b):
+                    conflict = self.create_semantic_conflict(req_a, req_b, similarity)
+                    conflicts.append(conflict)
+
+        return conflicts
+
+    def is_logically_contradictory(self, req_a: Requirement, req_b: Requirement) -> bool:
+        """
+        检测两个需求是否存在逻辑矛盾
+        """
+        # 提取动作和约束
+        actions_a = self.extract_actions(req_a)
+        constraints_a = self.extract_constraints(req_a)
+
+        actions_b = self.extract_actions(req_b)
+        constraints_b = self.extract_constraints(req_b)
+
+        # 检测矛盾模式
+        contradictory_patterns = [
+            self.check_exclusive_actions(actions_a, actions_b),
+            self.check_conflicting_constraints(constraints_a, constraints_b),
+            self.check_temporal_conflicts(req_a, req_b),
+            self.check_access_control_conflicts(req_a, req_b)
+        ]
+
+        return any(contradictory_patterns)
+```
+
+#### 1.2 业务规则冲突检测
+```python
+class BusinessRuleConflictDetector:
+    def __init__(self):
+        self.rule_parser = BusinessRuleParser()
+        self.logic_engine = LogicInferenceEngine()
+
+    def detect_rule_conflicts(self, business_rules: List[BusinessRule]) -> List[RuleConflict]:
+        """
+        检测业务规则间的冲突
+        """
+        conflicts = []
+
+        # 1. 解析业务规则为逻辑表达式
+        logical_rules = [self.rule_parser.parse(rule) for rule in business_rules]
+
+        # 2. 构建规则依赖图
+        dependency_graph = self.build_rule_dependency_graph(logical_rules)
+
+        # 3. 检测循环依赖
+        cycles = self.detect_circular_dependencies(dependency_graph)
+        for cycle in cycles:
+            conflicts.append(CircularDependencyConflict(cycle))
+
+        # 4. 检测逻辑矛盾
+        for rule_set in self.generate_rule_combinations(logical_rules):
+            if not self.logic_engine.is_satisfiable(rule_set):
+                conflicts.append(LogicalContradictionConflict(rule_set))
+
+        return conflicts
+
+    def generate_rule_combinations(self, rules: List[LogicalRule]) -> Iterator[List[LogicalRule]]:
+        """
+        生成可能产生冲突的规则组合
+        """
+        # 基于规则复杂度和相关性的智能组合生成
+        for size in range(2, min(len(rules) + 1, MAX_COMBINATION_SIZE)):
+            for combination in itertools.combinations(rules, size):
+                if self.is_potentially_conflicting(combination):
+                    yield list(combination)
+```
+
+### 2. 实现偏差检测算法
+
+#### 2.1 API 规格一致性检测
+```python
+class APIConsistencyDetector:
+    def __init__(self):
+        self.spec_parser = APISpecParser()
+        self.code_analyzer = CodeAnalyzer()
+
+    def detect_api_inconsistencies(self,
+                                   api_spec: APISpecification,
+                                   implementation: CodeBase) -> List[APIInconsistency]:
+        """
+        检测 API 规格与实现的不一致
+        """
+        inconsistencies = []
+
+        # 1. 解析 API 规格
+        spec_endpoints = self.spec_parser.extract_endpoints(api_spec)
+
+        # 2. 分析实现代码
+        impl_endpoints = self.code_analyzer.extract_endpoints(implementation)
+
+        # 3. 检测各种不一致类型
+        inconsistencies.extend(self.detect_missing_endpoints(spec_endpoints, impl_endpoints))
+        inconsistencies.extend(self.detect_extra_endpoints(spec_endpoints, impl_endpoints))
+        inconsistencies.extend(self.detect_signature_mismatches(spec_endpoints, impl_endpoints))
+        inconsistencies.extend(self.detect_response_format_mismatches(spec_endpoints, impl_endpoints))
+
+        return inconsistencies
+
+    def detect_signature_mismatches(self,
+                                   spec_endpoints: List[EndpointSpec],
+                                   impl_endpoints: List[EndpointImpl]) -> List[SignatureMismatch]:
+        """
+        检测方法签名不匹配
+        """
+        mismatches = []
+
+        for spec_endpoint in spec_endpoints:
+            impl_endpoint = self.find_matching_endpoint(spec_endpoint, impl_endpoints)
+            if impl_endpoint:
+                # 检测参数不匹配
+                param_mismatches = self.compare_parameters(
+                    spec_endpoint.parameters,
+                    impl_endpoint.parameters
+                )
+
+                # 检测返回类型不匹配
+                return_mismatches = self.compare_return_types(
+                    spec_endpoint.return_type,
+                    impl_endpoint.return_type
+                )
+
+                if param_mismatches or return_mismatches:
+                    mismatch = SignatureMismatch(
+                        endpoint=spec_endpoint.path,
+                        parameter_issues=param_mismatches,
+                        return_type_issues=return_mismatches
+                    )
+                    mismatches.append(mismatch)
+
+        return mismatches
+```
+
+#### 2.2 数据模型一致性检测
+```python
+class DataModelConsistencyDetector:
+    def __init__(self):
+        self.schema_analyzer = SchemaAnalyzer()
+        self.field_matcher = FieldMatcher()
+
+    def detect_model_inconsistencies(self,
+                                    specification_models: List[DataModel],
+                                    implementation_models: List[DataModel]) -> List[ModelInconsistency]:
+        """
+        检测数据模型的不一致性
+        """
+        inconsistencies = []
+
+        # 1. 建立模型映射关系
+        model_mappings = self.establish_model_mappings(specification_models, implementation_models)
+
+        # 2. 检测各种不一致类型
+        for spec_model, impl_model in model_mappings:
+            inconsistencies.extend(self.check_field_consistency(spec_model, impl_model))
+            inconsistencies.extend(self.check_relationship_consistency(spec_model, impl_model))
+            inconsistencies.extend(self.check_constraint_consistency(spec_model, impl_model))
+            inconsistencies.extend(self.check_validation_consistency(spec_model, impl_model))
+
+        # 3. 检测孤立模型
+        inconsistencies.extend(self.detect_orphaned_models(specification_models, implementation_models))
+
+        return inconsistencies
+
+    def check_field_consistency(self, spec_model: DataModel, impl_model: DataModel) -> List[FieldInconsistency]:
+        """
+        检测字段级别的不一致性
+        """
+        inconsistencies = []
+
+        spec_fields = {field.name: field for field in spec_model.fields}
+        impl_fields = {field.name: field for field in impl_model.fields}
+
+        # 检测缺失字段
+        missing_fields = set(spec_fields.keys()) - set(impl_fields.keys())
+        for field_name in missing_fields:
+            inconsistencies.append(MissingFieldInconsistency(
+                model=spec_model.name,
+                field=field_name,
+                specification=spec_fields[field_name]
+            ))
+
+        # 检测额外字段
+        extra_fields = set(impl_fields.keys()) - set(spec_fields.keys())
+        for field_name in extra_fields:
+            inconsistencies.append(ExtraFieldInconsistency(
+                model=impl_model.name,
+                field=field_name,
+                implementation=impl_fields[field_name]
+            ))
+
+        # 检测字段类型不匹配
+        common_fields = set(spec_fields.keys()) & set(impl_fields.keys())
+        for field_name in common_fields:
+            spec_field = spec_fields[field_name]
+            impl_field = impl_fields[field_name]
+
+            if not self.are_types_compatible(spec_field.type, impl_field.type):
+                inconsistencies.append(FieldTypeMismatchInconsistency(
+                    model=spec_model.name,
+                    field=field_name,
+                    spec_type=spec_field.type,
+                    impl_type=impl_field.type
+                ))
+
+        return inconsistencies
+```
+
+### 3. 版本不一致性检测算法
+
+#### 3.1 文档版本同步检测
+```python
+class DocumentVersionConsistencyDetector:
+    def __init__(self):
+        self.version_extractor = VersionExtractor()
+        self.dependency_analyzer = DocumentDependencyAnalyzer()
+
+    def detect_version_inconsistencies(self, documents: List[Document]) -> List[VersionInconsistency]:
+        """
+        检测文档间的版本不一致性
+        """
+        inconsistencies = []
+
+        # 1. 提取所有文档的版本信息
+        document_versions = self.extract_all_versions(documents)
+
+        # 2. 构建文档依赖关系图
+        dependency_graph = self.dependency_analyzer.build_dependency_graph(documents)
+
+        # 3. 检测版本不兼容
+        for doc_a, doc_b in dependency_graph.edges():
+            version_a = document_versions[doc_a.id]
+            version_b = document_versions[doc_b.id]
+
+            if not self.are_versions_compatible(version_a, version_b, dependency_graph.get_edge_data(doc_a, doc_b)):
+                inconsistency = VersionIncompatibilityInconsistency(
+                    source_document=doc_a,
+                    target_document=doc_b,
+                    source_version=version_a,
+                    target_version=version_b,
+                    dependency_type=dependency_graph.get_edge_data(doc_a, doc_b)['type']
+                )
+                inconsistencies.append(inconsistency)
+
+        return inconsistencies
+
+    def are_versions_compatible(self, version_a: Version, version_b: Version, dependency_info: Dict) -> bool:
+        """
+        检查两个版本是否兼容
+        """
+        dependency_type = dependency_info.get('type', 'reference')
+
+        if dependency_type == 'strict_dependency':
+            # 严格依赖要求精确版本匹配
+            return version_a == version_b
+        elif dependency_type == 'compatible_dependency':
+            # 兼容依赖允许向后兼容的版本
+            return version_a.is_compatible_with(version_b)
+        else:
+            # 一般引用允许较大的版本差异
+            return version_a.major == version_b.major
+```
+
+### 4. 智能冲突解决算法
+
+#### 4.1 冲突优先级评估
+```python
+class ConflictPriorityEvaluator:
+    def __init__(self):
+        self.impact_analyzer = ImpactAnalyzer()
+        self.complexity_evaluator = ComplexityEvaluator()
+
+    def evaluate_conflict_priority(self, conflict: Conflict) -> ConflictPriority:
+        """
+        评估冲突的解决优先级
+        """
+        # 1. 影响分析
+        business_impact = self.impact_analyzer.assess_business_impact(conflict)
+        technical_impact = self.impact_analyzer.assess_technical_impact(conflict)
+        user_impact = self.impact_analyzer.assess_user_impact(conflict)
+
+        # 2. 复杂度评估
+        resolution_complexity = self.complexity_evaluator.assess_resolution_complexity(conflict)
+
+        # 3. 风险评估
+        risk_level = self.assess_risk_level(conflict)
+
+        # 4. 计算综合优先级分数
+        priority_score = self.calculate_priority_score(
+            business_impact=business_impact,
+            technical_impact=technical_impact,
+            user_impact=user_impact,
+            resolution_complexity=resolution_complexity,
+            risk_level=risk_level
+        )
+
+        return ConflictPriority(
+            score=priority_score,
+            level=self.score_to_level(priority_score),
+            rationale=self.generate_priority_rationale(conflict, priority_score)
+        )
+
+    def calculate_priority_score(self, **factors) -> float:
+        """
+        基于多个因素计算优先级分数
+        """
+        weights = {
+            'business_impact': 0.3,
+            'technical_impact': 0.25,
+            'user_impact': 0.2,
+            'resolution_complexity': -0.15,  # 复杂度越高，优先级越低
+            'risk_level': 0.2
+        }
+
+        weighted_score = sum(
+            factors[factor] * weight
+            for factor, weight in weights.items()
+            if factor in factors
+        )
+
+        return min(max(weighted_score, 0.0), 1.0)  # 归一化到 [0, 1]
+```
+
+#### 4.2 自动解决方案生成
+```python
+class AutoResolutionGenerator:
+    def __init__(self):
+        self.resolution_strategies = ResolutionStrategyLibrary()
+        self.feasibility_checker = FeasibilityChecker()
+
+    def generate_resolution_options(self, conflict: Conflict) -> List[ResolutionOption]:
+        """
+        为冲突生成可能的解决方案
+        """
+        options = []
+
+        # 1. 基于冲突类型获取候选策略
+        candidate_strategies = self.resolution_strategies.get_strategies_for_conflict_type(conflict.type)
+
+        # 2. 为每个策略生成具体的解决方案
+        for strategy in candidate_strategies:
+            resolution_option = self.generate_resolution_from_strategy(conflict, strategy)
+
+            # 3. 评估可行性
+            feasibility = self.feasibility_checker.assess_feasibility(resolution_option)
+
+            if feasibility.is_feasible:
+                resolution_option.feasibility = feasibility
+                options.append(resolution_option)
+
+        # 4. 按预期效果排序
+        options.sort(key=lambda opt: opt.expected_effectiveness, reverse=True)
+
+        return options
+
+    def generate_resolution_from_strategy(self, conflict: Conflict, strategy: ResolutionStrategy) -> ResolutionOption:
+        """
+        基于策略生成具体的解决方案
+        """
+        if strategy.type == "merge_conflicting_requirements":
+            return self.generate_merge_solution(conflict, strategy)
+        elif strategy.type == "prioritize_and_exclude":
+            return self.generate_prioritization_solution(conflict, strategy)
+        elif strategy.type == "introduce_conditional_logic":
+            return self.generate_conditional_solution(conflict, strategy)
+        elif strategy.type == "refactor_architecture":
+            return self.generate_refactoring_solution(conflict, strategy)
+        else:
+            return self.generate_generic_solution(conflict, strategy)
+```
+
+## 📊 算法性能优化
+
+### 1. 并行处理优化
+```python
+class ParallelConflictDetector:
+    def __init__(self, max_workers: int = None):
+        self.max_workers = max_workers or cpu_count()
+        self.executor = ThreadPoolExecutor(max_workers=self.max_workers)
+
+    def detect_conflicts_parallel(self, documents: List[Document]) -> List[Conflict]:
+        """
+        并行执行冲突检测
+        """
+        # 1. 将文档分组以减少内存使用
+        document_groups = self.partition_documents(documents)
+
+        # 2. 并行检测每组内的冲突
+        intra_group_futures = [
+            self.executor.submit(self.detect_intra_group_conflicts, group)
+            for group in document_groups
+        ]
+
+        # 3. 并行检测组间冲突
+        inter_group_futures = [
+            self.executor.submit(self.detect_inter_group_conflicts, group_a, group_b)
+            for group_a, group_b in itertools.combinations(document_groups, 2)
+        ]
+
+        # 4. 收集结果
+        all_conflicts = []
+        for future in concurrent.futures.as_completed(intra_group_futures + inter_group_futures):
+            all_conflicts.extend(future.result())
+
+        return all_conflicts
+```
+
+### 2. 缓存和增量检测
+```python
+class IncrementalConflictDetector:
+    def __init__(self):
+        self.cache = ConflictDetectionCache()
+        self.change_tracker = DocumentChangeTracker()
+
+    def detect_conflicts_incremental(self,
+                                   documents: List[Document],
+                                   last_check_timestamp: datetime) -> List[Conflict]:
+        """
+        增量冲突检测
+        """
+        # 1. 识别自上次检查以来的变更
+        changed_documents = self.change_tracker.get_changed_documents(last_check_timestamp)
+
+        # 2. 从缓存中获取未变更文档的检测结果
+        cached_conflicts = self.cache.get_conflicts_for_unchanged_documents(
+            set(documents) - set(changed_documents)
+        )
+
+        # 3. 只对变更的文档及其依赖文档进行重新检测
+        affected_documents = self.get_affected_documents(changed_documents, documents)
+        new_conflicts = self.detect_conflicts_for_documents(affected_documents)
+
+        # 4. 更新缓存
+        self.cache.update_conflicts(affected_documents, new_conflicts)
+
+        return cached_conflicts + new_conflicts
+```
+
+## 🎯 质量保证
+
+### 算法测试框架
+```python
+class ConflictDetectionTestSuite:
+    def __init__(self):
+        self.test_data_generator = TestDataGenerator()
+        self.ground_truth_validator = GroundTruthValidator()
+
+    def run_comprehensive_tests(self):
+        """
+        运行全面的算法测试
+        """
+        test_results = TestResults()
+
+        # 1. 准确性测试
+        accuracy_results = self.test_detection_accuracy()
+        test_results.add_accuracy_results(accuracy_results)
+
+        # 2. 性能测试
+        performance_results = self.test_performance()
+        test_results.add_performance_results(performance_results)
+
+        # 3. 鲁棒性测试
+        robustness_results = self.test_robustness()
+        test_results.add_robustness_results(robustness_results)
+
+        # 4. 可扩展性测试
+        scalability_results = self.test_scalability()
+        test_results.add_scalability_results(scalability_results)
+
+        return test_results
+
+    def test_detection_accuracy(self) -> AccuracyResults:
+        """
+        测试检测精度
+        """
+        # 生成包含已知冲突的测试数据
+        test_datasets = self.test_data_generator.generate_conflict_datasets()
+
+        accuracy_metrics = []
+        for dataset in test_datasets:
+            detected_conflicts = self.detector.detect_conflicts(dataset.documents)
+
+            # 计算精确率、召回率和F1分数
+            precision = self.calculate_precision(detected_conflicts, dataset.ground_truth)
+            recall = self.calculate_recall(detected_conflicts, dataset.ground_truth)
+            f1_score = 2 * (precision * recall) / (precision + recall) if (precision + recall) > 0 else 0
+
+            accuracy_metrics.append(AccuracyMetric(
+                dataset_name=dataset.name,
+                precision=precision,
+                recall=recall,
+                f1_score=f1_score
+            ))
+
+        return AccuracyResults(accuracy_metrics)
+```
+
+## 📚 配置和扩展
+
+### 自定义冲突检测规则
+```yaml
+# .claude/conflict-detection-rules.yml
+conflict_detection_rules:
+  semantic_conflicts:
+    similarity_threshold: 0.7
+    contradiction_patterns:
+      - exclusive_actions: ["create", "delete"]
+      - temporal_conflicts: ["before", "after"]
+      - access_conflicts: ["public", "private"]
+
+  business_rule_conflicts:
+    max_combination_size: 5
+    logic_timeout: 30  # seconds
+    cyclic_dependency_detection: true
+
+  implementation_consistency:
+    api_signature_strictness: "strict"  # strict|moderate|relaxed
+    data_model_validation: true
+    version_compatibility_check: true
+
+  custom_patterns:
+    domain_specific_rules:
+      - name: "financial_compliance"
+        pattern: "audit_trail_required"
+        conflict_with: ["data_anonymization"]
+      - name: "security_requirements"
+        pattern: "encryption_required"
+        conflict_with: ["performance_optimization"]
+```
+
+### 插件扩展接口
+```python
+class ConflictDetectionPlugin:
+    """
+    冲突检测插件基类
+    """
+    def __init__(self, name: str):
+        self.name = name
+
+    def detect_conflicts(self, context: DetectionContext) -> List[Conflict]:
+        """
+        插件的冲突检测入口点
+        """
+        raise NotImplementedError
+
+    def get_supported_conflict_types(self) -> List[str]:
+        """
+        返回插件支持的冲突类型
+        """
+        raise NotImplementedError
+
+    def configure(self, config: Dict[str, Any]) -> None:
+        """
+        配置插件参数
+        """
+        pass
+
+# 示例：领域特定的冲突检测插件
+class FinancialComplianceConflictDetector(ConflictDetectionPlugin):
+    def __init__(self):
+        super().__init__("financial_compliance")
+
+    def detect_conflicts(self, context: DetectionContext) -> List[Conflict]:
+        conflicts = []
+
+        # 检测财务合规相关的冲突
+        audit_requirements = self.extract_audit_requirements(context.documents)
+        privacy_requirements = self.extract_privacy_requirements(context.documents)
+
+        for audit_req in audit_requirements:
+            for privacy_req in privacy_requirements:
+                if self.are_conflicting_compliance_requirements(audit_req, privacy_req):
+                    conflict = ComplianceConflict(
+                        type="audit_privacy_conflict",
+                        description=f"Audit requirement conflicts with privacy requirement",
+                        audit_requirement=audit_req,
+                        privacy_requirement=privacy_req,
+                        severity="high"
+                    )
+                    conflicts.append(conflict)
+
+        return conflicts
+```
+
+---
+
+**总结**: 这套冲突检测算法为 cc-devflow 提供了企业级的一致性保证能力，通过多层次、多维度的智能检测，确保从需求到实现的全链路质量，支持大规模项目的高效开发和维护。