# 文件管理模块架构升级方案

## 📋 目录
- [现状分析](#现状分析)
- [架构目标](#架构目标)
- [核心设计](#核心设计)
- [模块划分](#模块划分)
- [实施路线图](#实施路线图)

---

## 🔍 现状分析

### 当前问题
1. **全局变量泛滥**：4个全局单例（auditLogger, recycleBin, lockChecker, fileServer）
2. **代码重复严重**：路径验证、文件类型检查、错误处理模式重复
3. **魔法数字遍布**：至少15处硬编码常量
4. **过度防御性**：删除操作有3层硬限制
5. **性能隐患**：重复目录遍历、随机字符串生成低效
6. **可测试性差**：依赖全局状态，难以编写单元测试

### 技术债务评估
| 类别 | 债务量 | 优先级 | 影响范围 |
|------|--------|--------|----------|
| 重复代码 | 高 | P1 | 可维护性 |
| 性能问题 | 高 | P0 | 用户体验 |
| 架构问题 | 高 | P1 | 可扩展性 |
| 代码风格 | 中 | P2 | 可读性 |

---

## 🎯 架构目标

### 设计原则
1. **单一职责**：每个模块只负责一个功能领域
2. **依赖倒置**：面向接口编程，降低耦合
3. **开放封闭**：对扩展开放，对修改封闭
4. **配置驱动**：安全策略可配置，不硬编码

### 质量目标
- ✅ 零代码重复（DRY原则）
- ✅ 零全局变量（依赖注入）
- ✅ 零魔法数字（命名常量）
- ✅ 零性能隐患（优化热点）
- ✅ 100% 可测试（支持mock）

---

## 🏗️ 核心设计

### 1. 分层架构

```
┌─────────────────────────────────────────┐
│         Application Layer (app.go)       │
│     - 对外接口（Bindings）                │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│      Service Layer (FileSystemService)   │
│     - 编排业务逻辑                         │
│     - 事务管理                            │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│         Component Layer                  │
│  ┌────────────┬────────────┬──────────┐ │
│  │Validator   │Manager     │Handler   │ │
│  │路径验证     │文件管理     │文件服务   │ │
│  └────────────┴────────────┴──────────┘ │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│         Infrastructure Layer             │
│  ┌──────────┬──────────┬──────────────┐ │
│  │Audit     │Recycle   │Lock          │ │
│  │审计日志    │回收站     │文件锁         │ │
│  └──────────┴──────────┴──────────────┘ │
└──────────────────────────────────────────┘
```

### 2. 核心接口设计

```go
// FileService 文件操作核心接口
type FileService interface {
    Read(path string) (string, error)
    Write(path, content string) error
    Delete(path string) error
    List(path string) ([]FileInfo, error)
    Create(path string, isDir bool) error
    Move(src, dst string) error
    GetInfo(path string) (*FileInfo, error)
}

// PathValidator 路径验证接口
type PathValidator interface {
    Validate(path string) *ValidationError
    IsSafe(path string) bool
    IsSensitive(path string) bool
}

// FileTypeManager 文件类型管理接口
type FileTypeManager interface {
    GetMIMEType(ext string) string
    IsAllowed(ext string) bool
    GetMaxSize(ext string) int64
}

// SecurityGuard 安全策略接口
type SecurityGuard interface {
    CheckDelete(path string) error
    CheckAccess(path string) error
}
```

### 3. 配置驱动设计

```go
// Config 文件系统配置
type Config struct {
    // 安全配置
    Security SecurityConfig
    // 性能配置
    Performance PerformanceConfig
    // 功能开关
    Features FeatureConfig
}

// SecurityConfig 安全策略配置
type SecurityConfig struct {
    // 路径验证
    PathValidation PathValidationConfig
    // 删除限制
    DeleteRestrictions DeleteRestrictionsConfig
    // 文件类型
    FileTypes FileTypeConfig
}

// DeleteRestrictionsConfig 删除限制配置
type DeleteRestrictionsConfig struct {
    Enabled          bool    // 是否启用限制
    MaxSizeGB        float64 // 最大文件大小（GB）
    MaxDepth         int     // 最大目录深度
    MaxFileCount     int     // 最大文件数量
    RequireConfirm   bool    // 超过限制是否需要确认
    ForbiddenPaths   []string // 禁止删除的路径
}
```

---

## 📦 模块划分

### 模块1: 核心文件操作 (fs_core)
```
fs_core/
├── service.go          # FileService 实现
├── file_info.go        # FileInfo 结构
└── errors.go           # 错误定义
```

### 模块2: 路径验证 (validator)
```
validator/
├── path_validator.go   # PathValidator 接口和实现
├── config.go           # 验证配置
└── errors.go           # 验证错误
```

### 模块3: 文件类型管理 (filetype)
```
filetype/
├── manager.go          # FileTypeManager 实现
├── types.go            # 文件类型配置
└── mime.go             # MIME 类型映射
```

### 模块4: 基础设施 (infra)
```
infra/
├── audit/
│   └── logger.go       # 审计日志
├── recycle/
│   └── bin.go          # 回收站
├── lock/
│   └── checker.go      # 文件锁检查
└── server/
    └── handler.go      # HTTP 文件服务
```

### 模块5: ZIP 操作 (zip)
```
zip/
├── reader.go           # ZIP 读取
├── writer.go           # ZIP 写入
├── security.go         # ZIP 安全检查
└── temp.go             # 临时文件管理
```

### 模块6: 配置管理 (config)
```
config/
├── constants.go        # 常量定义
├── config.go           # 配置结构
└── defaults.go         # 默认配置
```

---

## 🗺️ 实施路线图

### 阶段1: 紧急修复（P0）- 1天
**目标**: 修复严重性能和稳定性问题

- [x] 任务1: 修复 `generateRandomString` 的 `time.Sleep`
- [x] 任务2: 修复文件锁检查的破坏性 rename

**影响**: 立即提升性能和稳定性

---

### 阶段2: 基础建设（P1）- 2天
**目标**: 统一配置和常量，消除技术债务

- [x] 任务3: 创建 constants.go，定义所有命名常量
- [x] 任务4: 创建 config.go，统一配置管理
- [x] 任务5: 定义核心接口（FileService, PathValidator, FileTypeManager）

**影响**: 提升代码质量，为重构打基础

---

### 阶段3: DRY重构（P1）- 3天
**目标**: 消除代码重复，提升可维护性

- [x] 任务6: 重构路径验证逻辑（PathValidator）
- [x] 任务7: 重构文件类型管理（FileTypeManager）
- [x] 任务8: 重构 ZIP 操作（withZipReader）

**影响**: 减少30%+代码量，提升可维护性

---

### 阶段4: 安全优化（P1）- 2天
**目标**: 优化过度防御，改善用户体验

- [x] 任务9: 重构 DeletePath 安全检查
- [x] 任务10: 配置化安全策略

**影响**: 提升用户体验，保留安全性

---

### 阶段5: 架构升级（P1）- 3天
**目标**: 引入依赖注入，消除全局变量

- [x] 任务11: 创建 FileSystemService
- [x] 任务12: 重构各组件为独立模块
- [x] 任务13: 消除全局变量

**影响**: 提升可测试性和可扩展性

---

### 阶段6: 代码质量（P2）- 2天
**目标**: 统一代码风格，完善文档

- [x] 任务14: 统一错误处理
- [x] 任务15: 添加结构化日志
- [x] 任务16: 统一注释风格
- [x] 任务17: 编写单元测试

**影响**: 提升代码可读性和可维护性

---

### 阶段7: 测试验证（P2）- 2天
**目标**: 确保重构质量，回归测试

- [x] 任务18: 编写集成测试
- [x] 任务19: 性能基准测试
- [x] 任务20: 安全测试

**影响**: 确保重构质量，无回归问题

---

## 📊 预期收益

### 代码质量
- **代码量**: 预计减少 30-40%
- **重复率**: 从 25% 降至 < 5%
- **圈复杂度**: 平均降低 40%

### 性能提升
- **删除操作**: 性能提升 60%（消除重复遍历）
- **回收站**: 性能提升 99%（修复 time.Sleep）
- **文件锁**: 安全性提升 100%（消除破坏性操作）

### 可维护性
- **测试覆盖率**: 从 0% 提升至 80%+
- **可测试性**: 从困难变为简单（依赖注入）
- **扩展性**: 新增功能无需修改核心代码

---

## 🔧 技术选型

### 依赖注入
- 考虑 Uber Fx 或 Google Wire
- 或者手动 DI（更简单，适合当前规模）

### 配置管理
- 使用结构体配置
- 支持 JSON/YAML 导入导出
- 环境变量覆盖

### 日志
- 结构化日志（logrus 或 zap）
- 可配置日志级别
- 支持日志轮转

### 测试
- 单元测试：testify/assert
- Mock：gomock
- 基准测试：内置 testing/benchmark

---

## 📝 注意事项

### 兼容性
- 保持对外接口（app.go 的方法）不变
- 内部重构对前端透明

### 渐进式重构
- 不重写，只重构
- 一次只改一个模块
- 每次重构后运行测试

### 回滚计划
- 使用 Git 分支管理
- 每个阶段完成后打 tag
- 出现问题可快速回滚

---

## 🎯 成功标准

### 功能完整性
- ✅ 所有现有功能正常工作
- ✅ 无新增 bug
- ✅ 性能不下降

### 代码质量
- ✅ 代码重复率 < 5%
- ✅ 测试覆盖率 > 80%
- ✅ 代码审查通过

### 文档完整性
- ✅ 架构文档完整
- ✅ API 文档完整
- ✅ 配置文档完整

---

*文档版本: 1.0*
*创建日期: 2026-01-27*
*作者: Claude Code*
