Neo-ZQYY/docs/specs/p13-miniapp-fe-polish/tasks.md

实施计划：P13 小程序前端联调补齐与格式统一

概述

按照 P13 PRD 文档，对小程序全部页面进行联调补齐与格式统一。执行策略：先完成通用工具函数，再逐页面由子代理审查修改。每个页面审查三个维度：① 通用规则（G1~G4）② 数据格式统一标准 ③ 页面专属功能点。子代理并行最大数量为 2，每个子代理每次处理一个页面。

参考文档

• PRD：docs/prd/specs/P13-miniapp-fe-polish.md
• 展示规范：docs/miniprogram-dev/design-system/DISPLAY-STANDARDS.md、DISPLAY-STANDARDS-2.md
• API 契约：docs/miniprogram-dev/API-contract.md
• API 输出规范：docs/miniprogram-dev/API-OUTPUT-SPEC.md
• VI 设计系统：docs/miniprogram-dev/design-system/VI-DESIGN-SYSTEM.md

任务

第零阶段：通用工具函数准备

• 0. 通用工具函数补充
  • 0.1 新建 apps/miniprogram/miniprogram/utils/storage-level.ts
    • 导出 formatStorageLevel(balance: number): string
    • 阈值：= 0 → "无"、< 200 → "少"、< 500 → "一般"、< 1500 → "多"、≥ 1500 → "非常多"
    • null/undefined 输入返回 "无"
    • 需求: REQ-G4
  • 0.2 修改 apps/miniprogram/miniprogram/utils/money.ts
    • 新增 formatTrendValue(value: number | null | undefined): string
    • 正数 → "+¥1,200"（千分位），负数 → "-¥800"，0/null/undefined → "--"
    • 需求: REQ-FMT-1
  • 0.3 修改 apps/miniprogram/miniprogram/utils/time.ts
    • 新增 formatDateShort(date: string | Date | null | undefined): string → "3月15日" 格式，空值 → "--"
    • 新增 formatDateFull(date: string | Date | null | undefined): string → "2026-03-15" 格式，空值 → "--"
    • 新增 formatDays(days: number | null | undefined): string → "3天" 格式，0/null/undefined → "--"
    • 需求: REQ-FMT-1
  • 0.4 修改 apps/miniprogram/miniprogram/utils/format.wxs
    • 补充 WXS 侧对应函数（如需要在 WXML 中直接调用）
    • 需求: REQ-FMT-1

第一阶段：逐页面审查修改（子代理并行，最大 2 个）

每个页面任务包含三个审查维度，子代理必须按顺序逐一完成：

• A. 通用规则审查（G1~G4 中适用于该页面的规则）
• B. 数据格式统一审查（金额/计数/百分比/课时/时间/空值是否通过格式化函数处理）
• C. 页面专属功能点修改（PRD 中该页面的具体需求）

---

• 1. 【子代理】task-list 页面审查修改
  • 1.A 通用规则审查
    • 1.A.1 G1 微信头像：确认 avatarUrl 从全局用户信息读取并赋值到 data，无头像时显示默认占位图
      • 检查 task-list.ts 中 avatarUrl 的赋值逻辑
      • 检查 task-list.wxml 中头像 image 组件的 src 绑定和默认图
      • 需求: REQ-G1, AC-G1.1, AC-G1.2
    • 1.A.2 G2 当月预估：确认收入标题根据 isCurrentMonth 切换"预估收入"/"我的收入"
      • 检查 TS 中是否有 isCurrentMonth 判断逻辑
      • 检查 WXML 中"预估"标签的条件渲染
      • 需求: REQ-G2, AC-G2.1
  • 1.B 数据格式统一审查
    • 1.B.1 检查所有金额展示是否通过 formatMoney / WXS money() 处理
    • 1.B.2 检查所有计数展示是否通过 formatCount / WXS count() 处理
    • 1.B.3 检查所有空值是否通过 safe() 兜底为 "--"
    • 1.B.4 检查课时展示是否通过 formatHours / WXS hours() 处理
    • 需求: REQ-FMT-2, REQ-FMT-3, AC-FMT
  • 1.C 页面专属功能点
    • 1.C.1 T1.2 比同期数据：确认 incomeTrend/incomeTrendDir 从后端获取，使用 formatTrendValue 格式化展示，配合 ↑/↓ 箭头
      • 需求: REQ-T1.2, AC-T1.2
    • 1.C.2 T1.3 放弃原因：确认 abandonReason 从后端 task 对象获取，不再硬编码空字符串
      • 需求: REQ-T1.3, AC-T1.3
    • 1.C.3 T1.4 盖戳动画：修改为页面加载后始终播放，移除 tierCompleted 条件依赖
      • 需求: REQ-T1.4, AC-T1.4

