perf(projects): eliminate preview request waterfall by huyanxius · Pull Request #431 · 1024XEngineer/Windup

huyanxius · 2026-08-19T06:53:11Z

项目列表直接交付每个项目的可用资产预览，并移除项目中心逐项目读取 Character 的请求队列，使一页项目只需一次业务 API 请求。

Why

项目中心原先先读取项目列表，再为每个缺少样例图的项目分别读取最多 6 个完整 Character。12 个项目最多产生 13 次 API 请求，并被并发限制排成多轮网络等待。

Changes

/projects 列表响应增加解析后的 preview_url。
项目中心直接消费项目列表预览，不再请求 /characters?project_id=...。
保留造型预览、角色参考图、第一动作帧的既有回退顺序与空状态。

Implementation

后端先分页读取项目，再用一条窗口查询批量取得当前页每个项目最新 6 个角色候选。
预览字段仅属于项目列表投影，不写回 Project，也不复制对象存储图片。
SQLAlchemy 查询计数测试验证项目数量增加不会增加 Character 查询次数。

Verification

UV_CACHE_DIR=/private/tmp/windup-uv-cache uv run pytest -q tests/test_project_api.py：13 项通过。
npm test -- src/entities/project/index.test.ts src/pages/projects/index.test.tsx：12 项通过。
npm run typecheck：通过。
npm run build：通过；仅有既存 chunk size 警告。
uv run ruff check ...：相关后端文件通过。
OpenAPI 重新生成后无漂移。

Scope

本 PR 不包含：Character Summary、图片缩略图、CDN、对象存储或 Release 调整。
后续事项：Character 列表摘要由 [Feature]: add lightweight character summaries for asset lists #426 跟踪。

Related Issues

Closes #425
Refs #426

Project cards currently trigger one character request per project. Add a bounded window query and expose the resolved preview on project lists. Project listing now resolves all card previews with one character query.

The project center maintains a client-side queue for missing card previews. Read the preview projection returned by the project list and remove the queue. Opening the project center no longer requests characters for each card.

Project preview priority and query count need an executable contract. Exercise every fallback and count real character SELECT statements. The tests prevent project count from reintroducing query fan-out.

Project cards must render previews without the character list adapter. Model list previews in the HTTP fixture and assert zero character requests. The page tests preserve pagination, empty states, and card previews.

The project collection now exposes a resolved preview URL. Regenerate the checked-in OpenAPI schema from the updated route model. API consumers can distinguish project list and detail representations.

vercel · 2026-08-19T06:53:16Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
windup	Ready	Preview	Aug 20, 2026 12:33pm

codecov · 2026-08-19T06:54:34Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

fennoai

Reviewed the fixed 9d855697b701a449b965d15953af1e1ed0687221...1f837ccd797020f66d8f5362ff8ee38591281a90 range across the project preview service, API projection, frontend adapter/page, fixtures, and OpenAPI schema. The batched preview query preserves the existing six-character ordering and fallback priority, the list/detail response split is coherent, and the client no longer issues per-project character requests.

python3 -m compileall and git diff --check pass. The repository test commands could not be run in this environment because uv is unavailable and frontend dependencies/Vitest are not installed.

xyh202131

批准：项目列表一次返回 preview_url，消除逐项目读取 Character 的请求瀑布；批量窗口查询保持既有回退顺序，并以查询计数测试锁定性能边界。

johnnyzhang-eng · 2026-08-20T02:14:45Z

这条也与 main 冲突了，落后 15 个提交，冲突同样在 frontend/src/pages/projects/index.tsx 与它的测试。重解时注意它删掉的那段预览队列正是 #433 刚改过的，别把 #433 的加载态区分一起丢掉。

项目卡片预览的冲突不是文本冲突：main 这段时间把预览做成了装载/空/失败/就绪四态加骨架屏、取消与逐页翻找，本分支的前提恰恰是把这套前端编排整体删掉，改由 /projects 一次返回 preview_url。按后端聚合后的真实状态重解： - 前端请求队列、并发闸门、AbortController、逐页翻找随编排一起去掉；列表响应到手时预览就已定，不再有"预览请求中"和"单个预览请求失败"这两态。 - 展示层保留 main 的成果：空态与图片错误走 ProjectPreviewMessage，预览图解码完成前仍盖 PixelMatrix 骨架，aria-busy 与 role=status 标注照旧。 - 测试同口径：删掉针对请求编排的用例，保留图片解码骨架与图片加载失败两例。

huyanxius · 2026-08-20T02:42:58Z

@fennoai 解决一下代码冲突

fennoai · 2026-08-20T02:43:02Z

已解决

已将最新 main（5ebe10a）合入原 PR 分支并推送，PR perf(projects): eliminate preview request waterfall #431 当前 mergeable: true、behind_by: 0。
唯一实际冲突位于 frontend/src/pages/projects/index.test.tsx：保留单次 /projects 预览请求逻辑，同时保留 main 新增的卡片 WebP 缩略图失败回退测试。
原 PR 最新提交：7dd2a4c。GitHub 的 blocked 状态表示仍需等待分支规则/检查，不再表示代码冲突。

验证

后端：tests/test_project_api.py，13 项通过。
前端：项目实体与项目页面测试，15 项通过。
前端：npm run typecheck 通过。
git diff --check 通过，无未解决冲突标记。

临时替代 PR 已关闭，保留原 PR #431 继续走检查与评审。

View job run

Replay the project preview aggregation changes on the latest main and retain the card-thumbnail fallback test.

