---
title: 开发文档
order: 3
category: atom
---

## 1. 组件基本信息

- **组件名称（英文）**：Financial Summary
- **建议导出组件名**：PisellFinancialSummary
- **组件编号**：pcl_FinancialSummary_V1.0
- **组件类型**：Plus Components
- **组件分类**：Plus Components
- **组件位置**：`packages/private-materials/src/plus/pisellFinancialSummary`
- **设计稿**：Figma 节点见设计文档链接；**样式以 Figma 为准**。设计标注已通过 **Figma MCP（plugin-figma-figma）** 的 `get_design_context` 获取，见下文「8. Figma 设计标注」。
- **金额格式**：使用 `formatAmountWithOptions(amount, symbol, { precision, ... })`，其中 precision 由 props.amountPrecision 传入。

## 2. 组件需求点罗列

### 2.1 核心功能

- 基于 **PisellHierarchicalSummaryList**（@pisell/materials）构建，将业务数据转换为 `PisellHierarchicalSummaryListItem[]`。
- 第一行：Balance Due（最终应付金额）；其下三个可展开块：Total、Paid、Refund。
- Total：支持多层级子项（Subtotal、Tax、Fee、Surcharge、Discount 等及其子级）。
- Paid：每笔支付为子项，**内置展示**支付方式、金额、时间等（统一数据结构）。
- Refund：退款记录，**内置展示**（统一数据结构）。
- 无 Paid 数据时隐藏 Paid 区块；无 Refund 数据时隐藏 Refund 区块；Total 无子项时不显示展开箭头。

### 2.2 展示与配置

- 金额格式：使用 `@pisell/utils` 的 `formatAmount` / `formatAmountWithOptions`；支持 props 配置小数位、货币符号、千分位等；若不满足则扩展 utils。
- 金额为 0：默认显示，可配置 `hideZeroAmountRows` 隐藏。
- 数据缺失（如 balanceDue 为 null）：显示 "—"（可配置占位文案）。
- **N items**：为一个字段，展示在对应行的 label 旁边（使用 PisellHierarchicalSummaryList 的 `itemsCount`）。
- 是否显示 Total / Paid / Refund / N items / 提示 icon：均通过 props 配置。
- 标题（Balance due、Total、Paid、Refund）：**全部内置多语言**（中/英/繁），使用 `locales.getText(key)`；支持 props 覆盖文案。

### 2.3 样式

- 严格按 **Figma** 标注实现（见下文「8. Figma 设计标注」）；设计信息已通过 Figma MCP 的 `get_design_context` 获取。

## 3. 组件描述

PisellFinancialSummary 是用于展示交易/订单相关资金信息的聚合组件。通过层级结构展示金额汇总、支付记录、退款记录及最终结算结果（Balance Due），适用于订单详情、销售记录、购物车结算、收银等场景。业务语义与结构解耦：复用 PisellHierarchicalSummaryList，由本组件负责数据转换与内置展示（支付/退款明细、多语言、金额格式化）。

## 4. 组件 API 设计

### 4.1 数据结构（由组件定义，全部内置展示）

**Total 下单项（可嵌套）**

```
FinancialSummaryLineItem {
  label: ReactNode;              // 行标题
  value?: number | null;         // 金额，缺失时展示 "—"
  children?: FinancialSummaryLineItem[];
  key?: React.Key;
  itemsCount?: ReactNode;       // 展示在 label 旁边，如 "3 items"
  infoTooltip?: ReactNode;       // 提示 icon 的 tooltip
}
```

**支付记录项（内置展示：支付方式 + 金额 + 时间等）**

```
FinancialSummaryPaymentItem {
  key?: React.Key;
  methodName?: string;           // 支付方式名称
  amount: number;
  time?: string;                 // 可选
  detail?: ReactNode;            // 可选额外明细
}
```

**退款记录项（内置展示）**

```
FinancialSummaryRefundItem {
  key?: React.Key;
  label?: ReactNode;             // 退款说明
  amount: number;
  time?: string;
  detail?: ReactNode;
}
```

**组件入参数据**