---

• 2. 【子代理】performance 页面审查修改
  • 2.A 通用规则审查
    • 2.A.1 G1 微信头像：确认 banner 区域 avatarUrl 从全局用户信息读取，无头像时显示默认占位图
      • 需求: REQ-G1, AC-G1.1, AC-G1.2
    • 2.A.2 G2 当月预估：确认收入标题根据 isCurrentMonth 切换"预估收入"/"我的收入"，"预估"标签条件渲染
      • 需求: REQ-G2, AC-G2.1
  • 2.B 数据格式统一审查
    • 2.B.1 检查所有金额展示是否通过格式化函数处理
    • 2.B.2 检查所有课时展示是否通过格式化函数处理
    • 2.B.3 检查所有百分比展示是否通过格式化函数处理
    • 2.B.4 检查所有空值是否兜底为 "--"
    • 需求: REQ-FMT-2, REQ-FMT-3, AC-FMT
  • 2.C 页面专属功能点
    • （无额外专属功能点，T2.1/T2.2 已由 G1/G2 覆盖）

---

• 3. 【子代理】performance-records 页面审查修改
  • 3.A 通用规则审查
    • 3.A.1 G1 微信头像：确认 banner 区域 avatarUrl 从全局用户信息读取
      • 需求: REQ-G1, AC-G1.1
    • 3.A.2 G2 当月预估：确认收入标题根据 isCurrentMonth 切换
      • 需求: REQ-G2, AC-G2.1
    • 3.A.3 G3 绩效折算：确认 hoursRaw !== hours 时展示"折前 Xh"灰色小字，无差异时不显示
      • 需求: REQ-G3, AC-G3.1, AC-G3.2
  • 3.B 数据格式统一审查
    • 3.B.1 检查所有金额/课时/计数/百分比展示是否通过格式化函数处理
    • 3.B.2 检查所有空值是否兜底为 "--"
    • 需求: REQ-FMT-2, REQ-FMT-3, AC-FMT
  • 3.C 页面专属功能点
    • 3.C.1 T3.3 总笔数：确认使用后端返回的 totalCount 字段，不再用 records.length 计算
      • 需求: REQ-T3.3, AC-T3.3

---

• 4. 【子代理】task-detail 页面审查修改
  • 4.A 通用规则审查
    • 4.A.1 G4 储值等级：确认从 detail.balance 调用 formatStorageLevel() 计算等级文案并展示
      • 需求: REQ-G4, AC-G4.1, AC-G4.2
  • 4.B 数据格式统一审查
    • 4.B.1 检查所有金额展示是否通过格式化函数处理
    • 4.B.2 检查所有时间/日期展示是否通过格式化函数处理
    • 4.B.3 检查所有空值是否兜底为 "--"
    • 需求: REQ-FMT-2, REQ-FMT-3, AC-FMT
  • 4.C 页面专属功能点
    • 4.C.1 T4.1 手机号码：修改 onCopyPhone 从 this.data.detail.customerPhone 获取，不再硬编码空字符串
      • 需求: REQ-T4.1, AC-T4.1
    • 4.C.2 T4.3 行动建议：确认后端返回 actionSuggestions: string[]，前端在维客线索下方渲染为卡片列表
      • 需求: REQ-T4.3, AC-T4.3

---

• 5. 【子代理】customer-service-records 页面审查修改
  • 5.A 通用规则审查
    • （无 G1~G4 适用项）
  • 5.B 数据格式统一审查
    • 5.B.1 检查所有金额/计数/时间展示是否通过格式化函数处理
    • 5.B.2 检查所有空值是否兜底为 "--"
    • 需求: REQ-FMT-2, REQ-FMT-3, AC-FMT
  • 5.C 页面专属功能点
    • 5.C.1 T5.2 本月服务次数：补齐 totalServiceCount 的 TypeScript 类型定义，移除 as any 断言
      • 需求: REQ-T5.2, AC-T5.2
    • 5.C.2 T5.3 课程标签：修改 getTypeLabel 为基于 courseType 枚举的直接映射，移除 includes 硬编码匹配
      • 需求: REQ-T5.3, AC-T5.3

