# 项目交接手册(给接班的 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 里搜对应 → 路由指向的组件文件 例:/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-`)不是邮箱,密码按 `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//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 --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 / local-data/worktrees/ 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 --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 `(接线+任务归属标注员)。 - **新任务没视频/帧范围加载失败的排查定式**:任务属于一个还没接线的 run → 跑 wire 脚本指定该 runId → 页面重试。已接线:`run-c1321...`、`run-f919a129...`(快照内 22 条标注任务全部覆盖)。 - **视频功能验证必须走 movi 路径**:断言页面上 `` 真的挂载了(localStorage 的 movi force 键或组件分支都可能回落到原生 `