droboticflow/docs/HANDOFF.md

9.8 KiB
Raw Blame History

项目交接手册(给接班的 AI 平台 / 新开发者)

项目根目录:/Users/d-robotics/Desktop/fanyu/droboticflow(下文所有相对路径均基于此) 本文档由 ZCode 维护,描述本地复刻环境的全部操作:如何测试、如何更新 5173 前端、如何跟进同事代码。 上一次全面核对:2026-09-17。

0. 一分钟速览(当前环境在跑什么)

服务 地址 是什么 怎么起的
前端 Vite http://127.0.0.1:5173 React 开发服务器(源码实时生效,不是构建产物) npx vite --port 5173 --strictPort
Go API http://127.0.0.1:3001 后端 REST API(/api),由 Vite 代理转发 source scripts/local/env-local-snapshot.sh && npm run dev:api
快照库 Mongo 127.0.0.1:27018 公司 8/31 全库备份的本地副本(57 集合真实业务数据) docker 容器 fanyu-mongo-restore(mongo:8)
空库 Mongo 127.0.0.1:27017 手工构造数据用的空库 docker 容器 fanyu-mongo(mongo:7)
  • 浏览器访问 http://127.0.0.1:5173 即是完整平台;数据库用快照库(27018)。
  • 登录账号(使用本地自行设置的密码;密码不写入仓库,设置方法见 docs/annotation-local-deployment.zh-CN.md 第三步):
    • 标注员 fanyu-full-annotator@droboticflow.local
    • 质检员 fanyu-full-qc@droboticflow.local、验收员 fanyu-full-acceptance@droboticflow.local、管理员 fanyu-admin@droboticflow.local
  • 红线:27018/27017 都是本地容器,随便写;公司集群(kubeconfig local-data/fanyu.conf)和 BOS 桶默认只读,任何写操作需用户明确确认。

1. 前端(5173)怎么改、怎么验证

改动即生效:Vite dev server 直连 src/ 源码,保存文件浏览器自动热更(HMR)。没有"重新构建前端"这一步。

