广告管理 Item 维度报表前端实施契约
产品 PRD 版本：1.1
前端实施契约版本：1.1
来源变更：CR-20260820-001
确认依据：用户提供的既有广告系统原型、Shopee/TikTok Item 字段与公式截图，以及本轮原型实施授权
来源与范围
本契约将用户提供的 Shopee/TikTok 业务字段、公式截图和 2026-08-20 只读走查到的实际页面，落为单页 Ant Design 报表原型。页面保留真实 ERP 的顶栏、左侧导航、筛选、趋势、横向指标卡和平台原生广告表格，再叠加 Item 聚合视图；原型数据为 Mock，不代表平台接口已联通。
页面清单
| 页面 ID | 页面名称 | 路由 | 页面母版 | 范围 |
|---|
| P-ADS-001 | 广告管理 | /prototype/ad-management/ | ERPAdPage | Shopee/TikTok 平台、真实页面骨架、筛选、趋势、指标卡、平台广告宽表和 Item 视图 |
P-ADS-001 广告管理
- 产品范式：ERP 分析与决策支持
- 页面母版：ERPAdPage（复刻
/yh-advertisemen/adShopee 与 /yh-advertisemen/adTiktok 的可见结构） - 页面目标：在同一筛选上下文中判断广告或 Item 表现并定位异常
- 页面区块顺序：平台标题 → 筛选 → 趋势卡（趋势标题 → 横向指标卡 → 趋势图）→ 结果表
- 主用户任务：选择分析范围，切换聚合对象，比较指标，定位 Item 并下钻关联广告
- 信息优先级：一级为平台、分析维度、关键结论与异常；二级为时间范围、趋势和 Item 宽表；三级为指标解释、关联广告和来源说明
- 主操作：导出当前视图
- 密度策略：standard
- 视觉强调：decision-first
- 视觉强调对象：异常诊断、效率指标与需要进一步处理的 Item
- 动效策略：standard
- 动效说明：平台/维度切换使用轻量内容切换；抽屉沿用 Ant Design 标准进入退出；不使用装饰性动画
- 推荐组件：自定义 ERP Shell、Card、Radio.Group、Select、DatePicker.RangePicker、Input、Segmented、Table、Line、Tag、Tooltip、Dropdown
- 必须避免：独立 Item 菜单、跨平台混算、卡片堆砌、深色大屏风格、渐变背景、只用颜色表达异常、Item 行直接编辑广告配置
产品功能覆盖矩阵
| 功能 ID | 页面/区域 | 产品来源 | 产品功能 | 实现目标 | 状态 | 排除项 |
|---|
| F-ADS-001 | P-ADS-001 顶部 | 产品方案 1 | Shopee/TikTok 平台切换 | 分平台切换数据与原生指标 | 实现 | 不跨平台汇总 |
| F-ADS-002 | P-ADS-001 顶部 | 产品方案 2 | 广告视图/Item 视图 | 同页切换分析对象并保留筛选 | 实现 | 不新增路由 |
| F-ADS-003 | P-ADS-001 筛选区 | 功能范围 | 共享筛选 | 店铺、状态、类型、日期、搜索、币种可操作 | 实现 | 不做高级筛选器 |
| F-ADS-004 | P-ADS-001 指标区 | 数据与口径 | 平台指标汇总 | 按平台显示已确认 Item 指标 | 实现 | 不平均比率 |
| F-ADS-005 | P-ADS-001 趋势区 | 功能设计 3 | 指标趋势 | 展示当前范围的花费与销售额趋势 | 实现 | 统计日期仅用 Mock |
| F-ADS-006 | P-ADS-001 诊断区 | 功能设计 3 | 异常诊断 | 点击诊断标签筛选表格 | 实现 | 阈值仅为示例 |
| F-ADS-007 | P-ADS-001 表格区 | 功能设计 4 | Item 宽表 | 商品身份、关联广告和指标列 | 实现 | 不做行内广告编辑 |
| F-ADS-008 | P-ADS-001 抽屉 | 2026-08-20 实际页面基线 | 广告详情 | 广告身份、预算/目标回报、状态、趋势、产品与创意素材 | 实现 | 不新建详情路由；真实暂停/删除不操作 |
| F-ADS-009 | P-ADS-001 表格工具栏 | 功能设计 5 | 指标设置与导出 | 控制可见列并反馈导出任务 | 实现 | 不新建任务中心 |
| F-ADS-010 | P-ADS-001 广告视图 | 2026-08-20 实际页面基线 | 广告对象表现 | 保留平台原生筛选、指标和广告表格列 | 继承 | 不扩展广告创建与编辑 |
| F-ADS-011 | P-ADS-001 页面框架 | 2026-08-20 实际页面基线 | ERP 页面骨架 | 深色顶栏、左侧导航、白色卡片、平台标题和密集表格 | 实现 | 不复制生产账号数据 |
| F-ADS-012 | P-ADS-001 写操作边界 | 用户只读要求 | 只读安全 | 原型所有广告操作控件只显示本地提示，不发起写请求 | 实现 | 不点击或模拟真实广告写入 |
| F-ADS-013 | P-ADS-001 广告详情 | 2026-08-20 预算编辑走查 | 预算编辑浮层 | 展示预算输入、取消/确认；本地确认仅提示，不保存 | 实现 | 不保存、不调用接口 |
页面设计决策
| 决策 | 采用方案 | 原因 |
|---|
| 信息架构 | 分析维度切换而非新菜单 | 两种视图共享平台和筛选上下文，避免重复页面 |
| 切换控件 | 紧邻平台页签的 Segmented | 平台是数据源，维度是分析对象，两者层级不同 |
| 主结果结构 | 指标 → 趋势/诊断 → 表格 | 先判断是否异常，再定位对象和证据 |
| 下钻方式 | 右侧 Drawer | 保留筛选、表格位置和对比上下文 |
| 广告操作 | Item 详情仅导航至关联广告 | 一个 Item 可映射多个广告，行内编辑存在误操作风险 |
页面-区域-组件映射
| 区域 | 组件 | 说明 |
|---|
| 应用框架 | 自定义 ERP Shell + Card | 对齐实际深色顶栏、左侧导航和浅灰内容背景 |
| 平台与维度 | 平台按钮 + Segmented | 平台切换数据源，维度切换聚合对象 |
| 筛选区 | Card + Select + RangePicker + Input.Search | 单行优先、可换行的共享业务筛选 |
| 指标区 | Card + Statistic | 6 个核心指标，避免过多首屏卡片 |
| 趋势区 | Card + Line | 双指标趋势和 Tooltip |
| 诊断区 | Card + Tag/Badge | 文案、数量和颜色共同表达状态 |
| 表格区 | antd Table | 横向滚动、固定主列、平台原生列和分页 |
| 详情 | Drawer + Table + Line + Modal | 对齐真实广告详情抽屉；预算编辑可打开但不保存 |
普通控件契约
| 控件 | 默认值 | 行为 |
|---|
| 平台 Tabs | Shopee | 切换为对应平台数据；不混算 |
| 分析维度 Segmented | 广告视图 | 切换下方完整分析结果；共享筛选不重置 |
| 店铺 Select | 全部店铺 | 支持清空和单选；原型提供平台对应 Mock 店铺 |
| 状态 Select | 全部状态 | 广告视图按广告状态，Item 视图按关联广告状态解释 |
| 日期粒度 Segmented | 日 | 日/周/月切换趋势采样粒度 |
| 日期范围 | 最近 7 天 | 改变指标、趋势、诊断和表格数据范围 |
| 商品搜索 | 商品名称 | 支持商品名称、Item ID、SellerSKU |
| 报表币种 | CNY | 继承原系统入口；原型不模拟真实汇率 |
| 重置 | - | 恢复当前平台的默认筛选 |
| 导出 | - | Notification 提示已创建当前视图导出任务 |
复杂控件契约
分析维度切换
- 输入：
ad | item。 - 输出：指标配置、诊断集合、表格列和表格数据整体切换。
- 保留：平台、店铺、日期、关键词、币种。
- 无障碍：控件有“分析维度”文字标签，不仅靠位置表达。
异常诊断
- 输入：诊断类型或全部。
- 输出：当前表格过滤结果和命中数量。
- 选中态：浅色底、明确边框、图标/圆点与文字，不仅颜色变化。
- 阈值说明：Tooltip 显示“示例规则，生产阈值待配置”。
Item 详情抽屉
- 打开来源：Item 表格“查看详情”。
- 内容：商品身份、关键指标、趋势、异常、关联广告表。
- 关闭后：保留筛选、维度和表格状态。
- 关联广告操作：点击“在广告视图查看”关闭抽屉、切换广告视图并设置广告关键词。
表格与数据展示契约
- ProTable 不启用内置搜索表单，业务筛选统一在页面筛选区。
- 商品列左侧固定，操作列右侧固定；常用桌面视口允许横向滚动。
- Item 视图固定商品身份列和操作列，中间字段横向滚动；表格上方显示“左右滑动查看更多字段”。指标卡超过容器宽度时提供左右箭头，点击后平滑移动一组指标。
- 金额按当前报表币种显示；本原型默认 CNY。
- 整数使用千分位；金额两位小数；ROAS/ROI 保留两位小数；百分比保留两位小数。
- 值为
null 或字段缺失显示 —；明确的 0 显示 0 或 0.00。 - 默认 Shopee Item 可见列：商品、店铺、关联广告、花费（含税）、ROAS（含税）、曝光量、点击量、点击率、订单量、转化率、销量、销售额、ACoS、每次转化成本、直接转化订单数、每次直接转化成本、直接转化率、直接 ACoS、直接 ROAS、直接销售金额、直接已售商品、诊断、操作。
- 默认 TikTok Item 可见列：商品、店铺、关联广告、花费、ROI、订单量、销售额、平均下单成本、净成本、诊断、操作。
状态与权限矩阵
| 状态/权限 | 指标 | 趋势 | 表格 | 详情 | 导出 |
|---|
| 正常查看 | 展示 | 展示 | 展示 | 可打开 | 按权限 |
| 加载中 | Skeleton | Skeleton | loading | 不可打开 | 禁用 |
| 无数据 | — | Empty | Empty | 不可打开 | 禁用 |
| 部分缺失 | 缺失值 — | 有效点继续展示 | 单元格 — | 标注缺失 | 可导出已有字段 |
| 平台错误 | Alert | 不展示旧平台替代数据 | 不展示旧平台替代数据 | 不可打开 | 禁用 |
| 无导出权限 | 正常 | 正常 | 正常 | 正常 | 隐藏或禁用并解释 |
交互与反馈
- 任何筛选变化均在 Mock 数据上即时更新；原型不模拟网络延迟。
- 平台与分析维度切换使用同页更新，不刷新路由。
- 点击诊断后表格标题显示当前诊断，点击“全部 Item/全部广告”取消。
- 点击导出后用 Notification 显示平台、维度和记录数。
- Item 视图隐藏新增广告、批量状态、预算和目标 ROAS/ROI 控件，避免把广告写操作带入商品聚合上下文。
- 关联广告定位动作使用 Message 反馈，并切回广告视图。
- “新增广告 / 更改状态 / 更改预算 / 更改 ROAS 或 ROI / 编辑 / 开关”均以只读提示收口；控件不连接真实系统、不提交表单。
- 广告列表“详情”打开右侧抽屉；抽屉预算编辑打开“广告预算编辑”浮层，取消关闭，确认只给出只读提示。
- 表格无结果时提供“清除诊断”和“重置筛选”动作。
文案
| 场景 | 文案 |
|---|
| 维度标签 | 分析维度 |
| 视图选项 | 广告视图 / Item 视图 |
| 数据说明 | 当前数据为原型 Mock，不代表平台实时数据 |
| 阈值说明 | 示例规则，生产阈值待配置 |
| 导出成功 | 导出任务已创建，可在系统任务中心查看 |
| 分母为 0 | — |
| 搜索占位 | 搜索商品名称、Item ID 或 SellerSKU |
视觉契约
- 继承 Ant Design 6 与项目 ERP 设计系统；浅灰页面背景、白色内容面板、紧凑边框和 8px 基础间距。
- 不新增品牌色体系；交互主色使用 Ant Design 蓝，Shopee/TikTok 仅以文字平台身份区分，不伪造平台 Logo。
- 首屏最多 6 张核心指标卡；异常状态使用低饱和背景和边框。
- 数据表格保持业务密度，商品图使用真实商品缩略图资产；不得使用表情符号或手工 SVG 代替图标。
- 图表使用双折线和可读 Tooltip；不使用渐变、3D、暗色大屏或无明细支撑的装饰图。
来源追踪
| 来源 | 用途 | 状态 |
|---|
| 用户提供的 Shopee Item 指标截图 | 指标范围与默认/可选列 | 已确认 |
| 用户提供的 TikTok Item 指标截图 | 指标范围 | 已确认 |
| 用户提供的 Shopee 字段/公式截图 | Shopee 字段映射与公式 | 已确认 |
| 用户提供的 TikTok 字段/公式截图 | TikTok 字段映射与公式 | 已确认 |
| 用户注释 | TikTok 平均下单成本、Shopee date 语义 | 已确认 |
| 2026-08-20 实际 Shopee/TikTok 广告页只读截图 | 顶栏、左导航、筛选顺序、指标卡、趋势和平台原生表格列 | 视觉基线（已脱敏，不入库） |
| Ant Design Pro 项目设计系统 | 组件、布局和状态 | 实施基线 |
前端验收清单
- [ ] Shopee/TikTok 平台页签可切换且指标语义不混用
- [ ] 广告视图/Item 视图可切换且共享筛选保持
- [ ] 店铺、状态、类型、日期粒度、日期范围、搜索、币种和重置可操作
- [ ] Shopee/TikTok Item 汇总指标和表格列符合产品 PRD
- [ ] 趋势图、诊断筛选、指标设置、详情抽屉和导出反馈可交互
- [ ] Item 详情可切到关联广告，且没有 Item 行内广告配置编辑
- [ ] 分母 0、缺失、无数据、加载、错误和无权限呈现不混淆
- [ ] 1280×720 与 1440×900 视口无遮挡，表格横向滚动可用
- [ ] 通过 prd:ready、prototype:pro:check、build、antd lint、prototype:guard、change:sync 和浏览器回归；用户仍需完成视觉验收
待决策
- 生产接口的统计日期字段、分页、数据延迟和最大查询范围尚需后端契约。
- 异常诊断阈值、是否按账号配置及权限主体尚需业务确认。
- 报表币种的汇率来源、换算时点和精度沿用原系统，当前不在本次原型中推演。