339 lines
10 KiB
Markdown
339 lines
10 KiB
Markdown
# 项目文件组织规范
|
||
|
||
**文档版本**: 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. **代码质量提升**: 强制的职责分离有助于代码质量
|
||
|
||
**重要提醒**: 所有开发代理在创建新文件或修改现有结构时，都必须严格遵循本规范。如有疑问，请参考本文档或向项目负责人咨询。
|
||
|
||
---
|
||
|
||
**文档维护**: 本文档将根据项目发展需要进行更新，所有变更将在版本历史中记录。
|