# Config-Man 项目结构

## 概述

Config-Man 项目采用现代Python项目标准结构，将源代码、测试、文档和示例分开组织，便于维护和扩展。

## 目录结构

```
config-man/
├── src/                          # 源代码目录
│   └── config_man/              # 主包
│       ├── __init__.py          # 包初始化文件
│       ├── cli/                 # CLI模块
│       │   ├── __init__.py
│       │   └── main.py         # CLI主程序
│       ├── core/                # 核心功能模块
│       │   ├── __init__.py
│       │   ├── config_manager.py    # 配置管理器
│       │   ├── display_manager.py   # 显示管理器
│       │   └── view_command.py      # 查看命令处理器
│       └── utils/               # 工具模块
│           ├── __init__.py
│           ├── crypto.py        # 加密解密工具
│           └── mock_rclone.py   # 模拟rclone环境
├── tests/                       # 测试目录
│   ├── __init__.py
│   ├── unit/                   # 单元测试
│   │   └── __init__.py
│   ├── integration/            # 集成测试
│   │   └── __init__.py
│   └── fixtures/               # 测试工具和数据
│       ├── __init__.py
│       ├── test_configs.py     # 测试配置生成器
│       └── test_data/          # 测试数据目录
├── docs/                       # 文档目录
│   ├── README.md              # 文档说明
│   ├── USAGE.md               # 使用说明
│   ├── progress-tracker.md    # 进度跟踪
│   ├── requirements.md        # 需求文档
│   └── workplan.md           # 工作计划
├── examples/                   # 示例目录
│   └── basic_usage.py         # 基本使用示例
├── main.py                    # 主入口文件
├── pyproject.toml             # 项目配置文件
├── README.md                  # 项目主文档
├── .gitignore                 # Git忽略文件
└── PROJECT_STRUCTURE.md       # 项目结构说明（本文件）
```

## 模块说明

### 源代码模块 (src/config_man/)

#### CLI模块 (cli/)
- **main.py**: CLI主程序，包含所有命令行命令的定义
- 使用Click框架实现命令行界面
- 支持view、suggest-update、force-update等命令

#### 核心模块 (core/)
- **config_manager.py**: 配置管理器，负责文件下载、解密、比较等核心功能
- **display_manager.py**: 显示管理器，负责格式化输出和表格显示
- **view_command.py**: 查看命令处理器，实现查看功能的核心逻辑

#### 工具模块 (utils/)
- **crypto.py**: 加密解密工具，提供DES加密解密功能
- **mock_rclone.py**: 模拟rclone环境，用于测试和开发

### 测试模块 (tests/)

#### 单元测试 (unit/)
- 测试各个模块的独立功能
- 测试边界条件和错误处理

#### 集成测试 (integration/)
- 测试模块间的集成功能
- 测试完整的工作流程

#### 测试工具 (fixtures/)
- **test_configs.py**: 测试配置生成器
- **test_data/**: 测试数据目录，包含模拟的配置文件

### 文档模块 (docs/)
- 包含所有项目文档
- 使用说明、需求文档、工作计划等

### 示例模块 (examples/)
- 提供使用示例和代码示例
- 帮助用户快速上手

## 设计原则

### 1. 分离关注点
- **源代码**: 只包含业务逻辑
- **测试**: 独立的测试代码和数据
- **文档**: 完整的使用和开发文档
- **示例**: 实际的使用示例

### 2. 模块化设计
- 每个模块职责单一
- 模块间依赖关系清晰
- 便于独立测试和维护

### 3. 可扩展性
- 新功能可以轻松添加到对应模块
- 测试可以独立添加
- 文档结构清晰，便于更新

### 4. 标准化
- 遵循Python项目标准结构
- 使用现代Python工具链
- 支持pip安装和开发模式

## 开发工作流

### 1. 开发新功能
```bash
# 在src/config_man/对应模块中添加代码
# 在tests/对应目录中添加测试
# 在docs/中添加文档
# 在examples/中添加示例
```

### 2. 运行测试
```bash
# 运行所有测试
pytest

# 运行单元测试
pytest tests/unit/

# 运行集成测试
pytest tests/integration/

# 生成覆盖率报告
pytest --cov=src/config_man
```

### 3. 代码质量检查
```bash
# 代码格式化
black src/ tests/

# 类型检查
mypy src/

# 代码检查
flake8 src/ tests/
```

### 4. 安装和发布
```bash
# 开发模式安装
pip install -e .

# 构建包
python -m build

# 发布到PyPI
twine upload dist/
```

## 最佳实践

### 1. 导入路径
- 使用相对导入在包内部
- 使用绝对导入从外部访问
- 避免循环导入

### 2. 测试组织
- 单元测试测试独立功能
- 集成测试测试模块协作
- 使用fixtures提供测试数据

### 3. 文档维护
- 代码和文档同步更新
- 提供完整的使用示例
- 保持文档结构清晰

### 4. 版本控制
- 合理的.gitignore配置
- 清晰的提交信息
- 版本号管理

## 扩展指南

### 添加新功能
1. 在`src/config_man/core/`中添加核心逻辑
2. 在`src/config_man/cli/main.py`中添加CLI命令
3. 在`tests/`中添加对应测试
4. 在`docs/`中更新文档
5. 在`examples/`中添加使用示例

### 添加新工具
1. 在`src/config_man/utils/`中添加工具函数
2. 在`tests/unit/`中添加单元测试
3. 在`docs/`中添加使用说明

### 添加新测试
1. 根据测试类型选择`tests/unit/`或`tests/integration/`
2. 使用`tests/fixtures/`中的测试数据
3. 遵循pytest最佳实践

这种项目结构确保了代码的可维护性、可测试性和可扩展性，符合现代Python项目的标准。