Yasin

## 目标
对完整仓库进行全面分析，以识别、优先排序、修复并记录所有可验证的缺陷、安全漏洞以及跨任何编程语言、框架或技术栈的关键问题。

## 阶段 1：初始仓库评估

### 1.1 架构映射
- 映射完整项目结构（src/、lib/、tests/、docs/、config/、scripts/ 等）
- 识别技术栈和依赖（package.json、requirements.txt、go.mod、pom.xml、Gemfile 等）
- 记录主要入口点、关键路径和系统边界
- 分析构建配置和 CI/CD 流水线
- 审查现有文档（README、API 文档、架构图）

### 1.2 开发环境分析
- 识别测试框架（Jest、pytest、PHPUnit、Go test、JUnit、RSpec 等）
- 审查 linting/格式化配置（ESLint、Prettier、Black、RuboCop 等）
- 检查现有问题跟踪（GitHub Issues、TODO/FIXME/HACK/XXX 注释）
- 分析提交历史以查找近期问题区域
- 审查现有测试覆盖率报告（如可用）

## 阶段 2：系统性缺陷发现

### 2.1 需识别的缺陷类别
**关键缺陷：**
- 安全漏洞（SQL 注入、XSS、CSRF、认证绕过等）
- 数据损坏或丢失风险
- 系统崩溃或死锁
- 内存泄漏或资源耗尽

**功能缺陷：**
- 逻辑错误（错误条件、错误计算、差一错误）
- 状态管理问题（竞态条件、状态不一致、不当变更）
- 错误的 API 契约或数据映射
- 缺失或不正确的验证
- 损坏的业务规则或工作流

**集成缺陷：**
- 错误的外部 API 使用
- 数据库查询错误或低效
- 消息队列处理问题
- 文件系统操作问题
- 网络通信错误

**边缘情况与错误处理：**
- Null/undefined/nil 处理
- 空集合或零值边缘情况
- 边界条件和限制违反
- 缺失错误传播或吞没异常
- 超时和重试逻辑问题

**代码质量问题：**
- 类型不匹配或不安全转换
- 已弃用 API 使用
- 死代码或不可达分支
- 循环依赖
- 性能瓶颈（N+1 查询、低效算法）

### 2.2 发现方法
- 使用语言特定工具进行静态代码分析
- 针对常见反模式的模式匹配
- 依赖漏洞扫描
- 对不可达或未测试代码的代码路径分析
- 配置验证
- 文档与实现的交叉引用

## 阶段 3：缺陷记录与优先级排序

### 3.1 缺陷报告模板
对于每个识别出的缺陷，记录：
```
BUG-ID: [顺序标识符]
严重性: [CRITICAL | HIGH | MEDIUM | LOW]
类别: [Security | Functional | Performance | Integration | Code Quality]
文件: [完整文件路径和行号]
组件: [受影响的模块/服务/功能]

描述:
- 当前行为（哪里错了）
- 预期行为（应该发生什么）
- 根本原因分析

影响评估:
- 用户影响（UX 降级、数据丢失、安全暴露）
- 系统影响（性能、稳定性、可扩展性）
- 业务影响（合规性、收入、声誉）

复现步骤:
1. [分步说明]
2. [如有需要，包含测试数据/条件]
3. [预期与实际结果]

验证方法:
- [演示缺陷的代码片段或测试]
- [显示问题的指标或日志]

依赖关系:
- 相关缺陷: [相关 BUG-ID 列表]
- 阻塞问题: [需要先修复什么]
```

### 3.2 优先级矩阵
使用以下标准对缺陷进行排序：
- **严重性**：Critical > High > Medium > Low
- **用户影响**：受影响用户/功能的数量
- **修复复杂度**：简单 < 中等 < 复杂
- **回归风险**：低 < 中 < 高

## 阶段 4：修复实施

### 4.1 修复策略
**对于每个缺陷：**
1. 创建隔离的修复分支（如果使用版本控制）
2. 首先编写失败的测试（TDD 方法）
3. 实施最小、聚焦的修复
4. 验证测试通过
5. 运行回归测试
6. 如有需要更新文档

### 4.2 修复指南
- **最小变更原则**：做出正确修复问题的最小变更
- **无范围蔓延**：避免无关的重构或改进
- **保持向后兼容性**：除非缺陷本身是破坏性 API
- **遵循项目标准**：使用现有代码风格和模式
- **添加防御性编程**：防止未来出现类似缺陷

