# docs/git_workflow.md — Git 操作手册

> 项目:TPS 中台
> 仓库:`tps-dashboard`(单位 Gitea)
> 文档版本:v1 · 2026-05-06
> 受众:**制片人(不会 Git)** + Cline(自动遵守此规则)

---

## 阅读说明

本手册分两部分:

- **第 1-3 章**:**给制片人看的**——每一步具体到敲哪条命令、看到什么算成功
- **第 4-5 章**:**给 Cline 看的规则**——commit 规范、提交时机、Cline 的边界

不会 Git 没关系——**照本宣科,你只需要会复制粘贴**。

---

## 第 1 章:基础概念(只讲能用上的)

### 1.1 三个核心概念,一分钟搞定

**Git 仓库**:就是一个"被 Git 管起来的文件夹"。打开本地 `D:\TPS-中台\` 这个文件夹,里面有所有项目文件 + 一个隐藏的 `.git` 子目录。**不要删 `.git`**,删了等于把保险撕了。

**commit(提交)**:相当于"存档"。每一次 commit 是一个时间点的快照,以后可以回到这个时间点。

**push(推送)**:把本地的 commit 同步到 Gitea 服务器。**push 之后才算"上传"了**,不 push 同事看不到。

**pull(拉取)**:把 Gitea 上的最新代码拉到本地。多设备开发时,**每天开工第一件事就是 pull**。

### 1.2 用菜场买菜类比

- 在家做饭(写代码)= 本地修改
- 用保鲜盒装好放冰箱(commit) = 本地存档
- 把保鲜盒带去单位食堂大冰柜(push) = 推到 Gitea
- 同事来食堂找出你的盒子带回家(pull) = 拉到他自己电脑

只要保鲜盒进了食堂大冰柜,谁来都能拿。

---

## 第 2 章:首次仓库初始化(Phase 0 Day 1 下午做)

> 单位 4090D 已装 Git、已配 用户名+邮箱(爱德华项目时弄好)。本章从创建新仓库开始。

### 2.1 在 Gitea 创建新仓库

**操作位置**:浏览器打开单位 Gitea 网址(就是你登爱德华项目的那个 Gitea)

1. 右上角点 `+` → 选 `新建仓库`(或英文 `New Repository`)
2. 填写表单:
   - **仓库名称**:`tps-dashboard`
   - **描述**:`TPS 中台 — 央视《军事科技》栏目内部工作台`
   - **可见性**:勾选 **"私有"** 或 **"团队可见"**(注意:跟爱德华那个公开仓库**不一样**,这个不公开)
   - **勾选项一定不要勾**:**不要勾** "Initialize Repository(With selected files and template)" —— 我们要的是空仓库
3. 点底部 `创建仓库`

**成功标志**:页面跳到一个新页面,显示 `tps-dashboard` 是空的,中间有一段灰底的命令提示,大概长这样(具体地址你以你那台 Gitea 的 URL 为准):

```
git clone http://localhost:3000/simonkoson/tps-dashboard.git
```

**把这一行复制下来,下一步要用**。

### 2.2 在本地 clone 仓库

**操作位置**:VS Code 打开任何窗口都行,在终端面板里执行(快捷键 `Ctrl + ` `)

```powershell
# 切换到你想放项目的位置
cd Z:\AIworks\

# 把刚才复制的 clone 命令粘贴运行
git clone http://localhost:3000/simonkoson/tps-dashboard.git
```

**期间可能要求输入 Gitea 账号密码**——输入即可,Git 会记住。

**成功标志**:终端显示类似:
```
Cloning into 'tps-dashboard'...
warning: You appear to have cloned an empty repository.
done.
```

`warning: empty repository` 是**正常的**——本来就是空仓库,不是错误。

完成后 `Z:\AIworks\` 下多了一个 `tps-dashboard` 文件夹。

### 2.3 进仓库目录

```powershell
cd Z:\AIworks\tps-dashboard
```

之后所有 git 命令都在这个目录里跑。

### 2.4 把五件套 + log 拷进来

> 你应该已经从 Claude.ai 下载了这五份文件:`.clinerules`、`project_plan.md`、`dev_plan.md`、`docs/git_workflow.md`、`README.md`,加上 `logs/phase1_log.md`。

**手动操作**(用 Windows 资源管理器):

1. 在 `Z:\AIworks\tps-dashboard\` 下:
   - 直接拷入 `.clinerules`、`project_plan.md`、`dev_plan.md`、`README.md`(平铺四份)
   
2. 在 `Z:\AIworks\tps-dashboard\` 下**新建文件夹** `docs`,把 `git_workflow.md` 拷进去

3. 在 `Z:\AIworks\tps-dashboard\` 下**新建文件夹** `logs`,把 `phase1_log.md` 拷进去

**最终结构应该是**:

```
Z:\AIworks\tps-dashboard\
├── .clinerules
├── project_plan.md
├── dev_plan.md
├── README.md
├── docs\
│   └── git_workflow.md
└── logs\
    └── phase1_log.md
