droboticflow/docs/HANDOFF.md

198 lines
18 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 平台 / 新开发者)
> 项目根目录:`/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`
- **红线**:公司集群(kubeconfig `local-data/fanyu.conf`)和 BOS 桶默认只读,任何写操作需用户明确确认。本地容器按场景区分使用:
- **27018 快照库(`env-local-snapshot.sh`)**:承载真实数据结构副本,用于日常工作台与接口验证;合成写测试应使用独立测试集合/数据库或运行后恢复夹具(如 `--remove`),避免脏状态干扰 `npm run test:go:gate`。
- **27017 空库(`env-local.sh`)**:用于空库初始化、合成测试与基础工作流 CRUD 调试。
## 日常验证入口
开发时先按[分层验证流程](agents/verification.md)选择检查。`verify:plan` 查看范围,`verify:quick` 用于编辑反馈,`verify:task` 用于本批业务流程验收;完整集成与发布检查独立执行。不要每次修改都重复本手册的所有验证命令。
## 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
```
**改前必跑的检查**(顺序固定):
```bash
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)怎么改、怎么验证
```bash
# 启动(终端 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`)的验证配方**:
```bash
# 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. 如何看同事的代码 / 如何同步最新基线
同事(Gitea 唯一作者 eust-w / longtao.wu)高频提交,工作模式:**客户需求 → 消化成 docs/ 契约文档 + 代码 + 测试同一提交**。
```bash
# 1. 检查当前工作树与线上/远端 dev 的新鲜度,并查看新提交
bash scripts/local/branch-freshness.sh
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. 同步或开启新工作(严禁在主工作区直接切分支或盲目 rebase,详见 docs/agents/branch-workflow.md)
# - 新独立任务:从最新 origin/dev 创建独立 worktree
# git worktree add --no-track -b <agent>/<slug> local-data/worktrees/<slug> origin/dev
# - 在已授权的独立任务 worktree 内同步上游:先确认 git status 干净及与基线关系,再按任务需要合入/变基 origin/dev
# 3. 按影响范围执行分层验证(详见 docs/agents/verification.md,不要无脑跑全量编译/全量门禁)
npm run verify:plan -- --base origin/dev
npm run verify:quick -- --base origin/dev # 日常编辑/同步后的快速检查
npm run verify:task -- --base origin/dev # 交付前跑受影响模块检查(仅在集成/发布范围才跑 npm run verify:integration 或 test:go:gate / test:frontend:gate)
# 4. 按需重启本地服务(仅当后端/前端改动需要本地运行态生效时执行;先用 lsof -nP -iTCP:3001,5173 -sTCP:LISTEN 确认进程属于当前工作树/当前任务,勿盲杀其他会话服务)
# 确认归属后再重启对应进程并硬刷新浏览器(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 条标注任务全部覆盖)。
- **视频功能验证必须走 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/README.md`(Fanyu 权威发布流程 `scripts/release.py`;旧 `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 已验证);若 `.git/config` 的 remote URL 中含认证信息,查看 remote 时必须先脱敏(`git remote -v | sed -E 's#//[^@/[[:space:]]+@#//<redacted>@#g'`),禁止将明文凭证打入日志或报告,推荐将凭证迁入系统 Keychain;
- 工作流:按 `docs/agents/branch-workflow.md` 在当前已授权工作树或独立任务分支提交 → 汇报本地分支状态等待用户授权 → **用户可一次性明确授权“推送并创建 PR”,或单独授权其中一项(只批准一项不会自动扩大到另一项)** → 获批后执行 `git push -u origin <分支名>` 及在 Gitea 发起 PR 到 `dev` → 同事审核合并。**未经授权不自动 push,且绝不直接 push `dev` 或 `poc`**;
- 当前进行中的 PR:https://gitea.d-robotics.cc/longtao.wu/droboticflow/pulls/1(本地工具箱 8 个提交);
- 同事已放行:下载 Capture 调试、直接改代码提交 PR 由他审核;
- 发布(需用户明确授权):Fanyu 镜像构建、预检、部署、验收与回退统一通过 `python3 scripts/release.py` 执行,完整规程见 `docs/release/README.md`(`scripts/deploy-k8s.sh` 已拦截 Fanyu);
- 提交风格跟同事(gitmoji + 清晰信息 + 配套文档/测试),PR 通过率高。
## 8. 接班平台快查表
| 用户说 | 你做 |
|---|---|
| "页面有 bug" | 定位组件(§1 规律)→ 读代码 → 复现(浏览器/curl)→ 改 → 按 `docs/agents/verification.md` 跑对应检查 → 让用户硬刷新 |
| "拉同事最新代码" | §3 流程五步 |
| "视频/帧范围加载失败" | §4 排查定式 |
| "测某个算子" | `scripts/local/run-operator.sh <slug>` |
| "改好了要发布" | 汇报分支状态等用户授权 push/PR(§7);Fanyu 发布严格按 `docs/release/README.md` 与 `scripts/release.py` 执行 |
| "测试报错了" | 先分辨是否上游测试债(§2 已知坑,`test:go:gate` / `test:frontend:gate`),再定位 |
## 9. 会话收尾清单(2026-10-14 复盘沉淀)
跨会话残留会累积(旧 worktree、上个会话的 dev API 今天还活着)。收尾时依次:
1. 杀掉本会话起的所有 dev 栈后台作业(`job_list` 里 running 的 vite / `npm run dev:api`),除非用户明说保留。
2. 清理 worktree 前须同时确认四项:**已合入 `origin/dev`、无未提交/需保留的未跟踪文件、无运行中服务占用、且 `local-data/releases/` 下的发布记录已保全到主目录**;未验收版本和恢复材料必须保留。
3. 探针/截图证据先拷回主仓 `local-data/**/probe-out*` 再删已满足清理条件的 worktree。
4. 发布中的记录(`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`。