---

• 6. 【子代理】board-finance 页面审查修改
  • 6.A 通用规则审查
    • 6.A.1 G2 当月预估：确认本月时间筛选时，经营一览标题含"预估"字样
      • 需求: REQ-G2, AC-G2.2
  • 6.B 数据格式统一审查
    • 6.B.1 检查所有金额展示是否通过格式化函数处理
    • 6.B.2 检查所有百分比/计数展示是否通过格式化函数处理
    • 6.B.3 检查所有空值是否兜底为 "--"
    • 需求: REQ-FMT-2, REQ-FMT-3, AC-FMT
  • 6.C 页面专属功能点
    • 6.C.1 T6.1 AI 智能洞察：修改 WXML 移除硬编码文案，改为从后端 aiInsights: Array<{ icon: string; text: string }> 动态渲染
      • 需求: REQ-T6.1, AC-T6.1

---

• 7. 【子代理】board-customer 页面审查修改
  • 7.A 通用规则审查
    • （无 G1~G4 适用项）
  • 7.B 数据格式统一审查
    • 7.B.1 检查所有金额/计数/百分比展示是否通过格式化函数处理
    • 7.B.2 检查所有空值是否兜底为 "--"
    • 需求: REQ-FMT-2, REQ-FMT-3, AC-FMT
  • 7.C 页面专属功能点
    • （T7.1 爱心 icon 已实现，无额外修改）

---

• 8. 【子代理】board-coach 页面审查修改
  • 8.A 通用规则审查
    • （无 G1~G4 适用项）
  • 8.B 数据格式统一审查
    • 8.B.1 检查所有金额/计数/课时展示是否通过格式化函数处理
    • 8.B.2 检查所有空值是否兜底为 "--"
    • 需求: REQ-FMT-2, REQ-FMT-3, AC-FMT
  • 8.C 页面专属功能点
    • （T9.1 级别 Icon 已实现，无额外修改）

---

• 9. 【子代理】coach-detail 页面审查修改
  • 9.A 通用规则审查
    • （无 G1~G4 适用项）
  • 9.B 数据格式统一审查
    • 9.B.1 检查所有金额/课时/计数展示是否通过格式化函数处理
    • 9.B.2 检查所有空值是否兜底为 "--"
    • 需求: REQ-FMT-2, REQ-FMT-3, AC-FMT
  • 9.C 页面专属功能点
    • 9.C.1 T10.1 任务执行统计：修改 taskStats 从后端 API 获取，移除硬编码 { recall: 24, callback: 14 }
      • 需求: REQ-T10.1, AC-T10.1

---

• 10. 【子代理】customer-detail 页面审查修改
  • 10.A 通用规则审查
    • （无 G1~G4 适用项）
  • 10.B 数据格式统一审查
    • 10.B.1 检查所有金额/计数/时间展示是否通过格式化函数处理
    • 10.B.2 检查所有空值是否兜底为 "--"
    • 需求: REQ-FMT-2, REQ-FMT-3, AC-FMT
  • 10.C 页面专属功能点
    • （T8.1 电话已实现，无额外修改）

---

• 11. 【子代理】chat 页面审查修改
  • 11.A 通用规则审查
    • （无 G1~G4 适用项）
  • 11.B 数据格式统一审查
    • 11.B.1 检查所有时间展示是否通过格式化函数处理（消息时间、IM 时间）
    • 11.B.2 检查所有空值是否兜底
    • 需求: REQ-FMT-2, REQ-FMT-3, AC-FMT
  • 11.C 页面专属功能点
    • （RNS1.4 已完成 chat 改造，无额外 P13 功能点）

---

• 12. 【子代理】chat-history 页面审查修改
  • 12.A 通用规则审查
    • （无 G1~G4 适用项）
  • 12.B 数据格式统一审查
    • 12.B.1 检查所有时间展示是否通过格式化函数处理
    • 12.B.2 检查所有空值是否兜底
    • 需求: REQ-FMT-2, REQ-FMT-3, AC-FMT
  • 12.C 页面专属功能点
    • （RNS1.4 已完成 chat-history 改造，无额外 P13 功能点）

---

• 13. 【子代理】notes 页面审查修改
  • 13.A 通用规则审查
    • （无 G1~G4 适用项）
  • 13.B 数据格式统一审查
    • 13.B.1 检查所有时间展示是否通过格式化函数处理
    • 13.B.2 检查所有空值是否兜底
    • 需求: REQ-FMT-2, REQ-FMT-3, AC-FMT
  • 13.C 页面专属功能点
    • （无额外 P13 功能点）

