From 58e0e50570c8f198f75bd1ec6db79ab545711d99 Mon Sep 17 00:00:00 2001 From: d-robotics Date: Mon, 12 Oct 2026 18:03:12 +0530 Subject: [PATCH] =?UTF-8?q?=F0=9F=A7=AA=20Retro=202026-10-12:=20CI=20gate,?= =?UTF-8?q?=20known-failure=20baselines,=20devboot=20regression=20test,=20?= =?UTF-8?q?workbench=20smoke,=20review=20standards?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Six follow-ups from the round8-12 hotfix retrospective: - web-ci.yml: lint + Go/frontend tests on every push and PR (nothing ran app checks before; the round10 dev-mode regression shipped green) - tests/known-failures.json + check-test-baseline.mjs: gate by exact failing-test id instead of hand-counted failure totals (14 frontend, 70 Go upstream debts recorded from the dev tip) - devboot.test.mjs: boots the real Vite dev server and pins the movi loader contract that broke round10 (query-less DEV url, /vendor stays off the module pipeline) - scripts/local/smoke-workbench.mjs: pre-release smoke covering the seven recurring acceptance points (login/pool/claim/play-while-loading/ captions/4x/playhead), 3x green against the local replica - docs/CODING_STANDARDS.md + AGENTS pointer: eligibility flags are server-shipped, the UI renders them (rounds 9+12 lesson) - vendor README host-element quirks section, HANDOFF gate pointers and movi-path verification rule, perf-audit report pinned with the post-round12 production 500 observation - husky pre-commit: lint-staged (repo prettier scope) + tsc + gofmt - gofmt: restore lint:go green on the dev tip (drift shipped silently in the perf merge and round12 because nothing gated it) --- .gitea/workflows/web-ci.yml | 29 + .gitignore | 1 + .husky/pre-commit | 3 + .lintstagedrc | 5 + .scratch/workflow-perf-audit-report.md | 84 +++ AGENTS.md | 4 + docs/CODING_STANDARDS.md | 31 + docs/HANDOFF.md | 8 +- internal/api/annotation_operations_test.go | 1 - internal/api/human_items_pagination_test.go | 2 +- internal/api/human_loop.go | 14 +- internal/api/server.go | 10 +- internal/api/slice_disposition_test.go | 10 +- internal/api/supplier_public_workflow_test.go | 24 +- .../store/human_loop_cursor_mongo_test.go | 6 +- internal/store/production_stats.go | 1 - internal/store/supplier_pool_conversion.go | 8 +- .../supplier_pool_conversion_mongo_test.go | 16 +- package-lock.json | 629 ++++++++++++++++++ package.json | 5 + public/vendor/movi-player-0.4.1/README.md | 31 + scripts/check-test-baseline.mjs | 126 ++++ scripts/local/smoke-workbench.mjs | 245 +++++++ tests/frontend/devboot.test.mjs | 58 ++ tests/known-failures.json | 90 +++ 25 files changed, 1405 insertions(+), 36 deletions(-) create mode 100644 .gitea/workflows/web-ci.yml create mode 100644 .husky/pre-commit create mode 100644 .lintstagedrc create mode 100644 .scratch/workflow-perf-audit-report.md create mode 100644 docs/CODING_STANDARDS.md create mode 100644 scripts/check-test-baseline.mjs create mode 100644 scripts/local/smoke-workbench.mjs create mode 100644 tests/frontend/devboot.test.mjs create mode 100644 tests/known-failures.json diff --git a/.gitea/workflows/web-ci.yml b/.gitea/workflows/web-ci.yml new file mode 100644 index 00000000..566ec870 --- /dev/null +++ b/.gitea/workflows/web-ci.yml @@ -0,0 +1,29 @@ +name: web-ci + +# App-code checks (tsc/gofmt/script syntax, Go tests, frontend tests) gated +# against tests/known-failures.json. Before this workflow existed nothing ran +# these on push/PR — a 2026-10-12 regression (source-import of a cache-busted +# /vendor asset) shipped to production green through every local check that +# didn't boot the dev server. +on: + push: + branches: ['**'] + pull_request: + +jobs: + checks: + runs-on: ubuntu-22.04 + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-go@v5 + with: + go-version-file: go.mod + cache: true + - uses: actions/setup-node@v4 + with: + node-version: 22 + cache: npm + - run: npm ci + - run: npm run lint + - run: npm run test:go:gate + - run: npm run test:frontend:gate diff --git a/.gitignore b/.gitignore index 011df7ca..2f17aaa1 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,4 @@ __pycache__/ local-runs/ .venv/ local-data/ +.husky/_/ diff --git a/.husky/pre-commit b/.husky/pre-commit new file mode 100644 index 00000000..002b8235 --- /dev/null +++ b/.husky/pre-commit @@ -0,0 +1,3 @@ +npx lint-staged +npm run lint:web +npm run lint:go diff --git a/.lintstagedrc b/.lintstagedrc new file mode 100644 index 00000000..379ae84a --- /dev/null +++ b/.lintstagedrc @@ -0,0 +1,5 @@ +{ + "src/**/*.{ts,tsx,css}": "prettier --write", + "src/services/api/*.js": "prettier --write", + "tests/frontend/**/*.mjs": "prettier --write" +} diff --git a/.scratch/workflow-perf-audit-report.md b/.scratch/workflow-perf-audit-report.md new file mode 100644 index 00000000..ff50f0cf --- /dev/null +++ b/.scratch/workflow-perf-audit-report.md @@ -0,0 +1,84 @@ +# 工作流全链路性能与数据 footprint 审计汇总报告 + +汇总自四份只读审计笔记(2026-10-09): +- A1 API 热路径:`.scratch/audit-notes/api-hotpaths.md`(P1–P9) +- A2 DB 足迹与清洗候选:`.scratch/audit-notes/db-footprint.md`(C1–C8) +- A3 Worker/交付管道 + part-index 激活:`.scratch/audit-notes/worker-delivery.md`(W1–W6) +- A4 前端工作流页面:`.scratch/audit-notes/frontend-workflow.md`(F1–F11) + +本报告不新增任何未验证结论,仅做合并、排序与交叉印证。已排除 slow-page-fix 已修复项(认证缓存、human-items 分页/投影、S4 点查等)。 + +## 1. 合并后的根因:视频强制服务端转码(F1 × A1/P5 × 部署线) + +三线交叉印证的同一根因:前端 `src/lib/video-preview.js:120-148` 无条件加 `transcode=browser`,`CaptureAnnotationWorkbench` 的 `browserReadyMedia` 默认 false 且页面未传 → 所有标注/审核/验收视频走 API 进程 ffmpeg 实时转码(`internal/api/human_loop.go:538-552` → serveRunArtifactContent),叠加全局 `Compress(5)` 再 gzip 视频流。 +- **影响**:打开任务首帧分钟级等待;API CPU 被转码占用并与 JSON 热路径争抢;多标注员并行打满。 +- **修复方向**(A4 建议):先直连(去 transcode,307 跳 BOS 预签名)失败再回退转码;中期在切片物化时产出 browser-ready 副本。收益:首帧分钟级→秒级 + 消除 API 最大 CPU 消耗点。风险:个别编码不可播,保留回退并埋点统计。 +- **置信度:高**(代码路径三线互证;线上实际回退率需验证后确认中期方案收益)。 + +## 2. 按收益 × 置信度排序的优化清单 + +| 排名 | 条目 | 来源 | 位置 | 收益 | 置信度 | 风险 | +|---|------|------|------|------|--------|------| +| 1 | 视频直连 + 回退(根因合并项,见 §1) | F1 | video-preview.js:120-148 等 | 首帧分钟级→秒级;释放 API CPU | 高 | 低(保留回退) | +| 2 | annotation-tasks 列表全组织 revision 扫描:`ListSliceRevisions/ListAnnotationRevisions(org,"")` 无 limit 无投影,列表请求拉全组织历史并内存过滤 | P1 | annotation_operations.go:692-693 | 消除数百 MB 级 BSON 解码/请求,随历史线性恶化被止住 | 高 | 低($in+投影不改契约) | +| 3 | loadProject 全量重载(9–11 请求 × 22 调用点,含 listTasks 无分页与 4 池各 500 条) | F2/F8/F7 | AnnotationOperations.tsx:953-1138 | 每次操作请求数 ~10→1–2,后端读放大同步大降 | 高 | 中(局部更新需核对旁路状态) | +| 4 | 验收池 listAcceptancePools 放大:非管理员 6 次全量分页扫描/次刷新 | F3 | human-loop.ts:62-97 | 全集合游标扫描→单次聚合接口 | 高 | 低 | +| 5 | human-batches 非管理员 batch×item 双重 N+1 全量记录 | P2 | human_loop.go:244-261 | B 次全量 item 查询→存在性判断 | 高 | 中(可见性需等价,留 fallback) | +| 6 | reviewed 池无界 ID $in + canClaimHumanItem 每条 2 次绕过缓存的 GetHumanBatch(500 条页 → 500–1000 次串行往返) | P3 | human_loop.go:851/856 | 纯冗余往返清除,行为不变 | 高 | 极低 | +| 7 | 验收决策写路径:整批串行重写(3N+ 写)+ v5.8 聚合 payload 全量重建(MB 级单文档,16MB 风险) | P4 | human_loop.go:1907-1953、2410-2605 | 决策延迟大降 + 消除文档膨胀 | 高 | 中(acceptance-package/v2 前端契约需同步) | +| 8 | workBuffer 3s 常驻轮询(20 req/min/人,无可见性暂停) | F4 | AnnotationOperations.tsx:4477 | 空闲期该端点流量降 80%+ | 高 | 低 | +| 9 | 交付管道:逐片 7 文件复制 + 同字节读 3 遍 + 每切片 2 次 ffprobe;上传每文件 4–6 次 BOS API + staging 中转 | W1/W2 | operator.py:1558-1602、capture_delivery.go:45-77 | 打包节点读 IO/子进程开销 −50%+(估) | 高 | 中(staging 直传受"不覆盖他人交付"契约约束) | +| 10 | prepareDeliveryTarget 每次全量 ListCaptureRecords 重叠检查 | W3 | capture_delivery.go:109 | 消除每次交付的全表扫描 | 高 | 低 | +| 11 | 最终验收打开即全切片全量翻页拉证据目录 | F5 | FinalAcceptanceWorkspace.tsx:170-181 | 打开请求数 O(N×页)→O(页) | 中高 | 低(服务端提交校验兜底) | +| 12 | task 详情全历史响应体 + GET 读路径写恢复/转码预热 | P5 | annotation_operations.go:833-911 | 响应体 MB 级→当前 generation | 中高 | 中(前端依赖 revisions 形状需核对) | +| 13 | 交付下载 manifest 逐文件串行预签名(最多 5 万文件,分钟级) | P7 | delivery_downloads.go:457-464 | manifest 生成分钟级→秒级 | 中高 | 中(下载器需配合) | +| 14 | part.json 全量读+解析 2 遍再读第 3 遍上传 | W4 | capture_delivery.go:317-356 | 消除重复多 MB JSON 解析 | 中 | 低 | +| 15 | 任务池无虚拟化 + taskContextById O(n²) | F6 | AnnotationOperations.tsx:5351、2001-2024 | 低配机点选卡顿消除 | 高 | 低 | +| 16 | rejects 无分页 N+1;随机领取逐候选全量 GetHumanItem | P6/P8 | human_loop.go:1956-1980;annotation_random_claim.go:226-306 | 中等冗余往返清除 | 高 | 低 | +| 17 | ProjectDetail 15s 轮询级联扇出;GET 4 次重试×轮询叠加;普通池 500 条静默截断(正确性问题) | F10/F11/F9 | ProjectDetail.tsx:435;client.ts:99-134;human-loop.ts:36-40 | 常态流量与雪崩放大收敛;截断正确性修复 | 高 | 低 | +| 18 | 完成后 ListPrefix 全量核对、小文件 marker 走完整 staging | W5/W6 | capture_delivery.go:282-290、156-167 | 小 | 中 | 低 | + +排位说明:1–8 直接作用于标注/审查/验收日常操作路径(人感最强);9–10 是交付管道结构性开销(part-index 激活后 W1 全免,见 §4);11–18 次之。 + +## 3. 数据清洗候选(全部需用户逐项拍板,均未执行任何写操作) + +体量基于 2026-10 快照库(127.0.0.1:27018/drobodata-fanyu,约 6 周数据),线上需按增长系数外推并复核。 + +| # | 对象 | 估计体量 | 建议 | 风险 | +|---|------|---------|------|------| +| C1 | BOS:已 accepted 分区的源目录 + 中间 pose/undistort/blur 产物 | **~50–60GiB**(39.1GiB 源 + ~22GiB 中间,需按 manifest 去重) | 删除(客户已拿 finalExport)| 高:不可逆;必须以 deliveryPackages.acceptanceReviews + finalExportArtifactIds 白名单为准,failed/未验收除外;先导出 manifest 备份 | +| C2 | runs.nodeExecutions 的 inputArtifacts/inputLineage/inputBindings 三重重复(占全库 99.8%) | 终态 run 30–40MB,全量 ~60MB | 归档/收缩为引用(>N 天终态 run);保留 status/时间/artifacts 摘要 | 中:重放调试需完整输入;同时使 /api/runs 列表传输降 ~90% | +| C3 | poseSummary 在 humanItems 与 annotationTasks 双份冗余 | ~200KB,随任务线性 | 保留 annotationTasks 权威,另一处迁移后 unset | 低 | +| C4 | humanEvents 历史事件(651 条,无 TTL/归档) | 现 0.4MB,无上限 | TTL 或 180 天归档 | 中:合规/审计要求需先确认合同 | +| C5 | annotationTimelineIndexes.body 内嵌 gzip | 3.9MB(22 条),随 part 增长 | 改 BOS 引用或大小阈值 | 低–中:查询延迟可能回退,与 P1 修复需权衡 | +| C6 | runs 15 个快照期 0 访问索引(前缀重叠) | ~0.3MB + 写放大 | 线上 $indexStats 复核后 drop | 中:快照≠线上,必须线上复核 | +| C7 | legacyAssignment 残留、终态 annotationDraft、一次性迁移/备份集合 | <100KB | 确认无读方后 unset/drop | 低 | +| C8 | 快照实例 9 个测试库 | 仅本地 ~130MB | 本地 drop | 无 | + +## 4. part-index worker 激活执行方案(合并 t3 结论) + +**变更性质**:05f2dc14 → da446d13 属向后兼容(hyperparam `PART_INDEX_DELIVERY` 默认 false,定义于 builtin_operators_catalog.json:7848;唯一读取点 operator.py:1531;worker 按产物特征自动路由(artifact_storage.go:357-366),对旧目录形态零行为变化;backend 与 operator-repos 镜像同步;有 capture_part_index_test.go 契约测试)。 + +**执行步骤**: +1. 镜像滚动更新(先 1 副本观察再全量),可与 API 同镜像。 +2. 灰度:仅对新增交付任务的打包节点设 `PART_INDEX_DELIVERY=true`(节点级覆盖,不改 catalog 默认)。 +3. 验证点:首个灰度 part 的 final part.json owner marker/sha256/manifest kind=="part-index";打包节点耗时与 BOS API 次数应显著下降(W1 全免:不再复制媒体字节)。 +4. 回滚:开关关回 false 即回到旧形态,无需回滚镜像;已发布 part.json 为冻结交付物不回滚。 +5. 存量迁移(需专项评审 + 用户批准):`scripts/part_index_migration.py` dry-run 只读(拒绝写对象存储、拒绝覆盖不同 part.json、复用算子源码保证同构);关键约束:存量已交付目录会被 worker "拒绝覆盖无主/已有文件目录"保护挡住,正常交付通道无法追加 part.json——需专项通道或随下一 revision 交付携带。v2 清单、calibration 为空、discard 无 reason 的 part 需人工确认。 + +## 5. 客户确认材料清单索引 + +需要用户逐项拍板/另行批准的事项及证据出处: +1. 优化清单 §2 各条的实施顺序与范围(证据:api-hotpaths.md / frontend-workflow.md / worker-delivery.md 对应条目)。 +2. 清洗候选 C1–C7(§3;C8 本地即可)。C1 涉及删除线上 BOS 对象、C4 涉及审计保留期限,须明确授权。 +3. part-index 激活的镜像发布与灰度节点选择(§4);存量迁移正式发布属对已交付目录的写入,需专项评审与批准。 +4. 待线上验证项(快照证据局限):runs 冗余索引线上访问统计(C6)、C1 的 BOS 实际对象体量与 manifest 去重、Mongo RTT 与线上增长系数(db-footprint.md §5)。 +5. 契约影响项:P4/F7 验收 payload 改引用需前端 acceptance-package/v2 同步改造;P7 下载器配合改造;P5 详情 history 分页需核对 workbench 调用方。 +6. 线上观察(2026-10-12,round12 上线后 12h 只读日志):`/api/projects/*/workflows`、`/api/human-items` 等出现 4 次零星 500,无 panic、无慢请求级联——与 F10(ProjectDetail 15s 轮询级联扇出 + GET 4 次重试叠加)、P2/P3(human-batches/reviewed 池扫描压力)特征一致。同事性能分支(codex/slow-page-performance-20261009)覆盖多项后应复测销项;未复测前不算新增回归。 + +## 6. 正面项(已确认无需改,避免重复投入) + +- human-items 列表分页 + ListProjection + 请求级 humanListReads 缓存。 +- delivery 下载媒体走 BOS 预签名直链;claim 幂等 receipt + 乐观版本控制;候选查询投影干净。 +- 目录发布 BOS 并行度 4;packages-manifest 最后串行发布保证可见性顺序;共享目录文件引用去重。 +- 会话心跳/续期为设计成本非热点;DataOperations 轮询有 hidden 感知可作 F4 范式;验收元数据按需加载。 diff --git a/AGENTS.md b/AGENTS.md index c901611c..7377f381 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -94,3 +94,7 @@ Use the five default triage roles. Before triaging issues, read `docs/agents/tri ### Domain docs Use a single-context layout: root `CONTEXT.md` and `docs/adr/`. Before exploring domain concepts or decisions, read `docs/agents/domain.md`. + +### Coding standards + +Before writing or reviewing pool/list eligibility logic (claim buttons, `canClaim`, task-pool gating), read `docs/CODING_STANDARDS.md` — eligibility flags are server-shipped; the UI renders them, it never rebuilds them. diff --git a/docs/CODING_STANDARDS.md b/docs/CODING_STANDARDS.md new file mode 100644 index 00000000..ba4a883f --- /dev/null +++ b/docs/CODING_STANDARDS.md @@ -0,0 +1,31 @@ +# Coding standards (review-time rules) + +Rules that cannot be enforced by a linter because they are cross-file +consistency contracts between the server and the UI. Apply them while writing +or reviewing the matching code; both exist because their violation shipped to +production twice in one day (2026-10-12, rounds 9 and 12). + +## Eligibility flags are server-shipped + +Pool and list endpoints ship server-computed eligibility flags (today: +`canClaim` on human-item pool entries). The UI renders those flags. + +The UI must not: + +- rebuild eligibility locally from membership or role data it fetched (or + failed to fetch) itself — a view that skips a members fan-out then "knows" + nobody can claim, and hides entries the server would happily let the user + take (round 12: 可领取 3 → "暂无可领取"); +- add gating conditions the server does not have (round 9: a leftover + `!projectId` disable kept the claim button grey in the all-projects view + that is now the default). + +Local derivation may at most produce a display hint; it may never hide an +entry, disable an action, or change the empty-state message. When a list view +needs a flag the payload does not carry, extend the server payload — do not +guess client-side. + +Rationale: `AGENTS.md` principle 5 already requires permissions to be enforced +on the server; this rule is its list-contract corollary. The server is the +only component that sees roles, project scoping, and claim state together; +every client-side reconstruction is a second, divergent permission model. diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index b4f3218f..3311d2ab 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -37,7 +37,7 @@ ```bash cd /Users/d-robotics/Desktop/fanyu/droboticflow npm run lint:web # tsc 类型检查,改 ts/tsx 后必跑 -npm run test:frontend # 98 个 node 内置 runner 测试(无需浏览器),约 1 分钟 +npm run test:frontend:gate # 全量前端测试(无需浏览器)对照 tests/known-failures.json,只在**新增失败**时报红;基线修剪用 --update ``` **针对性测试**:`node --test tests/frontend/annotation-shortcuts.test.mjs`(换你改的模块对应的测试文件;`ls tests/frontend/ | grep <关键词>` 找)。 @@ -61,7 +61,7 @@ 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),不是回归信号;判断标准是"你改动前后失败数不增加"。 +- 全量 `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。 @@ -106,7 +106,7 @@ git rebase origin/dev # 历史上零冲突(本地提交 # 3. 验证更新后的代码 npm run lint:web && go build ./... go test ./internal/api/ -run 'TestContinuous|TestAnnotation|TestDelivery' -count=1 # 他新功能相关 -# 全量 go test 失败数与更新前对比,不增加即可 +npm run test:go:gate # 全量 go test 按用例名对照基线,新增失败才报红 # 4. 重启服务生效(两个终端都要重启) kill $(lsof -nP -iTCP:3001 -sTCP:LISTEN -t) 2>/dev/null @@ -127,6 +127,7 @@ kill $(lsof -nP -iTCP:5173 -sTCP:LISTEN -t) 2>/dev/null; npx vite --port 5173 -- - `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 键或组件分支都可能回落到原生 `