# 前端开发指导文档

> **基于业务语义的UI骨架设计指南**

---

## 🎯 开发目标

**不是“纯UI铺页面”，而是**带业务语义的UI骨架（Business Skeleton）**

**目标**：所有页面结构完整 + 所有按钮有明确业务意义 + 能挂Service

---

## 🏗️ 标准开发流程

### Step 1：定义菜单结构（全局）

```text
Dashboard（总览）
Product（商品 / 利润）
Orders（订单）
Ad（广告）
Inventory（库存）
B2B（贸易）
Finance（结算 / 账单）
Compliance（合规）
Settings（配置）
```

**关键**：每个菜单 = 一个业务域（不是页面）

---

### Step 2：定义页面骨架

#### Product 页面骨架（标准结构）

```text
顶部：筛选区（店铺 / 分类 / 状态）
中间：核心表格（商品列表）
右侧/弹窗：操作面板（编辑 / AI / 定价）
底部/侧边：数据总结（利润 / ROI）
```

**目标**：把页面“分区”而不是写代码

---

### Step 3：填按钮（重点）

#### Product 页面按钮（标准版）

**行级操作（每个商品）**

```text
编辑商品
修改价格
查看ROI
AI优化定价 🔥
上下架
```

**批量操作**

```text
批量改价
批量上架
批量分析
```

**页面级操作**

```text
创建商品
导入商品
导出数据
```

**关键**：每个按钮必须能回答“点了之后业务发生什么变化？”

---

### Step 4：绑定假行为

**点击 → mock数据变化 → UI更新**

**示例**：点击【修改价格】

```text
输入新价格
→ 前端计算 ROI（假数据）
→ 表格实时更新
→ ROI变红/变绿
```

**意义**：验证UI是不是“活的”，而不是死页面

---

### Step 5：统一交互规范

#### 1️⃣ 所有操作必须有反馈

```text
loading → success / error
```

#### 2️⃣ 所有“影响钱”的操作必须有提示

```text
修改价格 → 显示 ROI变化
```

#### 3️⃣ 所有列表必须支持：

```text
分页 / 筛选 / 排序
```

#### 4️⃣ 所有弹窗统一：

- 宽度
- 按钮位置
- 提交流程

**目的**：让AI和你写的代码风格一致

---

### Step 6：输出前端任务模板

#### 页面：Product

```md
# 页面：Product

## 页面结构
- 筛选区
- 商品表格
- 操作弹窗

## 表格字段
- 商品名
- 成本
- 售价
- 利润
- ROI
- 库存

## 按钮
- 创建商品
- 修改价格
- AI定价
- 上下架

## 交互
- 修改价格 → 更新ROI（mock）
- AI定价 → loading → 返回建议价格

## 状态
- loading
- empty
- error
```

---

## 📚 参考产品结构

### 1️⃣ Shopify（电商后台结构）

**重点**：
- 商品管理
- 订单管理
- 分析面板

### 2️⃣ Google Analytics（数据驱动UI）

**重点**：
- 数据展示
- 图表交互
- 维度筛选

### 3️⃣ Jungle Scout（赚钱导向）

**重点**：
- 利润
- ROI
- 选品分析

**目标**：Shopify结构 + Analytics数据 + JungleScout赚钱逻辑

---

## 📋 各页面详细设计

### Dashboard（总览）

**页面结构**
- 顶部：时间范围选择
- 中间：核心KPI卡片
- 底部：趋势图表

**按钮**
- 刷新数据
- 导出报告
- 自定义仪表盘

**交互**
- 时间范围变化 → 所有数据更新
- 点击KPI → 跳转到详情页面

---

### Product（商品 / 利润）

**页面结构**
- 顶部：筛选区（店铺 / 分类 / 状态）
- 中间：商品表格
- 右侧：操作面板
- 底部：利润总结

**按钮**
- 行级：编辑、修改价格、查看ROI、AI定价、上下架
- 批量：批量改价、批量上架、批量分析
- 页面级：创建商品、导入商品、导出数据

**交互**
- 修改价格 → 更新ROI（mock）
- AI定价 → loading → 返回建议价格

---

### Orders（订单）

**页面结构**
- 顶部：筛选区（状态 / 时间 / 平台）
- 中间：订单表格
- 右侧：订单详情
- 底部：订单统计

**按钮**
- 行级：查看详情、处理订单、退款
- 批量：批量发货、批量取消、批量导出
- 页面级：创建订单、导入订单、导出数据

**交互**
- 点击订单 → 显示详情
- 处理订单 → 状态更新

---

### Ad（广告）

**页面结构**
- 顶部：筛选区（平台 / 状态 / 时间）
- 中间：广告表格
- 右侧：广告详情
- 底部：ROI分析

**按钮**
- 行级：编辑、投放、暂停、查看ROI
- 批量：批量启停、批量分析
- 页面级：创建广告、导入广告、导出数据

**交互**
- 投放广告 → loading → 显示投放结果
- 查看ROI → 显示详细分析

---

### Inventory（库存）

