disk-space-analyzer 0.1.0
一个功能强大的磁盘空间分析和管理工具，提供直观的可视化界面、安全的删除机制和灵活的分析选项
License: MIT
Requires Python: >=3.8
Keywords: disk, analyzer, space, filesystem, web, visualization

# 磁盘空间分析工具

一个功能强大的磁盘空间分析和管理工具，提供直观的可视化界面、安全的删除机制和灵活的分析选项。

## 功能特性

### 核心功能

#### 1. 磁盘信息可视化
- ✅ 物理分区自动去重识别
- ✅ 本地磁盘与远程挂载分类显示
- ✅ 点击分区卡片查看交互式目录树
- ✅ 实时容量和使用率监控

#### 2. 目录分析
- ✅ 可配置分析深度（1-5层）
- ✅ 灰活的排除规则（路径、扩展名）
- ✅ 实新进度显示
- ✅ 表格视图和树形视图双模式
- ✅ **表格视图多级树形展开**（最新）
- ✅ **中文路径支持**（最新）

#### 3. 安全删除
- ✅ **双重验证机制**（最新功能）
  - 路径手动输入验证（禁止粘贴）
  - 随机验证码验证（加减法运算）
- ✅ 系统关键目录保护
- ✅ 删除前详细信息确认
- ✅ 操作不可逆警告

#### 4. UI优化（进行中）
- 🔨 侧边栏布局（CSS已完成）
- ⏳ 磁盘卡片显示模式切换（Mini/横条/完整）
- ⏳ 分析结果视觉增强
- ⏳ 响应式设计

## 快速开始

### 方式1：通过 pip 安装（推荐）

#### 从本地源码安装

```bash
# 克隆仓库（如果还没有）
git clone https://github.com/username/disk_analyzer.git
cd disk_analyzer

# 常规安装
pip install .

# 或者开发模式安装（代码修改实时生效）
pip install -e .

# 安装开发依赖
pip install -e .[dev]
```

#### 从 PyPI 安装（未来可用）

```bash
pip install disk-analyzer
```

### 方式2：手动安装依赖

```bash
pip install -r requirements.txt
```

### 启动应用

#### 使用命令行工具（pip 安装后）

```bash
# 标准启动
disk-analyzer

# 调试模式
disk-analyzer --debug

# 自定义端口
disk-analyzer --port 9090

# 不自动打开浏览器
disk-analyzer --no-browser

# 查看版本
disk-analyzer --version
```

#### 使用 Python 模块运行

```bash
python -m disk_analyzer
python -m disk_analyzer --debug
```

#### 使用传统脚本（向后兼容）

```bash
# 标准模式
python start_disk_tool.py

# 调试模式（支持热更新）
python start_disk_tool.py --debug
```

#### 作为 Python 库使用

```python
from disk_analyzer import DiskAnalyzer

# 创建分析器实例
analyzer = DiskAnalyzer(max_depth=3)

# 分析目录
results = analyzer.analyze_directory('/path/to/analyze')

# 处理结果
for item in results:
    print(f"{item.path}: {item.size_human}")
```

### 访问界面

打开浏览器访问：`http://localhost:8080`

## 技术栈

### 后端
- **框架**：Flask 2.x
- **语言**：Python 3.8+
- **架构**：MVC模式

### 前端
- **框架**：Bootstrap 5.1.3
- **图标**：Bootstrap Icons 1.7.2
- **样式**：原生CSS + 渐变设计

### 数据存储
- **配置存储**：localStorage（浏览器本地）
- **无需数据库**

## 项目结构