---

• 14. 【子代理】my-profile 页面审查修改
  • 14.A 通用规则审查
    • 14.A.1 G1 微信头像：如页面展示头像，确认从全局用户信息读取
      • 需求: REQ-G1
  • 14.B 数据格式统一审查
    • 14.B.1 检查所有展示数据是否通过格式化函数处理
    • 14.B.2 检查所有空值是否兜底
    • 需求: REQ-FMT-2, REQ-FMT-3, AC-FMT
  • 14.C 页面专属功能点
    • （无额外 P13 功能点）

---

• 15. 【子代理】login / apply / reviewing / no-permission 页面审查修改
  • 15.A 通用规则审查
    • （无 G1~G4 适用项）
  • 15.B 数据格式统一审查
    • 15.B.1 检查所有展示数据是否通过格式化函数处理
    • 15.B.2 检查所有空值是否兜底
    • 需求: REQ-FMT-2, REQ-FMT-3, AC-FMT
  • 15.C 页面专属功能点
    • （无额外 P13 功能点，这四个页面为认证流程页，数据展示极少）

第二阶段：收尾验证

• 16. services/api.ts 接口字段对齐审查

  • 16.1 确认 fetchMe() 返回类型包含 avatarUrl、nickName、role、storeName
  • 16.2 确认 task 相关接口返回类型包含 abandonReason、customerPhone、actionSuggestions
  • 16.3 确认 performance-records 接口返回类型包含 totalCount、hoursRaw
  • 16.4 确认 customer 接口返回类型包含 totalServiceCount（无 as any）
  • 16.5 确认 coach-detail 接口返回类型包含 taskStats
  • 16.6 确认 board-finance 接口返回类型包含 aiInsights、isEstimated
  • 需求: 全部 REQ-T* 接口字段对齐

• 17. 最终检查点

  • 确认所有 15 个页面任务（任务 1~15）均已完成
  • 确认通用工具函数（任务 0）已就绪
  • 确认 services/api.ts 类型定义完整（任务 16）
  • 确认无硬编码 mock 数据残留
  • 确认所有空值展示为 "--"

执行规则

子代理调度

• 最大并行数：2 个子代理
• 每个子代理每次处理 1 个页面
• 子代理必须按 A → B → C 顺序审查每个页面
• 子代理需读取页面的 .ts、.wxml、.wxss 文件，以及相关的 WXS 文件

子代理审查清单（每个页面通用）

A. 通用规则审查

• G1：页面是否有 banner/头像区域？→ 检查 avatarUrl 来源
• G2：页面是否展示收入/金额标题？→ 检查 isCurrentMonth 判断
• G3：页面是否展示课时？→ 检查 hoursRaw vs hours 条件渲染
• G4：页面是否展示储值信息？→ 检查 formatStorageLevel 调用

B. 数据格式统一审查

• 金额：是否通过 formatMoney / WXS money() 处理？
• 计数：是否通过 formatCount / WXS count() 处理？
• 百分比：是否通过 formatPercent / WXS percent() 处理？
• 课时：是否通过 formatHours / WXS hours() 处理？
• 时间：是否通过 formatRelativeTime / formatDeadline / formatIMTime 处理？
• 空值：所有 null/undefined/0 是否通过 safe() 兜底为 "--"？
• 趋势值：是否通过 formatTrendValue 处理？

C. 页面专属功能点

• 对照 PRD 第二节该页面的功能点表格逐项检查
• 已标记 ✅ 的功能点仅做确认，不修改
• 未完成的功能点执行修改

参考文件清单（子代理必读）

• 目标页面的 .ts + .wxml + .wxss 文件
• apps/miniprogram/miniprogram/utils/money.ts — 金额格式化
• apps/miniprogram/miniprogram/utils/time.ts — 时间格式化
• apps/miniprogram/miniprogram/utils/format.wxs — WXS 格式化
• apps/miniprogram/miniprogram/utils/storage-level.ts — 储值等级（任务 0 新建）
• apps/miniprogram/miniprogram/services/api.ts — 接口定义
• docs/prd/specs/P13-miniapp-fe-polish.md — PRD 原文
• docs/miniprogram-dev/design-system/DISPLAY-STANDARDS.md — 展示规范