**页面结构**
- 顶部：筛选区（仓库 / 状态 / 分类）
- 中间：库存表格
- 右侧：库存详情
- 底部：库存预警

**按钮**
- 行级：编辑、补货、调拨、查看详情
- 批量：批量调整、批量导出
- 页面级：创建库存、导入库存、导出数据

**交互**
- 补货 → 显示补货建议
- 调拨 → 显示调拨选项

---

### B2B（贸易）

**页面结构**
- 顶部：筛选区（客户 / 状态 / 时间）
- 中间：订单表格
- 右侧：订单详情
- 底部：客户统计

**按钮**
- 行级：查看详情、处理订单、生成合同
- 批量：批量处理、批量导出
- 页面级：创建订单、导入订单、导出数据

**交互**
- 生成合同 → 显示合同预览
- 处理订单 → 状态更新

---

### Finance（结算 / 账单）

**页面结构**
- 顶部：筛选区（时间 / 类型 / 状态）
- 中间：账单表格
- 右侧：账单详情
- 底部：财务汇总

**按钮**
- 行级：查看详情、对账、导出
- 批量：批量对账、批量导出
- 页面级：创建账单、导入账单、导出数据

**交互**
- 对账 → 显示对账结果
- 查看详情 → 显示详细财务数据

---

### Transactions（交易记录）

**页面结构**
- 顶部：筛选区（时间 / 类型 / 状态）
- 中间：交易表格
- 右侧：交易详情
- 底部：交易统计

**按钮**
- 行级：查看详情、导出
- 批量：批量导出
- 页面级：导入交易、导出数据

**交互**
- 查看详情 → 显示详细交易信息

---

### Reconciliation（对账记录）

**页面结构**
- 顶部：筛选区（时间 / 状态）
- 中间：对账表格
- 右侧：对账详情
- 底部：对账统计

**按钮**
- 行级：查看详情、重新对账、导出
- 批量：批量对账、批量导出
- 页面级：导入对账、导出数据

**交互**
- 重新对账 → 显示对账结果
- 查看详情 → 显示详细对账信息

---

### Warehouses（仓库管理）

**页面结构**
- 顶部：筛选区（状态 / 类型）
- 中间：仓库表格
- 右侧：仓库详情
- 底部：仓库统计

**按钮**
- 行级：查看详情、编辑、删除
- 批量：批量导出
- 页面级：创建仓库、导入仓库、导出数据

**交互**
- 查看详情 → 显示详细仓库信息
- 编辑 → 显示编辑表单

---

### InventoryForecast（库存预测）

**页面结构**
- 顶部：时间范围选择
- 中间：预测图表
- 右侧：预测详情
- 底部：预测建议

**按钮**
- 刷新预测
- 导出预测
- 调整参数

**交互**
- 时间范围变化 → 预测数据更新
- 调整参数 → 重新计算预测

---

### Marketing（营销管理）

**页面结构**
- 顶部：时间范围选择
- 中间：营销概览卡片
- 底部：营销趋势图表

**按钮**
- 查看广告管理
- 查看竞争对手分析
- 查看营销绩效报表

**交互**
- 点击卡片 → 跳转到对应页面
- 时间范围变化 → 所有数据更新

---

### Ads（广告管理）

**页面结构**
- 顶部：筛选区（平台 / 状态 / 时间）
- 中间：广告表格
- 右侧：广告详情
- 底部：广告统计

**按钮**
- 行级：编辑、启动、暂停、删除
- 批量：批量启停、批量导出
- 页面级：创建广告、导入广告、导出数据

**交互**
- 启动/暂停 → 广告状态更新
- 查看详情 → 显示详细广告信息

---

### Competitors（竞争对手分析）

**页面结构**
- 顶部：筛选区（类别 / 时间）
- 中间：分析图表
- 右侧：竞争对手详情
- 底部：竞争对手列表

**按钮**
- 刷新分析
- 导出分析
- 添加竞争对手

**交互**
- 筛选变化 → 分析数据更新
- 查看详情 → 显示详细竞争对手信息

---

### Suppliers（供应商管理）

**页面结构**
- 顶部：筛选区（类别 / 状态）
- 中间：供应商表格
- 右侧：供应商详情
- 底部：供应商统计

**按钮**
- 行级：查看详情、编辑、删除
- 批量：批量导出
- 页面级：添加供应商、导入供应商、导出数据

**交互**
- 查看详情 → 跳转到供应商详情页面
- 编辑 → 显示编辑表单

---

### SupplierDetail（供应商详情）

**页面结构**
- 左侧：供应商信息表单
- 右侧：供应商产品列表
- 底部：历史订单和绩效评估

**按钮**
- 保存供应商信息
- 查看历史订单
- 查看绩效评估

**交互**
- 保存 → 显示保存结果
- 切换标签页 → 显示对应内容

---

### Reports（报表中心）

**页面结构**
- 顶部：报表类型卡片
- 中间：报表概览图表
- 底部：报表操作按钮

**按钮**
- 查看利润报表
- 查看绩效报表
- 导出所有报表

**交互**
- 点击卡片 → 跳转到对应报表页面
- 导出 → 下载报表文件

