config-man/PROJECT_STRUCTURE.md

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             # 项目配置文件
├── config-man.json            # 配置文件
├── 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. 开发新功能

# 在src/config_man/对应模块中添加代码
# 在tests/对应目录中添加测试
# 在docs/中添加文档
# 在examples/中添加示例

2. 运行测试

# 运行所有测试
pytest

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

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

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

3. 代码质量检查

# 代码格式化
black src/ tests/

# 类型检查
mypy src/

# 代码检查
flake8 src/ tests/

4. 安装和发布

# 开发模式安装
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项目的标准。