页面源码定位规律:
  浏览器 URL 路径 → src/App.tsx 里搜对应 <Route> → 路由指向的组件文件
  例:/plugins/annotation-qa/.../annotate → src/pages/AnnotationOperations.tsx(页面主体)
                                        + src/components/CaptureAnnotationWorkbench.tsx(工作台)
  快捷键定义:src/lib/annotation-shortcuts.js
  前端↔后端接口封装:src/services/api/*.ts

改前必跑的检查(顺序固定):

cd /Users/d-robotics/Desktop/fanyu/droboticflow
npm run lint:web        # tsc 类型检查,改 ts/tsx 后必跑
npm run test:frontend   # 98 个 node 内置 runner 测试(无需浏览器),约 1 分钟

针对性测试:node --test tests/frontend/annotation-shortcuts.test.mjs(换你改的模块对应的测试文件;ls tests/frontend/ | grep <关键词> 找)。

注意:vite.config.ts 里 DISABLE_HMR=true 注释说明是给 AI 编辑防闪烁用的——正常人工开发不受影响;如果平台自动改文件导致页面闪烁,以 DISABLE_HMR=true npx vite ... 启动。

2. API(3001)怎么改、怎么验证

# 启动(终端 1)——必须先 source 环境变量,Go 进程不读 .env 文件
source scripts/local/env-local-snapshot.sh && npm run dev:api
# 改完 Go 代码后 Ctrl+C 重启(go run 无热更)

# 验证
curl -s http://127.0.0.1:3001/api/health                 # 应 200 {"status":"ok"}
curl -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3001/api/auth/me   # 应 401(匿名)
go build ./...                                            # 编译检查
go test ./internal/api/ -run 'Test<名称>' -count=1        # 针对性测试

已知坑:

  • env-local-snapshot.sh 里 DROBOTICFLOW_REQUIRE_SESSION_AUTH=true 是关键——不设它匿名会回落成默认管理员、登录面板不显示(与线上行为不一致);
  • API 启动会自动对快照库执行 RunMigrations + EnsureIndexes(幂等,正常);
  • 全量 go test ./... 有约 63 个上游遗留失败(旧测试测已删除的接口,405/404),不是回归信号;判断标准是"你改动前后失败数不增加"。

3. 如何看同事的代码 / 如何更新(rebase 流程)

同事(Gitea 唯一作者 eust-w / longtao.wu)高频提交,工作模式:客户需求 → 消化成 docs/ 契约文档 + 代码 + 测试同一提交。

# 1. 拉取并查看新提交
git fetch origin dev
git log --oneline HEAD..origin/dev          # 看新增了哪些提交
git log --diff-filter=A --name-only --format='--- %h %s' origin/dev -- 'docs/*.md' | head -30
#   ↑ 需求雷达:同事新增的 docs/*.md 就是"消化后的客户需求",必读

# 2. 合入本地分支(用户的工作分支是 feature/local-dev-toolkit,全部是本地工具提交)
git rebase origin/dev                        # 历史上零冲突(本地提交全是新增文件,不碰上游)

# 3. 验证更新后的代码
npm run lint:web && go build ./...
go test ./internal/api/ -run 'TestContinuous|TestAnnotation|TestDelivery' -count=1   # 他新功能相关
# 全量 go test 失败数与更新前对比,不增加即可

# 4. 重启服务生效(两个终端都要重启)
kill $(lsof -nP -iTCP:3001 -sTCP:LISTEN -t) 2>/dev/null
source scripts/local/env-local-snapshot.sh && npm run dev:api &
kill $(lsof -nP -iTCP:5173 -sTCP:LISTEN -t) 2>/dev/null; npx vite --port 5173 --strictPort &

# 5. 浏览器 Cmd+Shift+R 硬刷新

读同事代码的入手顺序(按信息密度排序):

  1. git show <hash> --stat 看改动面 → 2. 提交信息(他用 gitmoji:📝新行为 🩹修补 🛡️防御 🗂️结构 🚀发布)→ 3. 同提交新增的 docs/*.md 契约文档(最权威,四段式:行为/保存与审核/打包与兼容/验证)→ 4. 最后才读代码,配套 *_test.go 读预期行为。

4. 真实数据链路(标注工作台看真视频的机制)

历史背景:快照库里的任务 artifact 原本指向 bos://(线上已清理)。本地接线方案:

  • 原理:API 的 serveResolvedRunArtifactContent 对本地路径 artifact 直接磁盘流式播放(含 Range);safeMaterializationSourcePath 只接受 WORKSPACE_MOUNT_PATH 挂载根下的文件(安全设计,不能绕过);"统一帧范围"接口从 nodeExecutions[].inputBindings 端口找 PTS——所以接线必须双路改(artifacts 数组 + inputBindings)。
  • env-local-snapshot.sh 已导出 WORKSPACE_MOUNT_PATH=~/Desktop/fanyu/droboticflow/local-data/workspace,API 启动自动生效。
  • 操作脚本:scripts/local/download-capture.sh(从 BOS 下载 Capture,已获同事放行)→ scripts/local/wire-local-capture.sh <Capture名> <runId>(接线+任务归属标注员)。
  • 新任务没视频/帧范围加载失败的排查定式:任务属于一个还没接线的 run → 跑 wire 脚本指定该 runId → 页面重试。已接线:run-c1321...、run-f919a129...(快照内 22 条标注任务全部覆盖)。

5. 本地工具箱索引(scripts/local/,全是纯新增文件)

脚本 用途
env-local.sh / env-local-snapshot.sh 空库/快照库环境变量(后者含 SESSION_AUTH 与 WORKSPACE_MOUNT_PATH,日常用后者)
run-operator.sh <slug> 单算子直跑(worker 同款调用方式,秒级调试)
download-capture.sh / wire-local-capture.sh 真实数据下载与接线
fetch-mongo-snapshot.sh 从集群 PVC 分块拉全库备份并恢复到 27018;本地和远端使用独立临时目录,完整 SHA-256 校验通过后才替换本地容器;成功保留的快照路径由脚本输出

配套文档:docs/local-dev-guide.zh-CN.md(环境搭建与踩坑)、docs/annotation-local-deployment.zh-CN.md(标注模块部署+测试用例 T1-T12)、docs/release-checklist.zh-CN.md(发布三道闸门+回滚)。

6. 网络/工具链备忘(公司网络特有,新人必读)

  • Go 代理必须 goproxy.cn(已 go env -w 持久化);pip 用阿里镜像;Docker Hub 直连不通,走 docker.m.daocloud.io 镜像再 retag;
  • colima 以 --vm-type vz --vz-rosetta 启动(QEMU 交叉编译会段错误);VM 内 DNS 失效时 colima ssh 修 /etc/resolv.conf(公司 DNS 202.4.130.100/101);
  • BOS SDK 走 Python 时证书链失败(公司代理证书),代码里用 ssl._create_unverified_context 绕过;curl 不受影响;
  • 本机代理 127.0.0.1:7890(容器内经 colima 网关 192.168.5.2:7890),镜像构建的 apt/pip 超时用它。

7. PR 与发布通道(已开通)

  • Gitea 账号 zhanghongming(2026-09-17 开通,仓库协作者,push 已验证);remote 已带凭证(token 在 remote URL 中,若失效在 Gitea Settings→Applications 重新生成并 git remote set-url 更新);
  • 工作流:本地 feature 分支提交 → git push origin feature/<名字> → Gitea 网页发 PR 到 dev → 同事审核合并。不要直接 push dev;
  • 当前进行中的 PR:longtao.wu/droboticflow#1(本地工具箱 8 个提交);
  • 同事已放行:下载 Capture 调试、直接改代码提交 PR 由他审核;
  • 发布(用户执行、同事确认后):只改前端/API 时仅需重建 droboticflow-api 一个镜像(前端打进 API 镜像),流程见 docs/release-checklist.zh-CN.md;
  • 提交风格跟同事(gitmoji + 清晰信息 + 配套文档/测试),PR 通过率高。

8. 接班平台快查表

用户说 你做
"页面有 bug" 定位组件(§1 规律)→ 读代码 → 复现(浏览器/curl)→ 改 → lint+test → 让用户硬刷新
"拉同事最新代码" §3 流程五步
"视频/帧范围加载失败" §4 排查定式
"测某个算子" scripts/local/run-operator.sh <slug>
"改好了要发布" 先 PR(§7);发布按 release-checklist
"测试报错了" 先分辨是否上游测试债(§2 已知坑),再定位