R524809
69 lines
6.8 KiB
Markdown
69 lines
6.8 KiB
Markdown
# Web 前端交接：商品编辑器与 AI 填报
|
||
|
||
更新日期：2026-09-23
|
||
|
||
本文记录 Web 编辑页的现行状态；跨领域总体进度以 [`../../docs/project/HANDOFF.md`](../../docs/project/HANDOFF.md) 的 1.39 为准。开始继续开发前请查看仓库根目录的 `git status --short`，保留目前 API、Worker、contracts、迁移及 Web 中未提交和未跟踪的改动。
|
||
|
||
## 当前状态（2026-09-23）
|
||
|
||
- 编辑页 `/products/:id/editor` 的 `ProductEditPage.tsx` 将底部操作条固定在视口底部，提供「AI 填报」和「保存草稿」；AI 生图、首次上架仍是占位/不可用入口。全局 AI 填报会先保存未保存草稿，再创建异步任务并轮询；核对商品、profile、来源版本和本地表单未变化后，只把合格结果填进空字段，不直接持久化。用户仍须检查并保存。
|
||
- 全局 AI 只回填 SPU 发布标题、标签、描述和中文对照，以及合格的类目、型号、未导入 SKU 货号与有证据的包装建议。类目有多个候选时，「确认 AI 推荐类目」弹窗用单选卡片让用户选择；选择前不自动写入类目。类目一旦确定，页面按现有机制加载动态属性，但不调用 AI 填写 Ozon 类目属性。
|
||
- SPU 的「中文商品名」和「俄文发布标题」在页面中均标为必填；发布就绪校验也要求俄文标题。标题、标签、描述各有中文对照入口；标题旁有加号，可开启 SKU 标题覆盖。SKU 默认继承 SPU 文案，用户可在当前 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-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。
|