NavisworksTransport/doc/working/项目文件组织规范_20250817.md

项目文件组织规范

文档版本: 1.0
创建日期: 2025-08-17
适用范围: NavisworksTransport项目开发代理

1. 概述

本文档规定了NavisworksTransport项目中各类文件的标准放置位置、命名约定和组织原则，确保所有开发代理遵循统一的文件组织标准，提高项目的可维护性和协作效率。

2. 标准目录结构

NavisworksTransport/
├── src/                          # 源代码目录
│   ├── Core/                     # 核心功能模块
│   ├── UI/                       # 用户界面模块
│   ├── PathPlanning/             # 路径规划模块
│   ├── Commands/                 # 命令模式实现
│   ├── Utils/                    # 工具类库
│   ├── Resources/                # 资源文件
│   └── Legacy/                   # 遗留代码（仅作参考）
├── tests/                        # 测试文件目录
│   ├── Unit/                     # 单元测试
│   ├── Integration/              # 集成测试
│   └── Performance/              # 性能测试
├── doc/                          # 文档目录
│   ├── working/                  # 工作文档和开发过程记录
│   ├── guide/                    # 使用指南和技术文档
│   ├── design/                   # 设计文档
│   ├── requirement/              # 需求文档
│   └── migration/                # 迁移文档
├── Properties/                   # 项目属性文件
└── 项目根目录文件               # 配置文件、解决方案文件等

3. 文件放置规则

3.1 源代码文件 (src/)

放置原则: 按功能模块组织，每个文件都应有明确的职责

规则详述:

• 核心功能: src/Core/ - 插件主体、管理器类、数据模型
• 用户界面: src/UI/ - WPF控件、WinForms对话框、视图模型
• 路径规划: src/PathPlanning/ - 算法实现、数据结构
• 命令模式: src/Commands/ - 命令接口、执行器、具体命令
• 工具类: src/Utils/ - 通用工具、转换器、辅助类
• 资源文件: src/Resources/ - 图标、字符串资源、配置文件

禁止内容:

• ❌ 测试文件（应放在 tests/ 目录）
• ❌ 使用示例代码（应放在 doc/working/ 目录）
• ❌ README文件（应放在 doc/working/ 目录）
• ❌ 临时调试代码

3.2 测试文件 (tests/)

放置原则: 所有测试相关文件统一管理

文件类型:

• 单元测试: tests/Unit/ - 单个类或方法的测试
• 集成测试: tests/Integration/ - 模块间协作测试
• 性能测试: tests/Performance/ - 性能基准测试
• UI测试: tests/UI/ - 界面功能测试

命名约定:

• 单元测试: {ClassName}Tests.cs
• 集成测试: {ModuleName}IntegrationTest.cs
• 性能测试: {FeatureName}PerformanceTest.cs

示例:

tests/
├── Unit/
│   ├── PathPlanningManagerTests.cs
│   ├── ViewModelBaseTests.cs
│   └── CoordinateConverterTests.cs
├── Integration/
│   ├── CommandFrameworkIntegrationTest.cs
│   ├── ClashDetectiveIntegrationTest.cs
│   └── UIStateManagerIntegrationTest.cs
└── Performance/
    └── PathfindingPerformanceTest.cs

3.3 工作文档 (doc/working/)

放置原则: 开发过程中的所有文档和说明

内容类型:

• 开发任务: 任务清单、进度报告、完成总结
• 技术方案: 实现方案、架构设计、问题解决
• 使用示例: 代码示例、使用说明、最佳实践
• 调试记录: 问题排查、错误修复、性能优化

命名约定:

• 任务文档: {功能名称}_{任务类型}_{日期}.md
• 技术方案: {方案名称}_技术设计方案_{日期}.md
• 问题记录: {问题描述}_修复报告_{日期}.md

3.4 技术文档 (doc/guide/)

放置原则: 稳定的技术指南和参考文档

内容类型:

• 开发指南: 开发环境搭建、编码规范
• API文档: 接口说明、使用方法
• 故障排除: 常见问题解决方案
• 最佳实践: 代码模式、设计原则

4. 文件命名约定

4.1 通用命名规则

• 语言: 中文文档使用中文命名，代码文件使用英文命名
• 格式: 无空格，使用下划线分隔，避免特殊字符
• 日期: 使用 YYYYMMDD 格式
• 版本: 使用语义化版本号（如适用）

4.2 具体命名规范

源代码文件:

类文件: {ClassName}.cs
接口文件: I{InterfaceName}.cs
管理器类: {ModuleName}Manager.cs
工具类: {FeatureName}Helper.cs 或 {FeatureName}Utility.cs

测试文件:

单元测试: {ClassName}Tests.cs
集成测试: {ModuleName}IntegrationTest.cs
示例代码: {FeatureName}Example.cs

文档文件:

工作文档: {主题}_{类型}_{日期}.md
技术指南: {主题}_guide.md
设计文档: {主题}_design.md

5. 开发代理遵循指南

5.1 文件创建检查清单

在创建新文件时，请按以下清单检查：

