57 lines
9.1 KiB
Markdown
57 lines
9.1 KiB
Markdown
# 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”。2026-10-05 起，“编辑上架”采集成功后打开 `/products/{productId}/editor?collection_item_id={collectionItemId}`，按 ERP 当前平台初始化或复用编辑上下文，再展示对应商品编辑页；采集商品只提示进入采集箱。早期采集测试页仍可独立用于解析检查。
|
|
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 白名单；已有旧版载荷必须重采集才会拥有这些字段。
|
|
|
|
## 2026-10-05 参数失败诊断
|
|
|
|
采集提交前按共享载荷契约校验；失败保留字段路径，不静默裁剪真实 SKU。服务端字段错误保留最多三项明细，后台经可序列化响应传回内容脚本，由浮窗显示；不再以后台未处理异常吞掉字段原因。浮窗错误提示只包含业务说明，不包含请求头、Cookie 或令牌。真实来源页无法直接读取时，需用户提供新版字段提示才能确认具体参数根因。
|
|
|
|
## 2026-10-06 多 SKU 容量
|
|
|
|
真实 1688 组合超过 100 时，旧采集载荷与编辑保存上限会拒绝整条商品。两处现统一提高到 1000，并共享 `PRODUCT_VARIANT_LIMIT`，不会用数组截断丢弃真实组合；首次发布仍按每批最多 50 个选择。采集响应返回实际未删除 SKU 数。1000 SKU 入库、编辑保存、复采身份保留与超限回滚已通过隔离集成测试。
|
|
|
|
## 2026-10-06 SKU 数量误采与开发包缓存修订
|
|
|
|
解析回退只从明确属性读取直接的对象/数组，不从字段名字符串或 null 跳读其他对象；1688 优先使用同一 skuModel，无来源 ID 的行需完整匹配规格并具有可售证据，元数据不生成 SKU。浮窗显示本次解析的 SKU 数。WXT 构建读取共享源码；开发与正式产物均须核对更新，不能只构建 chrome-mv3 后认为 chrome-mv3-dev 已同步。本次本地复现的 2→150 误采已修复，开发包旧 100 限制已更新，未核验被浏览器策略阻止的实际来源页数量。
|
|
|
|
## 配置与安全前提
|
|
|
|
2026-10-06 1688 画廊补采：明确读取 `.od-picture-gallery-list > .v-image-cover` 内联背景图，不要求旧外层容器或 200px 缩略图尺寸；排除视频控件、参数图标和 undefined 占位地址，还原 CDN 原图并去重。用户提供的商品 1012823100668 画廊样本得到 15 张独立图片。视频补充读取商品画廊内播放器的 currentSrc/src/source 及明确 gallery 脚本字段中的公开 HTTPS MP4/WebM 地址，DOM 与结构化来源去重、补充封面。仅有封面不会生成视频候选，blob/HLS 和画廊外推荐视频不采集。已完成离线样本、真实浏览器本地 DOM 回归和扩展 22 项测试；实际页面视频地址尚待用户提供播放器或公开直链片段，不能用本地合成视频验证替代实际来源验证。
|
|
|
|
2026-10-05 浮窗交互修订：右上角改为 24px 圆形横线最小化按钮（图标 14px），点击隐藏采集面板、显示 40px 圆形「A」入口（文字 20px）；点击「A」恢复面板。尺寸按维护者反馈从最初的 32px / 48px 缩小。最小化不销毁面板或清除当前采集提示，同一来源页的登录态/URL 更新沿用折叠状态。两个入口均支持键盘点击和焦点恢复；刷新页面后从展开状态开始。仅扩展展示与交互调整，采集、登录和编辑跳转继续由内容脚本处理。
|
|
|
|
- 扩展清单带有仅公开的 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`](./extension-login-alternatives.md)。
|
|
|
|
## 尚未实现
|
|
|
|
- Ozon 多 SKU 的真实来源页人工回归（`packages/reference/ozon1.html` 已作为三 SKU 快照）；Ozon Seller 网页四接口观察实验仍独立于此标准公开采集链路。
|
|
- Ozon Seller 网页四接口本地观察实验；1688、淘宝、天猫基础页面状态解析已在 M2.4 完成，但仍需要真实来源页面回归。
|
|
- 正式采集箱详情页的素材关联可视化、重试 UI 和商品编辑/发布闭环（当前仅 `/collection-test/{id}` 提供只读素材预览与关联 SKU）。
|
|
|
|
## 验收命令
|
|
|
|
```sh
|
|
./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)
|
|
```
|