### 4.3 代码审查清单
- [ ] 修复解决根本原因，而不仅仅是症状
- [ ] 所有边缘情况都已处理
- [ ] 错误消息清晰且可操作
- [ ] 性能影响可接受
- [ ] 考虑了安全影响
- [ ] 未引入新的警告或 linting 错误

## 阶段 5：测试与验证

### 5.1 测试要求
**对于每个修复的缺陷，提供：**
1. **单元测试**：针对特定修复的隔离测试
2. **集成测试**：如果缺陷涉及多个组件
3. **回归测试**：确保修复不会破坏现有功能
4. **边缘情况测试**：覆盖相关边界条件

### 5.2 测试结构
```[语言特定]
describe('BUG-[ID]: [缺陷描述]', () => {
  test('should fail with original bug', () => {
    // 此测试在修复前会失败
    // 演示缺陷
  });
  
  test('should pass after fix', () => {
    // 此测试在修复后通过
    // 验证正确行为
  });
  
  test('should handle edge cases', () => {
    // 额外的边缘情况覆盖
  });
});
```

### 5.3 验证步骤
1. 运行完整测试套件：`[npm test | pytest | go test ./... | mvn test | 等]`
2. 检查代码覆盖率变化
3. 运行静态分析工具
4. 验证性能基准（如适用）
5. 在不同环境中测试（如可能）

## 阶段 6：文档与报告

### 6.1 修复文档
对于每个修复的缺陷：
- 更新解释修复的内联代码注释
- 如果行为改变，添加/更新 API 文档
- 创建/更新故障排除指南
- 记录未修复问题的任何变通方法

### 6.2 执行摘要报告
```markdown
# 缺陷修复报告 - [仓库名称]
日期: [YYYY-MM-DD]
分析者: [工具/人员名称]

## 概述
- 发现缺陷总数: [X]
- 修复缺陷总数: [Y]
- 未修复/推迟: [Z]
- 测试覆盖率变化: [之前]% → [之后]%

## 关键发现
[列出发现并修复的前 3-5 个最关键缺陷]

## 按类别修复摘要
- 安全: [修复 X 个缺陷]
- 功能: [修复 Y 个缺陷]
- 性能: [修复 Z 个缺陷]
- 集成: [修复 W 个缺陷]
- 代码质量: [修复 V 个缺陷]

## 详细修复列表
[组织表格，列：BUG-ID | 文件 | 描述 | 状态 | 添加的测试]

## 风险评估
- 剩余高优先级问题: [列表]
- 建议的后续步骤: [行动]
- 识别的技术债务: [摘要]

## 测试结果
- 测试命令: [使用的确切命令]
- 通过的测试: [X/Y]
- 新增测试: [数量]
- 覆盖率提升act: [详情]
```

### 6.3 交付物清单
- [ ] 所有缺陷以标准格式记录
- [ ] 修复已实施并测试
- [ ] 测试套件已更新并通过
- [ ] 文档已更新
- [ ] 代码审查已完成
- [ ] 性能影响已评估
- [ ] 安全审查已进行（针对安全相关修复）
- [ ] 部署说明已准备

## 阶段 7：持续改进

### 7.1 模式分析
- 识别常见缺陷模式
- 建议预防措施
- 推荐工具改进
- 提出架构变更以防止类似问题

### 7.2 监控建议
- 建议跟踪的指标
- 推荐告警规则
- 提出日志改进
- 识别需要更好测试覆盖的领域

## 约束与最佳实践

1. **绝不为了简单而牺牲安全**
2. **维护所有变更的审计跟踪**
3. **如果修复更改 API，遵循语义化版本控制**
4. **测试外部服务时遵守速率限制**
5. **对高风险修复使用功能标志（如适用）**
6. **为每个修复考虑回滚策略**
7. **记录分析过程中所做的假设**

## 输出格式
以两种形式提供结果：
- Markdown 供人类阅读
- JSON/YAML 供自动处理
- CSV 供缺陷跟踪系统导入

## 特殊考虑
- 对于 monorepo：分别分析每个包
- 对于微服务：考虑服务间依赖
- 对于遗留代码：平衡修复风险与收益
- 对于第三方依赖：如有需要，向上游报告