Resolve the remaining project page test conflict by keeping the single-request project preview flow together with the card-thumbnail fallback coverage.

xyh202131

我复核了这版 project preview 聚合改动：后端把列表预览一次性投影出来，前端也同步删掉了逐项目的补请求编排，相关查询与回退测试都跟上了。当前 diff 本身我没看到新的正确性回归，这版代码我先批准；不过 PR 现在仍有冲突，合入前还需要先解冲突。

main 上项目卡片又加了视角/朝向/尺寸这类元信息，import 段与本分支删掉 characterApis 的改动撞在一起。取两边并集减去预览编排残留：保留 main 新增的 CHARACTER_PERSPECTIVE 与 DIRECTIONAL_MOVEMENT，characterApis 和 Character 不再回来。测试同样合并—— 留下 main 新增的"画廊内不重复出现新建入口"断言，请求断言保持本分支的 "只打 /projects"，放宽成白名单会让预览瀑布悄悄回来。

xyh202131

已复核当前提交：项目列表直接提供 preview_url，消除逐项目读取 Character 的请求瀑布；批量查询保持既有预览回退顺序，相关后端查询计数、前端适配与契约测试完整。当前检查无失败项。

huyanxius added 5 commits August 19, 2026 14:50

perf(projects): aggregate project previews

f42c8f7

Project cards currently trigger one character request per project. Add a bounded window query and expose the resolved preview on project lists. Project listing now resolves all card previews with one character query.

perf(projects): consume list previews

35af5ca

The project center maintains a client-side queue for missing card previews. Read the preview projection returned by the project list and remove the queue. Opening the project center no longer requests characters for each card.

test(projects): cover preview aggregation

19a9989

Project preview priority and query count need an executable contract. Exercise every fallback and count real character SELECT statements. The tests prevent project count from reintroducing query fan-out.

test(projects): verify single-request previews

3d96a8c

Project cards must render previews without the character list adapter. Model list previews in the HTTP fixture and assert zero character requests. The page tests preserve pagination, empty states, and card previews.

chore(openapi): publish project preview contract

1f837cc

The project collection now exposes a resolved preview URL. Regenerate the checked-in OpenAPI schema from the updated route model. API consumers can distinguish project list and detail representations.

fennoai Bot reviewed Aug 19, 2026

View reviewed changes

xyh202131 approved these changes Aug 19, 2026

View reviewed changes

xyh202131 previously approved these changes Aug 19, 2026

View reviewed changes

huyanxius requested a review from minorcell August 20, 2026 02:21

huyanxius dismissed xyh202131’s stale review via abd7afe August 20, 2026 02:31

vercel Bot deployed to Preview August 20, 2026 02:31 View deployment

chore: refresh PR mergeability

d7e3a5c

This was referenced Aug 20, 2026

perf(projects): eliminate preview request waterfall huyanxius/Windup#19

Closed

perf(projects): eliminate preview request waterfall #462

Closed

huyanxius added 2 commits August 20, 2026 03:11

perf(projects): eliminate preview request waterfall

8115597

Replay the project preview aggregation changes on the latest main and retain the card-thumbnail fallback test.

Merge latest main into perf/425-project-preview

7dd2a4c

Resolve the remaining project page test conflict by keeping the single-request project preview flow together with the card-thumbnail fallback coverage.

vercel Bot deployed to Preview August 20, 2026 03:12 View deployment

xyh202131 previously approved these changes Aug 20, 2026

View reviewed changes

huyanxius dismissed xyh202131’s stale review via bcd2337 August 20, 2026 12:33

vercel Bot deployed to Preview August 20, 2026 12:33 View deployment

xyh202131 approved these changes Aug 20, 2026

View reviewed changes

huyanxius merged commit 5ee863f into 1024XEngineer:main Aug 20, 2026
7 checks passed

huyanxius mentioned this pull request Aug 21, 2026

[Bug]: render the project loading shell before list data #510

Closed

7 tasks

huyanxius mentioned this pull request Aug 21, 2026

fix(projects): render project loading shell immediately #514

Merged

6 tasks

Navigation Menu

Uh oh!

perf(projects): eliminate preview request waterfall - #431

perf(projects): eliminate preview request waterfall#431
huyanxius merged 10 commits into
1024XEngineer:mainfrom
huyanxius:perf/425-project-preview

huyanxius commented Aug 19, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Aug 19, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Aug 19, 2026

Uh oh!

fennoai Bot left a comment

Uh oh!

xyh202131 left a comment

Uh oh!

johnnyzhang-eng commented Aug 20, 2026

Uh oh!

huyanxius commented Aug 20, 2026

Uh oh!

fennoai Bot commented Aug 20, 2026 •

edited

Loading

Uh oh!

xyh202131 left a comment

Uh oh!

xyh202131 left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

huyanxius commented Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

Changes

Implementation

Verification

Scope

Related Issues

Uh oh!

vercel Bot commented Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Aug 19, 2026

Codecov Report

Uh oh!

fennoai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

xyh202131 left a comment

Choose a reason for hiding this comment

Uh oh!

johnnyzhang-eng commented Aug 20, 2026

Uh oh!

huyanxius commented Aug 20, 2026

Uh oh!

fennoai Bot commented Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

已解决

验证

Uh oh!

xyh202131 left a comment

Choose a reason for hiding this comment

Uh oh!

xyh202131 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

huyanxius commented Aug 19, 2026 •

edited

Loading

vercel Bot commented Aug 19, 2026 •

edited

Loading

fennoai Bot commented Aug 20, 2026 •

edited

Loading