Shopee Listing 管理一期 · 前端实施契约
产品 PRD 版本：1.2
前端实施契约版本：2.0
来源变更：CR-20260823-001
确认依据：既有 Listing 一期功能 PRD；Freddy 已要求使用新的正式 Ant Design Pro 设计流程产出候选，未完成视觉验收。
来源与范围
权威输入是同目录产品 PRD、erp-ui-design-system.md、ant-design-pro-baseline.md 与正式 ui-library/react/business-filters.tsx。实现范围为 P-001 全球商品列表、P-002 站点 Listing 列表、P-003 Listing 编辑页，以及 P-002 快速价格/库存/Model Modal。
产品需求不因本次 UI 重构缩减。原型只使用本地数据，所有平台写入均为模拟反馈。
页面清单
| 页面 ID | 页面 | 对象 | 用户任务 |
|---|---|---|---|
| P-001 | 全球商品 | GlobalProduct | 查询商品并核对发布到哪些店铺/站点 |
| P-002 | 站点商品 | SiteListing | 定位 Listing，快速维护价格或库存 |
| P-003 | 编辑 Listing | SiteListing + ListingModel | 完成全量字段修改并分域提交 |
产品功能覆盖矩阵
| 功能 ID | 页面/表面 | PRD 来源 | 已确认产品功能 | 实现目标 | 覆盖状态 | 排除变更 |
|---|---|---|---|---|---|---|
| F-001 | P-001 | 全球商品与发布关系 | Global Item 独立页面、查询和发布映射 | ProTable、映射 Modal、进入目标 Listing | 实现 | — |
| F-002 | P-002 | 站点 Listing 列表 | 对象独立、查询、状态 Tab、规格表达 | ProTable Search、Tabs、Model 明细 | 实现 | — |
| F-003 | P-002/P-003 | 三层价格 | 原价/折扣价可编辑，当前售价只读 | 分组列、价格 Modal、规格编辑表 | 实现 | — |
| F-004 | P-002/P-003 | 双库存与仓库 | Shopee/ERP 并列，仓库条件展示 | 分组列、库存 Modal、规格编辑表 | 实现 | — |
| F-005 | P-003 | Listing 编辑 | 基本信息和类目属性 | 长表单前两分区与校验 | 实现 | — |
| F-006 | P-003 | Listing 编辑 | 规格价格库存与批量设置 | 勾选、禁用、批量 Modal、受影响数量 | 实现 | — |
| F-007 | P-003 | Listing 编辑 | 商品图、属性图和详细描述 | picture-card、属性图 Modal、描述编辑器 | 实现 | — |
| F-008 | P-003 | Listing 编辑 | 左长表单、右摘要/锚点、固定操作 | Grid、Affix、FooterToolbar | 实现 | — |
| F-009 | P-003 | 提交与反馈 | 内容/原价/折扣/库存分域确认 | 确认 Modal、提交结果 | 实现 | — |
| F-010 | P-001/P-002/P-003 | 权限、状态与异常 | 状态、只读、失败、部分成功 | Tag/Badge/Alert/禁用/反馈 | 实现 | — |
页面设计决策
P-001 全球商品
- 产品范式：ERP 运营管理
- 页面基线：Ant Design Pro List Page（ProLayout > PageContainer > ProTable）
- 页面母版：ListPage
- 页面目标：定位全球商品并核对它发布到了哪些店铺和站点
- 主用户任务：按 Global Item、SPU、SKU 查询并打开发布关系
- 信息优先级：一级为全球商品身份与发布覆盖；二级为规格结构和 SPU；三级为更新时间
- 主操作：查看发布关系
- 密度策略：compact
- 视觉强调：data-first
- 视觉强调对象：全球商品身份、发布站点数量与发布状态
- 动效策略：minimal
- 动效说明：只保留筛选、映射 Modal 与页面跳转反馈
- 推荐组件：PageContainer、ProTable、Modal、Table、Badge、Image
- 常驻信息：页面标题、查询、全球商品表、发布数量和更新时间
- 渐进呈现：发布站点明细只在“发布关系” Modal 中出现；进入具体 Listing 后再展示站点字段
- 页面结构预算：PageContainer + 一个 ProTable；映射为一层 Modal，不增加摘要卡或工作台
- 禁止冗余：不重复页面标题；不与站点 Listing 共用表；不加无来源 KPI、批量写入或营销卡片
- 必须避免：把 Global Item 当成站点 Listing、在首屏展开全部 Mapping
P-002 站点商品
- 产品范式：ERP 运营管理
- 页面基线：Ant Design Pro List Page（ProLayout > PageContainer > Tabs > ProTable）
- 页面母版：ListPage
- 页面目标：快速定位站点 Listing，并完成规格级价格或库存的高频维护
- 主用户任务：按店铺、站点、SKU/SPU、规格和更新时间筛选，通过状态 Tab 聚焦结果并打开维护 Modal
- 信息优先级：一级为 Listing 身份、状态、当前售价；二级为原价/折扣价、Shopee/ERP 库存；三级为规格结构与更新时间
- 主操作：行级快速维护（改价或改库存）；无页面级主按钮
- 密度策略：compact
- 视觉强调：decision-first
- 视觉强调对象：当前售价、售罄/违规状态、库存差异和行级维护入口
- 动效策略：minimal
- 动效说明：Tabs、ProTable 查询与中央 Modal 使用组件默认反馈，不自行添加装饰动效
- 推荐组件：PageContainer、Tabs、ProTable、TreeSelect、StandardDateRangeFilter、Modal、InputNumber、Dropdown、Tooltip
- 常驻信息：页面标题、状态 Tab、常用查询、商品身份、状态、三层价格、双库存、更新时间与两项高频操作
- 渐进呈现：多属性规格进入 Model 明细 Modal；价格和库存进入各自的中央 Modal；完整编辑收入“更多”；价格语义仅在 Tooltip 显示
- 页面结构预算：PageContainer + Tabs + 一个 ProTable；查询与结果复用同一个 ProTable 表面，不手写 Query Card 或再嵌套 Card
- 禁止冗余：禁止重复“站点商品/站点 Listing”标题；禁止把状态再放进查询表单；禁止三个价格或两个库存压成彩色堆叠标签；禁止添加汇总 KPI、任务条或无来源说明
- 必须避免：隐藏当前售价、展示折扣活动对象、Drawer 快速编辑、页面级横向滚动
P-003 编辑 Listing
- 产品范式：ERP 复杂对象编辑
- 页面基线：Ant Design Pro Long Form Page（ProLayout > PageContainer > Form + Card sections + Affix + FooterToolbar）
- 页面母版：LongFormPage
- 页面目标：在稳定长表单中完成站点 Listing 的内容、规格、图片、包裹物流和描述修改
- 主用户任务：逐区编辑并验证规格价格库存，最后提交一次分域修改
- 信息优先级：一级为必填内容、规格价格库存和校验错误；二级为图片、属性和包裹字段；三级为只读平台身份与辅助说明
- 主操作：提交修改
- 密度策略：standard
- 视觉强调：form-first
- 视觉强调对象：当前编辑分区、必填校验、三层价格和唯一提交按钮
- 动效策略：minimal
- 动效说明：Anchor、Modal 与 FooterToolbar 只使用官方默认交互
- 推荐组件：PageContainer、Form、Card、Table、Upload、Affix、Anchor、FooterToolbar、Modal、Alert
- 常驻信息：左侧六个业务分区、右侧对象摘要和编辑锚点、底部取消/提交操作
- 渐进呈现：批量设置、属性图绑定和提交确认使用 Modal；包裹字段核验说明使用一个 Alert；当前售价语义使用 Tooltip
- 页面结构预算：PageContainer + 一张编辑主表单；六张 Card 只对应 PRD 的六个业务分区，右侧为一个独立摘要/锚点 Card，底部只用 FooterToolbar
- 禁止冗余：禁止短描述、重复保存按钮、嵌套 Card、固定定位耦合页面壳、无来源的营销/任务模块
- 必须避免：让当前售价可编辑、把包裹字段复制到 Model 行、整页 Drawer 或页面级横向溢出
页面-区域-组件映射
| 页面 | 区域 | 组件 | 要点 |
|---|---|---|---|
| P-001 | 查询和结果 | ProTable | Global Item、SPU、SKU、发布状态；发布数量打开 Mapping |
| P-001 | 发布关系 | Modal + Table | 店铺、站点、Item ID、状态、进入 Listing |
| P-002 | 查询和结果 | ProTable Search + ProTable | 查询包含 StandardDateRangeFilter；价格/库存按分组列横向扫描 |
| P-002 | 状态过滤 | Tabs | 全部、在线、已售完、审核中、未上架、违规、疑似删除及数量 |
| P-002 | 快速维护 | centered Modal + Table | 单规格 560px，多规格 960px；当前售价只读 |
| P-003 | 编辑主区 | Form + 六张业务 Card | 每张 Card 对应一个 PRD 分区，非装饰嵌套 |
| P-003 | 摘要与导航 | Affix + Card + Anchor | 对象身份、当前售价和区块锚点 |
| P-003 | 操作栏 | FooterToolbar | 取消与唯一主按钮“提交修改” |
普通控件契约
| 控件 ID | 页面 | 组件 | 行为 |
|---|---|---|---|
| C-001 | P-001/P-002 | Input.Search / ProTable Search | 回车查询、清空可恢复全部结果 |
| C-002 | P-002 | StoreSelector / TreeSelect | 复用 getStoreSelectorFieldProps，多选、搜索、清空 |
| C-003 | P-002 | Tabs | 只过滤平台状态，数量跟当前查询结果同步 |
| C-004 | P-002 | StandardDateRangeFilter | 今天、昨天、近 7/30 天、本月、上月与自定义范围；无对比模式 |
| C-005 | P-003 | Input / Cascader / Select | 必填校验；类目变更需二次确认（候选保留结构） |
| C-006 | P-003 | InputNumber | 原价/折扣价非负，目标库存为非负整数 |
| C-007 | P-003 | Input.TextArea | 只维护详细描述，不出现短描述 |
复杂控件契约
X-001 三层价格与双库存规格表
原价、折扣价可编辑；当前售价只读并说明为平台生效价格。Shopee 库存为主值，ERP 库存为参考；ERP 未映射显示“未匹配”。勾选 Model 后才可批量设置；确认前说明受影响数量。
X-002 快速维护 Modal
使用 centered 且 maskClosable=false。价格 Modal 包含规格、SKU、原价、折扣价、当前售价；库存 Modal 包含规格、SKU、Shopee/ERP 库存、条件仓库和目标库存。多规格时表体内部滚动，禁止弹窗整体挤出视口。
X-003 商品图片
Upload 使用 listType="picture-card" 与 beforeUpload={() => false}。属性图的“增加”只打开已添加商品图片的选择 Modal，确认后绑定属性值；不上传外部文件。
表格与数据展示契约
P-002 使用两级表头：商品信息、价格信息、库存信息、更新时间、操作。价格与库存单独成列并右对齐，当前售价使用主文字，原价/折扣价使用常规文字；不把它们压成同一单元格的标签堆。操作列固定在容器右侧：改价、改库存常驻，编辑 Listing 进入“更多”。
表格在 1280px/1440px 视口内无页面级横向溢出；超出内容宽度时只在 ProTable 容器内滚动，固定操作列保持可见。
状态与权限矩阵
| 状态/权限 | 查看 | 快速修改 | 完整编辑 | 提交 |
|---|---|---|---|---|
| 查看权限 | 是 | 否 | 只读 | 否 |
| 编辑权限 | 是 | 是 | 是 | 是 |
| 审核中/违规且平台禁写 | 是 | 禁用并说明 | 禁用受限字段 | 阻断受限领域 |
| 接口读取失败 | 错误态 | 否 | 否 | 否 |
| 部分提交成功 | 刷新成功域 | 失败域可重试 | 保留失败输入 | 显示分域结果 |
交互与反馈
- P-001 发布关系 Modal 可进入目标站点 Listing。
- P-002 的状态 Tab、店铺树、日期快捷范围与查询可真实改变结果；快速改价/库存确认后更新本地数据并 Toast。
- P-002 的多属性入口打开 Model 明细 Modal；完整编辑进入 P-003。
- P-003 的 Anchor 定位区块；无选择时批量按钮禁用；属性图从图片池选择；提交前确认、完成后展示结果。
- 取消编辑且存在未提交修改时二次确认返回。
文案
- 页面：全球商品、站点商品、编辑 Listing。
- 操作：查看发布关系、改价、改库存、编辑 Listing、取消、提交修改、确认修改。
- 字段：原价、折扣价、当前售价、Shopee 库存、ERP 可用库存、更新时间。
- 禁止：店铺折扣活动、折扣商品、短描述、保存并刊登。
视觉契约
- 继承 Ant Design 6.5 默认 Token、4px 间距和三层表面；只有根
ConfigProvider，不在页面内二次覆写 Table/Card Token。 - P-001/P-002 采用
size="small"的 Pro 列表密度，依靠 ProTable 查询和标准表格行高，而不通过魔法数压扁控件。 - P-002 的 Tabs 是唯一状态切换面；查询、表格、分页由同一 ProTable 承载。
- P-003 六张 Card 是产品分区，不再额外 Card 包 Card；右侧吸顶采用 Affix，底部操作采用 FooterToolbar，不写死与侧栏耦合的位置。
- 状态使用 Tag/Badge 语义色，主色只用于当前 Tab、焦点和唯一主操作；不添加渐变、彩色 KPI、装饰插画或整列品牌色底。
来源追踪
| 来源 | 落点 |
|---|---|
| 既有 Listing PRD | P-001–P-003、F-001–F-010 的对象、字段、规则和验收范围 |
| CR-20260823-001 | 将漏实现的更新时间标准范围筛选回写到 P-002 |
| Ant Design Pro 基线 | ProLayout、PageContainer、ProTable、FooterToolbar 与表面层级 |
business-filters.tsx | 店铺 TreeSelect 与不含对比模式的日期快捷项 |
| UI 设计系统 | 页面计划、常驻/渐进呈现、结构预算和反冗余约束 |
前端验收清单
- [ ] P-001/P-002 是独立页面与独立对象。
- [ ] P-002 的店铺、SKU、SPU、站点、规格、更新时间范围与状态 Tab 都能真实操作。
- [ ] 日期范围具备今天、昨天、近 7 天、近 30 天、本月、上月快捷项，且没有对比模式。
- [ ] 价格、库存以分组列横向扫描；当前售价只读；操作列固定。
- [ ] 快速价格/库存和多属性 Model Modal 可操作。
- [ ] P-003 六分区、右侧 Affix、FooterToolbar、规格批量、属性图绑定和分域提交可操作。
- [ ] 没有重复标题、重复摘要、无理由 Card 嵌套、无来源 Tab/KPI 或历史静态依赖。
- [ ] 1280×800、1440×900 无页面级横向溢出或遮挡。
- [ ] TypeScript、生产构建、antd lint、prototype:guard、change:sync 通过。
待决策
折扣域生产活动策略、实时类目元数据、平台错误码和包裹字段能力等待后端联调。候选只验证页面结构、交互语义和本地数据反馈，不承诺生产写入。