```
disk_analyzer/
├── disk_analyzer/              # 主包目录
│   ├── __init__.py            # 包初始化，导出公共API
│   ├── __main__.py            # 支持 python -m disk_analyzer 运行
│   ├── analyzer.py            # 磁盘分析核心逻辑
│   ├── web_app.py             # Web应用（Flask + HTML/JS）
│   └── cli.py                 # 命令行入口
├── docs/                        # 文档目录
│   ├── 1-设计/                  # 设计文档
│   │   ├── 磁盘信息可视化优化实现文档.md
│   │   ├── 功能扩展与UI优化实施进度.md
│   │   └── 表格视图多层级展开修复与路径显示优化.md
│   ├── 200-需求管理/            # 需求文档
│   │   └── 功能扩展与UI优化需求.md
│   └── changelog/               # 详细变更日志
│       ├── CHANGLOG-20251222-192109.md (✨最新)
│       ├── CHANGLOG-20251222-181038.md
│       ├── CHANGELOG-20251222-133710.md
│       ├── CHANGLOG-20251222-132701.md
│       └── CHANGLOG-20251222-132000.md
├── pyproject.toml               # 现代化项目配置
├── setup.py                     # 传统安装配置（向后兼容）
├── MANIFEST.in                  # 非代码文件清单
├── LICENSE                      # MIT 开源许可证
├── requirements.txt             # Python依赖
├── CHANGELOG.md                 # 全局变更日志
├── README.md                    # 项目说明
├── PUBLISHING_GUIDE.md          # PyPI发布指南
├── scripts/                     # 发布和版本管理脚本
│   ├── README.md                # 脚本使用说明
│   ├── publish.sh               # 交互式发布脚本
│   ├── bump_version.py          # 版本号更新脚本
│   └── check_release.py         # 发布前检查脚本
└── start_disk_tool.py           # 传统启动器（向后兼容）
```

## 使用指南

### 1. 分析磁盘目录

1. 在"分析设置"中输入要分析的路径（默认 `/`）
2. 设置分析深度（1-5层，默认3层）
3. 可选：添加排除路径或扩展名
4. 点击"开始分析"
5. 等待分析完成，查看表格视图或树形视图

### 2. 查看分区详情

1. 在"系统磁盘信息"区域查看所有分区
2. 点击任意分区卡片
3. 弹窗显示该分区的目录树结构

### 3. 安全删除目录

1. 在分析结果中找到要删除的目录
2. 点击"删除"按钮
3. **安全验证步骤**：
   - **步骤1**：手动输入完整路径（禁止粘贴）
   - **步骤2**：计算并输入验证码答案
4. 两项验证通过后点击"确认删除"

### 4. 排除规则配置

**排除路径示例**：
```
/tmp,/var/log,/home/user/.cache
```

**排除扩展名示例**：
```
.log,.tmp,.cache,.bak
```

## API参考

### 获取分区列表
```
GET /api/partitions
```

### 获取分区目录树
```
POST /api/partition-tree
Body: {
  "mount_point": "/",
  "max_depth": 2,
  "limit": 20
}
```

### 开始目录分析
```
POST /api/analyze
Body: {
  "path": "/",
  "depth": 3,
  "limit": 50,
  "exclude_paths": ["/tmp"],
  "exclude_extensions": [".log"]
}
```

### 查询分析进度
```
GET /api/analysis-progress/{analysis_id}
```

### 安全删除文件/目录
```
POST /api/delete
Body: {
  "path": "/path/to/delete"
}
```

## 安全性

### 删除操作安全机制

**前端验证**：
- ✅ 路径完全匹配（区分大小写）
- ✅ 禁止复制粘贴（强制手动输入）
- ✅ 随机验证码验证
- ✅ 实时状态反馈

**后端保护**：
- ✅ 系统关键目录拦截（/、/proc、/sys等）
- ✅ 路径规范化（防止相对路径逃逸）
- ✅ 权限检查
- ✅ 错误分类处理

**建议增强**（后续版本）：
- 后端路径二次验证
- 删除操作日志记录
- 回收站机制（可撤销删除）

## 性能优化

- ✅ 分区识别使用设备号，性能开销可忽略
- ✅ 树形分析限制深度和数量，单次分析耗时1-3秒
- ✅ CSS transition代替JavaScript动画，提升帧率
- ✅ 前端渲染初始仅渲染前两层，深层节点懒加载

