atlas-seller-kit/apps/web/HANDOFF.md

# Web 前端交接：商品编辑器与 AI 填报

更新日期：2026-09-30

本文记录 Web 编辑页的现行状态；跨领域总体进度以 [`../../docs/project/HANDOFF.md`](../../docs/project/HANDOFF.md) 的 1.39 为准。开始继续开发前请查看仓库根目录的 `git status --short`，保留目前 API、Worker、contracts、迁移及 Web 中未提交和未跟踪的改动。

## 当前状态（2026-09-30）

- 编辑页 `/products/:id/editor` 的 `ProductEditPage.tsx` 将底部操作条固定在视口底部，提供「AI 填报」和「保存草稿」；AI 套图生成仍是占位入口；首次上架已接入，见下方记录。全局 AI 填报会先保存未保存草稿，再创建异步任务并轮询；核对商品、profile、来源版本和本地表单未变化后，只把合格结果填进空字段，不直接持久化。用户仍须检查并保存。
- 全局 AI 只回填 SPU 发布标题、标签、描述和中文对照，以及合格的类目、型号、未导入 SKU 货号与有证据的包装建议。类目有多个候选时，「确认 AI 推荐类目」弹窗用单选卡片让用户选择；选择前不自动写入类目。类目一旦确定，页面按现有机制加载动态属性，但不调用 AI 填写 Ozon 类目属性。
- SPU 的「中文商品名」和「俄文标题」标示首次上架必填，草稿保存允许留空；俄文标题可在通用与按 SKU 设置间切换并保存模式，按 SKU 设置时清空、禁用 SPU 标题并在各 SKU 填写。标题、标签、描述各有中文对照入口；用户可在当前 SKU 弹窗中单独生成、预览并明确应用，不因全局 AI 填报而批量覆盖 SKU。
- SKU 的 Ozon `is_aspect` 字段现在直接放在展开卡片的「SKU 信息」中，不另显示「Ozon 变体属性」标题。产品类目 Cascader 的清除事件按空类目处理，避免读取 `undefined.at`。来源采集信息侧栏仍展示来源资料与差异处理。
- 关键组件：`ProductMainInfoSection.tsx`（名称、类目、SPU 标题等）、`ProductAttributeSection.tsx`（SPU 属性、标签与描述）、`ProductVariantSection.tsx`（SKU 信息及动态变体字段）、`ProductCopyAiDialogs.tsx`（SKU AI 生成与中俄对照）。商品编辑流程编排仍主要在 `ProductEditPage.tsx`。

下一轮前端回归应覆盖固定 footer 在不同视口/侧栏状态下不遮挡内容、类目清除和候选确认、AI 任务失败/部分成功/版本过期、SPU/SKU 文案继承与中文对照保存后重读。俄文禁汉字的最终拦截在 Worker，旧文案不会由前端自动清洗。本次更新只修改交接文档，未重新运行浏览器回归。

## 2026-09-30 首次上架

- `ProductPublishActions.tsx` 提供「上架至 OZON」「部分上架」，沿用父页面草稿保存与版本锁，按指定 SKU 调用预检；超过 50 个需分批选择，任一待提交项失败不创建任务。
- 选择表禁选已导入/进行中 SKU，并显示原因；确认摘要列出店铺、货号、售价和图片数量。任务列表恢复最近任务，轮询后仅合并 listing 状态，保留未保存表单。
- 发布标题最多 500、货号最多 50、SKU 图片最多 30；中文来源商品名仍为 1000。已导入或进行中锁定型号，进行中锁定换店；其他草稿资料可以编辑。
- Web 类型检查及构建通过。隔离数据库页面验证了禁选、全部/部分预检、缺货号阻断、确认提交和刷新恢复；没有向真实 Ozon 店铺导入。
- VAT 首期省略且生产发布默认关闭；真实店铺与七牛图片交付待验收。后端契约见 `docs/api/product-editor-and-publishing.md` 第 7 节。

## 2026-09-11 历史前端记录（以下内容仅供追溯）

### 商品编辑器

