# 项目文件组织规范

**文档版本**: 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 当前需要迁移的文件

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

**测试文件迁移**:

```bash
# 需要从源码目录迁移到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
```

**示例文件迁移**:

```bash
# 需要从源码目录迁移到文档目录的文件
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: 备份当前文件**

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

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

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

**步骤3: 移动文件**

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

**步骤4: 更新引用和导入**

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

**步骤5: 验证迁移结果**

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

## 7. 质量检查清单

### 7.1 日常检查项目

**文件组织检查**:

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

**命名规范检查**:

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

**代码质量检查**:

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

### 7.2 违规文件检测脚本

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

```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. **代码质量提升**: 强制的职责分离有助于代码质量

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

---

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