## 浏览器兼容性

- Chrome/Edge ≥ 90
- Firefox ≥ 88
- Safari ≥ 14

## 版本历史

### alpha-1.0 (2025-12-22)
- ✅ 删除安全机制强化（双重验证）
- 🔨 侧边栏布局优化（CSS框架）
- 📝 文档体系建立

详见：[CHANGELOG.md](CHANGELOG.md)

## 开发计划

### 短期（本周）
- [ ] 完成侧边栏HTML结构重构
- [ ] 实现侧边栏折叠/展开功能
- [ ] 实现磁盘卡片显示模式切换
- [ ] 分析结果视觉增强

### 中期（下周）
- [ ] 树形结构多级展开
- [ ] 系统磁盘信息折叠功能
- [ ] 全面测试和优化
- [ ] 浏览器兼容性测试

### 长期（未来迭代）
- [ ] 后端路径验证增强
- [ ] 删除操作日志记录
- [ ] 撤销删除功能
- [ ] 键盘快捷键支持
- [ ] 暗色模式
- [ ] 导出PDF报告

## 贡献指南

### 开发规范

请参考项目规范文档：
- `.cursor/rules/ep.mdc` - 主导航索引
- `.cursor/rules/需求分析流程.mdc` - 需求分析规范
- `.cursor/rules/任务管理与功能点完成流程.mdc` - 任务管理规范

### 提交规范

遵循约定式提交（Conventional Commits）：
```
feat: 添加新功能
fix: 修复Bug
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
perf: 性能优化
test: 测试相关
```

## 许可证

[待定]

## 联系方式

[待补充]

## 致谢

- Bootstrap - 前端UI框架
- Flask - Python Web框架
- Bootstrap Icons - 图标库
- Firefox ≥ 88
- Safari ≥ 14

## 版本历史

### alpha-1.0 (2025-12-22)
- ✅ 删除安全机制强化（双重验证）
- 🔨 侧边栏布局优化（CSS框架）
- 📝 文档体系建立

详见：[CHANGELOG.md](CHANGELOG.md)

## 开发计划

### 短期（本周）
- [ ] 完成侧边栏HTML结构重构
- [ ] 实现侧边栏折叠/展开功能
- [ ] 实现磁盘卡片显示模式切换
- [ ] 分析结果视觉增强

### 中期（下周）
- [ ] 树形结构多级展开
- [ ] 系统磁盘信息折叠功能
- [ ] 全面测试和优化
- [ ] 浏览器兼容性测试

### 长期（未来迭代）
- [ ] 后端路径验证增强
- [ ] 删除操作日志记录
- [ ] 撤销删除功能
- [ ] 键盘快捷键支持
- [ ] 暗色模式
- [ ] 导出PDF报告

## 贡献指南

### 开发规范

请参考项目规范文档：
- `.cursor/rules/ep.mdc` - 主导航索引
- `.cursor/rules/需求分析流程.mdc` - 需求分析规范
- `.cursor/rules/任务管理与功能点完成流程.mdc` - 任务管理规范

### 提交规范

遵循约定式提交（Conventional Commits）：
```
feat: 添加新功能
fix: 修复Bug
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
perf: 性能优化
test: 测试相关
```

### 发布和版本管理

项目提供了完整的发布和版本管理工具：

1. **版本号管理**：使用 `scripts/bump_version.py` 脚本统一更新所有文件中的版本号
2. **发布前检查**：运行 `scripts/check_release.py` 确保发布准备工作完成
3. **交互式发布**：使用 `scripts/publish.sh` 脚本进行交互式发布
4. **详细指南**：查看 `PUBLISHING_GUIDE.md` 获取完整的PyPI发布指南

详细信息请参考 `scripts/README.md`。

## 许可证

[待定]

## 联系方式

[待补充]

## 致谢

- Bootstrap - 前端UI框架
- Flask - Python Web框架
- Bootstrap Icons - 图标库