```
FinancialSummaryData {
  balanceDue: number | null;    // 最终应付，null 时显示 "—"
  total?: {
    value?: number | null;      // Total 汇总值，可选
    children?: FinancialSummaryLineItem[];
  };
  paid?: FinancialSummaryPaymentItem[];
  refund?: FinancialSummaryRefundItem[];
}
```

### 4.2 Props

```
PisellFinancialSummaryProps {
  data: FinancialSummaryData;

  showTotal?: boolean;           // 默认 true
  showPaid?: boolean;            // 默认 true
  showRefund?: boolean;          // 默认 true
  showItemsCount?: boolean;     // 是否显示 N items（label 旁），默认 true
  showInfoIcon?: boolean;        // 是否显示提示 icon，默认 true（或按设计）
  hideZeroAmountRows?: boolean; // 是否隐藏金额为 0 的行，默认 false

  titleBalanceDue?: ReactNode;  // 覆盖内置「Balance due」等多语言
  titleTotal?: ReactNode;
  titlePaid?: ReactNode;
  titleRefund?: ReactNode;

  currencySymbol?: string;      // 金额货币符号，默认 ''
  amountPrecision?: number;      // 小数位，默认 2
  useThousandsSeparator?: boolean;
  hideDecimalForWholeNumbers?: boolean;  // 整数是否隐藏 .00

  missingValuePlaceholder?: ReactNode;   // 数据缺失时展示，默认 "—"

  className?: string;
  style?: CSSProperties;
}
```

### 4.3 多语言 key（内置，中/英/繁）

- 如：`pisell2.financialSummary.balanceDue`、`pisell2.financialSummary.total`、`pisell2.financialSummary.paid`、`pisell2.financialSummary.refund`，以及 N items 等占位文案。具体 key 在 locales 文件中定义。

## 5. 组件模块拆解

### 5.1 目录结构（计划）

```
pisellFinancialSummary/
├── index.tsx
├── PisellFinancialSummary.tsx
├── PisellFinancialSummary.less
├── types.ts
├── locales.ts                 # 中/英/繁
├── utils/
│   └── buildSummaryItems.ts    # data -> PisellHierarchicalSummaryListItem[]
├── components/                # 如需子组件（如支付行、退款行）可放此处
└── docs/
    ├── pisellFinancialSummary.md
    ├── pisellFinancialSummary.$tab-design.md
    ├── pisellFinancialSummary.$tab-dev.md
    └── pisellFinancialSummary.$tab-test.md
```

### 5.2 组件结构图

```
PisellFinancialSummary
├── 输入: data (FinancialSummaryData) + props
├── utils/buildSummaryItems: 将 data 转为 PisellHierarchicalSummaryListItem[]
│   ├── 第一项: Balance Due（无 children，不展开）
│   ├── 第二项: Total（value 可选聚合，children 为 FinancialSummaryLineItem 递归转换）
│   ├── 第三项: Paid（children 为 FinancialSummaryPaymentItem 转成的 list items，内置渲染）
│   └── 第四项: Refund（同上，内置渲染）
└── PisellHierarchicalSummaryList(items={items}, levelConfig, aggregate, ...)
```

## 6. 组件实现方案

### 6.1 关键点

- **数据转换**：`buildSummaryItems(data, options)` 根据 `showTotal/showPaid/showRefund`、`hideZeroAmountRows`、标题覆盖、金额格式化选项，生成 `PisellHierarchicalSummaryListItem[]`。Balance Due 为第一行；Total/Paid/Refund 仅在有数据且对应 show 为 true 时加入，且无子项时 Total 不展示展开箭头。
- **金额格式化**：统一使用 `@pisell/utils` 的 `formatAmountWithOptions`；`value` 为 `null/undefined` 时渲染 `missingValuePlaceholder`（默认 "—"）。
- **多语言**：所有标题与占位文案使用 `locales.getText(key)`，在 `locales.ts` 中提供中/英/繁；标题可通过 props 覆盖。
- **支付/退款行**：每条 Payment/Refund 转为一条 HierarchicalSummaryListItem，label 内置展示 methodName + 时间等，value 内置展示格式化的 amount；detail 若有则作为 extra 或子内容。
- **N items**：对应 list item 的 `itemsCount` 字段，展示在 label 旁边。
- **样式**：按 Figma 标注（见「8. Figma 设计标注」）配置 `levelConfig`、indent、rowGap、颜色、字号等。

