From 0219b1a2f4d95244383ca93d790573c5a55296ec Mon Sep 17 00:00:00 2001 From: zhangyahui Date: Thu, 7 May 2026 13:53:06 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=95=86=E5=93=81=E7=BC=96=E8=BE=91?= =?UTF-8?q?=E9=A1=B5=E9=9D=A2=E7=9A=84agents.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../MyListings/EditDetail/agents.md | 46 +++++++++++++++++-- 1 file changed, 43 insertions(+), 3 deletions(-) diff --git a/src/views/SellerDashboard/MyListings/EditDetail/agents.md b/src/views/SellerDashboard/MyListings/EditDetail/agents.md index d7f2d287..55112b27 100644 --- a/src/views/SellerDashboard/MyListings/EditDetail/agents.md +++ b/src/views/SellerDashboard/MyListings/EditDetail/agents.md @@ -30,12 +30,21 @@ This directory owns the seller listing edit/create detail page. Detail API images are mapped by `category`: - `cover` -> `currentListing.cover` +- `cover_from` -> `currentListing.coverFrom`; `imageUrl` stores the source image URL, not the literal source key. Resolve it against `sketch` and `mainProductImage` when hydrating. Keep backward compatibility for old rows whose `imageUrl` is `sketch` or `mainProductImage`. - `sketch` -> `currentListing.sketch` -- `mainProductImage` -> `currentListing.mainProductImage` -- `main_product` or `product` -> `currentListing.prodImageList` +- `mainProductImage` or `main_product` -> `currentListing.mainProductImage` +- `product` -> non-video entries in `currentListing.prodImageList` +- `firstFrame`, `gif`, and `video` -> one video entry in `currentListing.prodImageList` when the three rows share the same `sortOrder` - `apparel` -> `currentListing.sketchList` -When saving, preserve the backend's expected image categories. Confirm backend naming before changing `main_product`, `product`, or `mainProductImage`. +When saving, preserve the backend's expected image categories. Confirm backend naming before changing `main_product`, `product`, `firstFrame`, `gif`, `video`, or `mainProductImage`. + +中文补充： + +- 详情接口返回的 `images` 要按 `category` 回填到页面状态，不要只按数组顺序猜类型。 +- `cover_from` 不是封面图本身，而是记录封面裁剪来源。它的 `imageUrl` 传来源图片链接，回显时用这个 URL 和 `sketch`、`mainProductImage` 比较，恢复裁剪弹窗里的来源选择。 +- `main_product` 表示页面右上方的主产品图 URL；普通 `product` 只表示产品图列表里的非视频图片。 +- 视频不要保存成 `product`。视频必须拆成 `firstFrame`、`gif`、`video` 三类，并在回显时按相同 `sortOrder` 合并成一个视频项。 ## Product Image Rules @@ -43,12 +52,43 @@ When saving, preserve the backend's expected image categories. Confirm backend n - `firstSelectedIndex` is stored on each `ListingItem` and passed to `ProductImageList.vue`. - Selecting a product image should only set `mainProductImage` when no main image is currently tracked by that listing's `firstSelectedIndex`. - Unselecting the current main product image clears `mainProductImage` and resets `firstSelectedIndex`. +- Videos can be selected and saved, but they cannot become `mainProductImage`, must not set `firstSelectedIndex`, and must not display the `main` badge. + +中文补充： + +- `main` 标识只给图片，不给视频。 +- 第一次选择视频时可以弹 warning，但视频本身仍然要保持选中；只是不要把它写入 `mainProductImage`，也不要更新 `firstSelectedIndex`。 +- 如果先选中视频，再选中图片，图片仍然可以成为第一个主图。 +- 如果取消的是当前主图图片，需要清空 `mainProductImage` 和 `firstSelectedIndex`；取消普通图片或视频不应影响主图。 + +## Save Image Ordering + +- Every saved image row must include `sortOrder`. +- `sortOrder` is scoped per category; each category starts its own sequence. +- For `product` rows, save the image currently used as `mainProductImage` first, selected non-main images next, and unselected images last. +- Save video media as three rows with categories `firstFrame`, `gif`, and `video`. The three rows from the same video item must share the same `sortOrder`. +- When hydrating detail data, group `firstFrame`, `gif`, and `video` rows by matching `sortOrder` and restore the combined video item, including its selected state. Accept `isSelected`, old typo `isSeleted`, and `selected` from the API. + +中文补充： + +- `sortOrder` 是按 category 分开排的，不同 category 之间不要共用一个全局序号。 +- `product` 的排序规则是：当前作为 `mainProductImage` 的图片第一，其他已选图片其次，未选图片最后。 +- 同一个视频拆出的 `firstFrame`、`gif`、`video` 三条数据必须使用同一个 `sortOrder`。例如第一个视频三条都是 `sortOrder: 1`，第二个视频三条都是 `sortOrder: 2`。 +- 回显视频时，用相同 `sortOrder` 找回一组 `firstFrame/gif/video`。三条里任意一条带选中标记，都应恢复为这个视频已选中。 +- 选中字段要兼容 `isSelected`、历史拼写 `isSeleted`、以及 `selected`。 ## Crop Flow - `TopImageSection.vue` and `ApparelSketchList.vue` emit `crop`. - `index.vue` handles `handleClickCrop`, opens `ImageClipDialog`, uploads with `uploadFile`, then writes the returned URL into the correct field/list item. - Keep cover crop ratio at `[4, 5]`; other crop types use `[9, 16]`. +- Cover crop can be based on `sketch` or `mainProductImage`. Store the chosen source in `coverFrom`, save it via `cover_from.imageUrl` as the source image URL, and pass it back into `ImageClipDialog` so reopening cover crop restores the selected source. + +中文补充： + +- cover 裁剪弹窗会在 `sketch` 和 `mainProductImage` 之间切来源。用户保存 cover 时，父组件需要同时保存裁剪后的 cover URL 和本次使用的来源。 +- 下次重新打开 cover 裁剪时，应该按 `coverFrom` 恢复来源选择，并用对应的原图作为裁剪图，不要直接拿已裁好的 cover 图再次裁。 +- 如果只有一个来源图可用，就按可用来源打开；如果两个来源都可用，要显示来源切换。 ## Form Flow