Snowbot Mechanical 仓库上传规范与 PowerShell 操作手册

PUB-2604-0015-DOC · 1.0

Barcode ARCP978SJFFK6

一、用途

本文件用于规范 Snowbot 机械结构设计文件的正式交付路径。
适用对象：结构设计工程师、兼职工程师、外包工程师。
适用仓库：arcbos/snowbot-mechanical
核心原则：所有正式交付必须进入 GitHub 仓库；未进入 GitHub 的内容，不视为正式交付。

二、仓库信息

GitHub 组织：arcbos
仓库名称：snowbot-mechanical
仓库地址：https://github.com/arcbos/snowbot-mechanical
默认分支：main

三、交付总原则

1. 所有结构相关正式交付，统一进入 GitHub 仓库。
2. 所有文件必须放入正确目录，不允许乱放。
3. 所有交付必须可追踪、可复用、可接手。
4. 仅聊天说明、仅截图、仅口头说明，不构成正式交付。
5. 无源文件、无仓库记录、无实际推进作用的，不计入有效提交。
6. 后续工程结算、验收与进度确认，统一以 GitHub 仓库中的正式记录为准。

四、仓库目录规范

snowbot-mechanical/
├─ 00_admin/                # 项目管理、规范、需求
├─ 01_overall/              # 整机/总装
├─ 02_chassis/              # 底盘结构
├─ 03_mobility/             # 行走系统（驱动、履带/轮组、张紧）
├─ 04_snow-head/            # 前端除雪机构（绞龙/抛雪/推雪）
├─ 05_power-bay/            # 电池仓/电源结构
├─ 06_equipment/            # 电控设备安装结构
├─ 07_body/                 # 外壳/装甲/盖板
├─ 08_interfaces/           # 模块接口结构
├─ 09_service/              # 维护/检修结构
├─ drawings/                # 工程图
├─ exports/
│  ├─ step/                 # STEP导出
│  ├─ pdf/                  # PDF导出
│  └─ dxf/                  # DXF导出（如适用）
└─ release/                 # 冻结版本

五、文件类型要求

每次正式提交，至少应包含以下一种或多种：

1. 原始设计文件（如 SolidWorks）
2. STEP 文件
3. 关键 2D 工程图
4. 总装图 / 分总成图
5. 必要的结构说明文件
6. 如有修订，必须附修订说明
7. 如涉及装配推进，应附装配支撑记录或相关说明

六、命名规范

统一命名格式：
模块_部件_版本_日期

例如：

chassis_frame_V1_20260420.step
battery_bay_V2_20260420.SLDPRT
front_interface_V1_20260420.pdf

禁止使用：

最终版
最新版
test
new
改改改
123

七、正式交付判定标准

以下条件同时满足时，才可视为正式交付：

1. 文件已上传至公司指定 GitHub 仓库
2. 文件放在正确目录
3. 文件可打开、可复用、可接手
4. 具备必要源文件或工程文件
5. 对当前样机推进有实际作用

以下情况不构成交付：

1. 仅口头说明
2. 仅微信聊天记录
3. 仅截图或渲染图
4. 未上传到 GitHub 的本地文件
5. 无源文件或无法复用的零散文件

八、PowerShell + GitHub 上传操作手册

1. 前提准备

在开始前，需确保以下条件已满足：

1. 已安装 Git for Windows
   下载地址：https://git-scm.com/download/win

2. 已拥有 GitHub 账号

3. 已被授予 arcbos/snowbot-mechanical 仓库访问权限

2. 获取 GitHub Personal Access Token

GitHub 推送代码时，通常不再直接使用账户密码，而使用 Personal Access Token。

获取路径：

GitHub 右上角头像
→ Settings
→ Developer settings
→ Personal access tokens
→ Generate new token

要求：

1. 至少授予 repo 相关权限
2. 生成后复制保存 token
3. token 只会显示一次，丢失需重新生成

3. 打开 PowerShell

例如在 D 盘创建工作目录：

cd D:\
mkdir work
cd work

4. 克隆仓库

git clone https://github.com/arcbos/snowbot-mechanical.git
cd snowbot-mechanical

说明：

1. 该命令会将远端仓库完整拉到本地
2. 后续所有正式交付文件，都必须放在该本地仓库目录中
3. 不允许脱离仓库单独维护交付文件夹

5. 查看当前目录结构

dir

6. 将本地工作文件放入对应目录

例如将本地文件复制到底盘目录：

Copy-Item "D:\ChenChao\SnowbotFiles\*" ".\02_chassis\" -Recurse

要求：

1. 必须按模块放入对应目录
2. 不允许将所有文件直接丢在根目录
3. 原始文件、STEP、工程图尽量分别归档

7. 首次配置 Git 用户信息（仅需一次）

git config --global user.name "你的GitHub用户名"
git config --global user.email "你的GitHub邮箱"

例如：

git config --global user.name "chenchao"
git config --global user.email "your_email@example.com"

8. 查看本次修改状态

git status

9. 添加文件到提交区

全部添加：

git add .

如仅添加某些目录：

git add .\02_chassis
git add .\exports\step
git add .\drawings

10. 提交说明

git commit -m "Alpha结构提交：底盘主结构、电池仓、STEP与工程图"

要求：

1. 提交说明必须写清楚本次提交内容
2. 禁止使用 update、test、aaa 等无意义说明

11. 推送到远端仓库

git push origin main

若系统提示输入用户名和密码：

用户名：GitHub 用户名
密码位置：填写 Personal Access Token，不填写 GitHub 登录密码

12. 验证是否成功

推送成功后：

1. 打开仓库页面：https://github.com/arcbos/snowbot-mechanical
2. 检查文件是否已出现在正确目录
3. 检查 commit 记录是否存在

也可在 PowerShell 中查看最近提交记录：

git log --oneline -n 5

13. 后续每周标准流程

cd D:\work\snowbot-mechanical
git pull origin main
# 放入新文件或修改文件
git status
git add .
git commit -m "本周结构更新说明"
git push origin main

九、常见错误与处理

1. 权限错误

原因：未被授予仓库权限，或 token 权限不足。
处理：检查仓库权限和 token 设置。

2. 认证失败

原因：推送时填写了 GitHub 登录密码，而不是 token。
处理：重新输入 Personal Access Token。

3. 分支冲突

原因：本地落后于远端。
处理：先拉取远端更新。
git pull origin main

4. 大文件无法推送

原因：文件体积过大，可能需启用 Git LFS。
处理：如遇到该问题，再单独配置 Git LFS。

十、最终要求

从正式执行日起，所有结构交付统一按本文件执行。

即：
1. 文件必须按仓库目录归档
2. 必须有源文件
3. 必须在 GitHub 可追踪
4. 必须可复用、可接手
5. 必须对样机推进有实际作用

后续所有进度确认、有效提交认定与结算，统一以 GitHub 仓库中的正式记录为准。

一句话原则：
不进 GitHub，不算交付。