# 通用组件清单

- 文档目标：整理跨页面可复用的 UI 组件和业务组件，避免每个页面重复定义结构，也避免把未来能力过早做成当前刚性组件。
- 使用方式：页面规格优先定义“页面职责”，本文件定义“可复用部件”；如果两者冲突，以页面职责和全局业务规则为准。

---

## 1. 使用原则

### 1.1 先抽共性，不抽幻觉

- 只有跨页面稳定复用的结构，才进入通用组件清单。
- 还没有冻结的能力，不做刚性组件。

### 1.2 先抽职责，不先抽字段

- 组件先定义“解决什么问题”。
- 字段可以随接口阶段调整，不应反过来驱动组件设计。

### 1.3 先服务当前阶段，再预留未来阶段

- `V1.0` 交易主链路相关组件优先级最高。
- `V1.1 / V2.0 / V2.1 / V3.0` 组件可以预留，但要明确阶段边界。

---

## 2. 全局基础组件

| 编码 | 组件名称 | 主要职责 | 适用页面 | 适用阶段 |
| --- | --- | --- | --- | --- |
| `G01` | 顶部导航栏 | 二级页返回、标题、右侧操作占位 | 全部二级页 | `V1.0+` |
| `G02` | 底部 TabBar | 四个 Tab 页面切换 | `T01 / T02 / T03 / T04` | `V1.0+` |
| `G03` | 页面空态卡片 | 列表无数据时统一提示和 CTA | 列表页、结果页 | `V1.0+` |
| `G04` | 页面错误卡片 | 网络失败、数据异常、重试 | 全部业务页 | `V1.0+` |
| `G05` | 状态标签 | 订单状态、活动状态、会员状态等语义标签 | 订单、活动、会员页 | `V1.0+` |
| `G06` | 固定底部主操作栏 | 承载主 CTA，处理安全区和禁用态 | 结算页、订单详情页 | `V1.0+` |

---

## 3. 门店与场景组件

| 编码 | 组件名称 | 主要职责 | 适用页面 | 适用阶段 |
| --- | --- | --- | --- | --- |
| `G10` | 门店切换条 | 展示当前门店并进入切店流程 | 首页、点餐页 | `V1.0+` |
| `G11` | 场景切换条 | 在门店支持范围内切换外卖 / 自提 / 堂食 | 首页、点餐页 | `V1.0+` |
| `G12` | 门店信息卡 | 展示门店地址、营业状态、电话、基础服务信息 | 首页、结算页、堂食确认页 | `V1.0+` |
| `G13` | 服务规则条 | 展示起送价、配送费、自提说明、堂食提示等简要规则 | 首页、点餐页、结算页 | `V1.0+` |
| `G14` | 场景结果卡 | 展示当前场景的前置信息，如地址、自提门店、桌台 | 地址页、堂食确认页、结算页 | `V1.0+` |

---

## 4. 商品与购物车组件

| 编码 | 组件名称 | 主要职责 | 适用页面 | 适用阶段 |
| --- | --- | --- | --- | --- |
| `G20` | 类目导航 | 承接分类切换、当前类目高亮、吸顶表达 | 点餐页 | `V1.0+` |
| `G21` | 商品卡片 | 展示商品图、标签、价格、活动摘要、加购入口 | 点餐页、活动页 | `V1.0+` |
| `G22` | 数量步进器 | 商品数量加减和禁用态表达 | 点餐页、抽屉、购物车 | `V1.0+` |
| `G23` | 商品详情头部 | 展示商品图、标题、描述、销量、价格、售罄态 | 商品详情抽屉 | `V1.0+` |
| `G24` | 规格选项组 | 承接规格、做法、套餐组等选择 | 商品详情抽屉 | `V1.0+` |
| `G25` | 加料选项组 | 承接附加项和加价项选择 | 商品详情抽屉 | `V1.0+` |
| `G26` | 底部购物车栏 | 展示已选件数、金额和去结算入口 | 点餐页 | `V1.0+` |
| `G27` | 购物车商品行 | 展示已选商品、规格摘要、数量编辑、删除动作 | 购物车抽屉 | `V1.0+` |
| `G28` | 凑单 / 优惠提示条 | 展示凑单距离、优惠提示、配送门槛说明 | 购物车抽屉、结算页 | `V1.0+` |

---

## 5. 结算与订单组件

