Files
2026-11-16 17:26:44 -08:00

156 lines
7.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 前端协作开发指南(给同事的 AI Agent)
> 读者:在同事机器上运行的 AI coding agent(如 Claude Code)。
> 目标:在同事这台机器上只跑**前端(control-web)**,UI 连到**团队中央 control-server**(host 那台机器),实现热更新调试 + 编码前端,**不在本机跑后端、satellite、数据库**。
---
## 0. 心智模型(必读,先理解再动手)
这是一个 monorepo(Bun workspaces),分四个包:
| 包 | 作用 | 同事这边要不要跑 |
|----|------|------------------|
| `control-server` | 控制平面:**SQLite 单一真相源** + REST API + WebSocket + 调度 | ❌ 不跑(用 host 那台的) |
| `satellite` | 执行节点:claude 评估/修复、操作 TikTok 仓库 | ❌ 不跑 |
| `control-web` | **前端看板(React + Vite)** | ✅ 只跑这个 |
| `shared` | 共享类型 / 协议(被前端 import) | 只读引用,一般不改 |
**架构关键点**:control-server 是**唯一**持有数据库的进程。前端从不直连数据库——它通过 `/api`(HTTP)和 `/ws`(WebSocket)跟 control-server 通信。所以同事只需把本地 Vite 的代理指向中央 control-server,就能看到和操作**和团队完全一样的实时数据**,无需任何数据库配置。
```
同事机器 host(中央服务器)
┌──────────────────────────┐ ┌────────────────────────────┐
│ control-web (Vite :8080) │ /api, /ws │ Caddy :443 │
│ 你在这里改 React 代码 │ ─────────────► │ └─► control-server :5173 │
│ 浏览器 localhost:8080 │ (HTTPS/WSS) │ └─► SQLite (SSOT) │
└──────────────────────────┘ └────────────────────────────┘
```
---
## 1. 硬性约束(DO / DON'T)
**DO**
- 只修改 `control-web/` 下的代码(React 组件、hooks、样式、`lib/`)。
- 需要新增/调整共享类型时,可以读 `shared/src/types.ts`、`shared/src/protocol.ts`,但**改动要谨慎**(会影响后端),优先只读。
**DON'T**
- ❌ 不要启动或修改 `control-server/`、`satellite/`。
- ❌ 不要在本机找 / 创建 / 连接 SQLite 数据库——本机没有数据库,也不需要。
- ❌ 不要修改 `control-web/vite.config.ts`(已做成环境变量驱动,用 `API_TARGET` 即可,见下)。
- ❌ 不要提交任何把代理地址、域名、token 写死的临时改动。
> ⚠️ **数据是共享的生产数据**:你连的是团队真实中央库。读取/浏览随意;但点"删除任务""驳回""确认计划"等**写操作会真的改到大家的数据**。调试 UI 交互时注意别误触发破坏性按钮(delete / abort / reject / confirm)。拿不准就只读浏览。
---
## 2. 一次性准备
```bash
# 1. 确认在仓库根目录,且 git 是最新的
cd <仓库根> # 包含 control-web/ control-server/ 的那层
git pull
# 2. 装运行时 Bun(如果没有):https://bun.sh
# macOS: curl -fsSL https://bun.sh/install | bash
bun --version # 确认能用
# 3. 安装依赖(在仓库根,Bun workspaces 会装好所有包)
bun install
```
---
## 3. 启动前端(连中央 API)
只要设一个环境变量 `API_TARGET` 指向中央服务器,然后跑 `dev:web`:
```bash
# 在仓库根执行。把 URL 换成团队 host 的中央地址(向 host 负责人确认域名)。
API_TARGET=https://streamline-internal-api.bytedance.net bun run dev:web
```
然后浏览器打开 **http://127.0.0.1:8080** 。
发生了什么:
- `vite.config.ts` 检测到 `API_TARGET`,把 `/api` 和 `/ws` 代理到中央 control-server(自动 `changeOrigin`,HTTPS→WSS 自动换协议)。
- 因为是同源代理(浏览器只看到 `localhost:8080`),**没有跨域问题,cookie/请求头照常透传**。
- HMR(热更新)走 Vite 默认本地端口,改 React 代码即时刷新。
> 嫌每次输环境变量麻烦,可在仓库根建一个**不提交**的 `.env.local` 或直接 export;但**不要**把它写进 `vite.config.ts` 或任何会被 git 跟踪的文件。
---
## 4. 验证连通
打开 http://127.0.0.1:8080 后确认:
1. 看板能加载出任务卡片(说明 `/api/tasks` 通了)。
2. 新任务/状态变化会**实时**出现(说明 `/ws` WebSocket 通了)。
3. 浏览器 DevTools → Network:`/api/tasks` 返回 200、`/ws` 是 101 Switching Protocols。
如果加载失败:
- `/api/*` 报错 → `API_TARGET` 域名/可达性问题,找 host 负责人确认服务在跑、域名对、你的网络能访问(可能需要 VPN / Tailscale,见第 7 节)。
- 页面空白但接口 200 → 是前端代码问题,正常调试即可。
---
## 5. 前端代码地图
```
control-web/src/
├── App.tsx # 主壳 + 看板泳道布局(入口)
├── main.tsx # React 挂载点
├── lib/
│ ├── api.ts # 所有后端接口的 HTTP 封装(要调哪个接口先看这里)
│ ├── sso.ts # SSO 身份(本地开发下大概率拿不到登录态,见第 6 节)
│ └── i18n.ts # 多语言
├── hooks/
│ ├── useTasks.ts # WebSocket 连接 + 任务实时数据(数据流核心)
│ └── useSso.ts # 当前用户/管理员判定
└── components/ # TaskCard / ImportDialog / LogPanel /
# TaskDetailDrawer / Dashboard / Management 等 UI
```
**改 UI** → 找 `components/`。**改数据获取/接口** → 找 `lib/api.ts` + `hooks/useTasks.ts`。
---
## 6. 关于 SSO / 管理员功能
前端有些接口是带身份的(`/api/me`、`/api/admin/*`,见 `lib/api.ts` 里 `{ authed: true }` 的调用)。在同事本机的纯 localhost 环境下,**通常拿不到中央 SSO 登录态**,所以:
- `api.me()` 可能返回 `email: null, isAdmin: false`——这是**正常的**。
- 管理员专属按钮(如 `remind`、改 admin 名单)在本地可能不可用或报 401/403。
对**绝大多数前端 UI 调试**没有影响。如果你要调的恰好是管理员功能,找 host 负责人协助(可能需要在中央页面登录、或临时把你的邮箱加进 admin 名单)。
---
## 7. 网络访问不通时
如果 `API_TARGET` 的域名在公网不可达,团队大概率用 **Tailscale** 等私有网络互联。这种情况下:
1. 让 host 负责人邀请你加入 Tailnet。
2. `API_TARGET` 改用 host 在 Tailnet 内的地址(`https://<tailscale-域名或100.x.x.x:端口>`)。
其余步骤不变。
---
## 8. 提交规范
- 分支:从最新 `main` 切出 `feat/<你的功能>` 或 `fix/<...>`,**不要直接推 main**。
- 改动范围:应当**只在 `control-web/`**(必要时含 `shared/` 的只读类型补充)。提 PR 前自查 `git diff --stat` 没有动到 `control-server/`、`satellite/`、`vite.config.ts`。
- 类型检查:`cd control-web && bun x tsc --noEmit`(或仓库根 `bun run typecheck`)。
- PR 描述里写清楚改了哪些 UI / 交互,附截图更好。
---
## 9. TL;DR(最短路径)
```bash
git pull && bun install
API_TARGET=https://streamline-internal-api.bytedance.net bun run dev:web
# 浏览器开 http://127.0.0.1:8080,改 control-web/src/** 即时热更新
```
只跑前端、连中央 API、看共享真实数据、别碰后端和破坏性按钮。完。