From 1ccb37f0c7778729d602bcf979bacf3321dbe42b Mon Sep 17 00:00:00 2001
From: simonkoson <28867558@qq.com>
Date: Fri, 3 Jul 2026 21:27:10 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E5=8F=8C=E6=9C=BA?=
 =?UTF-8?q?=E5=90=8C=E6=AD=A5=E5=BC=80=E5=8F=91=E6=8C=87=E5=8D=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 docs/dual_machine_sync.md | 134 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 134 insertions(+)
 create mode 100644 docs/dual_machine_sync.md

diff --git a/docs/dual_machine_sync.md b/docs/dual_machine_sync.md
new file mode 100644
index 0000000..523622c
--- /dev/null
+++ b/docs/dual_machine_sync.md
@@ -0,0 +1,134 @@
+# 双机同步开发指南
+
+> 单位 4090D（主力开发机） ↔ 家里电脑，通过 Gitea 云端仓库同步。
+> 仓库地址：`http://101.42.29.217:3000/simonkoson/tps-dashboard.git`
+
+---
+
+## 到家后第一次（克隆 + 环境搭建）
+
+如果家里电脑还没有这个项目，先克隆：
+
+```powershell
+git clone http://101.42.29.217:3000/simonkoson/tps-dashboard.git
+cd tps-dashboard
+```
+
+然后搭建环境：
+
+```powershell
+# 1. 创建 Python 虚拟环境
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+
+# 2. 安装后端依赖
+pip install fastapi uvicorn sqlmodel python-dotenv psycopg2-binary bcrypt==4.0.1 itsdangerous==2.2.0 python-multipart==0.0.9 openai python-docx
+
+# 3. 安装前端依赖
+cd frontend
+npm install
+cd ..
+```
+
+配置环境变量（**两个 .env 文件，都不在 git 里，需要手动创建**）：
+
+```powershell
+# backend/.env — 从单位机器上复制内容，包含：
+# DATABASE_URL=postgresql://...
+# SECRET_KEY=...
+# MINIMAX_EMBED_API_KEY=...
+# MINIMAX_GROUP_ID=...
+# DEEPSEEK_API_KEY=...
+
+# ai-labeling/.env — 包含：
+# MIMO_API_KEY=...
+```
+
+**注意**：数据库连接指向腾讯云 PostgreSQL，两台机器连的是同一个数据库，不需要本地装 PostgreSQL。
+
+---
+
+## 每次开工（不管在哪台机器）
+
+```powershell
+cd E:\tps-dashboard    # 或者家里对应的路径
+git pull origin main   # 拉取对方机器推送的最新代码
+```
+
+如果有新的前端依赖（别人装了新 npm 包），还需要：
+
+```powershell
+cd frontend && npm install && cd ..
+```
+
+如果有新的 Python 依赖，激活虚拟环境后 pip install。
+
+---
+
+## 启动开发服务器
+
+开两个 PowerShell 窗口：
+
+**窗口 1 — 后端**：
+
+```powershell
+cd E:\tps-dashboard
+.\.venv\Scripts\Activate.ps1
+cd backend
+python -m uvicorn app.main:app --reload --port 8000
+```
+
+**窗口 2 — 前端**：
+
+```powershell
+cd E:\tps-dashboard\frontend
+npm run dev
+```
+
+浏览器访问 `http://localhost:5173`（或 5174）。
+
+---
+
+## 收工推送（每次下班前必做）
+
+```powershell
+cd E:\tps-dashboard
+git add -A
+git status              # 检查一眼，确认没有不该提交的文件（.env 等）
+git commit -m "你的提交信息"
+git push origin main
+```
+
+---
+
+## 常见问题
+
+### pull 时报冲突
+说明两台机器改了同一个文件。先看冲突内容：
+```powershell
+git diff
+```
+手动解决冲突后：
+```powershell
+git add .
+git commit -m "resolve merge conflict"
+git push origin main
+```
+
+### 忘记 push 就换了机器
+在另一台机器上 `git pull` 会发现没有新内容。回到原来的机器先 push，再回来 pull。
+
+### .env 文件丢失
+.env 不进 git，换机器需要手动复制。建议用安全的方式（如加密 U 盘或密码管理器）在两台机器间同步 .env 内容。
+
+---
+
+## 给 Claude Code 的指令
+
+如果你在家里用 Claude Code 开新 session，让它先执行：
+
+```
+请先阅读 CLAUDE.md 和 docs/dual_machine_sync.md，了解项目背景和双机开发环境。
+然后阅读 docs/git_workflow.md 第 7 章了解 git 工作流。
+我现在在家里的电脑上，代码已经 pull 到最新。请帮我启动开发环境并确认一切正常。
+```