joey5628/atlas-seller-kit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2b06ef06927c6719cab37ecbc05ee5cfdf120ec9
atlas-seller-kit/docs/project/m2.2-m2.3-extension-collection.md
T
R524809 319887726e Update seller store experience
2026-09-08 16:19:38 +08:00

6.1 KiB
Raw Blame History

M2.2 / M2.3：扩展授权、素材候选与 Ozon 公开页采集

状态：已完成首个可运行闭环（2026-09-05）。Seller 网页四接口观察实验不属于本批次，仍待独立任务实施。

已交付

  1. 扩展按毛子 ERP 风格复用 Atlas Web 登录态：点击登录会打开 Atlas Web；Web 登录/恢复后把当前短期 access token 写入本站 localStorage，扩展每 2 秒从该 Atlas 标签读取并保存到 extension storage。未登录时用户在该页完成登录，标签不会被扩展自动关闭。
  2. 扩展以同步到的 Web Bearer token 调用会话检查和采集接口；服务端同时验证 JWT 与未撤销的 Web session，并从当前用户成员关系解析工作空间。Token 失效时插件清除缓存并重新要求从 Atlas Web 登录同步。
  3. 扩展上报仅携带来源、规范化 SKU/规格轴、候选素材 URL 和证据；POST /api/extension/materials 从 Web Bearer 身份解析工作空间，不接受目标平台、门店、Cookie 或 API Key。非 Ozon 来源按 item key 复用；Ozon 额外按已确认 source_sku 集合相交复用同一采集记录。
  4. 上报事务创建来源采集记录、SPU、来源确认 SKU 和媒体候选（pending_selection）；同一来源商品再次采集时保留记录与商品 ID，并用本次来源快照替换来源字段、SKU 与候选素材。采集本身不下载媒体也不写素材 Outbox。编辑流程选中候选后，POST /api/collection-items/{id}/asset-materializations 才将指定候选置为 queued 并经 Transactional Outbox 进入 Worker；任务带快照版本，Worker 仅处理当前版本，旧任务不得回写。Worker 仅下载 HTTPS 公网地址，限制重定向、私网地址；图片限制 20MB 和 PNG/JPEG/WebP，视频限制 200MB 和 MP4/WebM，均按 SHA-256 去重后写入对象存储。单张失败不会使商品草稿丢失。
  5. Ozon (ru/kz/by) 商品详情页显示 Shadow DOM 小浮窗。未登录只显示“登录 Atlas ERP”；已登录显示“编辑上架 / 采集商品 / 进入 ERP”。商品编辑模块尚未完成时，“编辑上架”成功后打开 /collection-test/{collectionItemId} 供审查采集结果；采集商品只提示进入采集箱。
  6. Ozon 解析器保留当前公开 SKU 作为入口证据，优先解析 state-webAspects-*.data-state.aspects[].variants[] 的真实变体；不会扫描整页 SKU 或把规格轴做笛卡尔积。来源未给可确认组合时，仍保留当前 SKU。
  7. Ozon 多 SKU 补全通过受限 MAIN world bridge 调用同源公开页面 JSON：先读取 modal/aspectsNew 的 webAspectsModal，再以并发 3、上限 100 的队列补全 /product/<sku>/ 中的标题、价格、画廊和关联 SKU。每个已补全 SKU 的画廊图片使用 variant_direct 关联；单个请求失败保留已发现 SKU 与失败证据。
  8. Ozon 公开响应没有可依赖 SPU/组 ID。服务端在同一来源平台下按新旧 source_sku 集合相交覆盖快照；若命中多条历史记录返回 SOURCE_VARIANT_GROUP_AMBIGUOUS，不静默合并。
  9. 图片采集沿用旧采集插件已验证的分组 profile：1688、淘宝、天猫只从主图画廊、规格选择器和商品详情容器读取图片，绝不扫描全页 document.images。淘宝/天猫详情图排除评论和推荐卡片；URL 会在入库前还原 CDN 原图并按归一化 URL 去重。
  10. Ozon 只从 webGallery 读取商品画廊，coverImage 与 images[].src 归为该真实 SKU 的 source_main + variant_direct，不会将第二张及以后的画廊图误标为 SKU 图；webAspects.data.coverImage 作为 source_sku + axis_value。受限 bridge 额外读取固定的富文本页段来获取 webDescription / webRichContent / webFeatures 内的详情图，仍不接触评价或推荐组件。
  11. 采集数据测试页对未转存候选直接加载 source_url；图片展示缩略图，视频采用不预加载的原生播放器，最快核对且不产生对象存储/Worker 下载费用；已经生成 asset_id 的历史素材才按 4 路并发申请短时预览 URL。页面会展示关联来源 SKU；预览 URL 不保存到业务数据。Ozon 解析器 ozon-public-2.3.0 现额外读取短/完整 web*Characteristics.characteristics[] 为公共属性，并将 webDescription.richAnnotationJson 转为公共描述文本、原 JSON 放入 raw_value。该桥接仍只允许固定 Ozon 页面段和 widget 白名单；已有旧版载荷必须重采集才会拥有这些字段。

配置与安全前提

  • 扩展清单带有仅公开的 RSA key，Chrome 因此为自托管和解压加载生成稳定 ID；该 ID 不参与登录授权，严禁提交私钥。
  • 本地默认 API 为 http://localhost:8200。生产构建应为 Atlas API 域配置扩展 host permission 与 ATLAS_API_ORIGIN；不需要按用户登记回调 URI。
  • Web access token 镜像到 Atlas Web 自己的 localStorage 是维护者批准的自托管插件例外；扩展不读取 refresh Cookie、来源站 Cookie 或来源站 localStorage。Worker 不接触浏览器 Cookie。安全取舍见 extension-login-alternatives.md。

尚未实现

  • Ozon 多 SKU 的真实来源页人工回归（packages/reference/ozon1.html 已作为三 SKU 快照）；Ozon Seller 网页四接口观察实验仍独立于此标准公开采集链路。
  • Ozon Seller 网页四接口本地观察实验；1688、淘宝、天猫基础页面状态解析已在 M2.4 完成，但仍需要真实来源页面回归。
  • 正式采集箱详情页的素材关联可视化、重试 UI 和商品编辑/发布闭环（当前仅 /collection-test/{id} 提供只读素材预览与关联 SKU）。

验收命令

./packages/contracts/node_modules/.bin/tsc -p packages/contracts/tsconfig.json
./apps/api/node_modules/.bin/tsc -p apps/api/tsconfig.json --noEmit
./apps/worker/node_modules/.bin/tsc -p apps/worker/tsconfig.json --noEmit
(cd apps/extension && ./node_modules/.bin/wxt prepare && ./node_modules/.bin/tsc -p tsconfig.json --noEmit && ./node_modules/.bin/wxt build)
(cd apps/extension && ./node_modules/.bin/tsx --test test/*.test.mts)
(cd apps/web && ./node_modules/.bin/vite build)
Reference in New Issue View Git Blame Copy Permalink