chore: 项目宪法五件套 + Phase 1 家用机日志初始化

2026-05-08 17:43:08 +08:00
commit f1170dbe01
7 changed files with 2034 additions and 0 deletions
@@ -0,0 +1,438 @@
+# 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://你的Gitea地址/你的用户名/tps-dashboard.git
+```
+
+**把这一行复制下来,下一步要用**。
+
+### 2.2 在本地 clone 仓库
+
+**操作位置**:VS Code 打开任何窗口都行,在终端面板里执行(快捷键 `Ctrl + ` `)
+
+```powershell
+# 切换到你想放项目的位置(避免中文路径,推荐 D:\)
+cd D:\
+
+# 把刚才复制的 clone 命令粘贴运行
+git clone http://你的Gitea地址/你的用户名/tps-dashboard.git
+```
+
+**期间可能要求输入 Gitea 账号密码**——输入即可,Git 会记住。
+
+**成功标志**:终端显示类似:
+```
+Cloning into 'tps-dashboard'...
+warning: You appear to have cloned an empty repository.
+done.
+```
+
+`warning: empty repository` 是**正常的**——本来就是空仓库,不是错误。
+
+完成后 `D:\` 下多了一个 `tps-dashboard` 文件夹。
+
+### 2.3 进仓库目录
+
+```powershell
+cd D:\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. 在 `D:\tps-dashboard\` 下:
+   - 直接拷入 `.clinerules`、`project_plan.md`、`dev_plan.md`、`README.md`(平铺四份)
+   
+2. 在 `D:\tps-dashboard\` 下**新建文件夹** `docs`,把 `git_workflow.md` 拷进去
+
+3. 在 `D:\tps-dashboard\` 下**新建文件夹** `logs`,把 `phase1_log.md` 拷进去
+
+**最终结构应该是**:
+
+```
+D:\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 D:\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://你的Gitea地址/你的用户名/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 D:\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 D:\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 D:\
+git clone http://你的Gitea地址/你的用户名/tps-dashboard.git
+cd tps-dashboard
+# 然后跟原来一样开工就行
+```
+
+### Q6:某次 commit 写错了想撤回
+
+**只在最近一次 commit 还没 push 时可撤回**:
+
+```powershell
+git reset HEAD~1     # 撤回最近一次 commit,文件改动保留
+```
+
+**已经 push 的 commit**:不要自行处理,找 Claude Opus 4.7。
+
+---
+
+## 第 7 章:多设备同步(家用机 ↔ 单位机)
+
+### 离开 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 | 初版 |
+
+---
+
+*本文件与 `.clinerules` 第七章互为补充。Cline 必须遵守第 4-5 章规则。*