```

### 2.5 创建 .gitignore

`.gitignore` 是"告诉 Git 哪些文件不要管"的清单。

**操作**:在 VS Code 终端里执行:

```powershell
cd Z:\AIworks\tps-dashboard
notepad .gitignore
```

记事本会弹出来(可能问你"找不到文件,要创建吗?"——选 **是**)。

把下面这些粘贴进去,**保存**:

```
# Python
__pycache__/
*.pyc
*.pyo
*.pyd
.venv/
venv/
env/

# Node
node_modules/
dist/
build/
.vite/

# 环境配置(永远不上传)
.env
.env.local

# 编辑器
.vscode/
.idea/
*.swp

# 操作系统
.DS_Store
Thumbs.db

# 日志运行产物
*.log
cookie.txt

# 临时文件
*.tmp
*.bak
```

### 2.6 第一次 commit 和 push

**操作**:VS Code 终端里依次执行:

**第 1 条:看看 Git 看到了哪些文件**

```powershell
git status
```

**成功标志**:终端会列出一堆文件(.clinerules、project_plan.md 等),颜色应该是**红色**(表示"未跟踪")。

**第 2 条:把所有文件加进暂存区**

```powershell
git add -A
```

**成功标志**:命令执行无任何输出(Git 的传统是"没消息就是好消息")。再跑一次 `git status`,文件应该变成**绿色**了。

**第 3 条:第一次 commit**

```powershell
git commit -m "chore: 项目宪法五件套 + Phase 1 家用机日志初始化"
```

**成功标志**:终端显示类似:
```
[main (root-commit) abc1234] chore: 项目宪法五件套 + Phase 1 家用机日志初始化
 6 files changed, 1234 insertions(+)
 create mode 100644 .clinerules
 ...
```

**第 4 条:推送到 Gitea**

```powershell
git push -u origin main
```

> 如果你的 Gitea 默认分支不叫 main 而叫 master,把命令里的 `main` 换成 `master`。

**期间可能要求输入 Gitea 账号密码**,输入即可。

**成功标志**:终端显示类似:
```
Enumerating objects: ...
Writing objects: 100% (...)
To http://localhost:3000/simonkoson/tps-dashboard.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.
```

### 2.7 验证:浏览器看 Gitea

刷新一下 Gitea 那个 `tps-dashboard` 页面——**应该能看到所有文件出现了**,不再是空仓库。

**到此 Phase 0 Day 1 下午的 Git 部分完成**。继续 Day 2 装 VS Code + Cline。

---

## 第 3 章:日常使用(每天会用到的命令)

### 3.1 每天开工第一件事

```powershell
cd Z:\AIworks\tps-dashboard
git status                # 看看本地有没有未提交的改动
git pull                  # 拉 Gitea 最新(如果别的机器推过)
```

### 3.2 每次离开机器前

```powershell
git status                # 看看有没有未提交的
# 如果有改动,让 Cline 自己 commit + push;
# 或者你手工(下面)
```

### 3.3 让 Cline 帮你提交

最方便的方式——**让 Sonnet 在 Plan 里下命令**:

> "现在改完了,请帮我 commit + push,commit message 写: feat: 添加 XXX 功能"

Cline(Sonnet → DeepSeek)会自动跑 git add / git commit / git push。**这是默认推荐方式**。

### 3.4 你自己手工提交(备选)

```powershell
cd Z:\AIworks\tps-dashboard
git add -A
git commit -m "fix: 修复登录页跳转问题"
git push
```

### 3.5 Phase 收尾仪式(打 tag)

每完成一个 Phase,**让 Cline 替你做这一套动作**:

```powershell
git tag -a phase1-complete -m "Phase 1 后端 + 前端骨架完工"
git push origin phase1-complete
```

**tag 命名规则**(`.clinerules` 第 7.4 节锁定):

- `phase0-env-ready`
- `phase1-complete`
- `phase2-dashboard-done`
- `phase3-knowledge-base`
- `phase4a-mvp-launch` ← **这是项目第一次对内发布,郑重一点**
- `phase4b-tps-complete`
- `phase4c-radar`
- `phase5-production` ← **这是项目正式上线**

---

## 第 4 章:commit message 规范(给 Cline 守的规矩)

### 4.1 格式

```
<type>: <中文正文>

