feat(edit): 编辑页上报ozon 开发
This commit is contained in:
R524809
+17
-8
@@ -1,12 +1,12 @@
|
||||
# Atlas Seller Kit 交接说明
|
||||
|
||||
> 更新：2026-09-29。此文是新 AI 对话、架构讨论与开发工作的首读入口。开始开发前，必须先阅读并遵守 [`development-collaboration-contract.md`](./development-collaboration-contract.md) 和仓库 `AGENTS.md`。下方按日期记录的旧方案仅供追溯；当前状态以本节、2026-09-29 类目佣金记录及最新的 1.47 节为准。
|
||||
> 更新：2026-09-30。此文是新 AI 对话、架构讨论与开发工作的首读入口。开始开发前，必须先阅读并遵守 [`development-collaboration-contract.md`](./development-collaboration-contract.md) 和仓库 `AGENTS.md`。下方按日期记录的旧方案仅供追溯；当前状态以本节、2026-09-29 类目佣金记录及最新的 1.47 节为准。
|
||||
|
||||
## 1. 项目定位
|
||||
|
||||
这是一个全新的云端产品，不是 `ozon-seller-kit` 的本地版重构。目标用户可拥有多个门店，每个门店只能绑定一个平台；平台自身可支持多个市场、国家、语言和币种。因此语言、币种、类目和发布规则不能写死为 Ozon 或中文/俄文。
|
||||
|
||||
pnpm monorepo 包含 Web、NestJS API、BullMQ Worker、WXT 浏览器扩展、共享契约、数据库包和本地基础设施。认证、工作空间隔离、门店/素材、采集箱、商品编辑草稿、平台级商品参考目录、发布预检和商品 AI 填报已有实现；SKU 定价试算与确认、在线商品同步已有实现，真正的 Ozon 首次发布仍待接入。不要从旧项目复制 SQLite 模型、无鉴权 API、旧 `/trial/:id` 或商品编辑页组件；复用纯规则前须适配多租户和云端边界。
|
||||
pnpm monorepo 包含 Web、NestJS API、BullMQ Worker、WXT 浏览器扩展、共享契约、数据库包和本地基础设施。认证、工作空间隔离、门店/素材、采集箱、商品编辑草稿、平台级商品参考目录、发布预检和商品 AI 填报已有实现；SKU 定价试算与确认、在线商品同步已有实现，Ozon 首次发布已实现，真实店铺 VAT 和七牛图片交付仍待验收。不要从旧项目复制 SQLite 模型、无鉴权 API、旧 `/trial/:id` 或商品编辑页组件；复用纯规则前须适配多租户和云端边界。
|
||||
|
||||
当前运行时基线：Node 24.20.0、pnpm 11.25.0、PostgreSQL 18.6、Redis 7.4.11、MinIO `RELEASE.2025-09-07T16-13-09Z`；Web 默认端口为 `8100`，API 默认端口为 `8200`，扩展 dev server 默认端口为 `8110`（仅本地开发用），Worker 无 HTTP 端口。完整目录、依赖边界与版本表见 [`architecture/project-structure.md`](../architecture/project-structure.md) 和 [`architecture/technology-and-deployment.md`](../architecture/technology-and-deployment.md)。
|
||||
|
||||
@@ -14,12 +14,21 @@ pnpm monorepo 包含 Web、NestJS API、BullMQ Worker、WXT 浏览器扩展、
|
||||
|
||||
已完成“采集 → 采集箱 → 商品编辑草稿”的主要数据闭环、平台级类目/属性/字典目录与发布预检。编辑页已接入异步「AI 填报」：基于来源资料与 Atlas 类目树生成类目建议、型号/SKU 货号、证据充分的包装建议及 SPU 中俄文案；单 SKU 文案由用户单独生成并确认应用。AI 结果只回填未保存表单，保存草稿仍是持久化边界。Ozon 动态类目属性可按已选类目加载并手工填写，**当前不由 AI 自动填报**。SKU 图片选择现支持采集候选图、工作空间上传图和网络导入图；在弹窗确认后回填草稿，页面保存后持久化。
|
||||
|
||||
SKU 定价已打通试算、表单应用与原子保存确认，在线商品同步已有 API/Worker。可直接发布的闭环仍缺真正的 Ozon 发布 job/import 及结果轮询；正式定价还需完成 CEL 费率及类目佣金映射审核。AI 类目推荐和文案已能运行，但不能等同于跨来源样本验收；尤其应继续用 1688/淘宝/天猫样本核验 Atlas 类目候选质量，以及俄文文案、包装证据和 SKU 继承行为。AI 套图生图仍是占位入口；图片「编辑」菜单中的一键 3:4、添加水印和单张 AI 编辑已接入异步素材任务。
|
||||
SKU 定价已打通试算、表单应用与原子保存确认，在线商品同步已有 API/Worker。首次发布 job/import 与结果轮询已接入；生产启用仍需完成 VAT 与七牛图片交付验收；正式定价还需完成 CEL 费率及类目佣金映射审核。AI 类目推荐和文案已能运行，但不能等同于跨来源样本验收；尤其应继续用 1688/淘宝/天猫样本核验 Atlas 类目候选质量，以及俄文文案、包装证据和 SKU 继承行为。AI 套图生图仍是占位入口；图片「编辑」菜单中的一键 3:4、添加水印和单张 AI 编辑已接入异步素材任务。
|
||||
|
||||
当前优先事项：用真实来源样本回归 AI 类目推荐、文案与图片选择，补做真实图片上传/网络导入联调；审核正式物流费率与佣金映射，并用实际结算账单核对 Ozon 平台服务费、收款费和其他扣费；让首次发布 job 复用既有发布预检，再实现 Ozon import 与结果轮询。平台参考目录目前由平台级参考源和同步任务维护，不能把 9 月 10 日的门店级缓存描述当作现行架构。
|
||||
当前优先事项：用真实来源样本回归 AI 类目推荐、文案与图片选择，补做真实图片上传/网络导入联调；审核正式物流费率与佣金映射，并用实际结算账单核对 Ozon 平台服务费、收款费和其他扣费；完成首次发布在中国主体跨境 rFBS 测试店铺的 VAT 省略与七牛延迟抓图验收。平台参考目录目前由平台级参考源和同步任务维护，不能把 9 月 10 日的门店级缓存描述当作现行架构。
|
||||
|
||||
接手前请先阅读 `git status --short`，确认当前工作区状态；本轮图片选择的 Web、API、contracts、迁移、测试和文档随本报告一起提交。不要用 `git reset --hard` 或批量清理未跟踪文件。共享 contracts 类型需先构建，再执行 Web/API/Worker 检查。开发验证需要时可按 `AGENTS.md` 先确认进程与端口，再启动或重启 API/Worker；下方旧章节中的“不可重启”说法已失效。
|
||||
|
||||
### 2026-09-30：商品编辑页首次上架
|
||||
|
||||
- Web、API、Worker、contracts 与 database 同步实现，接口以 [商品编辑与首次上架 §7](../api/product-editor-and-publishing.md) 为准；研究、产品决策及验收见 [实施记录](../product/ozon-first-publish-review-plan.md)。扩展未改动。
|
||||
- 两个入口为「上架至 OZON」「部分上架」，只提交未导入或失败 SKU，显示已导入/进行中的跳过原因；每批最多 50，先保存草稿、预检和确认，再原子写入不可变快照及 Outbox。成功锁定型号和历史货号，其他资料仍能保存。任务状态可刷新恢复。
|
||||
- Worker 提交前检查远端货号，导入后轮询；受理结果不确定时仅对账，禁止盲目重发。七牛图片校验 checksum、复制发布对象、WebP 转 JPEG，再签发独立私有 HTTPS 下载地址，默认 7 天；不持久化签名或 URL。
|
||||
- VAT 按维护者确认首期省略，不默认 `0`；rFBS 首期不提交条码、库存和仓库。生产 `OZON_PUBLISH_ENABLED=auto` 默认关闭，真实店铺与图片验收后显式启用。MinIO 素材不能直接供 Ozon 抓取，需要迁移到七牛；环境项见 `.env.example`。
|
||||
- `055` 全量空库迁移和本地开发库应用通过。26 项 API/编辑器/素材与 14 项 Worker 测试通过；contracts/API/Worker/Web 类型检查与构建通过，Web 仍有既有 bundle 提示。隔离库浏览器验证了禁选、全部/部分预检、缺字段阻断、提交及刷新恢复，未发送真实 Ozon 导入。
|
||||
- 维护者原有 API8200、Web8100、Worker 保持运行，通过监听自动加载改动；验证用 API8201、Web8101 已关闭，隔离测试库已清理。
|
||||
|
||||
### 2026-09-29：类目佣金 JSON 导入与定价接入
|
||||
|
||||
- 已先编写[实施方案](../product/category-commission-import-plan.md)，并完成[API 契约](../api/category-commissions.md)、迁移 `052`、导入解析器、原子启用、管理页面及试算展示。影响 Web、API、contracts、database；未涉及 Worker 和扩展。
|
||||
@@ -468,7 +477,7 @@ BullMQ Worker（最多 5 次，5 秒起指数退避）
|
||||
- 全局填报读取 Atlas 平台级活动类目树，按层向模型提供有限候选；对大分支分段初选、再决选，只接受给定选项。明确结果可回填类目，有多个命中则在「确认 AI 推荐类目」弹窗中由用户选择。已有类目不被覆盖；未确认类目时不能生成依赖它的型号和货号。型号是 SPU 共用稳定码，未导入 SKU 的货号分别生成并检查长度、连接符及冲突。
|
||||
- 全局文案只生成 SPU 的俄文标题、主题标签、产品描述及逐项中文对照；描述要求概述与「Характеристики:」分段、项目符号。SKU 默认继承 SPU 三项文案；用户可打开当前 SKU 的 AI 弹窗，预览后明确点击应用，才写入该 SKU 的未保存表单。SPU/SKU 都有中俄对照查看入口，俄文被手工修改后旧中文对照标为待更新。
|
||||
- 包装重量和尺寸仅在来源有可逐字核对的证据时建议；缺证据则留空。原计划的「AI 填写 Ozon 类目属性」已撤回：当前只在类目确定后按 schema 动态加载商品/SKU 属性，用户自行填写。`030_product_ai_attribute_fill.sql` 与历史 `attribute_fill` 类型保留兼容，不代表当前仍会创建或执行该任务。
|
||||
- 编辑页已把「内部商品名」文案改为「中文商品名」，「俄文发布标题」在表单与发布就绪校验中必填；SPU 标题有加号入口开启 SKU 标题覆盖。SKU 的 Ozon 变体字段已并入「SKU 信息」，不另设「Ozon 变体属性」标题。底部 `editor-footer` 固定在视口底部；AI 类目候选弹窗已调整为说明、单选候选和明确确认操作。类目输入框清除时的空值处理已修正。
|
||||
- 编辑页已把「内部商品名」文案改为「中文商品名」；「俄文标题」默认在 SPU，支持切换为按 SKU 设置并持久化模式。草稿保存允许标题留空，首次上架预检按通用或逐 SKU 模式检查。SKU 的 Ozon 变体字段已并入「SKU 信息」，不另设「Ozon 变体属性」标题。底部 `editor-footer` 固定在视口底部；AI 类目候选弹窗已调整为说明、单选候选和明确确认操作。类目输入框清除时的空值处理已修正。
|
||||
- 最新俄文文案规则同时作用于 SPU 与 SKU Prompt：`title.ru`、`tags[].ru`、`description.ru` 不得出现汉字；来源中文事实应翻译为自然俄文，只有有依据的拉丁品牌/型号及阿拉伯数字可保留。Worker 结果校验会丢弃仍含汉字的对应字段，中文对照与包装原文证据不受此限制。旧已保存文案不会自动改写，需重新生成或手工修订。
|
||||
|
||||
**验证状态与下一步**
|
||||
@@ -567,7 +576,7 @@ BullMQ Worker（最多 5 次，5 秒起指数退避）
|
||||
| 采集 SKU | 只有来源给出稳定 SKU/组合证据时创建多个 SKU；不能把规格轴做笛卡尔积。没有专属 SKU 图时，真实 SKU 继承父商品默认图而不复制资产。 |
|
||||
| 媒体 | 采集主图/详情图是商品候选池；来源明确给出 SKU、或可靠的规格轴值（如颜色）与图片关系时才自动绑定。其余素材由编辑页人工选择。 |
|
||||
| 发布与在线商品 | 商品采集、编辑、定价、AI 媒体和首次导入至 Ozon 后台是核心闭环。正式发布使用官方 Seller API，按一 SKU 一 import item/offer 执行并轮询结果；首期不传库存或仓库，用户在 Ozon 后台设置库存。已导入 SKU 不可再次上架，未上架 SKU 仍可首次上架；SPU 在当前平台汇总为未上架/已部分上架/已上架。在线商品由异步 Ozon API 同步，按 Ozon 商品 SKU 展示，亦包含非 Atlas 发布商品。 |
|
||||
| 平台商品参考目录 | `platform_id` 下共享类目/类型树、属性定义和字典候选值；同平台门店共用，本阶段不维护门店差异层。定时同步、系统管理员页面、手动排队、商品编辑器读取和发布预检已实现；真正的 Ozon 发布 job 待开发。 |
|
||||
| 平台商品参考目录 | `platform_id` 下共享类目/类型树、属性定义和字典候选值；同平台门店共用，本阶段不维护门店差异层。定时同步、系统管理员页面、手动排队、商品编辑器读取和发布预检已实现；真正的 Ozon 发布 job 已实现，真实店铺联调待验收。 |
|
||||
|
||||
## 3. Ozon 已核对结论
|
||||
|
||||
@@ -602,7 +611,7 @@ User → Workspace → Membership / Role
|
||||
- 所有接口遵循统一鉴权、工作空间隔离、页头平台上下文、金额字符串、错误格式、`Idempotency-Key`、`If-Match` 和异步 `operation` 约定。
|
||||
- **响应信封是强制契约：** 成功单资源或同步动作返回 `{ "data": T }`，列表返回 `{ "data": T[], "meta": PaginationMeta }`，失败返回 `{ "error": ApiError }`，`204 No Content` 不返回响应体。项目不采用完整 JSON:API；任何调用方不得自行增加嵌套 `data` 或以 `data: null` 表示错误。完整规则见 [`api/conventions.md`](../api/conventions.md)。
|
||||
- 关键异步动作必须在同一事务写入业务记录、`operations`（如需用户可见进度）和 `outbox_events`；Dispatcher 至少一次投递 BullMQ，Worker 必须幂等。
|
||||
- 早期 DDL 已通过本地隔离 PostgreSQL 验证；迁移执行器、认证/工作空间基础、幂等与 Outbox 写入闭环、Outbox Dispatcher、Ozon 凭据验证、采集清理、来源素材转存及商品 AI Worker 已有实现。新近 `029`/`030` 迁移在目标环境中的应用状态需单独核对；商品发布和在线商品同步 Worker 仍待实现。
|
||||
- 早期 DDL 已通过本地隔离 PostgreSQL 验证；迁移执行器、认证/工作空间基础、幂等与 Outbox 写入闭环、Outbox Dispatcher、Ozon 凭据验证、采集清理、来源素材转存及商品 AI Worker 已有实现。新近 `029`/`030` 迁移在目标环境中的应用状态需单独核对；商品发布和在线商品同步 Worker 已实现，真实平台联调状态见最新记录。
|
||||
|
||||
仍需在对应模块开始编码前完成的 P1/P2 决策和数据模型补丁，集中记录在 [`reviews/implementation-readiness-open-items.md`](../reviews/implementation-readiness-open-items.md)。
|
||||
|
||||
@@ -616,7 +625,7 @@ User → Workspace → Membership / Role
|
||||
|
||||
1. 核对 AI 任务迁移、运行进程版本和四类来源的真实样本；回归类目选择、中俄文案（俄文字段不含汉字）、包装证据、SKU 文案继承及候选媒体按需物化，并联调 SKU 图片上传、网络导入与保存。
|
||||
2. 完成定价确认、平台目录大字典续传与管理员浏览器回归；旧门店目录继续保留，暂不清理。
|
||||
3. 将真正的 `publish-jobs` 创建事务接入已完成的发布预检，固化发布快照后实现 Ozon `/v3/product/import` 与结果轮询，再推进在线商品同步；不得重新实现另一套目录判断。
|
||||
3. 首次发布 job、快照、Ozon 导入/轮询和在线同步已实现；下一步完成真实中国主体跨境 rFBS 店铺的 VAT 省略和七牛图片交付验收。
|
||||
|
||||
### 历史计划（仅供追溯）
|
||||
|
||||
|
||||
Reference in New Issue
Block a user