---

### ProfitReport（利润报表）

**页面结构**
- 顶部：筛选区（时间范围 / 类别）
- 中间：利润概览卡片
- 底部：利润明细表格和图表

**按钮**
- 导出报表
- 刷新数据
- 调整参数

**交互**
- 筛选变化 → 利润数据更新
- 查看详情 → 显示详细利润信息

---

### PerformanceReport（绩效报表）

**页面结构**
- 顶部：筛选区（时间范围 / 渠道）
- 中间：绩效概览卡片
- 底部：绩效明细表格和图表

**按钮**
- 导出报表
- 刷新数据
- 调整参数

**交互**
- 筛选变化 → 绩效数据更新
- 查看详情 → 显示详细绩效信息

---

### Settings（设置）

**页面结构**
- 顶部：设置类型卡片
- 中间：设置概览
- 底部：设置操作按钮

**按钮**
- 查看个人设置
- 查看租户设置
- 查看用户管理

**交互**
- 点击卡片 → 跳转到对应设置页面

---

### ProfileSettings（个人设置）

**页面结构**
- 顶部：头像上传
- 中间：个人信息表单
- 底部：密码修改表单

**按钮**
- 保存个人信息
- 修改密码

**交互**
- 保存 → 显示保存结果
- 修改密码 → 显示修改结果

---

### TenantSettings（租户设置）

**页面结构**
- 顶部：基本信息表单
- 底部：功能设置开关

**按钮**
- 保存基本信息
- 保存功能设置

**交互**
- 保存 → 显示保存结果
- 切换开关 → 实时更新设置

---

### UserManagement（用户管理）

**页面结构**
- 顶部：筛选区（角色 / 状态）
- 中间：用户表格
- 底部：用户统计

**按钮**
- 行级：编辑、删除
- 批量：批量导出
- 页面级：添加用户、导入用户、导出数据

**交互**
- 添加用户 → 显示添加用户表单
- 编辑 → 显示编辑表单
- 删除 → 显示删除确认

---

### Compliance（合规）

**页面结构**
- 顶部：筛选区（类型 / 状态 / 时间）
- 中间：证书表格
- 右侧：证书详情
- 底部：合规统计

**按钮**
- 行级：查看详情、更新、验证
- 批量：批量验证、批量导出
- 页面级：创建证书、导入证书、导出数据

**交互**
- 验证证书 → 显示验证结果
- 更新证书 → 显示更新表单

---

### Settings（配置）

**页面结构**
- 左侧：配置菜单
- 右侧：配置表单

**按钮**
- 保存配置
- 重置配置
- 导出配置

**交互**
- 保存 → 显示保存结果
- 重置 → 显示重置确认

---

## 🎨 设计规范

### 颜色系统

- 主色：#1890ff
- 成功：#52c41a
- 警告：#faad14
- 错误：#f5222d
- 信息：#1890ff

### 字体系统

- 标题：16px / 20px
- 正文：14px
- 小文本：12px

### 布局规范

- 页面边距：16px
- 卡片间距：16px
- 按钮间距：8px
- 输入框高度：32px

### 响应式设计

- 桌面端：1200px+
- 平板端：768px - 1199px
- 移动端：< 768px

---

## 📝 前端任务模板

### 页面任务模板

```md
# 页面：[页面名称]

## 页面结构
- [结构1]
- [结构2]
- [结构3]

## 表格字段
- [字段1]
- [字段2]
- [字段3]

## 按钮
- [按钮1]
- [按钮2]
- [按钮3]

## 交互
- [交互1]
- [交互2]

## 状态
- loading
- empty
- error
```

### 组件任务模板

```md
# 组件：[组件名称]

## 功能描述
[组件功能描述]

## 输入属性
- [属性1]: [类型] - [描述]
- [属性2]: [类型] - [描述]

## 输出事件
- [事件1]: [描述]
- [事件2]: [描述]

## 样式规范
- [样式1]
- [样式2]

## 交互规范
- [交互1]
- [交互2]
```

---

## 🔄 开发流程

### 第一步：搭建骨架
- 定义页面结构
- 创建基础组件
- 实现布局

### 第二步：实现交互
- 绑定假数据
- 实现按钮功能
- 验证UI交互

### 第三步：对接服务
- 替换假数据
- 对接后端API
- 实现真实业务逻辑

### 第四步：优化测试
- 性能优化
- 兼容性测试
- 用户体验优化

---

## 📌 注意事项

1. **业务语义优先**：每个UI元素都要有明确的业务意义
2. **一致性**：保持交互规范的一致性
3. **可扩展性**：设计时考虑未来功能扩展
4. **性能**：注意前端性能优化
5. **用户体验**：关注用户操作流程的流畅性

---

## 🎯 验收标准

- [ ] 页面结构完整
- [ ] 按钮功能明确
- [ ] 交互流畅
- [ ] 响应式适配
- [ ] 性能良好
- [ ] 代码规范

---

> **记住：你现在做的不是“页面开发”，而是在搭“业务操作台的骨架”。**