Neo-ZQYY/docs/prd/Neo_Specs/review-audit/P8-NS1-14.md

P8→NS1/RNS1 缺失项 #14：财务看板数字的格式化规范

简要结论

• 状态：✅ 已解决
• 风险等级：🟡 低
• 千分位、小数位、货币符号的格式化规范已在设计文档中定义，工具函数已实现（TS + WXS 双版本），财务看板已使用

详细审查

审查范围

• docs/miniprogram-dev/design-system/DISPLAY-STANDARDS.md
• apps/miniprogram/miniprogram/utils/money.ts
• apps/miniprogram/miniprogram/utils/format.wxs
• apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts
• apps/miniprogram/miniprogram/pages/board-coach/board-coach.ts

发现

1. 设计规范文档已完善

DISPLAY-STANDARDS.md 第 1 章"金额展示规范"明确定义了：

• 正常金额：¥N,NNN（千分位逗号，无小数）
• 负数金额：-¥N,NNN（负号在 ¥ 前）
• 零值：¥0
• 空值：--
• 大额金额：不简写，保留完整数字
• 禁止事项：禁止 ¥-368、¥0.00、¥12万、toLocaleString()

2. TS 工具函数已实现（utils/money.ts）

• formatMoney(value) — 金额格式化，千分位 + ¥ 前缀
• formatCount(value, unit) — 计数格式化，千分位 + 单位
• formatNumber(value) — 纯数字千分位
• formatPercent(value) — 百分比，保留 1 位小数
• formatTrendValue(value) — 同比/环比差值，+¥/-¥ 前缀
• toProgressWidth(value) — 进度条宽度，截断至 [0, 100]

3. WXS 工具函数已实现（utils/format.wxs）

• money(value) — 金额格式化（WXS 版，用于 WXML 模板）
• count(value, unit) — 计数格式化
• percent(value) — 百分比
• hours(value) — 课时格式化
• trendValue(value) — 同比/环比差值
• safe(val) — 空值兜底

4. 看板页面已使用格式化函数

• board-finance.ts：导入并使用 formatMoney 格式化赠送卡矩阵数据
• board-coach.ts：导入并使用 formatMoney、formatCount、formatHours 格式化助教数据
• board-finance.wxml：未引入 format.wxs（财务看板数据在 TS 层预格式化后传入模板）
• board-customer.wxml：引入 format.wxs，使用 fmt.safe() 兜底

证据

DISPLAY-STANDARDS.md 金额规范：

| 场景 | 格式 | 示例 |
|---|---|---|
| 正常金额 | `¥N,NNN`（千分位逗号，无小数） | `¥12,680` |
| 负数金额 | `-¥N,NNN`（负号在 ¥ 前） | `-¥368` |
| 零值 | `¥0` | `¥0` |
| 空值 / undefined | `--` | `--` |

money.ts 核心函数：

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}`
}

format.wxs 金额函数（WXS 版，逻辑一致）：

function money(value) {
  if (value === undefined || value === null) return '--'
  if (value === 0) return '¥0'
  // ... 千分位处理
  return (value < 0 ? '-¥' : '¥') + result
}

board-finance.ts 使用示例：

import { formatMoney } from '../../utils/money'
// ...
wine: formatMoney(row.liquor?.value),
table: formatMoney(row.tableFee?.value),

建议

无。格式化规范已完整覆盖：

• 设计文档（DISPLAY-STANDARDS.md）定义了规则
• TS 工具函数（money.ts）供 JS 层使用
• WXS 工具函数（format.wxs）供 WXML 模板使用
• 看板页面已实际调用格式化函数