diff --git a/.claude/file_organization.json b/.claude/file_organization.json new file mode 100644 index 0000000..d1c7db1 --- /dev/null +++ b/.claude/file_organization.json @@ -0,0 +1,173 @@ +{ + "description": "文件组织和归档配置 - 定义了代码和文档的自动归类规则", + "version": "1.0.0", + "last_updated": "2025-11-15", + + "directories": { + "archives": { + "bug_fixes": { + "path": "archives/bug_fixes", + "pattern": "{date}_{bug_name}", + "subdirs": ["code", "docs", "tests"], + "description": "Bug修复归档目录" + }, + "updates": { + "path": "archives/updates", + "pattern": "{date}_{feature_name}", + "subdirs": ["code", "docs", "tests"], + "description": "功能更新归档目录" + }, + "versions": { + "path": "archives/versions", + "pattern": "v{major}.{minor}.{patch}", + "subdirs": ["backup"], + "description": "版本归档目录" + } + }, + "docs": { + "fixes": { + "path": "docs/fixes", + "description": "Bug修复文档（当前活跃）" + }, + "updates": { + "path": "docs/updates", + "description": "功能更新文档（当前活跃）" + }, + "guides": { + "path": "docs/guides", + "description": "使用指南和教程" + }, + "protocol": { + "path": "docs/protocol", + "description": "通信协议文档" + } + }, + "source": { + "src": { + "path": "src", + "description": "源代码主目录" + }, + "include": { + "path": "include", + "description": "头文件目录" + }, + "examples": { + "path": "examples", + "description": "示例代码" + } + } + }, + + "file_types": { + "code": { + "extensions": [".cpp", ".c", ".h", ".hpp", ".py"], + "default_location": "src", + "description": "代码文件" + }, + "headers": { + "extensions": [".h", ".hpp"], + "default_location": "include", + "description": "头文件" + }, + "docs": { + "extensions": [".md", ".txt", ".pdf"], + "default_location": "docs", + "description": "文档文件" + }, + "configs": { + "extensions": [".json", ".yaml", ".yml", ".ini", ".conf"], + "default_location": ".", + "description": "配置文件" + } + }, + + "naming_conventions": { + "bug_fix": { + "folder": "{YYYYMMDD}_{bug_description}", + "doc": "BUG_{bug_description}_{YYYYMMDD}.md", + "example": "20251115_fix_path_tracking / BUG_path_tracking_20251115.md" + }, + "feature_update": { + "folder": "{YYYYMMDD}_{feature_name}", + "doc": "UPDATE_{feature_name}_{YYYYMMDD}.md", + "example": "20251115_adaptive_lookahead / UPDATE_adaptive_lookahead_20251115.md" + }, + "version": { + "folder": "v{major}.{minor}.{patch}", + "doc": "release_notes.md", + "example": "v1.2.0 / release_notes.md" + } + }, + + "workflow_rules": { + "bug_fix": { + "steps": [ + "1. 在主代码目录 (src/, include/) 进行修复", + "2. 提交 git commit", + "3. 创建归档目录: archives/bug_fixes/{date}_{name}/{code,docs,tests}", + "4. 复制修复的代码到归档目录", + "5. 创建修复文档到归档目录", + "6. 复制文档副本到 docs/fixes/ 供快速查阅" + ], + "archive_to": "archives/bug_fixes", + "doc_copy_to": "docs/fixes" + }, + "feature_update": { + "steps": [ + "1. 在主代码目录 (src/, include/) 开发新功能", + "2. 提交 git commit", + "3. 创建归档目录: archives/updates/{date}_{name}/{code,docs,tests}", + "4. 复制新增/修改的代码到归档目录", + "5. 创建更新文档到归档目录", + "6. 复制文档副本到 docs/updates/ 供快速查阅" + ], + "archive_to": "archives/updates", + "doc_copy_to": "docs/updates" + }, + "version_release": { + "steps": [ + "1. 更新版本号", + "2. 编写 release_notes.md", + "3. 创建版本目录: archives/versions/vX.Y.Z/", + "4. 可选：备份完整代码到 backup/ 子目录", + "5. 创建 git tag" + ], + "archive_to": "archives/versions" + } + }, + + "auto_categorization_rules": { + "enabled": true, + "rules": [ + { + "type": "bug_fix", + "trigger_keywords": ["bug", "fix", "修复", "错误", "问题"], + "target_dir": "archives/bug_fixes", + "doc_dir": "docs/fixes" + }, + { + "type": "feature", + "trigger_keywords": ["feature", "update", "新增", "功能", "更新", "add", "implement"], + "target_dir": "archives/updates", + "doc_dir": "docs/updates" + }, + { + "type": "version", + "trigger_keywords": ["version", "release", "版本", "发布"], + "target_dir": "archives/versions" + } + ] + }, + + "templates": { + "bug_fix_doc": ".claude/templates/bug_fix_template.md", + "feature_update_doc": ".claude/templates/feature_update_template.md", + "release_notes": ".claude/templates/release_notes_template.md" + }, + + "scripts": { + "archive_bug_fix": "scripts/archive_bug_fix.sh", + "archive_feature": "scripts/archive_feature.sh", + "create_release": "scripts/create_release.sh" + } +} diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 3e8b82c..346d5ac 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -5,7 +5,10 @@ "Bash(head:*)", "Bash(echo:*)", "Bash(test:*)", - "Bash(test -f:*)" + "Bash(test -f:*)", + "Bash(mkdir:*)", + "Bash(chmod:*)", + "Bash(./scripts/archive_bug_fix.sh:*)" ], "deny": [], "ask": [] diff --git a/.claude/templates/bug_fix_template.md b/.claude/templates/bug_fix_template.md new file mode 100644 index 0000000..112ab06 --- /dev/null +++ b/.claude/templates/bug_fix_template.md @@ -0,0 +1,87 @@ +# Bug修复: {{BUG_DESCRIPTION}} + +**日期**: {{DATE}} +**修复者**: {{AUTHOR}} +**相关Issue**: #{{ISSUE_NUMBER}}（如有） +**Git Commit**: {{COMMIT_HASH}} + +--- + +## Bug描述 + +{{详细描述bug的表现，包括错误信息、异常行为等}} + +## 复现步骤 + +1. {{步骤1}} +2. {{步骤2}} +3. {{步骤3}} +4. **观察到的错误行为**: {{描述错误}} + +## 根本原因 + +{{分析bug的根本原因，包括代码逻辑问题、边界条件、数据异常等}} + +### 问题代码位置 +- 文件: `{{FILE_PATH}}` +- 行号: {{LINE_NUMBER}} +- 函数/类: `{{FUNCTION_NAME}}` + +## 修复方案 + +{{描述如何修复这个bug，包括修改的逻辑、算法改进等}} + +### 修改前代码 +```cpp +{{原始代码片段}} +``` + +### 修改后代码 +```cpp +{{修复后的代码片段}} +``` + +## 修改文件清单 + +- `{{FILE_1}}` - {{修改说明1}} +- `{{FILE_2}}` - {{修改说明2}} +- `{{FILE_3}}` - {{修改说明3}} + +## 测试验证 + +### 测试场景 +{{描述测试场景和测试数据}} + +### 测试步骤 +1. {{测试步骤1}} +2. {{测试步骤2}} +3. {{测试步骤3}} + +### 测试结果 +- ✅ {{成功的测试案例}} +- ✅ {{成功的测试案例}} + +### 性能影响 +{{描述修复对性能的影响，如有}} + +## Git提交信息 + +``` +Commit ID: {{COMMIT_HASH}} +Commit Message: {{COMMIT_MESSAGE}} +Branch: {{BRANCH_NAME}} +``` + +## 相关文档 + +- [{{相关文档1}}]({{LINK1}}) +- [{{相关文档2}}]({{LINK2}}) + +## 备注 + +{{其他需要说明的内容、注意事项、后续改进计划等}} + +--- + +**归档位置**: `archives/bug_fixes/{{DATE}}_{{BUG_NAME}}/` +**文档副本**: `docs/fixes/` diff --git a/.claude/templates/feature_update_template.md b/.claude/templates/feature_update_template.md new file mode 100644 index 0000000..cada8e0 --- /dev/null +++ b/.claude/templates/feature_update_template.md @@ -0,0 +1,188 @@ +# 功能更新: {{FEATURE_NAME}} + +**日期**: {{DATE}} +**开发者**: {{AUTHOR}} +**相关Issue**: #{{ISSUE_NUMBER}}（如有） +**Git Commit**: {{COMMIT_HASH}} + +--- + +## 功能概述 + +{{简要描述新功能的目的和价值，1-2句话说明为什么需要这个功能}} + +## 需求背景 + +{{详细描述需求背景、使用场景、要解决的问题}} + +### 用户场景 +- **场景1**: {{描述使用场景1}} +- **场景2**: {{描述使用场景2}} + +### 功能目标 +- {{目标1}} +- {{目标2}} +- {{目标3}} + +## 设计方案 + +{{技术设计方案描述}} + +### 架构设计 + +{{如有架构层面的变更或新增模块，在此说明}} + +``` +[架构图或流程图的ASCII描述，或引用外部图片] +``` + +### 模块划分 + +- **模块1**: {{模块1功能说明}} +- **模块2**: {{模块2功能说明}} +- **模块3**: {{模块3功能说明}} + +### 数据结构 + +```cpp +// 新增或修改的数据结构 +{{数据结构定义}} +``` + +### API设计 + +```cpp +// 公开接口 +{{API接口定义}} +``` + +#### 接口说明 + +| 接口名称 | 参数 | 返回值 | 功能说明 | +|---------|------|--------|---------| +| {{API1}} | {{参数}} | {{返回值}} | {{说明}} | +| {{API2}} | {{参数}} | {{返回值}} | {{说明}} | + +## 实现细节 + +### 新增文件 + +- `{{FILE_1}}` - {{文件功能说明}} +- `{{FILE_2}}` - {{文件功能说明}} + +### 修改文件 + +- `{{FILE_3}}` - {{修改内容说明}} +- `{{FILE_4}}` - {{修改内容说明}} + +### 核心代码 + +```cpp +{{核心实现代码片段}} +``` + +### 算法说明 + +{{如涉及特定算法，详细说明算法原理和实现}} + +## 使用方法 + +### 基本用法 + +```cpp +// 示例代码1: 基本使用 +{{示例代码}} +``` + +### 高级用法 + +```cpp +// 示例代码2: 高级特性 +{{示例代码}} +``` + +### 配置说明 + +{{如有配置参数，说明配置方法和参数含义}} + +| 参数名称 | 类型 | 默认值 | 说明 | +|---------|------|--------|------| +| {{PARAM1}} | {{TYPE}} | {{DEFAULT}} | {{说明}} | + +## 测试验证 + +### 单元测试 + +```cpp +// 单元测试代码 +{{测试代码}} +``` + +### 集成测试 + +{{描述集成测试场景和结果}} + +### 性能测试 + +| 测试场景 | 执行时间 | 内存占用 | 备注 | +|---------|---------|---------|------| +| {{场景1}} | {{时间}} | {{内存}} | {{说明}} | + +### 测试结果 + +- ✅ {{测试通过项1}} +- ✅ {{测试通过项2}} +- ✅ {{测试通过项3}} + +## Git提交信息 + +``` +Commit ID: {{COMMIT_HASH}} +Commit Message: {{COMMIT_MESSAGE}} +Branch: {{BRANCH_NAME}} +``` + +## 依赖关系 + +### 外部依赖 +- {{依赖库1}} - {{版本}} - {{用途}} +- {{依赖库2}} - {{版本}} - {{用途}} + +### 内部依赖 +- {{模块1}} - {{依赖关系说明}} +- {{模块2}} - {{依赖关系说明}} + +## 兼容性说明 + +### API兼容性 +- {{是否破坏现有API}} +- {{迁移指南（如需要）}} + +### 版本兼容性 +- 最低支持版本: {{VERSION}} +- 推荐版本: {{VERSION}} + +## 已知问题 + +- {{问题1描述及临时解决方案}} +- {{问题2描述及临时解决方案}} + +## 后续计划 + +- [ ] {{待完善的功能1}} +- [ ] {{待完善的功能2}} +- [ ] {{性能优化计划}} + +## 相关文档 + +- [{{相关文档1}}]({{LINK1}}) +- [{{相关文档2}}]({{LINK2}}) + +## 备注 + +{{其他需要说明的内容}} + +--- + +**归档位置**: `archives/updates/{{DATE}}_{{FEATURE_NAME}}/` +**文档副本**: `docs/updates/` diff --git a/.claude/templates/release_notes_template.md b/.claude/templates/release_notes_template.md new file mode 100644 index 0000000..776ea19 --- /dev/null +++ b/.claude/templates/release_notes_template.md @@ -0,0 +1,201 @@ +# Release Notes - v{{VERSION}} + +**发布日期**: {{RELEASE_DATE}} +**版本号**: {{VERSION}} +**发布类型**: {{RELEASE_TYPE}} (Major/Minor/Patch) + +--- + +## 版本概述 + +{{简要描述本版本的主要更新内容和重点特性}} + +## 重要变更 ⚠️ + +{{列出所有重大变更、破坏性更新、需要用户注意的事项}} + +- **{{变更1}}**: {{详细说明}} +- **{{变更2}}**: {{详细说明}} + +## 新增功能 ✨ + +### {{功能类别1}} + +- **{{功能1名称}}** + - 说明: {{功能描述}} + - 相关文档: [{{文档名称}}]({{链接}}) + - Commit: {{commit_hash}} + +- **{{功能2名称}}** + - 说明: {{功能描述}} + - 相关文档: [{{文档名称}}]({{链接}}) + - Commit: {{commit_hash}} + +### {{功能类别2}} + +- **{{功能3名称}}** + - 说明: {{功能描述}} + - 相关文档: [{{文档名称}}]({{链接}}) + - Commit: {{commit_hash}} + +## Bug修复 🐛 + +### 严重Bug修复 + +- **{{Bug1名称}}** + - 问题: {{问题描述}} + - 影响: {{影响范围}} + - 修复: {{修复说明}} + - Commit: {{commit_hash}} + +### 一般Bug修复 + +- **{{Bug2名称}}** - {{简短描述}} ({{commit_hash}}) +- **{{Bug3名称}}** - {{简短描述}} ({{commit_hash}}) +- **{{Bug4名称}}** - {{简短描述}} ({{commit_hash}}) + +## 性能优化 🚀 + +- **{{优化项1}}**: {{优化描述和性能提升数据}} +- **{{优化项2}}**: {{优化描述和性能提升数据}} +- **{{优化项3}}**: {{优化描述和性能提升数据}} + +## 文档更新 📚 + +- {{文档更新1}} +- {{文档更新2}} +- {{文档更新3}} + +## API变更 + +### 新增API + +```cpp +// 新增的公开接口 +{{新API定义}} +``` + +### 修改API + +| API名称 | 变更类型 | 说明 | 迁移指南 | +|---------|---------|------|---------| +| {{API1}} | {{类型}} | {{说明}} | {{指南}} | + +### 废弃API + +| API名称 | 替代方案 | 移除计划版本 | +|---------|---------|------------| +| {{API1}} | {{替代}} | {{版本}} | + +## 依赖更新 + +| 依赖库 | 旧版本 | 新版本 | 变更原因 | +|-------|--------|--------|---------| +| {{LIB1}} | {{OLD}} | {{NEW}} | {{原因}} | +| {{LIB2}} | {{OLD}} | {{NEW}} | {{原因}} | + +## 兼容性说明 + +### 向后兼容性 +- ✅ 完全兼容 v{{PREVIOUS_VERSION}} +- ⚠️ 部分不兼容（详见API变更） +- ❌ 不兼容（需要迁移） + +### 系统要求 +- **编译器**: {{编译器要求}} +- **操作系统**: {{OS要求}} +- **依赖库**: {{依赖要求}} + +## 升级指南 + +### 从 v{{OLD_VERSION}} 升级 + +1. **备份当前版本** + ```bash + {{备份命令}} + ``` + +2. **更新代码** + ```bash + {{更新命令}} + ``` + +3. **处理API变更** + {{迁移步骤说明}} + +4. **重新编译** + ```bash + {{编译命令}} + ``` + +5. **测试验证** + {{测试建议}} + +### 配置迁移 + +{{如有配置文件格式变更，说明迁移方法}} + +## 已知问题 + +- **{{问题1}}**: {{描述和临时解决方案}} +- **{{问题2}}**: {{描述和临时解决方案}} + +## 统计数据 + +- **新增代码行数**: {{LINE_COUNT}} +- **修改文件数**: {{FILE_COUNT}} +- **关闭Issue数**: {{ISSUE_COUNT}} +- **Pull Request数**: {{PR_COUNT}} +- **贡献者**: {{CONTRIBUTOR_COUNT}} + +## 提交历史 + +``` +总提交数: {{COMMIT_COUNT}} + +主要提交: +{{COMMIT_HASH_1}} - {{COMMIT_MESSAGE_1}} +{{COMMIT_HASH_2}} - {{COMMIT_MESSAGE_2}} +{{COMMIT_HASH_3}} - {{COMMIT_MESSAGE_3}} +... +``` + +## 贡献者 👥 + +感谢以下贡献者对本版本的贡献： + +- {{CONTRIBUTOR_1}} - {{贡献说明}} +- {{CONTRIBUTOR_2}} - {{贡献说明}} + +## 下一版本计划 + +### v{{NEXT_VERSION}} (计划中) + +- [ ] {{计划功能1}} +- [ ] {{计划功能2}} +- [ ] {{计划优化项}} + +## 获取此版本 + +### 源码下载 +```bash +git clone {{REPO_URL}} +git checkout v{{VERSION}} +``` + +### 二进制包 +- [Windows x64]({{DOWNLOAD_LINK}}) +- [Linux x64]({{DOWNLOAD_LINK}}) + +## 反馈和支持 + +- **Bug报告**: {{ISSUE_URL}} +- **功能请求**: {{FEATURE_REQUEST_URL}} +- **讨论**: {{DISCUSSION_URL}} +- **文档**: {{DOCS_URL}} + +--- + +**完整变更日志**: [v{{OLD_VERSION}}...v{{VERSION}}]({{COMPARE_URL}}) + +**归档位置**: `archives/versions/v{{VERSION}}/` diff --git a/ARCHIVE_USAGE_GUIDE.md b/ARCHIVE_USAGE_GUIDE.md new file mode 100644 index 0000000..79f0731 --- /dev/null +++ b/ARCHIVE_USAGE_GUIDE.md @@ -0,0 +1,450 @@ +# 自动归档配置使用指南 + +本文档说明如何使用项目的自动归档配置和辅助脚本。 + +--- + +## 配置文件 + +### `.claude/file_organization.json` + +这是主配置文件，定义了项目的文件组织规则，包括： + +- **目录结构定义**: 归档目录、文档目录、源码目录的路径和用途 +- **文件类型规则**: 不同文件扩展名的默认存放位置 +- **命名规范**: Bug修复、功能更新、版本发布的命名模板 +- **工作流规则**: 各类归档的标准流程 +- **自动分类规则**: 根据关键词自动识别归档类型 +- **模板路径**: 文档模板的位置 +- **脚本路径**: 辅助脚本的位置 + +### 配置加载 + +配置文件会被以下工具自动读取： +- Claude Code AI (自动识别文件组织规则) +- 辅助脚本 (使用配置生成归档) + +--- + +## 文档模板 + +模板位置: `.claude/templates/` + +### 1. `bug_fix_template.md` +Bug修复文档模板，包含以下占位符： +- `{{BUG_DESCRIPTION}}` - Bug描述 +- `{{DATE}}` - 日期 +- `{{AUTHOR}}` - 作者 +- `{{COMMIT_HASH}}` - Git提交哈希 +- `{{FILE_PATH}}` - 文件路径 +- 等等... + +### 2. `feature_update_template.md` +功能更新文档模板，包含以下占位符： +- `{{FEATURE_NAME}}` - 功能名称 +- `{{DATE}}` - 日期 +- `{{AUTHOR}}` - 开发者 +- `{{COMMIT_HASH}}` - Git提交哈希 +- 等等... + +### 3. `release_notes_template.md` +版本发布说明模板，包含以下占位符： +- `{{VERSION}}` - 版本号 +- `{{RELEASE_DATE}}` - 发布日期 +- `{{RELEASE_TYPE}}` - 发布类型 +- `{{COMMIT_COUNT}}` - 提交数量 +- 等等... + +--- + +## 辅助脚本 + +脚本位置: `scripts/` + +### 1. Bug修复归档脚本 + +**脚本**: `scripts/archive_bug_fix.sh` + +**功能**: +- 自动创建Bug修复归档目录结构 +- 生成Bug修复文档 +- 复制文档到快速查阅目录 + +**使用方法**: +```bash +# 基本用法 +./scripts/archive_bug_fix.sh + +# 指定作者 +./scripts/archive_bug_fix.sh "作者名称" + +# 示例 +./scripts/archive_bug_fix.sh path_tracking_error +./scripts/archive_bug_fix.sh csv_load_issue "张三" +``` + +**执行流程**: +1. 验证是否在项目根目录 +2. 创建归档目录: `archives/bug_fixes/YYYYMMDD_/` +3. 创建子目录: `code/`, `docs/`, `tests/` +4. 从模板生成文档并替换占位符 +5. 复制文档到 `docs/fixes/` 供快速查阅 +6. 显示下一步操作提示 + +**创建的目录结构**: +``` +archives/bug_fixes/20251115_path_tracking_error/ +├── code/ # 存放修复的代码文件 +├── docs/ # 存放详细文档 +│ └── BUG_path_tracking_error_20251115.md +└── tests/ # 存放测试文件 + +docs/fixes/ # 文档快速查阅副本 +└── BUG_path_tracking_error_20251115.md +``` + +--- + +### 2. 功能更新归档脚本 + +**脚本**: `scripts/archive_feature.sh` + +**功能**: +- 自动创建功能更新归档目录结构 +- 生成功能更新文档 +- 复制文档到快速查阅目录 + +**使用方法**: +```bash +# 基本用法 +./scripts/archive_feature.sh <功能名称> + +# 指定开发者 +./scripts/archive_feature.sh <功能名称> "开发者名称" + +# 示例 +./scripts/archive_feature.sh adaptive_lookahead +./scripts/archive_feature.sh dynamic_obstacle_avoidance "李四" +``` + +**执行流程**: +1. 验证是否在项目根目录 +2. 创建归档目录: `archives/updates/YYYYMMDD_<功能名称>/` +3. 创建子目录: `code/`, `docs/`, `tests/` +4. 从模板生成文档并替换占位符 +5. 复制文档到 `docs/updates/` 供快速查阅 +6. 显示下一步操作提示 + +**创建的目录结构**: +``` +archives/updates/20251115_adaptive_lookahead/ +├── code/ # 存放新增/修改的代码 +├── docs/ # 存放详细文档 +│ └── UPDATE_adaptive_lookahead_20251115.md +└── tests/ # 存放测试文件 + +docs/updates/ # 文档快速查阅副本 +└── UPDATE_adaptive_lookahead_20251115.md +``` + +--- + +### 3. 版本发布脚本 + +**脚本**: `scripts/create_release.sh` + +**功能**: +- 创建版本归档目录 +- 生成Release Notes +- 创建Git Tag +- 可选备份完整代码 + +**使用方法**: +```bash +# 基本用法 +./scripts/create_release.sh <版本号> + +# 指定发布类型 +./scripts/create_release.sh <版本号> + +# 示例 +./scripts/create_release.sh 1.2.0 +./scripts/create_release.sh 2.0.0 Major +./scripts/create_release.sh 1.2.1 Patch +``` + +**版本号格式**: X.Y.Z +- **X** (Major): 重大版本，可能包含不兼容的API变更 +- **Y** (Minor): 次要版本，新增功能但向后兼容 +- **Z** (Patch): 补丁版本，仅bug修复 + +**执行流程**: +1. 验证版本号格式和git仓库 +2. 确定发布类型 (自动或手动指定) +3. 创建版本目录: `archives/versions/vX.Y.Z/` +4. 统计提交和文件变更 +5. 生成Release Notes +6. 创建Git Tag +7. 可选：备份源码到归档目录 +8. 显示推送tag的命令 + +**创建的目录结构**: +``` +archives/versions/v1.2.0/ +├── release_notes.md # 版本发布说明 +└── backup/ # 可选：完整代码备份 + └── source_code.tar.gz +``` + +--- + +## 完整工作流程 + +### Bug修复流程 + +1. **在主代码目录修复bug** + ```bash + vim src/path_tracker.cpp + # 修复bug... + ``` + +2. **提交git** + ```bash + git add src/path_tracker.cpp + git commit -m "fix: 修复路径跟踪误差累积问题" + ``` + +3. **创建归档** + ```bash + ./scripts/archive_bug_fix.sh path_tracking_error "你的名字" + ``` + +4. **编辑文档** + ```bash + vim archives/bug_fixes/20251115_path_tracking_error/docs/BUG_path_tracking_error_20251115.md + # 填写详细的bug信息、原因分析、修复方案等 + ``` + +5. **复制相关文件到归档** + ```bash + # 复制修复的代码 + cp src/path_tracker.cpp archives/bug_fixes/20251115_path_tracking_error/code/ + + # 如有测试文件 + cp tests/test_path_tracker.cpp archives/bug_fixes/20251115_path_tracking_error/tests/ + ``` + +6. **提交归档** + ```bash + git add archives/bug_fixes/ docs/fixes/ + git commit -m "archive: Bug修复 - path_tracking_error" + ``` + +--- + +### 功能更新流程 + +1. **在主代码目录开发新功能** + ```bash + vim src/adaptive_lookahead.cpp + vim include/adaptive_lookahead.h + # 开发新功能... + ``` + +2. **提交git** + ```bash + git add src/adaptive_lookahead.cpp include/adaptive_lookahead.h + git commit -m "feature: 实现自适应前视距离算法" + ``` + +3. **创建归档** + ```bash + ./scripts/archive_feature.sh adaptive_lookahead "你的名字" + ``` + +4. **编辑文档** + ```bash + vim archives/updates/20251115_adaptive_lookahead/docs/UPDATE_adaptive_lookahead_20251115.md + # 填写功能说明、设计方案、使用方法等 + ``` + +5. **复制相关文件到归档** + ```bash + # 复制新增的代码 + cp src/adaptive_lookahead.cpp archives/updates/20251115_adaptive_lookahead/code/ + cp include/adaptive_lookahead.h archives/updates/20251115_adaptive_lookahead/code/ + + # 如有测试和示例 + cp tests/test_adaptive_lookahead.cpp archives/updates/20251115_adaptive_lookahead/tests/ + cp examples/example_adaptive.cpp archives/updates/20251115_adaptive_lookahead/code/ + ``` + +6. **提交归档** + ```bash + git add archives/updates/ docs/updates/ + git commit -m "archive: 功能更新 - adaptive_lookahead" + ``` + +--- + +### 版本发布流程 + +1. **确保所有变更已提交** + ```bash + git status + # 应该显示 "working tree clean" + ``` + +2. **运行发布脚本** + ```bash + ./scripts/create_release.sh 1.2.0 + ``` + +3. **编辑Release Notes** + ```bash + vim archives/versions/v1.2.0/release_notes.md + # 填写版本概述、新增功能、bug修复等 + ``` + +4. **提交归档** + ```bash + git add archives/versions/ + git commit -m "release: v1.2.0" + ``` + +5. **推送tag** + ```bash + git push origin v1.2.0 + ``` + +6. **在GitHub/GitLab创建Release** + - 上传编译好的二进制文件 + - 复制Release Notes内容 + - 发布 + +--- + +## AI辅助使用 + +当使用Claude Code时，AI会自动读取 `.claude/file_organization.json` 配置，并根据以下规则工作： + +### 自动识别归档类型 + +AI会根据关键词自动识别任务类型： + +- **Bug修复关键词**: bug, fix, 修复, 错误, 问题 + - 文件归档到: `archives/bug_fixes/` + - 文档归档到: `docs/fixes/` + +- **功能更新关键词**: feature, update, 新增, 功能, 更新, add, implement + - 文件归档到: `archives/updates/` + - 文档归档到: `docs/updates/` + +- **版本发布关键词**: version, release, 版本, 发布 + - 文件归档到: `archives/versions/` + +### 示例对话 + +``` +用户: 我发现了一个路径跟踪的bug，帮我修复并归档 + +AI: 我会帮你修复这个bug并按照项目规范归档。根据配置，我会： + 1. 修复代码 + 2. 创建归档目录 archives/bug_fixes/YYYYMMDD_path_tracking/ + 3. 生成修复文档 + 4. 复制代码和文档到相应位置 +``` + +``` +用户: 实现一个新的自适应前视距离功能 + +AI: 我会实现这个新功能并归档。根据配置，我会： + 1. 开发新功能代码 + 2. 创建归档目录 archives/updates/YYYYMMDD_adaptive_lookahead/ + 3. 生成功能文档 + 4. 创建使用示例 +``` + +--- + +## 目录快速参考 + +``` +project_root/ +├── .claude/ +│ ├── file_organization.json # 主配置文件 +│ └── templates/ # 文档模板 +│ ├── bug_fix_template.md +│ ├── feature_update_template.md +│ └── release_notes_template.md +│ +├── scripts/ # 辅助脚本 +│ ├── archive_bug_fix.sh # Bug修复归档 +│ ├── archive_feature.sh # 功能更新归档 +│ └── create_release.sh # 版本发布 +│ +├── archives/ # 归档目录 +│ ├── bug_fixes/ # Bug修复归档 +│ │ └── YYYYMMDD_bug名称/ +│ │ ├── code/ +│ │ ├── docs/ +│ │ └── tests/ +│ ├── updates/ # 功能更新归档 +│ │ └── YYYYMMDD_功能名称/ +│ │ ├── code/ +│ │ ├── docs/ +│ │ └── tests/ +│ └── versions/ # 版本归档 +│ └── vX.Y.Z/ +│ ├── release_notes.md +│ └── backup/ +│ +├── docs/ # 当前文档 +│ ├── fixes/ # Bug修复文档（快速查阅） +│ ├── updates/ # 功能更新文档（快速查阅） +│ ├── guides/ # 使用指南 +│ └── protocol/ # 协议文档 +│ +├── src/ # 源代码（主工作目录） +├── include/ # 头文件（主工作目录） +└── examples/ # 示例代码（主工作目录） +``` + +--- + +## 常见问题 + +### Q: 为什么要同时保存到归档目录和docs目录? + +A: +- **归档目录** (`archives/`): 完整归档，包含代码、文档、测试，用于长期保存和追溯 +- **文档目录** (`docs/`): 文档副本，方便快速查阅最新的修复和更新 + +### Q: 脚本在Windows上能用吗? + +A: 脚本是bash脚本，需要在Git Bash、WSL或Cygwin中运行。也可以手动执行脚本中的步骤。 + +### Q: 如何自定义模板? + +A: 直接编辑 `.claude/templates/` 下的模板文件，使用 `{{占位符}}` 格式添加自定义字段。 + +### Q: AI如何知道要使用这些配置? + +A: AI会自动读取 `.claude/file_organization.json` 配置文件，并根据其中的规则工作。 + +### Q: 可以修改归档路径吗? + +A: 可以，编辑 `.claude/file_organization.json` 中的 `directories` 部分，修改路径配置。 + +--- + +## 维护建议 + +1. **定期检查归档**: 每月检查归档目录，确保文档完整 +2. **更新模板**: 根据实际需求不断完善文档模板 +3. **脚本优化**: 根据使用反馈优化脚本功能 +4. **配置同步**: 团队成员保持配置文件一致 + +--- + +最后更新: 2025-11-15 diff --git a/FILE_ORGANIZATION.md b/FILE_ORGANIZATION.md new file mode 100644 index 0000000..e40a5c9 --- /dev/null +++ b/FILE_ORGANIZATION.md @@ -0,0 +1,276 @@ +# 文件组织规范 + +本文档定义了AGV路径跟踪项目的文件组织规范，用于管理bug修复、程序更新和版本归档。 + +## 目录结构 + +``` +agv_path_tracking/ +├── archives/ # 归档目录 +│ ├── bug_fixes/ # Bug修复归档 +│ │ └── YYYYMMDD_bug名称/ # 按日期和bug名称组织 +│ │ ├── code/ # 修复的代码文件 +│ │ ├── docs/ # 相关文档 +│ │ └── tests/ # 测试文件 +│ ├── updates/ # 功能更新归档 +│ │ └── YYYYMMDD_功能名称/ # 按日期和功能名称组织 +│ │ ├── code/ # 新增/修改的代码 +│ │ ├── docs/ # 更新文档 +│ │ └── tests/ # 测试文件 +│ └── versions/ # 版本归档 +│ └── vX.Y.Z/ # 按版本号组织 +│ ├── release_notes.md +│ └── backup/ # 完整代码备份 +├── docs/ # 项目文档 +│ ├── fixes/ # Bug修复文档（当前） +│ ├── updates/ # 功能更新文档（当前） +│ ├── guides/ # 使用指南 +│ └── protocol/ # 协议文档 +├── src/ # 源代码（主工作目录） +├── include/ # 头文件（主工作目录） +└── examples/ # 示例代码（主工作目录） +``` + +## 命名规范 + +### 1. Bug修复命名 +- **文件夹命名**: `YYYYMMDD_bug描述` + - 例如: `20251115_fix_path_tracking_error` +- **文件命名**: 保持原有文件名，或添加`_fixed`后缀 + - 例如: `path_tracker_fixed.cpp` + +### 2. 功能更新命名 +- **文件夹命名**: `YYYYMMDD_功能描述` + - 例如: `20251115_add_adaptive_lookahead` +- **文件命名**: 清晰描述功能 + - 例如: `adaptive_lookahead.cpp` + +### 3. 文档命名 +- **Bug修复文档**: `BUG_描述_日期.md` + - 例如: `BUG_path_tracking_error_20251115.md` +- **更新文档**: `UPDATE_功能描述_日期.md` + - 例如: `UPDATE_adaptive_lookahead_20251115.md` + +## 工作流程 + +### Bug修复流程 + +1. **创建工作目录** + ```bash + mkdir -p archives/bug_fixes/YYYYMMDD_bug名称/{code,docs,tests} + ``` + +2. **在主代码目录进行修复** + - 在 `src/`, `include/` 等目录直接修复bug + - 及时提交git commit + +3. **归档修复** + - 将修复的文件副本保存到 `archives/bug_fixes/YYYYMMDD_bug名称/code/` + - 创建修复文档保存到 `archives/bug_fixes/YYYYMMDD_bug名称/docs/` + - 同时在 `docs/fixes/` 创建文档副本供快速查阅 + +4. **文档内容应包含** + - Bug描述和复现步骤 + - 根本原因分析 + - 修复方案说明 + - 修改的文件列表 + - 测试验证结果 + - 相关的git commit ID + +### 功能更新流程 + +1. **创建工作目录** + ```bash + mkdir -p archives/updates/YYYYMMDD_功能名称/{code,docs,tests} + ``` + +2. **在主代码目录进行开发** + - 在 `src/`, `include/` 等目录添加新功能 + - 及时提交git commit + +3. **归档更新** + - 将新增/修改的文件副本保存到 `archives/updates/YYYYMMDD_功能名称/code/` + - 创建更新文档保存到 `archives/updates/YYYYMMDD_功能名称/docs/` + - 同时在 `docs/updates/` 创建文档副本供快速查阅 + +4. **文档内容应包含** + - 功能需求描述 + - 设计方案 + - 实现细节 + - API文档（如有） + - 使用示例 + - 测试结果 + - 相关的git commit ID + +### 版本发布流程 + +1. **创建版本目录** + ```bash + mkdir -p archives/versions/vX.Y.Z/backup + ``` + +2. **准备发布** + - 更新版本号 + - 编写 `release_notes.md` + - 汇总本版本所有bug修复和功能更新 + +3. **创建备份** + - 可选：将完整代码打包到 `archives/versions/vX.Y.Z/backup/` + - 创建git tag + +4. **发布说明应包含** + - 版本号和发布日期 + - 新增功能列表 + - Bug修复列表 + - 重大变更说明 + - 升级指南（如需要） + +## 文档模板 + +### Bug修复文档模板 + +```markdown +# Bug修复: [Bug简短描述] + +**日期**: YYYY-MM-DD +**修复者**: [姓名] +**相关Issue**: #[编号]（如有） + +## Bug描述 +[详细描述bug的表现] + +## 复现步骤 +1. [步骤1] +2. [步骤2] +3. [观察到的错误行为] + +## 根本原因 +[分析bug的根本原因] + +## 修复方案 +[描述如何修复这个bug] + +## 修改文件 +- `src/xxx.cpp` - [修改说明] +- `include/xxx.h` - [修改说明] + +## 测试验证 +[描述如何测试验证修复有效] + +## Git Commit +- Commit ID: [commit_hash] +- Commit Message: [message] + +## 备注 +[其他需要说明的内容] +``` + +### 功能更新文档模板 + +```markdown +# 功能更新: [功能名称] + +**日期**: YYYY-MM-DD +**开发者**: [姓名] +**相关Issue**: #[编号]（如有） + +## 功能概述 +[简要描述新功能的目的和价值] + +## 需求背景 +[为什么需要这个功能] + +## 设计方案 +[技术设计方案描述] + +### 架构变更 +[如有架构层面的变更，在此说明] + +### API设计 +[如果是库函数，描述API接口] + +## 实现细节 + +### 新增文件 +- `src/xxx.cpp` - [文件说明] +- `include/xxx.h` - [文件说明] + +### 修改文件 +- `src/yyy.cpp` - [修改说明] + +## 使用方法 +```cpp +// 示例代码 +``` + +## 测试结果 +[测试场景和结果] + +## Git Commit +- Commit ID: [commit_hash] +- Commit Message: [message] + +## 后续计划 +[如有待完善的内容] + +## 备注 +[其他需要说明的内容] +``` + +## 最佳实践 + +1. **及时归档**: 完成修复或更新后立即归档，不要拖延 +2. **详细文档**: 文档要详细清晰，方便他人理解和维护 +3. **代码备份**: 归档时保存相关代码的副本，便于追溯 +4. **版本控制**: 善用git，每次修复/更新都要commit +5. **交叉引用**: 文档中包含git commit ID，方便关联 +6. **定期整理**: 定期检查归档目录，清理过时内容 +7. **命名一致**: 严格遵循命名规范，保持一致性 + +## 快速参考 + +### 创建Bug修复归档 +```bash +DATE=$(date +%Y%m%d) +BUG_NAME="bug_description" +mkdir -p archives/bug_fixes/${DATE}_${BUG_NAME}/{code,docs,tests} +mkdir -p docs/fixes/ +# 编辑文档 +vim archives/bug_fixes/${DATE}_${BUG_NAME}/docs/BUG_${BUG_NAME}_${DATE}.md +# 复制到快速查阅目录 +cp archives/bug_fixes/${DATE}_${BUG_NAME}/docs/BUG_${BUG_NAME}_${DATE}.md docs/fixes/ +``` + +### 创建功能更新归档 +```bash +DATE=$(date +%Y%m%d) +FEATURE_NAME="feature_description" +mkdir -p archives/updates/${DATE}_${FEATURE_NAME}/{code,docs,tests} +mkdir -p docs/updates/ +# 编辑文档 +vim archives/updates/${DATE}_${FEATURE_NAME}/docs/UPDATE_${FEATURE_NAME}_${DATE}.md +# 复制到快速查阅目录 +cp archives/updates/${DATE}_${FEATURE_NAME}/docs/UPDATE_${FEATURE_NAME}_${DATE}.md docs/updates/ +``` + +### 查看归档历史 +```bash +# 查看所有bug修复 +ls -la archives/bug_fixes/ + +# 查看所有功能更新 +ls -la archives/updates/ + +# 查看所有版本 +ls -la archives/versions/ +``` + +## 维护说明 + +本规范文档应该： +- 随着项目发展持续更新 +- 被所有项目成员遵守 +- 在项目README中引用 + +最后更新: 2025-11-15 +``` diff --git a/README.md b/README.md index 9b92a72..0c3c381 100644 --- a/README.md +++ b/README.md @@ -104,6 +104,8 @@ chmod +x build.sh ### 🎯 快速参考 - [QUICK_REFERENCE.md](QUICK_REFERENCE.md) - 快速参考指南 - [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) - 完整项目结构 +- [FILE_ORGANIZATION.md](FILE_ORGANIZATION.md) - 文件组织规范 ⭐ +- [ARCHIVE_USAGE_GUIDE.md](ARCHIVE_USAGE_GUIDE.md) - 归档工具使用指南 ⭐ ### 📘 使用指南 - [docs/guides/START_HERE.txt](docs/guides/START_HERE.txt) - 新手入门 @@ -176,6 +178,14 @@ while (running) { ## 📝 更新日志 +### 2025-11-15 - 文件组织规范 +- ✅ 创建文件组织和归档配置系统 +- ✅ 添加Bug修复归档脚本 +- ✅ 添加功能更新归档脚本 +- ✅ 添加版本发布脚本 +- ✅ 创建文档模板系统 +- ✅ 编写详细的使用指南 + ### 2025-11-14 - 项目重组 - ✅ 重新组织项目文件结构 - ✅ 文档归类到 `docs/` 目录 diff --git a/scripts/archive_bug_fix.sh b/scripts/archive_bug_fix.sh new file mode 100644 index 0000000..e547436 --- /dev/null +++ b/scripts/archive_bug_fix.sh @@ -0,0 +1,229 @@ +#!/bin/bash + +# Bug修复归档脚本 +# 用途: 自动创建Bug修复归档目录结构，并生成文档模板 + +set -e + +# 颜色定义 +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# 打印带颜色的信息 +print_info() { + echo -e "${BLUE}[INFO]${NC} $1" +} + +print_success() { + echo -e "${GREEN}[SUCCESS]${NC} $1" +} + +print_warning() { + echo -e "${YELLOW}[WARNING]${NC} $1" +} + +print_error() { + echo -e "${RED}[ERROR]${NC} $1" +} + +# 检查是否在项目根目录 +check_project_root() { + if [ ! -f "FILE_ORGANIZATION.md" ]; then + print_error "请在项目根目录运行此脚本" + exit 1 + fi +} + +# 显示使用说明 +show_usage() { + echo "使用方法: $0 [作者名称]" + echo "" + echo "示例:" + echo " $0 path_tracking_error \"张三\"" + echo " $0 csv_load_issue" + echo "" + echo "说明:" + echo " - bug名称使用英文和下划线，如: path_tracking_error" + echo " - 作者名称可选，默认从git config获取" + exit 1 +} + +# 获取当前日期 +get_date() { + date +%Y%m%d +} + +# 获取作者名称 +get_author() { + if [ -n "$1" ]; then + echo "$1" + else + git config user.name || echo "Unknown" + fi +} + +# 获取最新的commit信息 +get_latest_commit() { + if git rev-parse --git-dir > /dev/null 2>&1; then + echo "$(git rev-parse --short HEAD)" + else + echo "N/A" + fi +} + +# 创建归档目录 +create_archive_dirs() { + local date=$1 + local bug_name=$2 + local archive_path="archives/bug_fixes/${date}_${bug_name}" + + print_info "创建归档目录: ${archive_path}" + + mkdir -p "${archive_path}/code" + mkdir -p "${archive_path}/docs" + mkdir -p "${archive_path}/tests" + mkdir -p "docs/fixes" + + print_success "目录创建完成" + echo "${archive_path}" +} + +# 生成文档 +create_document() { + local date=$1 + local bug_name=$2 + local author=$3 + local commit_hash=$4 + local archive_path=$5 + + local doc_name="BUG_${bug_name}_${date}.md" + local doc_path="${archive_path}/docs/${doc_name}" + local template_path=".claude/templates/bug_fix_template.md" + + print_info "生成文档: ${doc_name}" + + # 如果模板存在，使用模板；否则创建基本文档 + if [ -f "${template_path}" ]; then + cp "${template_path}" "${doc_path}" + + # 替换模板变量 + sed -i "s/{{BUG_DESCRIPTION}}/${bug_name}/g" "${doc_path}" + sed -i "s/{{DATE}}/${date}/g" "${doc_path}" + sed -i "s/{{AUTHOR}}/${author}/g" "${doc_path}" + sed -i "s/{{COMMIT_HASH}}/${commit_hash}/g" "${doc_path}" + sed -i "s/{{DATE}}_{{BUG_NAME}}/${date}_${bug_name}/g" "${doc_path}" + else + # 创建基本文档 + cat > "${doc_path}" << EOF +# Bug修复: ${bug_name} + +**日期**: ${date} +**修复者**: ${author} +**Git Commit**: ${commit_hash} + +--- + +## Bug描述 + +[详细描述bug的表现] + +## 复现步骤 + +1. [步骤1] +2. [步骤2] +3. [观察到的错误] + +## 根本原因 + +[分析bug的根本原因] + +## 修复方案 + +[描述修复方案] + +## 修改文件清单 + +- \`file1.cpp\` - [修改说明] + +## 测试验证 + +[测试结果] + +## Git提交信息 + +\`\`\` +Commit ID: ${commit_hash} +\`\`\` + +--- + +**归档位置**: \`archives/bug_fixes/${date}_${bug_name}/\` +EOF + fi + + # 复制到快速查阅目录 + cp "${doc_path}" "docs/fixes/${doc_name}" + + print_success "文档生成完成" + echo "${doc_path}" +} + +# 显示下一步操作 +show_next_steps() { + local doc_path=$1 + local archive_path=$2 + + echo "" + print_success "Bug修复归档创建完成!" + echo "" + echo "📁 归档目录: ${archive_path}" + echo "📄 文档位置: ${doc_path}" + echo "📋 快速查阅: docs/fixes/" + echo "" + print_info "下一步操作:" + echo " 1. 编辑文档: vim ${doc_path}" + echo " 2. 复制修复的代码到: ${archive_path}/code/" + echo " 3. 添加测试文件到: ${archive_path}/tests/" + echo " 4. 提交git: git add . && git commit -m \"archive: Bug修复 - ${bug_name}\"" + echo "" +} + +# 主函数 +main() { + # 检查参数 + if [ $# -lt 1 ]; then + show_usage + fi + + local bug_name=$1 + local author=$(get_author "$2") + + # 检查项目根目录 + check_project_root + + # 获取信息 + local date=$(get_date) + local commit_hash=$(get_latest_commit) + + print_info "开始创建Bug修复归档" + print_info "Bug名称: ${bug_name}" + print_info "日期: ${date}" + print_info "作者: ${author}" + print_info "Commit: ${commit_hash}" + echo "" + + # 创建目录 + local archive_path=$(create_archive_dirs "${date}" "${bug_name}") + + # 生成文档 + local doc_path=$(create_document "${date}" "${bug_name}" "${author}" "${commit_hash}" "${archive_path}") + + # 显示下一步操作 + show_next_steps "${doc_path}" "${archive_path}" +} + +# 运行主函数 +main "$@" diff --git a/scripts/archive_feature.sh b/scripts/archive_feature.sh new file mode 100644 index 0000000..e641311 --- /dev/null +++ b/scripts/archive_feature.sh @@ -0,0 +1,251 @@ +#!/bin/bash + +# 功能更新归档脚本 +# 用途: 自动创建功能更新归档目录结构，并生成文档模板 + +set -e + +# 颜色定义 +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# 打印带颜色的信息 +print_info() { + echo -e "${BLUE}[INFO]${NC} $1" +} + +print_success() { + echo -e "${GREEN}[SUCCESS]${NC} $1" +} + +print_warning() { + echo -e "${YELLOW}[WARNING]${NC} $1" +} + +print_error() { + echo -e "${RED}[ERROR]${NC} $1" +} + +# 检查是否在项目根目录 +check_project_root() { + if [ ! -f "FILE_ORGANIZATION.md" ]; then + print_error "请在项目根目录运行此脚本" + exit 1 + fi +} + +# 显示使用说明 +show_usage() { + echo "使用方法: $0 <功能名称> [开发者名称]" + echo "" + echo "示例:" + echo " $0 adaptive_lookahead \"李四\"" + echo " $0 dynamic_obstacle_avoidance" + echo "" + echo "说明:" + echo " - 功能名称使用英文和下划线，如: adaptive_lookahead" + echo " - 开发者名称可选，默认从git config获取" + exit 1 +} + +# 获取当前日期 +get_date() { + date +%Y%m%d +} + +# 获取开发者名称 +get_developer() { + if [ -n "$1" ]; then + echo "$1" + else + git config user.name || echo "Unknown" + fi +} + +# 获取最新的commit信息 +get_latest_commit() { + if git rev-parse --git-dir > /dev/null 2>&1; then + echo "$(git rev-parse --short HEAD)" + else + echo "N/A" + fi +} + +# 创建归档目录 +create_archive_dirs() { + local date=$1 + local feature_name=$2 + local archive_path="archives/updates/${date}_${feature_name}" + + print_info "创建归档目录: ${archive_path}" + + mkdir -p "${archive_path}/code" + mkdir -p "${archive_path}/docs" + mkdir -p "${archive_path}/tests" + mkdir -p "docs/updates" + + print_success "目录创建完成" + echo "${archive_path}" +} + +# 生成文档 +create_document() { + local date=$1 + local feature_name=$2 + local developer=$3 + local commit_hash=$4 + local archive_path=$5 + + local doc_name="UPDATE_${feature_name}_${date}.md" + local doc_path="${archive_path}/docs/${doc_name}" + local template_path=".claude/templates/feature_update_template.md" + + print_info "生成文档: ${doc_name}" + + # 如果模板存在，使用模板；否则创建基本文档 + if [ -f "${template_path}" ]; then + cp "${template_path}" "${doc_path}" + + # 替换模板变量 + sed -i "s/{{FEATURE_NAME}}/${feature_name}/g" "${doc_path}" + sed -i "s/{{DATE}}/${date}/g" "${doc_path}" + sed -i "s/{{AUTHOR}}/${developer}/g" "${doc_path}" + sed -i "s/{{COMMIT_HASH}}/${commit_hash}/g" "${doc_path}" + sed -i "s/{{DATE}}_{{FEATURE_NAME}}/${date}_${feature_name}/g" "${doc_path}" + else + # 创建基本文档 + cat > "${doc_path}" << EOF +# 功能更新: ${feature_name} + +**日期**: ${date} +**开发者**: ${developer} +**Git Commit**: ${commit_hash} + +--- + +## 功能概述 + +[简要描述新功能的目的和价值] + +## 需求背景 + +[详细描述需求背景和使用场景] + +## 设计方案 + +[技术设计方案描述] + +### 架构设计 + +[架构设计说明] + +### API设计 + +\`\`\`cpp +// 接口定义 +\`\`\` + +## 实现细节 + +### 新增文件 + +- \`file1.cpp\` - [文件说明] + +### 修改文件 + +- \`file2.cpp\` - [修改说明] + +## 使用方法 + +\`\`\`cpp +// 使用示例 +\`\`\` + +## 测试验证 + +[测试结果] + +## Git提交信息 + +\`\`\` +Commit ID: ${commit_hash} +\`\`\` + +## 后续计划 + +- [ ] [待完善项1] +- [ ] [待完善项2] + +--- + +**归档位置**: \`archives/updates/${date}_${feature_name}/\` +EOF + fi + + # 复制到快速查阅目录 + cp "${doc_path}" "docs/updates/${doc_name}" + + print_success "文档生成完成" + echo "${doc_path}" +} + +# 显示下一步操作 +show_next_steps() { + local doc_path=$1 + local archive_path=$2 + + echo "" + print_success "功能更新归档创建完成!" + echo "" + echo "📁 归档目录: ${archive_path}" + echo "📄 文档位置: ${doc_path}" + echo "📋 快速查阅: docs/updates/" + echo "" + print_info "下一步操作:" + echo " 1. 编辑文档: vim ${doc_path}" + echo " 2. 复制新增/修改的代码到: ${archive_path}/code/" + echo " 3. 添加测试文件到: ${archive_path}/tests/" + echo " 4. 更新使用示例到: examples/" + echo " 5. 提交git: git add . && git commit -m \"feature: ${feature_name}\"" + echo "" +} + +# 主函数 +main() { + # 检查参数 + if [ $# -lt 1 ]; then + show_usage + fi + + local feature_name=$1 + local developer=$(get_developer "$2") + + # 检查项目根目录 + check_project_root + + # 获取信息 + local date=$(get_date) + local commit_hash=$(get_latest_commit) + + print_info "开始创建功能更新归档" + print_info "功能名称: ${feature_name}" + print_info "日期: ${date}" + print_info "开发者: ${developer}" + print_info "Commit: ${commit_hash}" + echo "" + + # 创建目录 + local archive_path=$(create_archive_dirs "${date}" "${feature_name}") + + # 生成文档 + local doc_path=$(create_document "${date}" "${feature_name}" "${developer}" "${commit_hash}" "${archive_path}") + + # 显示下一步操作 + show_next_steps "${doc_path}" "${archive_path}" +} + +# 运行主函数 +main "$@" diff --git a/scripts/create_release.sh b/scripts/create_release.sh new file mode 100644 index 0000000..4a9c6aa --- /dev/null +++ b/scripts/create_release.sh @@ -0,0 +1,373 @@ +#!/bin/bash + +# 版本发布脚本 +# 用途: 创建版本发布归档，生成release notes，创建git tag + +set -e + +# 颜色定义 +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# 打印带颜色的信息 +print_info() { + echo -e "${BLUE}[INFO]${NC} $1" +} + +print_success() { + echo -e "${GREEN}[SUCCESS]${NC} $1" +} + +print_warning() { + echo -e "${YELLOW}[WARNING]${NC} $1" +} + +print_error() { + echo -e "${RED}[ERROR]${NC} $1" +} + +# 检查是否在项目根目录 +check_project_root() { + if [ ! -f "FILE_ORGANIZATION.md" ]; then + print_error "请在项目根目录运行此脚本" + exit 1 + fi +} + +# 检查是否在git仓库中 +check_git_repo() { + if ! git rev-parse --git-dir > /dev/null 2>&1; then + print_error "不在git仓库中" + exit 1 + fi +} + +# 显示使用说明 +show_usage() { + echo "使用方法: $0 <版本号> [发布类型]" + echo "" + echo "参数:" + echo " 版本号 格式: X.Y.Z (如: 1.2.0)" + echo " 发布类型 Major | Minor | Patch (可选，默认根据版本号判断)" + echo "" + echo "示例:" + echo " $0 1.2.0" + echo " $0 1.2.0 Minor" + echo " $0 2.0.0 Major" + echo "" + echo "说明:" + echo " - Major: 重大版本更新，可能包含不兼容的API变更" + echo " - Minor: 次要版本更新，新增功能但向后兼容" + echo " - Patch: 补丁版本，仅包含bug修复" + exit 1 +} + +# 验证版本号格式 +validate_version() { + local version=$1 + if ! [[ $version =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + print_error "版本号格式错误，应为 X.Y.Z" + exit 1 + fi +} + +# 判断发布类型 +determine_release_type() { + local version=$1 + local provided_type=$2 + + if [ -n "$provided_type" ]; then + echo "$provided_type" + return + fi + + # 自动判断 + local last_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0") + local last_version=${last_tag#v} + + IFS='.' read -r -a curr_parts <<< "$version" + IFS='.' read -r -a last_parts <<< "$last_version" + + if [ "${curr_parts[0]}" -gt "${last_parts[0]}" ]; then + echo "Major" + elif [ "${curr_parts[1]}" -gt "${last_parts[1]}" ]; then + echo "Minor" + else + echo "Patch" + fi +} + +# 获取当前日期 +get_date() { + date +%Y-%m-%d +} + +# 创建版本归档目录 +create_version_dirs() { + local version=$1 + local version_path="archives/versions/v${version}" + + print_info "创建版本归档目录: ${version_path}" + + mkdir -p "${version_path}/backup" + + print_success "目录创建完成" + echo "${version_path}" +} + +# 获取commit统计 +get_commit_stats() { + local last_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "") + + if [ -z "$last_tag" ]; then + # 如果没有tag，统计所有commit + git rev-list --count HEAD + else + # 统计从上个tag到现在的commit + git rev-list --count ${last_tag}..HEAD + fi +} + +# 获取变更的文件数 +get_changed_files() { + local last_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "") + + if [ -z "$last_tag" ]; then + git diff --name-only --diff-filter=ACMR | wc -l + else + git diff --name-only --diff-filter=ACMR ${last_tag}..HEAD | wc -l + fi +} + +# 生成release notes +create_release_notes() { + local version=$1 + local release_type=$2 + local release_date=$3 + local version_path=$4 + + local notes_path="${version_path}/release_notes.md" + local template_path=".claude/templates/release_notes_template.md" + + print_info "生成Release Notes: ${notes_path}" + + local commit_count=$(get_commit_stats) + local file_count=$(get_changed_files) + local last_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0") + local last_version=${last_tag#v} + + # 如果模板存在，使用模板 + if [ -f "${template_path}" ]; then + cp "${template_path}" "${notes_path}" + + # 替换模板变量 + sed -i "s/{{VERSION}}/${version}/g" "${notes_path}" + sed -i "s/{{RELEASE_DATE}}/${release_date}/g" "${notes_path}" + sed -i "s/{{RELEASE_TYPE}}/${release_type}/g" "${notes_path}" + sed -i "s/{{COMMIT_COUNT}}/${commit_count}/g" "${notes_path}" + sed -i "s/{{FILE_COUNT}}/${file_count}/g" "${notes_path}" + sed -i "s/{{OLD_VERSION}}/${last_version}/g" "${notes_path}" + sed -i "s/{{PREVIOUS_VERSION}}/${last_version}/g" "${notes_path}" + else + # 创建基本release notes + cat > "${notes_path}" << EOF +# Release Notes - v${version} + +**发布日期**: ${release_date} +**版本号**: ${version} +**发布类型**: ${release_type} + +--- + +## 版本概述 + +[简要描述本版本的主要更新内容] + +## 重要变更 ⚠️ + +[列出所有重大变更] + +## 新增功能 ✨ + +- [功能1] +- [功能2] + +## Bug修复 🐛 + +- [Bug修复1] +- [Bug修复2] + +## 性能优化 🚀 + +- [优化项1] +- [优化项2] + +## 统计数据 + +- **总提交数**: ${commit_count} +- **修改文件数**: ${file_count} +- **上一版本**: ${last_version} + +## 升级指南 + +### 从 v${last_version} 升级 + +1. 备份当前版本 +2. 更新代码 +3. 重新编译 +4. 测试验证 + +## 获取此版本 + +\`\`\`bash +git clone +git checkout v${version} +\`\`\` + +--- + +**归档位置**: \`archives/versions/v${version}/\` +EOF + fi + + print_success "Release Notes生成完成" + echo "${notes_path}" +} + +# 创建git tag +create_git_tag() { + local version=$1 + local tag_name="v${version}" + + print_info "检查是否已存在tag: ${tag_name}" + + if git rev-parse "${tag_name}" >/dev/null 2>&1; then + print_warning "Tag ${tag_name} 已存在" + read -p "是否删除并重新创建? (y/N): " -n 1 -r + echo + if [[ $REPLY =~ ^[Yy]$ ]]; then + git tag -d "${tag_name}" + print_info "已删除旧tag" + else + print_info "跳过创建tag" + return + fi + fi + + print_info "创建git tag: ${tag_name}" + git tag -a "${tag_name}" -m "Release version ${version}" + print_success "Git tag创建完成" + + echo "" + print_info "推送tag到远程仓库:" + echo " git push origin ${tag_name}" +} + +# 可选：备份代码 +backup_code() { + local version_path=$1 + + echo "" + read -p "是否备份完整代码到归档目录? (y/N): " -n 1 -r + echo + + if [[ $REPLY =~ ^[Yy]$ ]]; then + print_info "创建代码备份..." + + local backup_file="${version_path}/backup/source_code.tar.gz" + + tar -czf "${backup_file}" \ + --exclude='.git' \ + --exclude='build' \ + --exclude='archives' \ + --exclude='*.o' \ + --exclude='*.so' \ + --exclude='*.dll' \ + src/ include/ examples/ CMakeLists.txt + + print_success "代码备份完成: ${backup_file}" + else + print_info "跳过代码备份" + fi +} + +# 显示下一步操作 +show_next_steps() { + local version=$1 + local notes_path=$2 + local version_path=$3 + + echo "" + print_success "版本发布归档创建完成!" + echo "" + echo "📁 版本目录: ${version_path}" + echo "📄 Release Notes: ${notes_path}" + echo "🏷️ Git Tag: v${version}" + echo "" + print_info "下一步操作:" + echo " 1. 编辑Release Notes: vim ${notes_path}" + echo " 2. 检查并补充版本信息" + echo " 3. 提交归档: git add archives/versions/ && git commit -m \"release: v${version}\"" + echo " 4. 推送tag: git push origin v${version}" + echo " 5. 在GitHub/GitLab创建Release" + echo "" +} + +# 主函数 +main() { + # 检查参数 + if [ $# -lt 1 ]; then + show_usage + fi + + local version=$1 + local release_type=$2 + + # 验证版本号 + validate_version "${version}" + + # 检查环境 + check_project_root + check_git_repo + + # 确定发布类型 + release_type=$(determine_release_type "${version}" "${release_type}") + + # 获取日期 + local release_date=$(get_date) + + print_info "开始创建版本发布" + print_info "版本号: ${version}" + print_info "发布类型: ${release_type}" + print_info "发布日期: ${release_date}" + echo "" + + # 确认 + read -p "确认创建版本 v${version}? (y/N): " -n 1 -r + echo + if [[ ! $REPLY =~ ^[Yy]$ ]]; then + print_info "取消操作" + exit 0 + fi + + # 创建版本目录 + local version_path=$(create_version_dirs "${version}") + + # 生成Release Notes + local notes_path=$(create_release_notes "${version}" "${release_type}" "${release_date}" "${version_path}") + + # 创建Git Tag + create_git_tag "${version}" + + # 可选备份 + backup_code "${version_path}" + + # 显示下一步操作 + show_next_steps "${version}" "${notes_path}" "${version_path}" +} + +# 运行主函数 +main "$@" diff --git a/src/can/CANController.h b/src/can/CANController.h deleted file mode 100644 index e482461..0000000 --- a/src/can/CANController.h +++ /dev/null @@ -1,109 +0,0 @@ -/** - * CAN 控制器封装类 - * 功能：简化 CAN 设备的操作，提供易用的接口 - */ - -#ifndef CAN_CONTROLLER_H -#define CAN_CONTROLLER_H - -#include "../../lib/ControlCAN.h" -#include -#include -#include - -/** - * CAN 控制器类 - */ -class CANController { -public: - // 回调函数类型：接收到 CAN 数据时调用 - using ReceiveCallback = std::function; - - /** - * 构造函数 - * @param device_type 设备类型（VCI_USBCAN2 = 4） - * @param device_index 设备索引（第几个设备，从0开始） - * @param can_index CAN 通道索引（0 或 1） - */ - CANController(DWORD device_type = VCI_USBCAN2, - DWORD device_index = 0, - DWORD can_index = 0); - - ~CANController(); - - /** - * 初始化 CAN 设备 - * @param baud_t0 波特率定时器0 - * @param baud_t1 波特率定时器1 - * @param mode 工作模式：0=正常，1=只听，2=自发自收 - * @return 成功返回 true - */ - bool Initialize(BYTE baud_t0 = 0x00, BYTE baud_t1 = 0x1C, BYTE mode = 0); - - /** - * 关闭 CAN 设备 - */ - void Close(); - - /** - * 发送标准帧 - * @param can_id CAN ID（11位） - * @param data 数据指针 - * @param len 数据长度（最大8字节） - * @return 成功返回 true - */ - bool SendStandardFrame(UINT can_id, const BYTE* data, BYTE len); - - /** - * 发送扩展帧 - * @param can_id CAN ID（29位） - * @param data 数据指针 - * @param len 数据长度（最大8字节） - * @return 成功返回 true - */ - bool SendExtendedFrame(UINT can_id, const BYTE* data, BYTE len); - - /** - * 接收 CAN 数据（非阻塞） - * @param frames 接收缓冲区 - * @param max_count 最大接收帧数 - * @return 实际接收到的帧数 - */ - DWORD Receive(std::vector& frames, DWORD max_count = 2500); - - /** - * 获取接收缓冲区中的帧数量 - */ - DWORD GetReceiveNum(); - - /** - * 清空接收缓冲区 - */ - bool ClearBuffer(); - - /** - * 读取设备信息 - */ - bool GetDeviceInfo(VCI_BOARD_INFO& info); - - /** - * 设置接收回调函数 - */ - void SetReceiveCallback(ReceiveCallback callback) { - m_callback = callback; - } - - /** - * 是否已初始化 - */ - bool IsInitialized() const { return m_initialized; } - -private: - DWORD m_device_type; - DWORD m_device_index; - DWORD m_can_index; - bool m_initialized; - ReceiveCallback m_callback; -}; - -#endif // CAN_CONTROLLER_H