| 编码 | 组件名称 | 主要职责 | 适用页面 | 适用阶段 |
| --- | --- | --- | --- | --- |
| `G30` | 履约信息卡 | 根据场景展示配送地址、自提门店或堂食桌台信息 | 结算页、订单详情页 | `V1.0+` |
| `G31` | 手动资产选择单元格 | 展示并进入手动资产选择入口 | 结算页 | `V1.0+` |
| `G32` | 自动优惠命中列表 | 展示自动命中的优惠结果和说明 | 结算页 | `V1.0+` |
| `G33` | 费用明细卡 | 展示商品金额、配送费、优惠、应付金额 | 结算页、订单详情页 | `V1.0+` |
| `G34` | 订单摘要卡 | 展示订单门店、状态、金额、时间和主动作 | 订单页、支付成功页 | `V1.0+` |
| `G35` | 履约时间轴 | 展示顾客可理解的订单阶段和进展 | 订单详情页、退款详情页 | `V1.1+` |
| `G36` | 退款原因选择区 | 退款原因和补充说明输入 | 退款申请页 | `V1.1+` |
| `G37` | 评价输入区 | 星级、文本输入和最小评价反馈区 | 评价页 | `V1.1+` |

---

## 6. 我的、资产与增长组件

| 编码 | 组件名称 | 主要职责 | 适用页面 | 适用阶段 |
| --- | --- | --- | --- | --- |
| `G40` | 用户头部卡 | 展示头像、昵称、会员信息摘要 | 我的页、会员中心页 | `V1.0+` |
| `G41` | 资产摘要卡 | 展示会员、积分、余额、次卡等摘要信息 | 我的页 | `V2.0+` |
| `G42` | 订单快捷入口组 | 展示待支付、进行中、已完成等快捷入口 | 我的页 | `V1.0+` |
| `G43` | 资产入口列表 | 承接会员、积分、储值、次卡等二级页入口 | 我的页 | `V2.0+` |
| `G44` | 活动券卡片 | 展示券模板名称、门槛、有效期和领取 CTA | 领券中心页 | `V2.1+` |
| `G45` | 活动商品卡 | 展示秒杀或限时折扣商品及活动状态 | 秒杀页、限时折扣页 | `V2.1+` |
| `G46` | 充值方案卡 | 展示充值金额、赠送说明和到账结果 | 储值充值页 | `V2.0+` |
| `G47` | 次卡卡片 | 展示次卡名称、权益摘要、剩余次数和有效期 | 次卡页 | `V2.0+` |
| `G48` | 服务入口组 | 展示帮助、消息、客服等服务入口 | 我的页、帮助中心页 | `V3.0+` |

---

## 7. 服务与预留组件

| 编码 | 组件名称 | 主要职责 | 适用页面 | 适用阶段 |
| --- | --- | --- | --- | --- |
| `G50` | 消息列表项 | 展示消息标题、摘要、时间和已读状态 | 消息中心页 | `V3.0+` |
| `G51` | 帮助问题列表项 | 展示问题标题、分类和跳转入口 | 帮助中心页 | `V3.0+` |
| `G52` | 服务兜底卡 | 展示客服电话、在线客服、售后指引等信息 | 帮助中心页、我的页 | `V3.0+` |

---

## 8. 当前必须守住的组件边界

### 8.1 场景切换条

- `G11` 必须跟随门店 `serviceTypes` 控制可用场景。
- 不能做固定三按钮硬编码。

### 8.2 商品卡和商品详情抽屉

- `G21` 必须区分简单商品和复杂商品。
- 简单商品可直接加购。
- 复杂商品必须进入 `G23 / G24 / G25` 组合后的商品详情抽屉流程。

### 8.3 结算资产组件

- `G31` 当前只冻结：
  - 优惠券
  - 余额
  - 次卡
- `积分抵扣` 当前不进入该组件的已冻结范围。

### 8.4 自动优惠组件

- `G32` 当前只展示自动命中结果。
- 当前冻结范围包括：
  - 满减
  - 新客优惠
  - 会员折扣
  - 免配送费

### 8.5 订单操作组件

- `G06` 不应把商家动作直接变成顾客动作。
- `催单 / 骑手轨迹 / 取餐码` 当前都不作为固定组件按钮写死。

### 8.6 消息与帮助组件

- `G50` 当前只是未来职责预留，不代表已经冻结完整消息 inbox。
- `G51 / G52` 当前用于服务兜底，不默认假设 FAQ CMS 或客服系统已经成熟存在。

---

## 9. 通用实现要求

- 所有可点击组件都要有禁用态或不可点击态。
- 所有异步主按钮都要有 `loading` 反馈。
- 金额显示格式在全应用保持一致。
- 状态标签颜色语义在全应用保持一致。
- 固定底部组件需要处理小程序安全区。
- 组件文案优先使用顾客语言，不使用商家后台字段名。