# Web 前端交接：商品编辑器与门店类目

更新日期：2026-09-11

本文只覆盖 `apps/web/` 当前未提交的前端改动。开始继续开发前，请先查看仓库根目录的 `git status --short`；工作区同时存在服务端、Worker 和文档改动，它们不属于前端接手者的修改范围。

## 当前完成状态

### 商品编辑器

- 编辑页为 `/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 展开编辑、货源链接按钮对齐，以及调试页的树形渲染。

## 前端边界

- 仅修改 `apps/web/` 及前端相关文档。
- 不启动、停止或修改 API/Worker；若类目刷新或 schema 请求失败，应先检查服务端运行状态与 API 契约，再交由服务端维护者处理。
- 不在浏览器持久化、日志或页面状态中保存 Ozon API Key。