- 编辑页为 `/products/:id/editor`，主文件为 `src/pages/products/ProductEditPage.tsx`。
- 已接入门店级类目 Cascader：保存时只提交末级类目 ID；父级节点可展开，只有叶子节点可选。类目下拉菜单高度为 324px（相对 Ant Design 默认菜单高度提高 80%）。
- “更多特征”位于 **02 产品属性** Card 内，不再单独使用 Card；展开后按当前选定类目加载 schema，折叠再展开且类目未变时复用已加载的 schema。加载、空 schema、同步类目属性、字典值搜索、清除字段和旧属性告警均在该区处理。
- 动态属性字段按 schema 渲染：普通值为输入框、布尔值为选择框、字典值为可搜索下拉、多值为多选/标签输入；保存时会过滤空的可选属性值，避免提交无效空数组。
- “主题标签”和“JSON 富内容”属于产品属性的普通字段，不属于“更多特征”。
- 编辑页表单已去除页面级的字号、控件高度覆盖，恢复 Ant Design 主题默认规格。仍保留业务性宽度：型号/品牌/条码 170px，包装重量 150px，包装尺寸各 130px。
- 包装重量通过 `package-weight-field` 单独约束输入组宽度，避免 `addonAfter="g"` 与输入框分离；父表单的标签列为 190px、控件区域为可收缩 680px，避免控件被换到标签下一行。

### 组件拆分现状

已拆出的组件：

- `src/pages/products/components/ProductMainInfoSection.tsx`：主要信息、目标门店、类目、标题、品牌、型号、父商品包装规格。
- `src/pages/products/components/ProductOtherSection.tsx`：货源链接和备注。
- `src/pages/products/components/CollectedProductInfoPanel.tsx`：右侧“采集的商品信息”侧栏。

仍在 `ProductEditPage.tsx` 中的视图：产品属性/更多特征，以及变体设置。后续若继续组件化，应将它们分别迁为展示组件；父页面只保留快照读取、草稿保存、类目/schema/字典同步和状态编排。迁移时不要改变 `Form.List` 字段路径、乐观锁保存流程或动态属性的按需加载缓存条件。

### 门店与类目调试入口

- 店铺列表的“刷新门店类目”按钮在 `src/pages/shops/ShopsPage.tsx`；前端会等待请求完成才结束 loading，并展示成功或失败反馈。
- 左侧菜单新增“调试 → Ozon 类目树调试”，路由为 `/shops/category-tree-debug`。
- 调试页文件：`src/pages/shops/CategoryTreeDebugPage.tsx`、`CategoryTreeDebugPage.css`；服务封装为 `src/services/categoryTreeDebug.ts`。该页只负责调用已存在的前端 API 封装并以 Ant Design 树展示响应，不能在前端处理或持久化 API Key。

## 关键前端行为

1. 选定目标门店后才读取该门店的类目缓存；加载期间 Cascader 显示“正在读取该店铺的类目缓存”。
2. 切换类目会清空草稿属性；展开“更多特征”后才读取新类目的 schema。
3. 动态属性的字典搜索输入至少两个字符后，用户可显式选择“从 Ozon 搜索”；前端不传递或记录 API Key。
4. 页面 API、错误码和返回结构以 `docs/api/` 与 `@atlas/contracts` 为准。前端不要自行扩展接口字段或模拟同步完成状态。

## 已执行验证

本次前端改动已执行：

```bash
cd apps/web
../../node_modules/.bin/tsc -p tsconfig.json --noEmit
git diff --check
```

两项均通过。后续对交互或样式作变更时，应在已启动的 Web 环境中回归：类目选择、更多特征展开/收起与加载状态、字典查询、包装重量同一行展示、SKU 展开编辑、货源链接按钮对齐，以及调试页的树形渲染。

## 当前工作约定

- 当前任务可按仓库 `AGENTS.md` 修改相关项目代码；跨领域改动需遵守 [`../../docs/project/development-collaboration-contract.md`](../../docs/project/development-collaboration-contract.md) 并说明影响范围。
- 验证需要时可在确认目标进程和端口后启动、停止或重启 API/Worker；完成后说明实际操作与状态。上方 2026-09-11 的验证记录不能替代新改动的检查。
- 不在浏览器持久化、日志或页面状态中保存 Ozon API Key。