# 前端展示规范总表（小程序）

> **文档编号**：DS-DISPLAY-001  
> **版本**：v1.0.0  
> **适用范围**：NeoZQYY 小程序所有前端页面  
> **最后更新**：2026-03-18  
> **关联文档**：[日期时间展示规范](./DATETIME-DISPLAY-STANDARD.md)

---

## 目录

1. [金额展示规范](#1-金额展示规范)
2. [课时与时长展示规范](#2-课时与时长展示规范)
3. [数字与计数展示规范](#3-数字与计数展示规范)
4. [空值与缺失值规范](#4-空值与缺失值规范)
5. [百分比展示规范](#5-百分比展示规范)
6. [等级文案规范](#6-等级文案规范)
7. [任务截止日期展示规范](#7-任务截止日期展示规范)
8. [评分与星级展示规范](#8-评分与星级展示规范)
9. [Mock 数据规范](#9-mock-数据规范)

---

## 1. 金额展示规范

### 1.1 规则总表

| 场景 | 格式 | 示例 |
|---|---|---|
| 正常金额 | `¥N,NNN`（千分位逗号，无小数） | `¥12,680` |
| 负数金额 | `-¥N,NNN`（负号在 ¥ 前） | `-¥368` |
| 零值 | `¥0` | `¥0` |
| 空值 / undefined | `--` | `--` |
| 大额金额 | 不简写，保留完整数字 | `¥120,000` |

### 1.2 禁止事项

- ❌ 禁止 `¥-368`（负号位置错误）
- ❌ 禁止 `¥0.00`（零值不保留小数）
- ❌ 禁止 `¥12万`（不做大额简写）
- ❌ 禁止 `toLocaleString()` 直接用于展示（各设备行为不一致）
- ❌ Mock 数据中金额字段统一为 `number` 类型，不含 `¥` 前缀，由格式化层统一添加

### 1.3 实现参考（`utils/money.ts`，待新建）

```typescript
export function formatMoney(value: number | null | undefined): string {
  if (value === null || value === undefined) return '--'
  if (value === 0) return '¥0'
  const abs = Math.round(Math.abs(value))
  const formatted = abs.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ',')
  return value < 0 ? `-¥${formatted}` : `¥${formatted}`
}
```

### 1.4 当前涉及位置（待统一）

| 文件 | 问题 |
|---|---|
| `pages/task-list/task-list.ts` | `perf.customerBalance.toLocaleString()` 裸调 |
| `pages/performance-records/performance-records.ts` | Mock 字符串硬编码 `¥510`、`¥280` 等 |
| `pages/task-detail/task-detail.ts` | `serviceRecords.income` 硬编码 `¥200` 等 |
| `pages/board-coach/board-coach.ts` | `salary`、`svAmount` 硬编码 `¥12,680` 等 |

---

## 2. 课时与时长展示规范

### 2.1 规则总表

| 场景 | 格式 | 示例 |
|---|---|---|
| 整数小时 | `Nh` | `2h` |
| 非整数小时（保留1位） | `N.Nh` | `2.5h` |
| 带折算备注 | `实际h（折后 原始h）` | `2.0h（折后 2.5h）` |
| 零值 | `0h` | `0h` |
| 空值 | `--` | `--` |

### 2.2 实现参考（追加至 `utils/time.ts`）

```typescript
export function formatHours(hours: number | null | undefined): string {
  if (hours === null || hours === undefined) return '--'
  if (hours === 0) return '0h'
  return hours % 1 === 0 ? `${hours}h` : `${hours.toFixed(1)}h`
}
```

### 2.3 折算标注字段约定

- `hours`：折算后实际计入课时（`number`）
- `hoursRaw`：折算前原始小时数（`number | undefined`）
- 仅当 `hoursRaw` 存在且与 `hours` 不同时展示括号备注
- WXML 示例：`{{item.hours}}h{{item.hoursRaw ? '（折后 ' + item.hoursRaw + 'h）' : ''}}`

### 2.4 当前使用折算标注的位置（待统一）

| 文件 | 当前写法 | 目标写法 |
|---|---|---|
| `pages/performance-records/performance-records.ts` r7 | `deduct: '(折0.5h)'` 字符串 | `hours: 2, hoursRaw: 2.5`（number） |
| `pages/performance-records/performance-records.ts` r16 | 同上 | 同上 |
| `pages/performance-records/performance-records.ts` r21 | 同上 | 同上 |
| `pages/performance-records/performance-records.ts` r27 | 同上 | 同上 |
| `pages/task-detail/task-detail.ts` serviceRecords r1 | `durationRaw: '3.0h'` 字符串 | 改为 `number` 类型 |
| `components/service-record-card` | `hours-raw` prop 字符串 | 对齐 `number` 类型后格式化 |

---

## 3. 数字与计数展示规范

### 3.1 规则总表

| 场景 | 规则 | 示例 |
|---|---|---|
| 计数类（笔/次/人） | Mock 只存 `number`，单位由前端模板拼接 | API 返回 `32`，WXML 展示 `32笔` |
| 大数字（≥ 1000） | 千分位逗号 | `1,280` |
| 零值 | `--` | `--` |
| 空值 / undefined | `--` | `--` |

### 3.2 单位映射表

| 字段语义 | 单位 |
|---|---|
| 服务记录数 / 交易笔数 | `笔` |
| 到店次数 / 服务次数 | `次` |
| 客户数 / 人数 | `人` |
| 任务数 | `个` |
| 工龄 | `年` |

### 3.3 实现参考（追加至 `utils/money.ts`）

```typescript
export function formatCount(
  value: number | null | undefined,
  unit: string
): string {
  if (value === null || value === undefined || value === 0) return '--'
  const n = value >= 1000
    ? value.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ',')
    : String(value)
  return `${n}${unit}`
}
```

### 3.4 当前涉及位置（待统一）

| 文件 | 问题 |
|---|---|
| `pages/performance-records/performance-records.ts` | `totalCount: '32笔'` 字符串硬编码单位 |
| `pages/customer-service-records/customer-service-records.ts` | `monthCount: '6次'` 字符串硬编码单位 |
| `pages/board-coach/board-coach.ts` | `svCustomerCount: '18'` 裸字符串无单位 |

---

## 4. 空值与缺失值规范

### 4.1 统一占位符：`--`

| 场景 | 处理方式 |
|---|---|
| 数值型字段缺失（金额/课时/评分） | 展示 `--` |
| 文本型字段缺失（名称/备注/标签） | 展示 `--` |
| 列表为空 | 空态组件 `<t-empty />`，不用 `--` |
| 图片加载失败 | 默认占位图，不用 `--` |

### 4.2 禁止事项

- ❌ 禁止向用户展示 `undefined`、`null`、`NaN`、空字符串
- ❌ 禁止使用 `暂无`、`无`、`N/A`、`-` 等其他占位符
- ❌ 禁止直接绑定可能为 `undefined` 的字段而不加兜底

### 4.3 WXS 兜底函数（追加至 `utils/format.wxs`）

```javascript
function safe(val) {
  if (val === undefined || val === null || val === '') return '--'
  return val
}
// WXML 用法：{{fmt.safe(item.someField)}}
```

---

## 5. 百分比展示规范

### 5.1 规则总表

| 场景 | 格式 | 示例 |
|---|---|---|
| 展示文字 | 保留1位小数 + `%` | `58.3%`、`120.0%` |
| 进度条 CSS 宽度 | 保留1位小数，截断至100防溢出 | `width:58.3%` |
| 超过100%的展示文字 | 正常展示，不截断 | `120.0%` |
| 零值 | `0%` | `0%` |
| 空值 | `--` | `--` |

### 5.2 实现参考（追加至 `utils/money.ts`）

```typescript
export function formatPercent(value: number | null | undefined): string {
  if (value === null || value === undefined) return '--'
  if (value === 0) return '0%'
  return `${value.toFixed(1)}%`
}

export function toProgressWidth(value: number): string {
  return `${Math.min(100, Math.max(0, value)).toFixed(1)}%`
}
```

### 5.3 当前涉及位置（待统一）

| 文件 | 问题 |
|---|---|
| `pages/task-list/task-list.ts` | `filledPct` 计算用 `Math.round(*1000)/10`，精度逻辑分散 |
| `pages/task-list/task-list.wxml` | `width: {{perfData.tierProgress}}%` 无小数位 |

---

## 6. 等级文案规范

### 6.1 助教等级

**英文 Key 标准（单一数据源：`vi-colors.ts` `COACH_LEVEL_COLORS`）：**

| 英文 Key | 中文展示文案 |
|---|---|
| `junior` | 初级 |
| `middle` | 中级 |
| `senior` | 高级 |
| `star` | ⭐ 星级 |

**规范要求：**
- API / Mock 统一返回英文 key
- 所有组件、页面、常量统一使用英文 key，中文文案只在渲染层转换
- `coach-level-tag` 组件的 `LEVEL_MAP` 改为英文 key（当前为中文 key）

**当前待统一的位置：**

| 文件 | 问题 |
|---|---|
| `components/coach-level-tag/coach-level-tag.ts` | `LEVEL_MAP` key 为中文，需改为英文 |
| `pages/board-coach/board-coach.ts` | `level: '星级'` 等直接使用中文字符串 |
| `pages/board-coach/board-coach.ts` `LEVEL_CLASS` | key 为中文，需改为英文 |
| `utils/mock-data.ts` | 助教相关 Mock `level` 字段使用中文 |

### 6.2 关系等级

**英文 Key 标准（单一数据源：`vi-colors.ts` `RELATIONSHIP_LEVELS`）：**

| 英文 Key | 中文展示文案 | 分数范围 |
|---|---|---|
| `excellent` | 很好 | `> 8.5` |
| `good` | 良好 | `6 ~ 8.5` |
| `normal` | 一般 | `3.5 ~ 6` |
| `poor` | 待发展 | `< 3.5` |

**规范要求：**
- `task-detail.ts` 中的 `updateRelationshipDisplay` 应调用 `vi-colors.ts` 的 `getRelationshipLevel()`，不得重复维护判断逻辑
- 中文文案统一从 `RELATIONSHIP_LEVELS[key].name` 读取

**当前待统一的位置：**

| 文件 | 问题 |
|---|---|
| `pages/task-detail/task-detail.ts` | `updateRelationshipDisplay` 内联等级判断逻辑，与 `vi-colors.ts` 重复 |

### 6.3 客户标签类别

**英文 Key 标准（`vi-colors.ts` `CUSTOMER_TAG_COLORS`）：**

| 英文 Key | 中文展示文案 |
|---|---|
| `basic_info` | 客户基础 |
| `consumption` | 消费习惯 |
| `play_pref` | 玩法偏好 |
| `promo_pref` | 促销偏好 |
| `social` | 社交关系 |
| `feedback` | 重要反馈 |

**规范要求：**
- `CUSTOMER_TAG_COLORS` 的 key 从中文改为英文
- Mock 数据中 `category` 字段统一使用英文 key

**当前待统一的位置：**

| 文件 | 问题 |
|---|---|
| `utils/vi-colors.ts` `CUSTOMER_TAG_COLORS` | key 为中文，需改为英文 |
| `utils/mock-data.ts` `mockRetentionClues` | `category` 字段已是英文，保持不变 |

> 第 7～9 章及附录见：[DISPLAY-STANDARDS-2.md](./DISPLAY-STANDARDS-2.md)