### 6.2 与 PisellHierarchicalSummaryList 的对应

- `items`：由 `buildSummaryItems` 产出。
- `aggregate`：Total 若需对 children 求和，可配置 `mode: 'sum'` 与 `getNumberValue`。
- `levelConfig`：L1 用于 Balance Due，L2 用于 Total/Paid/Refund 标题行，L3+ 用于明细；具体数值以 Figma 为准。
- `defaultExpandedLevel`：可选 0或1，控制初始是否展开 Total/Paid/Refund。

## 7. 通用性与可扩展性

- 标题、占位文案、金额格式均可通过 props 覆盖或配置。
- Total 的 `FinancialSummaryLineItem` 支持任意层级与 `infoTooltip`/`itemsCount`，满足复杂费用构成。
- 支付/退款采用统一结构，便于后续扩展字段（如状态、流水号）而不破坏 API。

## 8. Figma 设计标注（来自 Figma MCP）

以下标注通过 **Figma MCP**（server: `plugin-figma-figma`，tool: `get_design_context`）获取，节点：fileKey=`pM8Ho6d7kCMv9vIBvFHUlj`，主框架 nodeId=`3383:6304`（默认）。实现时请严格按此规范。

### 8.1 颜色

| 用途 | Token/说明 | 值 |
|------|------------|-----|
| 标题/主文案 | Text/Text_1, Base/Black | #1B1B1B |
| 金额（强调，L1） | Warning/600 | #DC6803 |
| 正文/行文案 | Base/Black, Text black | #000000 |
| 次要信息（N items 等） | Gray/500 | #667085 |
| 背景 | Base/White | #FFFFFF |
| 分割线/边框 | Gray/300 | #D0D5DD |
| 免责等小字 | Gray/500 + Text sm | #667085 |

### 8.2 字体与字号

| 用途 | 字体 | 字号 | 字重 | 行高 |
|------|------|------|------|------|
| L1 标题（Total/Balance Due 等） | Inter Bold | 16px | 700 | 24px |
| L2 行标题与金额 | Inter Medium | 16px | 500 | 24px |
| 次要说明/免责 | Inter Medium | 14px | 500 | 20px |

### 8.3 布局与间距

- **容器内边距**：20px（与 Figma Frame 427320317 一致）
- **行间距（gap）**：8px（rows / 区块间）
- **Label 与 N items**：同排，间距 8px；Label 与 help icon 间距 4px
- **行结构**：左右分布（justify-between），左侧 label 区（可含 N items、help icon），右侧 value，右对齐
- **展开图标**：24×24px（chevron-up/chevron-down）
- **Help icon**：16×16px
- **区块间分割**：border-bottom，颜色 #D0D5DD，solid

### 8.4 层级与组件对应

- **L1**：Balance Due 单行；Total / Paid / Refund 标题行（标题 Bold #1B1B1B，金额 Bold **Warning/600 #DC6803** + 展开箭头）
- **L2+**：明细行（Medium 16px，label #000000，value #000000；N items #667085；可选 help icon）
- 负金额（折扣/退款）与正金额同一套样式，仅数值带负号

### 8.5 获取方式说明

- 使用 Figma 设计稿时，**请通过 Figma MCP 插件访问**，不要直接请求 figma.com 网页。
- **设计文档中的 Figma 链接（以最新为准）**：
  - 链接 1：`fileKey` = `pM8Ho6d7kCMv9vIBvFHUlj`，nodeId = `14169:13540`（总结）；主视觉「默认」nodeId = `14169:13541`。
  - 链接 2：`fileKey` = `pM8Ho6d7kCMv9vIBvFHUlj`，nodeId = `14256:4201`（总结）；主视觉「默认」nodeId = `14256:4202`。
- 调用 `get_design_context(nodeId="14169:13541", fileKey="pM8Ho6d7kCMv9vIBvFHUlj")` 或 `nodeId="14256:4202"` 可获取 L1 行（Balance due + 金额 + 展开图标）的设计代码与标注。