16 KiB
项目交接手册(给接班的 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:gate # 全量前端测试(无需浏览器)对照 tests/known-failures.json,只在**新增失败**时报红;基线修剪用 --update
针对性测试: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 ./...有约 70 个上游遗留失败(旧测试测已删除的接口,405/404),不是回归信号;用npm run test:go:gate对照tests/known-failures.json按失败用例名判新增(不再人工数失败数;修剪基线用node scripts/check-test-baseline.mjs go --update)。跑 Go 闸前先停本地 API:个别 worker 测试耦合快照库里的任务领取状态,栈在跑/冒烟刚写过领取时可能误报新增失败;
登录本地快照账号:快照库里的账号是超级管理员与组织管理员两类。fanyu-admin@... 是 isSuperAdmin,本地未开 DROBOTICFLOW_LEGACY_ORG_ADMIN 时登录会被拒;用组织管理员
fanyu-ops-admin@droboticflow.local(org-29cd7a684faba19f630f8ad5890e18bb)即可。登录标识符是 phone(形如 local-test-user-<id>)不是邮箱,密码按 docs/annotation-local-deployment.zh-CN.md 第二步重置到本地 27018。
part 级总 JSON 交付(PART_INDEX_DELIVERY)的验证配方:
# 1) 算子 + worker + API 三层的 part-index 用例
.venv/bin/python -m pytest tests/backend/test_part_index_package.py tests/backend/test_part_index_migration.py -q
go test ./internal/worker/ ./internal/api/ -run 'TestPartIndex' -count=1
# 2) 真实媒体下的边界:审核层保留逐片视频,交付索引不含任何媒体引用
FANYU_DISCARD_ARTIFACT_DIR=$PWD/local-data/verification/part-index-replica/materialization \
go test ./internal/api/ -run TestSliceDiscardMaterialization60Seconds -count=1
FANYU_PART_INDEX_MATERIALIZATION_CONTEXT=$PWD/local-data/verification/part-index-replica/materialization/verification-context.json \
.venv/bin/python -m pytest tests/backend/test_part_index_real_materialization.py -q
# 3) 在跑着的 API 上核对读取路径(夹具只写本地容器,可随时撤销)
.venv/bin/python local-data/verification/part-index-replica/seed_part_index_fixture.py
curl -s -b cookies.txt "http://127.0.0.1:3001/api/runs/run-fixture-part-index-replica/artifacts/<artifactId>/members"
.venv/bin/python local-data/verification/part-index-replica/seed_part_index_fixture.py --remove
# 4) 已交付老目录的迁移(默认 dry run,不写对象存储)
python3 scripts/part_index_migration.py --delivery-root <part 目录副本> --revision-root <物化修订目录> --out /tmp/dry-run
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 # 他新功能相关
npm run test:go:gate # 全量 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 硬刷新
读同事代码的入手顺序(按信息密度排序):
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 条标注任务全部覆盖)。 - 视频功能验证必须走 movi 路径:断言页面上
<movi-player>真的挂载了(localStorage 的 movi force 键或组件分支都可能回落到原生<video>——原生回退没有 movi 的宿主怪癖,会把 movi 路径的 bug 全部遮住,round11 的"线上字幕从不渲染"就是这样漏掉的)。宿主怪癖清单与升级检查表:public/vendor/movi-player-0.4.1/README.md的 Host-element quirks 节。
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 校验通过后才替换本地容器;成功保留的快照路径由脚本输出 |
smoke-workbench.mjs |
发布前工作台冒烟(需本地栈 5173/3001 在跑 + Chromium/Edge):审核员登录 → 池渲染 → 随机领取 → 视频加载中直接点播放 → 字幕叠加 → 4× 倍速 → 进度条推进,7 个高频回归点一次过 |
配套文档: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 已知坑),再定位 |
9. 会话收尾清单(2026-10-14 复盘沉淀)
跨会话残留会累积(旧 worktree、上个会话的 dev API 今天还活着)。收尾时依次:
- 杀掉本会话起的所有 dev 栈后台作业(
job_list里 running 的 vite /npm run dev:api),除非用户明说保留。 - 删除已合入集成分支的 ticket worktree 与对应本地分支(
git worktree remove+branch -d)。 - 探针/截图证据先拷回主仓
local-data/**/probe-out*再删 worktree。 - 发布中的记录(
python3 scripts/release.py status)若非 completed,向用户交代状态后再收。
10. 本地验证护栏(2026-10-16)
- 安装依赖时
prepare自动安装并检查 Husky。使用npm ci --ignore-scripts后运行npm run hooks:install;随时用npm run hooks:check检查。自定义 hooksPath 不会被覆盖,CI / HUSKY=0 会明确跳过。 - 启动快照 API 用
npm run dev:api:replica:重新编译并写入当前提交版本;有已跟踪文件改动时标记-dirty。端口被占用时先核对进程归属,不自动终止旧服务。 - 打开本地页面后运行
npm run dev:status -- http://localhost:5173,核对 Vite 工作目录、提交、改动状态,以及代理实际返回的 API 版本。旧 Vite 没有/__dev/status,需要重启对应 Vite 才能提供信息。出现 IPv4 / IPv6 多监听时分别检查http://127.0.0.1:5173和http://[::1]:5173。Vite 状态接口仅开发模式存在,API 凭据不返回。 npm run test:frontend:gate和npm run test:go:gate每次保留完整 stdout、stderr 和 summary.json 到local-data/test-results/;可用--log-dir <目录>指定目录。失败不会自动重跑或更新已知失败基线。CI 上传该目录,保留 14 天。- CI 的
npm run test:browser:editing启动隔离的 5188 端口合成工作台,验证 E/G 确认、取消舍弃整片重置,以及 E 修改→截断确认→Enter→撤销/重做,覆盖普通和聚焦模式。使用真实组件和历史协调器,保存回调为合成实现;后端持久化与权限仍由 Go 检查负责。CI 失败截图和 Vite 日志保存在上述目录。代理本地浏览器验证使用tests/browser/discard-focus-track.mjs导出的 CUA 驱动。
生产前端产物启动门禁(2026-10-20)
发布前使用独立、由当前 lockfile 安装的依赖;不要把共享 node_modules 的版本清单或组件夹具通过当成生产包可启动的证据。曾出现父目录 React 19.3 与共享 ReactDOM 19.2.4 混入产物,build 成功但线上 React #527 空白。
npm run build:web 后必须运行 BROWSER_EXECUTABLE=<已有Chromium路径> npm run test:production:boot。该测试真实加载 dist,API 为本机桩,不连公司;Fanyu release.py 本地检查已强制加入。镜像须复制这份通过门禁的 dist 并核对字节。事件与红绿证据见 docs/verification/platform-feedback-runtime-20261020/report.md。