Initial import of streamline

This commit is contained in:
2026-11-16 17:26:44 -08:00
commit 8e4aec1855
1221 changed files with 274256 additions and 0 deletions
+155
View File
@@ -0,0 +1,155 @@
# 前端协作开发指南(给同事的 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、看共享真实数据、别碰后端和破坏性按钮。完。