[可选:更详细的中文说明]
```

### 4.2 type 取值表

| type | 中文 | 示例 |
|---|---|---|
| `feat` | 新功能 | `feat: 添加用户登录接口` |
| `fix` | 修 bug | `fix: 修复 created_at 字段 NOT NULL 报错` |
| `docs` | 改文档 | `docs: 更新 phase1_log` |
| `chore` | 杂项(依赖、配置)| `chore: 升级 bcrypt 到 4.0.1` |
| `refactor` | 重构 | `refactor: 重构 authStore 状态管理` |
| `style` | 格式化(空格/缩进)| `style: 统一前端缩进为 2 空格` |
| `test` | 加测试 | `test: 添加 auth 接口测试` |

**前缀英文小写,正文中文**——前缀方便工具分类,正文方便人阅读。

### 4.3 提交时机

每个独立动作单独 commit,**不要堆一坨大 commit**:

- 装完依赖 → 立刻 commit
- 建完 SQL 表 → 立刻 commit
- 写完一个完整接口 → 立刻 commit
- 修完一个 bug → 立刻 commit

**禁止**:"晚上一起 commit"或"一个 commit 多功能"。

---

## 第 5 章:Cline 的 Git 边界(给 AI 守的规矩)

### 5.1 Cline 可以自动执行(无需问用户)

- `git add`
- `git commit`
- `git push`(限当前分支)
- `git pull`
- `git status`
- `git log`(查看历史)
- `git tag -a` + `git push origin <tag>`

### 5.2 Cline 必须停下问用户

- `git reset --hard`(任何形式的 hard reset)
- `git push --force` / `git push -f`
- `git rebase`(任何形式)
- 删除分支:`git branch -d` / `git branch -D`
- 删除 tag:`git tag -d` / `git push origin --delete <tag>`
- 删除远程引用

### 5.3 永远禁止

- 删除整个 `.git/` 目录
- 修改 `.git/` 目录内任何文件

---

## 第 6 章:常见问题速查

### Q1:我推不上去,提示"Permission denied"

**原因**:Gitea 账号密码错或没权限
**解决**:确认你登录 Gitea 网页版能正常访问 `tps-dashboard` 仓库;如果能,重新输入账号密码即可。

### Q2:`git push` 时提示"rejected,请先 pull"

**原因**:Gitea 上有别的设备推过新内容,本地落后了
**解决**:先 `git pull`,再 `git push`。如果 pull 时报 conflict(冲突),停下问 Cline 或我。

### Q3:`git status` 看到一堆 .pyc 或 node_modules

**原因**:`.gitignore` 没生效
**解决**:确认 `.gitignore` 文件就在仓库根目录(`D:\tps-dashboard\.gitignore`),内容跟第 2.5 节一致。

### Q4:不小心 commit 了 .env 文件怎么办

**严重**:`.env` 含密码,绝不能进 Gitea。
**解决**:**立刻停下找 Claude Opus 4.7 处理**——这事儿要小心做,不要自己瞎搞,容易把历史搞乱。

### Q5:换了一台机器,怎么把代码搞过来

```powershell
cd Z:\AIworks\tps-dashboard
git clone http://localhost:3000/simonkoson/tps-dashboard.git
cd tps-dashboard
# 然后跟原来一样开工就行
```

### Q6:某次 commit 写错了想撤回

**只在最近一次 commit 还没 push 时可撤回**:

```powershell
git reset HEAD~1     # 撤回最近一次 commit,文件改动保留
```

**已经 push 的 commit**:不要自行处理,找 Claude Opus 4.7。

---

## 第 7 章:多设备同步(已废弃)

> ⚠️ **2026-05-14 更新**:家用机已于 2026-05-14 退役,项目统一在单位 4090D 开发。
> 本章描述的多设备同步模式**已废弃**,保留仅供历史参考。
> 当前工作流:单一开发机,每日开工 `git pull`,离开前 `git push`。

---

### 7.1 历史模式(已废弃)

#### 离开 A 机器前

```powershell
git status         # 看有没有未提交的
git add -A         # 加进暂存
git commit -m "..."
git push
```

### 到 B 机器开工

```powershell
git pull           # 拉最新
git status         # 确认干净
# 开始干活
```

**铁律**:**永远在 push 之前 pull**,永远在开工前 pull。这两条做到,99% 不会冲突。

---

## 第 8 章:版本演进

| 版本 | 日期 | 变化 |
|---|---|---|
| v1 | 2026-05-06 | 初版 |
| **v2** | **2026-05-14** | **项目目录从 NAS(Z:\AIworks\)迁移至本地 SSD(E:\tps-dashboard\);家用机退役,唯一开发环境为单位 4090D;Phase 2 起 MiniMax M2.7 正式日常使用;更新版本演进记录** |

---

*本文件与 `.clinerules` 第七章互为补充。Cline 必须遵守第 4-5 章规则。*