• 确定文件类型: 源代码、测试、文档、配置
• 选择正确目录: 根据文件功能选择标准目录
• 遵循命名约定: 使用标准命名格式
• 检查文件职责: 确保文件功能单一、职责明确
• 避免重复放置: 检查是否已存在类似文件

5.2 代码文件组织原则

单一职责原则:

• 每个文件应专注于单一功能
• 避免在一个文件中混合多种类型的代码

模块化原则:

• 相关功能的文件应放在同一目录下
• 跨模块依赖应最小化

可维护性原则:

• 使用清晰的文件和目录命名
• 添加适当的注释和文档

5.3 禁止的文件放置模式

严格禁止:

• ❌ 在 src/ 目录下放置测试文件
• ❌ 在源代码目录下放置README或使用说明
• ❌ 在项目根目录下创建临时文件
• ❌ 在 Legacy/ 目录下添加新代码

强烈不建议:

• 🚫 在不相关的模块目录下放置文件
• 🚫 使用含糊不清的文件名
• 🚫 创建单一功能的深层目录结构

6. 文件迁移指导

6.1 当前需要迁移的文件

根据项目现状，以下文件需要重新组织：

测试文件迁移:

# 需要从源码目录迁移到tests目录的文件
src/Commands/CommandFrameworkTest.cs           → tests/Integration/CommandFrameworkIntegrationTest.cs
src/Commands/CommandPatternIntegrationTest.cs → tests/Integration/CommandPatternIntegrationTest.cs
src/Core/ClashDetectiveIntegrationTest.cs     → tests/Integration/ClashDetectiveIntegrationTest.cs
src/UI/WPF/ViewModels/ViewModelBaseTest.cs    → tests/Unit/ViewModelBaseTests.cs

示例文件迁移:

# 需要从源码目录迁移到文档目录的文件
src/Commands/README.md                         → doc/working/Commands模块使用说明_20250817.md
src/Core/UIStateManagerExample.cs             → doc/working/UIStateManager使用示例_20250817.md
src/UI/WPF/Collections/ThreadSafeObservableCollectionUsageExample.cs → doc/working/ThreadSafeObservableCollection使用示例_20250817.md

6.2 迁移步骤

步骤1: 备份当前文件

# 确保git状态清洁
git status
git add .
git commit -m "迁移前备份"

步骤2: 创建目标目录结构

# 创建测试目录结构
mkdir tests/Unit
mkdir tests/Integration
mkdir tests/Performance
mkdir tests/UI

步骤3: 移动文件

# 使用git mv保持版本历史
git mv src/Commands/CommandFrameworkTest.cs tests/Integration/CommandFrameworkIntegrationTest.cs
# 重复其他文件...

步骤4: 更新引用和导入

• 更新命名空间
• 修复相对路径引用
• 更新项目文件引用

步骤5: 验证迁移结果

• 编译项目确保无错误
• 运行测试确保功能正常
• 提交迁移变更

7. 质量检查清单

7.1 日常检查项目

文件组织检查:

• 所有测试文件都在 tests/ 目录下
• 源代码文件按模块正确分类
• 文档文件在相应的 doc/ 子目录下
• 没有在源代码目录下的README或示例文件

命名规范检查:

• 文件名符合命名约定
• 目录结构清晰合理
• 避免使用临时或模糊的命名

代码质量检查:

• 每个文件职责单一
• 命名空间与目录结构一致
• 适当的注释和文档

7.2 违规文件检测脚本

可以使用以下PowerShell脚本检测违规文件：

# 检测源码目录下的测试文件
Get-ChildItem -Path "src" -Recurse -Name "*Test*.cs" | ForEach-Object {
    Write-Warning "发现测试文件在源码目录: $_"
}

# 检测源码目录下的README文件
Get-ChildItem -Path "src" -Recurse -Name "README.*" | ForEach-Object {
    Write-Warning "发现README文件在源码目录: $_"
}

# 检测源码目录下的示例文件
Get-ChildItem -Path "src" -Recurse -Name "*Example*.cs" | ForEach-Object {
    Write-Warning "发现示例文件在源码目录: $_"
}

7.3 项目结构验证

必要目录检查:

• src/ 目录存在且包含核心模块
• tests/ 目录存在且有子分类
• doc/working/ 目录存在且有当前文档
• 项目根目录整洁，无临时文件

目录内容检查:

• src/ 下只有源代码文件
• tests/ 下只有测试相关文件
• doc/ 下按类型正确分类

8. 总结

遵循本规范可以确保：

1. 项目结构清晰: 便于新成员快速理解项目组织
2. 协作效率提升: 减少因文件位置混乱导致的沟通成本
3. 维护成本降低: 标准化的文件组织便于长期维护
4. 代码质量提升: 强制的职责分离有助于代码质量

重要提醒: 所有开发代理在创建新文件或修改现有结构时，都必须严格遵循本规范。如有疑问，请参考本文档或向项目负责人咨询。

---

文档维护: 本文档将根据项目发展需要进行更新，所有变更将在版本历史中记录。