diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index fa72d4cdc..913bfcf94 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -4389,3 +4389,12 @@ - 运维与回滚：用 `scripts/gitea-ci-job-image.sh build|verify|export|load-runner` 管理镜像，按 `build/verify -> export 仓库外镜像归档和 SHA-256 sidecar -> load-runner -> 确认无活跃 job -> 备份 config -> 增加或替换 label -> docker restart --timeout 660` 切换。config 与镜像归档只放仓库外受控位置；共享文档只记录通用备份规则，不记录宿主绝对路径、注册信息或 token。重启后先验证真实 CI 再清理旧镜像；回滚先把 workflow `runs-on` 改回 `ubuntu-latest`，再恢复 config 备份并重启 runner。 - 影响范围：`.gitea/workflows/project-ci.yml`、`deploy/container/gitea-ci-job.Dockerfile`、`scripts/gitea-ci-job-image.sh`、`scripts/check-gitea-ci-job-image.sh`、`scripts/check-gitea-ci-job-runtime.sh`、runner label/config 和 Gitea CI 运维文档。 - 验证方式：构建脚本校验宿主与 runner 内层 Image ID 一致；环境脚本校验 Node、Rust、`rustfmt`、Chrome、bwrap、原生命令与 pkg-config 依赖；runtime 脚本执行完整 bwrap 和 Chrome headless canary；真实 PR 的四个 job 全部通过，同时复核 `Privileged=false`、`Binds=[]`、`MaskedPaths=[]`、`ReadonlyPaths=[]` 和独立网络。 + +## 2026-07-22 陶泥儿精选改为顺序循环分列 Masonry + +- 背景：CSS multi-column 会按纵向高度平衡卡片，少量素材或活动卡与普通素材高度差较大时，桌面首行会只放一到两张，后续卡片提前从左侧下一段开始，无法满足“每行填满三张再换行”。 +- 决策：`/creation` 陶泥儿精选保持平面 DOM 顺序，按当前列数将第 `index` 张循环分配到 `index % columns` 列。三列下第 1/2/3 张分别进入第 1/2/3 列，第 4/5/6 张再分别接续三列；不采用最短列贪心排序，避免同一组多张连续进入同一列。 +- 宽度与高度边界：列数由精选容器实际宽度、0.92rem computed gap 和 288px 首选最小列宽共同决定，最多三列。卡片先获得目标列宽，再按真实 preview aspect ratio 和内容测量高度；同列紧凑堆叠，不拉伸、裁切或等待其它列高卡。循环分列只消除列内空洞，较短列在整个容器底部仍可有尾部高度差。 +- 动态与可用性边界：`useLayoutEffect` 首次同步测量，`ResizeObserver + requestAnimationFrame` 在容器变宽、卡高变化、筛选重排和 cursor 追加后全量重排。只有当宽度、卡数和所有高度完整时才进入 absolute ready；否则保留 Grid fallback，防止卡片重叠和分页 sentinel 提前触发。DOM/Tab/读屏顺序始终不变，容器与卡片显式为 list/listitem。 +- 兼容边界：保留现有 `.creation-landing__asset-waterfall` 类名、筛选、排序、cursor 分页、预览与点赞链路；只替换布局算法。该决策覆盖 2026-07-07 multi-column 及本日早先 row-major Grid 的布局部分，不改变精选仍是动态素材流的产品定位。 +- 验证方式：纯函数测试锁定容器临界宽度、循环列序、列内 top 和容器高度；`src/index.test.ts` 锁定 Grid fallback 与 Masonry ready。Playwright 在同一 viewport 中变更容器宽度，核对 3/2/1 列、每列 gap、容器高度、DOM 顺序、无重叠/横溢出和 console/page error。 diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md index 0c4dc32bb..7bd8c2c13 100644 --- a/docs/project-memory/shared-memory/pitfalls.md +++ b/docs/project-memory/shared-memory/pitfalls.md @@ -119,13 +119,14 @@ - 验证：`creationShowcaseModel.test.ts` 覆盖展示名优先、陶泥号兜底和内部 owner/user id 不展示；`editorProjectClient.test.ts` 覆盖公开精选接口客户端保留公开作者字段；若改动 SpacetimeDB read model，再运行 `npm run spacetime:generate`、`cargo check -p spacetime-client -p api-server --manifest-path server-rs/Cargo.toml` 和 `npm run check:spacetime-schema`。 - 关联：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`server-rs/crates/spacetime-client/src/mapper/editor_project.rs`、`server-rs/crates/api-server/src/editor_project.rs`、`src/components/creation-home/creationShowcaseModel.ts`。 -## 陶泥儿精选瀑布流变宽先查 multi-column 容器宽度 +## 陶泥儿精选顺序分列不要用 multi-column 或共享 Grid 行高 -- 现象：release `/creation` 桌面端精选卡片明显变宽，第三列被裁到屏幕外，页面内部可横向滑动；dev 看起来正常。 -- 原因：精选瀑布流使用 `column-count`，当它作为 grid item 时如果没有显式 `width: 100%` / `min-width: 0`，Chrome 会用多列内容的 intrinsic width 反向撑开 grid track。线上实测 1920 视口下 section 为 `1296px`，waterfall 被撑到约 `2048px`，单卡宽约 `672px`。 -- 处理：保留 multi-column 瀑布流时，`.creation-landing__asset-waterfall` 必须显式约束 `width: 100%` 和 `min-width: 0`；不要只看单张图片天然尺寸或改卡片宽度。 -- 验证：Playwright / CSSOM 检查 `.creation-landing__section`、`.creation-landing__asset-waterfall`、首张 `.creation-landing__asset-card` 的 `getBoundingClientRect()`，waterfall 宽度应等于 section 宽度。 -- 关联：`src/index.css`、`src/components/creation-home/CreationLandingView.tsx`。 +- 现象：`/creation` 桌面端主内容区明明能放下三张卡，首行却只出现一到两张，后续素材提前回到左侧下一段；活动卡与普通素材高度差较大时尤其明显。 +- 原因：`column-count` 按纵向文章列流入并平衡，三张卡可排成 `2 + 1 + 0` 列；标准 CSS Grid 虽会横向先填三张，但整行共用最高卡行轨，短卡下会留下高度差。`align-items: start` 只是不拉伸短卡，不能消除行轨空白；`grid-auto-flow: dense` 也不能填单个网格项内的剩余高度。 +- 处理：保留平面 DOM 和 `.creation-landing__asset-waterfall` 旧类名，按当前列数将第 `index` 张显式放入 `index % columns` 列；三列时第 1/2/3 张分别进入三列，第 4/5/6 张再分别接到三列下方。列数以容器实际宽度和 288px 首选最小列宽计算，不以 viewport 硬切；先设目标卡宽再测真实卡高，列内用 computed gap 紧凑堆叠。 +- 动态边界：只有当容器宽度、卡数和所有卡高有效时才进入 absolute Masonry ready；否则保留 Grid fallback。`ResizeObserver + requestAnimationFrame` 在容器变宽、图片/字体/文本改变高度、筛选重排和 cursor 追加后全量重算；cleanup 必须兼容 StrictMode，避免分页 sentinel 因容器短暂零高提前触发。 +- 验证：纯函数测试锁定容器宽度临界值、`index % columns` 和最高列容器高；样式契约同时锁定 Grid fallback 与 Masonry ready。Playwright 需在同一 viewport 内改容器宽度验证 3/2/1 列，检查每列相邻卡间距等于 gap、容器高等于最高列底、DOM 顺序不变且无重叠/横向溢出。 +- 关联：`src/index.css`、`src/index.test.ts`、`src/components/creation-home/CreationLandingView.tsx`、`src/components/creation-home/showcaseMasonryLayout.ts`。 ## 画板外部生成排队超时不是失败 diff --git a/docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md b/docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md index bcc053f41..053e616b7 100644 --- a/docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md +++ b/docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md @@ -75,11 +75,11 @@ ### 陶泥儿精选 -`陶泥儿精选` 是页面底部的全站公开画布生成素材瀑布流，不承载玩法入口列表。瀑布流卡片按真实素材宽高设置预览比例，同一行允许出现不同高度卡片，不使用固定等高网格。创作入口配置仍继续来自 `/api/creation-entry/config`，供旧创作入口和具体 `/creation/` 工作台使用，但不作为本页精选区内容。 +`陶泥儿精选` 是页面底部的全站公开画布生成素材流，不承载玩法入口列表。列表按 DOM 顺序做循环分列：当前为三列时，第 1 / 2 / 3 张分别进入第 1 / 2 / 3 列，第 4 / 5 / 6 张再分别接到这三列下方，后续持续循环；不用最短列贪心分配改变每组的列归属。列数根据精选容器真实可用宽度自动在三、二、一列之间切换，不以整个 viewport 宽度硬判断。卡片仍按真实素材宽高设置预览比例，每张紧贴本列上一张且保留正常 gap，不拉伸、裁成等高卡，也不使用 multi-column 的纵向平衡或标准 Grid 的共享行高。 精选内容只使用用户从账号级素材库主动提交、后台审核通过且展示状态开启的 `editor_showcase_asset` 快照。新生成素材不会默认公开，审核通过后也不会自动展示；运营可在后台按前台具体 Tab 设置分类（角色、UI、音乐、美宣）并开启展示，未设置分类的素材不会隐藏，会进入前台“全部”。旧 `editor_project_resource.public_showcase_enabled` 只保留历史兼容，不再作为 `/creation` 精选事实源。账号级 `editor_asset` 仍是素材库私有事实；只有 `sourceType="generated"`、有媒体内容、提交审核并通过的素材才可进入精选，上传素材、公开作品图片和 `mock_generated` 资源都不进入精选。审核通过时按生成成本返还 50% 泥点，返还流水使用确定性 `editor-showcase-refund:{showcaseId}` 保证幂等；批准状态、钱包返还流水和 `refund_completed_at` 必须在同一个 SpacetimeDB 事务中完成，任一步失败都保持待审核，历史已通过但未返还记录重复批准时按同一流水补齐且不得重复入账。已通过、已开启展示且返还完成的精选快照必须按同 owner 的精确 `assetObjectId` 或 `objectKey` 派生匿名读取授权，不能放开整个 `generated-*` 前缀。公开 BFF 必须返回作者公开展示字段：优先 `authorDisplayName` / `display_name`，没有展示名时兜底 `authorPublicUserCode` / 陶泥号；前端展示绝不能兜底到内部 `ownerUserId` / `user_id`。若现有数据缺少提示词、作者公开标识或成本字段，v1 显示保守占位，不伪造内容。 -瀑布流通过 `GET /api/editor/showcase/resources` 按通过审核时间 / `showcaseId` 倒序 cursor 分页读取，每页最多 36 条；响应有 `nextCursor` 时，页面滚动到底部继续请求 `?cursor=...` 并追加到现有瀑布流，而不是固定只展示首屏数量。响应可以额外携带后台配置的固定活动卡，用于在列表首位展示运营精选。活动卡图片继续保持 private：后台直传 OSS 后必须先确认正式 `asset_object`，公开读取只由已启用 `global` 配置对活动卡专用目录中的当前 exact `imageObjectKey` 派生，禁用或替换图片后旧 key 不再可读；历史缺 metadata 的当前活动卡可通过同一 exact 配置授权恢复，但新上传不能跳过 confirm。 +精选素材流通过 `GET /api/editor/showcase/resources` 按通过审核时间 / `showcaseId` 倒序 cursor 分页读取，每页最多 36 条；响应有 `nextCursor` 时，页面滚动到底部继续请求 `?cursor=...` 并追加到现有列表，而不是固定只展示首屏数量。追加、筛选、分类和容器/卡片尺寸变化都必须按当前完整 DOM 顺序重算循环分列；位置未完整时保留正常文档流 fallback，不能让分页 sentinel 因容器短暂零高提前触发。响应可以额外携带后台配置的固定活动卡，用于在列表首位展示运营精选；活动卡作为第一张进入第一列，普通素材从第二张继续同一循环列序。活动卡图片继续保持 private：后台直传 OSS 后必须先确认正式 `asset_object`，公开读取只由已启用 `global` 配置对活动卡专用目录中的当前 exact `imageObjectKey` 派生，禁用或替换图片后旧 key 不再可读；历史缺 metadata 的当前活动卡可通过同一 exact 配置授权恢复，但新上传不能跳过 confirm。 Tab： @@ -164,7 +164,7 @@ Tab： ### 创作主页 - 新增 `CreationLandingView`。 -- 实现首屏主视觉、九大功能区、最近项目区和陶泥儿精选素材瀑布流。 +- 实现首屏主视觉、九大功能区、最近项目区和陶泥儿精选顺序循环分列素材流。 - 九大功能区卡片必须是可点击按钮；已开放卡片复用 `createEditorProject` 和画布现有生成器，不新增入口系统；暂未开放卡片复用移动端欢迎弹窗样式。 - 桌面端复用现有平台壳层，保留上方栏和左侧导航栏。 - 主页整体采用浅色布局，避免外站品牌文案。 @@ -223,8 +223,8 @@ git diff --check - 移动端进入 `/` 首页时显示 `欢迎` 弹窗，正文包含移动端仅支持作品展示和电脑端访问提示，按钮为 `好`。 - 移动端直达 `/creation` 显示“请在桌面端打开创作主页”，点击“返回首页”回到 `/`。 - “我的”页没有项目快捷入口。 -- 陶泥儿精选素材瀑布流不出现账号级非项目素材、公开作品补充、上传素材、mock 素材、假作者或假泥点成本。 -- 陶泥儿精选素材卡按真实素材宽高呈现瀑布流，不退化为固定等高网格。 +- 陶泥儿精选素材流不出现账号级非项目素材、公开作品补充、上传素材、mock 素材、假作者或假泥点成本。 +- 陶泥儿精选按 DOM 索引循环分列，每组卡片依次占用当前所有列，列内不因其它列的高卡留空；卡片按真实素材宽高呈现，不强制固定等高。列数必须根据精选容器实际宽度自动变为三/二/一列，不以 viewport 断点代替容器宽度。 - 陶泥儿精选不出现玩法入口卡或公开作品图片补充展示。 ## 非目标 diff --git a/src/components/creation-home/CreationLandingView.test.tsx b/src/components/creation-home/CreationLandingView.test.tsx index fdd3acb0c..a85a5d614 100644 --- a/src/components/creation-home/CreationLandingView.test.tsx +++ b/src/components/creation-home/CreationLandingView.test.tsx @@ -470,7 +470,7 @@ describe('CreationLandingView', () => { expect(within(card as HTMLElement).getByText('20泥点')).toBeTruthy(); }); - it('likes a featured asset from the waterfall card action', async () => { + it('likes a featured asset from the list card action', async () => { const user = userEvent.setup(); listEditorProjectsMock.mockResolvedValueOnce(projectItems); listPublicEditorProjectResourcesMock.mockResolvedValueOnce([ @@ -684,7 +684,7 @@ describe('CreationLandingView', () => { ); }); - it('uses Taonier featured as the generated project resource waterfall instead of creation entries', async () => { + it('uses Taonier featured as the generated project resource list instead of creation entries', async () => { listEditorProjectsMock.mockResolvedValueOnce(projectItems); listPublicEditorProjectResourcesMock.mockResolvedValueOnce([ { @@ -736,9 +736,13 @@ describe('CreationLandingView', () => { expect(await screen.findByText('精选素材 A')).toBeTruthy(); expect(screen.getByText('精选素材 B')).toBeTruthy(); expect(screen.queryByText('上传素材')).toBeNull(); - expect(screen.getByLabelText('用户素材瀑布流').className).toContain( + const showcaseList = screen.getByRole('list', { + name: '陶泥儿精选素材列表', + }); + expect(showcaseList.className).toContain( 'creation-landing__asset-waterfall', ); + expect(within(showcaseList).getAllByRole('listitem')).toHaveLength(2); const firstPreview = container.querySelector( '.creation-landing__asset-preview', ) as HTMLElement | null; @@ -804,7 +808,7 @@ describe('CreationLandingView', () => { ); }); - it('loads more featured resources when the waterfall reaches the end', async () => { + it('loads more featured resources when the list reaches the end', async () => { const observers = installIntersectionObserverMock(); listEditorProjectsMock.mockResolvedValueOnce(projectItems); listPublicEditorProjectResourcesMock @@ -898,10 +902,10 @@ describe('CreationLandingView', () => { await screen.findByRole('button', { name: '读取更多素材失败，点击重试' }), ).toBeTruthy(); expect(screen.getByText('精选素材 A')).toBeTruthy(); - expect(screen.getByLabelText('用户素材瀑布流')).toBeTruthy(); + expect(screen.getByLabelText('陶泥儿精选素材列表')).toBeTruthy(); }); - it('keeps the featured waterfall empty when project resources are empty', async () => { + it('keeps the featured list empty when project resources are empty', async () => { renderCreationLanding({ authValue: createAuthValue({ user: null, @@ -910,7 +914,7 @@ describe('CreationLandingView', () => { }); expect(await screen.findByText('暂无素材')).toBeTruthy(); - expect(screen.queryByLabelText('用户素材瀑布流')).toBeNull(); + expect(screen.queryByLabelText('陶泥儿精选素材列表')).toBeNull(); expect(screen.queryByText('精选入口')).toBeNull(); }); }); diff --git a/src/components/creation-home/CreationLandingView.tsx b/src/components/creation-home/CreationLandingView.tsx index 4abd9bcbf..b3496951f 100644 --- a/src/components/creation-home/CreationLandingView.tsx +++ b/src/components/creation-home/CreationLandingView.tsx @@ -1,5 +1,12 @@ import { Film, Image as ImageIcon, Music2 } from 'lucide-react'; -import { useCallback, useEffect, useMemo, useRef, useState } from 'react'; +import { + useCallback, + useEffect, + useLayoutEffect, + useMemo, + useRef, + useState, +} from 'react'; import { useResolvedAssetReadUrl } from '../../hooks/useResolvedAssetReadUrl'; import { ApiClientError } from '../../services/apiClient'; @@ -30,6 +37,10 @@ import { type ShowcaseAssetPreview, type ShowcaseTabId, } from './creationShowcaseModel'; +import { + applySequentialShowcaseMasonry, + resetSequentialShowcaseMasonry, +} from './showcaseMasonryLayout'; type CreationLandingViewProps = { onOpenProject: ( @@ -171,6 +182,59 @@ function getPreviewAspectRatio(preview: ShowcaseAssetPreview) { : undefined; } +function useSequentialShowcaseMasonry( + itemOrderKey: string, + expectedItemCount: number, +) { + const containerRef = useRef(null); + + useLayoutEffect(() => { + const container = containerRef.current; + if (!container) { + return; + } + + const view = container.ownerDocument.defaultView; + let animationFrame: number | null = null; + const layout = () => { + animationFrame = null; + applySequentialShowcaseMasonry(container, { expectedItemCount }); + }; + const scheduleLayout = () => { + if (animationFrame !== null) { + return; + } + if (view?.requestAnimationFrame) { + animationFrame = view.requestAnimationFrame(layout); + return; + } + layout(); + }; + + layout(); + const ResizeObserverConstructor = globalThis.ResizeObserver; + const resizeObserver = ResizeObserverConstructor + ? new ResizeObserverConstructor(scheduleLayout) + : null; + resizeObserver?.observe(container); + for (const card of container.querySelectorAll( + ':scope > .creation-landing__asset-card', + )) { + resizeObserver?.observe(card); + } + + return () => { + if (animationFrame !== null && view?.cancelAnimationFrame) { + view.cancelAnimationFrame(animationFrame); + } + resizeObserver?.disconnect(); + resetSequentialShowcaseMasonry(container); + }; + }, [expectedItemCount, itemOrderKey]); + + return containerRef; +} + function getPreviewIcon(preview: ShowcaseAssetPreview) { if (preview.mediaType === 'audio') { return