# 需求文档：P13 小程序前端联调补齐与格式统一

## 概述

小程序前端页面已完成 H5 原型还原（P6~P9），但在 MOCK 数据排查中发现多处功能点未对接真实数据或逻辑缺失。本 SPEC 统一收敛这些遗漏项，确保每个页面在联调后数据展示完整、格式统一。

## 需求来源

- PRD：`docs/prd/specs/P13-miniapp-fe-polish.md`
- 依赖：P6~P9 前端页面 + P3 认证 + P4 核心业务 + 后端接口

## 需求列表

### 通用规则（跨页面）

- REQ-G1：微信头像与用户信息 — 登录成功后从后端获取用户信息（avatarUrl、nickName、role、storeName），三个 banner 页面（task-list、performance、performance-records）统一从全局用户信息读取 avatarUrl，无头像时显示默认占位图
- REQ-G2：当月预估判断 — 当查看月份 = 当前自然月时显示"预估"标签，历史月份不显示。影响页面：performance、performance-records、board-finance
- REQ-G3：绩效折算（折前/折后）— 后端返回 hours（折后）和 hoursRaw（折前），两者不同时展示"折前 Xh"灰色小字
- REQ-G4：储值等级显示规则 — 根据 balance 计算等级文案（无/少/一般/多/非常多），工具函数放 utils/storage-level.ts

### 各页面功能点

- REQ-T1.2：task-list 比同期数据 — 后端返回与上月同期差值（数值），前端展示 +¥X / -¥X + ↑/↓ 箭头
- REQ-T1.3：task-list 放弃原因 — 从后端 task 对象的 abandonReason 字段获取展示
- REQ-T1.4：task-list 盖戳动画 — 改为页面加载后始终播放，不依赖 tierCompleted
- REQ-T3.3：performance-records 总笔数 — 使用后端返回的 totalCount 字段，不再前端 records.length 计算
- REQ-T4.1：task-detail 手机号码 — 从 detail 获取 customerPhone，不再硬编码空字符串
- REQ-T4.3：task-detail 行动建议 — 后端返回 actionSuggestions: string[]，前端在维客线索下方展示为卡片列表
- REQ-T5.2：customer-service-records 本月服务次数 — 前端类型定义补齐 totalServiceCount
- REQ-T5.3：customer-service-records 课程标签 — 后端返回 courseType 枚举，前端直接映射，不再 includes 猜测
- REQ-T6.1：board-finance AI 智能洞察 — 后端返回 aiInsights 数组，前端动态渲染
- REQ-T10.1：coach-detail 任务执行统计 — 后端返回 taskStats，前端从 API 获取，不再硬编码

### 数据格式统一

- REQ-FMT-1：补充格式化工具函数 — formatDateShort、formatDateFull、formatDays、formatStorageLevel、formatTrendValue
- REQ-FMT-2：全页面格式化调用审查 — 确保所有金额/计数/百分比/课时/时间/空值均通过已有格式化函数处理
- REQ-FMT-3：接口端格式对齐 — 后端返回原始数值，前端负责格式化；所有 null/undefined/0 统一展示为 `--`

## 验收标准

- AC-G1.1：三个 banner 页面展示微信头像，无头像时显示默认占位图
- AC-G1.2：用户昵称、角色、门店名称正确展示
- AC-G2.1：本月数据显示"预估"标签，历史月份不显示
- AC-G2.2：board-finance 本月时间筛选时，经营一览标题含"预估"字样
- AC-G3.1：存在折算差异时，课时旁显示"折前 Xh"灰色小字
- AC-G3.2：无折算差异时不显示"折前"
- AC-G4.1：task-detail 储值区域根据 balance 正确显示等级文案
- AC-G4.2：balance 为 0 时显示"无"
- AC-T1.2：比同期显示为数值差（如 +¥1,200），非百分比
- AC-T1.3：已放弃任务卡片展示放弃备注
- AC-T1.4：页面加载后盖戳动画始终播放
- AC-T3.3：总笔数使用后端 totalCount
- AC-T4.1：手机号码从 detail 获取
- AC-T4.3：行动建议卡片列表正确渲染
- AC-T5.2：totalServiceCount 类型定义完整
- AC-T5.3：课程标签基于枚举映射
- AC-T6.1：AI 智能洞察动态渲染
- AC-T10.1：任务执行统计从 API 获取
- AC-FMT：所有页面数据格式统一，空值显示 `--`