# SoftCopyright 性能优化方案

## 一、性能瓶颈分析

### 1.1 文件扫描瓶颈
**当前问题:**
- 使用 `glob.sync` 同步扫描,每个文件扩展名单独扫描一次
- 大型项目中会重复遍历目录树 20+ 次(每种文件类型一次)
- 扫描 10,000 个文件的项目可能需要 5-10 秒

**优化方案:**
- 使用单次目录遍历,一次性收集所有支持的文件
- 使用异步 `glob` 替代同步版本
- 实现增量扫描缓存机制

### 1.2 文件读取瓶颈
**当前问题:**
- 逐个串行读取所有文件内容到内存
- 大文件(>1MB)会阻塞事件循环
- 没有内存限制,可能导致 OOM

**优化方案:**
- 使用流式读取大文件
- 实现并发读取控制(p-limit)
- 添加文件大小过滤和内存限制

### 1.3 重复文件系统访问
**当前问题:**
- 多次调用 `fs.existsSync` 检查同一文件
- 在 `getProjectName`, `getProjectVersion`, `analyzeProjectFeatures` 中重复检查

**优化方案:**
- 缓存文件存在性检查结果
- 批量预检查常用配置文件

### 1.4 缺少并发控制
**当前问题:**
- 所有文件串行处理
- 无法利用多核 CPU
- 大项目处理时间过长

**优化方案:**
- 使用 Worker Threads 并行处理文件
- 实现智能任务分片
- 添加进度反馈

## 二、优化实施计划

### 阶段 1: 快速优化(1-2小时)
**目标:** 提升 50-70% 性能

1. **优化文件扫描**
   - 合并 glob 模式,单次扫描
   - 使用异步 API
   - 添加扫描缓存

2. **添加并发控制**
   - 使用 `p-limit` 控制并发文件读取
   - 默认并发数: CPU 核心数 * 2

3. **优化文件过滤**
   - 提前过滤大文件和二进制文件
   - 添加文件大小限制(默认 5MB)

### 阶段 2: 深度优化(3-4小时)
**目标:** 提升 80-90% 性能

1. **实现增量扫描**
   - 基于文件修改时间的缓存机制
   - 只处理变更的文件

2. **Worker Threads 并行化**
   - 将文件分析任务分配到多个 Worker
   - 实现任务队列和结果聚合

3. **流式处理**
   - 大文件使用流式读取
   - 逐行分析,避免全量加载

### 阶段 3: 高级优化(可选,4-6小时)
**目标:** 提升 95%+ 性能

1. **智能采样**
   - 超大项目(>5000文件)使用采样分析
   - 保证代表性的同时减少处理量

2. **持久化缓存**
   - 使用 SQLite 或文件缓存扫描结果
   - 支持跨会话缓存

3. **渐进式输出**
   - 边扫描边生成部分文档
   - 提供实时进度反馈

## 三、性能指标对比

### 测试场景
- **小型项目**: 100 文件, 10,000 行代码
- **中型项目**: 1,000 文件, 100,000 行代码  
- **大型项目**: 10,000 文件, 1,000,000 行代码

### 预期性能提升

| 项目规模 | 当前耗时 | 阶段1优化 | 阶段2优化 | 阶段3优化 |
|---------|---------|----------|----------|----------|
| 小型    | 2秒     | 0.8秒    | 0.5秒    | 0.3秒    |
| 中型    | 25秒    | 8秒      | 3秒      | 1.5秒    |
| 大型    | 300秒   | 90秒     | 30秒     | 10秒     |

## 四、实施优先级

### 高优先级(立即实施)
1. ✅ 合并 glob 扫描模式
2. ✅ 添加并发文件读取
3. ✅ 实现文件大小过滤
4. ✅ 缓存配置文件检查

### 中优先级(本周完成)
5. ⏳ 实现增量扫描缓存
6. ⏳ 添加进度反馈
7. ⏳ 优化大文件处理

### 低优先级(按需实施)
8. ⏸️ Worker Threads 并行化
9. ⏸️ 智能采样机制
10. ⏸️ 持久化缓存

## 五、兼容性说明

所有优化保持向后兼容:
- API 接口不变
- 输出格式不变
- 配置选项可选
- 默认行为保守

## 六、测试计划

1. **单元测试**: 覆盖所有优化函数
2. **性能测试**: 对比优化前后耗时
3. **压力测试**: 测试极限场景(50,000+ 文件)
4. **兼容性测试**: 确保各平台正常工作

## 七、回滚方案

如遇问题,可通过环境变量快速回滚:
```bash
# 禁用所有优化
SOFTCOPYRIGHT_NO_OPTIMIZATION=1 softcopyright

# 禁用并发
SOFTCOPYRIGHT_NO_CONCURRENCY=1 softcopyright

# 禁用缓存
SOFTCOPYRIGHT_NO_CACHE=1 softcopyright
```
