chore: 文档与 IDE 配置整理

- .kiro/specs/ → docs/specs/（41 个历史需求 spec 迁移，移除 .config.kiro） - CLAUDE.md 三层拆分：根文件精简 + apps/backend/CLAUDE.md + .claude/commands/ - 新增 /spec-close、/pre-change 两个工作流命令 - DDL 基线刷新（从测试库重新导出 11 个文件，dws 35→38 表，biz 18→21 表） - BD_Manual → BD_manual 命名统一（48 个文件） - 修复 3 处文档与数据库不一致（auth.users.status 默认值、scheduled_tasks 字段、RLS 视图数） - 新增 BD_manual_public_rbac_tables.md（public schema 8 张 RBAC/工作流表） - 合并 biz.trigger_jobs 文档（10→12 字段，归档独立文档） - docs/database/README.md 索引更新 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-06 00:02:37 +08:00
parent 8228b3fa37
commit 70324d8542
185 changed files with 13595 additions and 1219 deletions
--- a/docs/specs/p13-miniapp-fe-polish/tasks.md
+++ b/docs/specs/p13-miniapp-fe-polish/tasks.md
@@ -0,0 +1,320 @@
+# 实施计划：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`
+
+## 任务
+
+### 第零阶段：通用工具函数准备
+
+- [x] 0. 通用工具函数补充
+  - [x] 0.1 新建 `apps/miniprogram/miniprogram/utils/storage-level.ts`
+    - 导出 `formatStorageLevel(balance: number): string`
+    - 阈值：`= 0` → "无"、`< 200` → "少"、`< 500` → "一般"、`< 1500` → "多"、`≥ 1500` → "非常多"
+    - null/undefined 输入返回 "无"
+    - _需求: REQ-G4_
+  - [x] 0.2 修改 `apps/miniprogram/miniprogram/utils/money.ts`
+    - 新增 `formatTrendValue(value: number | null | undefined): string`
+    - 正数 → "+¥1,200"（千分位），负数 → "-¥800"，0/null/undefined → "--"
+    - _需求: REQ-FMT-1_
+  - [x] 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_
+  - [x] 0.4 修改 `apps/miniprogram/miniprogram/utils/format.wxs`
+    - 补充 WXS 侧对应函数（如需要在 WXML 中直接调用）
+    - _需求: REQ-FMT-1_
+
+### 第一阶段：逐页面审查修改（子代理并行，最大 2 个）
+
+每个页面任务包含三个审查维度，子代理必须按顺序逐一完成：
+- A. 通用规则审查（G1~G4 中适用于该页面的规则）
+- B. 数据格式统一审查（金额/计数/百分比/课时/时间/空值是否通过格式化函数处理）
+- C. 页面专属功能点修改（PRD 中该页面的具体需求）
+
+---
+
+- [x] 1. 【子代理】task-list 页面审查修改
+  - [x] 1.A 通用规则审查
+    - [x] 1.A.1 G1 微信头像：确认 `avatarUrl` 从全局用户信息读取并赋值到 data，无头像时显示默认占位图
+      - 检查 `task-list.ts` 中 `avatarUrl` 的赋值逻辑
+      - 检查 `task-list.wxml` 中头像 image 组件的 src 绑定和默认图
+      - _需求: REQ-G1, AC-G1.1, AC-G1.2_
+    - [x] 1.A.2 G2 当月预估：确认收入标题根据 isCurrentMonth 切换"预估收入"/"我的收入"
+      - 检查 TS 中是否有 `isCurrentMonth` 判断逻辑
+      - 检查 WXML 中"预估"标签的条件渲染
+      - _需求: REQ-G2, AC-G2.1_
+  - [x] 1.B 数据格式统一审查
+    - [x] 1.B.1 检查所有金额展示是否通过 `formatMoney` / WXS `money()` 处理
+    - [x] 1.B.2 检查所有计数展示是否通过 `formatCount` / WXS `count()` 处理
+    - [x] 1.B.3 检查所有空值是否通过 `safe()` 兜底为 "--"
+    - [x] 1.B.4 检查课时展示是否通过 `formatHours` / WXS `hours()` 处理
+    - _需求: REQ-FMT-2, REQ-FMT-3, AC-FMT_
+  - [x] 1.C 页面专属功能点
+    - [x] 1.C.1 T1.2 比同期数据：确认 `incomeTrend`/`incomeTrendDir` 从后端获取，使用 `formatTrendValue` 格式化展示，配合 ↑/↓ 箭头
+      - _需求: REQ-T1.2, AC-T1.2_
+    - [x] 1.C.2 T1.3 放弃原因：确认 `abandonReason` 从后端 task 对象获取，不再硬编码空字符串
+      - _需求: REQ-T1.3, AC-T1.3_
+    - [x] 1.C.3 T1.4 盖戳动画：修改为页面加载后始终播放，移除 `tierCompleted` 条件依赖
+      - _需求: REQ-T1.4, AC-T1.4_
+
+---
+
+- [x] 2. 【子代理】performance 页面审查修改
+  - [x] 2.A 通用规则审查
+    - [x] 2.A.1 G1 微信头像：确认 banner 区域 `avatarUrl` 从全局用户信息读取，无头像时显示默认占位图
+      - _需求: REQ-G1, AC-G1.1, AC-G1.2_
+    - [x] 2.A.2 G2 当月预估：确认收入标题根据 isCurrentMonth 切换"预估收入"/"我的收入"，"预估"标签条件渲染
+      - _需求: REQ-G2, AC-G2.1_
+  - [x] 2.B 数据格式统一审查
+    - [x] 2.B.1 检查所有金额展示是否通过格式化函数处理
+    - [x] 2.B.2 检查所有课时展示是否通过格式化函数处理
+    - [x] 2.B.3 检查所有百分比展示是否通过格式化函数处理
+    - [x] 2.B.4 检查所有空值是否兜底为 "--"
+    - _需求: REQ-FMT-2, REQ-FMT-3, AC-FMT_
+  - [x] 2.C 页面专属功能点
+    - （无额外专属功能点，T2.1/T2.2 已由 G1/G2 覆盖）
+
+---
+
+- [x] 3. 【子代理】performance-records 页面审查修改
+  - [x] 3.A 通用规则审查
+    - [x] 3.A.1 G1 微信头像：确认 banner 区域 `avatarUrl` 从全局用户信息读取
+      - _需求: REQ-G1, AC-G1.1_
+    - [x] 3.A.2 G2 当月预估：确认收入标题根据 isCurrentMonth 切换
+      - _需求: REQ-G2, AC-G2.1_
+    - [x] 3.A.3 G3 绩效折算：确认 `hoursRaw !== hours` 时展示"折前 Xh"灰色小字，无差异时不显示
+      - _需求: REQ-G3, AC-G3.1, AC-G3.2_
+  - [x] 3.B 数据格式统一审查
+    - [x] 3.B.1 检查所有金额/课时/计数/百分比展示是否通过格式化函数处理
+    - [x] 3.B.2 检查所有空值是否兜底为 "--"
+    - _需求: REQ-FMT-2, REQ-FMT-3, AC-FMT_
+  - [x] 3.C 页面专属功能点
+    - [x] 3.C.1 T3.3 总笔数：确认使用后端返回的 `totalCount` 字段，不再用 `records.length` 计算
+      - _需求: REQ-T3.3, AC-T3.3_
+
+---
+
+- [x] 4. 【子代理】task-detail 页面审查修改
+  - [x] 4.A 通用规则审查
+    - [x] 4.A.1 G4 储值等级：确认从 `detail.balance` 调用 `formatStorageLevel()` 计算等级文案并展示
+      - _需求: REQ-G4, AC-G4.1, AC-G4.2_
+  - [x] 4.B 数据格式统一审查
+    - [x] 4.B.1 检查所有金额展示是否通过格式化函数处理
+    - [x] 4.B.2 检查所有时间/日期展示是否通过格式化函数处理
+    - [x] 4.B.3 检查所有空值是否兜底为 "--"
+    - _需求: REQ-FMT-2, REQ-FMT-3, AC-FMT_
+  - [x] 4.C 页面专属功能点
+    - [x] 4.C.1 T4.1 手机号码：修改 `onCopyPhone` 从 `this.data.detail.customerPhone` 获取，不再硬编码空字符串
+      - _需求: REQ-T4.1, AC-T4.1_
+    - [x] 4.C.2 T4.3 行动建议：确认后端返回 `actionSuggestions: string[]`，前端在维客线索下方渲染为卡片列表
+      - _需求: REQ-T4.3, AC-T4.3_
+
+---
+
+- [x] 5. 【子代理】customer-service-records 页面审查修改
+  - [x] 5.A 通用规则审查
+    - （无 G1~G4 适用项）
+  - [x] 5.B 数据格式统一审查
+    - [x] 5.B.1 检查所有金额/计数/时间展示是否通过格式化函数处理
+    - [x] 5.B.2 检查所有空值是否兜底为 "--"
+    - _需求: REQ-FMT-2, REQ-FMT-3, AC-FMT_
+  - [x] 5.C 页面专属功能点
+    - [x] 5.C.1 T5.2 本月服务次数：补齐 `totalServiceCount` 的 TypeScript 类型定义，移除 `as any` 断言
+      - _需求: REQ-T5.2, AC-T5.2_
+    - [x] 5.C.2 T5.3 课程标签：修改 `getTypeLabel` 为基于 `courseType` 枚举的直接映射，移除 includes 硬编码匹配
+      - _需求: REQ-T5.3, AC-T5.3_
+
+---
+
+- [x] 6. 【子代理】board-finance 页面审查修改
+  - [x] 6.A 通用规则审查
+    - [x] 6.A.1 G2 当月预估：确认本月时间筛选时，经营一览标题含"预估"字样
+      - _需求: REQ-G2, AC-G2.2_
+  - [x] 6.B 数据格式统一审查
+    - [x] 6.B.1 检查所有金额展示是否通过格式化函数处理
+    - [x] 6.B.2 检查所有百分比/计数展示是否通过格式化函数处理
+    - [x] 6.B.3 检查所有空值是否兜底为 "--"
+    - _需求: REQ-FMT-2, REQ-FMT-3, AC-FMT_
+  - [x] 6.C 页面专属功能点
+    - [x] 6.C.1 T6.1 AI 智能洞察：修改 WXML 移除硬编码文案，改为从后端 `aiInsights: Array<{ icon: string; text: string }>` 动态渲染
+      - _需求: REQ-T6.1, AC-T6.1_
+
+---
+
+- [x] 7. 【子代理】board-customer 页面审查修改
+  - [x] 7.A 通用规则审查
+    - （无 G1~G4 适用项）
+  - [x] 7.B 数据格式统一审查
+    - [x] 7.B.1 检查所有金额/计数/百分比展示是否通过格式化函数处理
+    - [x] 7.B.2 检查所有空值是否兜底为 "--"
+    - _需求: REQ-FMT-2, REQ-FMT-3, AC-FMT_
+  - [x] 7.C 页面专属功能点
+    - （T7.1 爱心 icon 已实现，无额外修改）
+
+---
+
+- [x] 8. 【子代理】board-coach 页面审查修改
+  - [x] 8.A 通用规则审查
+    - （无 G1~G4 适用项）
+  - [x] 8.B 数据格式统一审查
+    - [x] 8.B.1 检查所有金额/计数/课时展示是否通过格式化函数处理
+    - [x] 8.B.2 检查所有空值是否兜底为 "--"
+    - _需求: REQ-FMT-2, REQ-FMT-3, AC-FMT_
+  - [x] 8.C 页面专属功能点
+    - （T9.1 级别 Icon 已实现，无额外修改）
+
+---
+
+- [x] 9. 【子代理】coach-detail 页面审查修改
+  - [x] 9.A 通用规则审查
+    - （无 G1~G4 适用项）
+  - [x] 9.B 数据格式统一审查
+    - [x] 9.B.1 检查所有金额/课时/计数展示是否通过格式化函数处理
+    - [x] 9.B.2 检查所有空值是否兜底为 "--"
+    - _需求: REQ-FMT-2, REQ-FMT-3, AC-FMT_
+  - [x] 9.C 页面专属功能点
+    - [x] 9.C.1 T10.1 任务执行统计：修改 `taskStats` 从后端 API 获取，移除硬编码 `{ recall: 24, callback: 14 }`
+      - _需求: REQ-T10.1, AC-T10.1_
+
+---
+
+- [x] 10. 【子代理】customer-detail 页面审查修改
+  - [x] 10.A 通用规则审查
+    - （无 G1~G4 适用项）
+  - [x] 10.B 数据格式统一审查
+    - [x] 10.B.1 检查所有金额/计数/时间展示是否通过格式化函数处理
+    - [x] 10.B.2 检查所有空值是否兜底为 "--"
+    - _需求: REQ-FMT-2, REQ-FMT-3, AC-FMT_
+  - [x] 10.C 页面专属功能点
+    - （T8.1 电话已实现，无额外修改）
+
+
+---
+
+- [x] 11. 【子代理】chat 页面审查修改
+  - [x] 11.A 通用规则审查
+    - （无 G1~G4 适用项）
+  - [x] 11.B 数据格式统一审查
+    - [x] 11.B.1 检查所有时间展示是否通过格式化函数处理（消息时间、IM 时间）
+    - [x] 11.B.2 检查所有空值是否兜底
+    - _需求: REQ-FMT-2, REQ-FMT-3, AC-FMT_
+  - [x] 11.C 页面专属功能点
+    - （RNS1.4 已完成 chat 改造，无额外 P13 功能点）
+
+---
+
+- [x] 12. 【子代理】chat-history 页面审查修改
+  - [x] 12.A 通用规则审查
+    - （无 G1~G4 适用项）
+  - [x] 12.B 数据格式统一审查
+    - [x] 12.B.1 检查所有时间展示是否通过格式化函数处理
+    - [x] 12.B.2 检查所有空值是否兜底
+    - _需求: REQ-FMT-2, REQ-FMT-3, AC-FMT_
+  - [x] 12.C 页面专属功能点
+    - （RNS1.4 已完成 chat-history 改造，无额外 P13 功能点）
+
+---
+
+- [x] 13. 【子代理】notes 页面审查修改
+  - [x] 13.A 通用规则审查
+    - （无 G1~G4 适用项）
+  - [x] 13.B 数据格式统一审查
+    - [x] 13.B.1 检查所有时间展示是否通过格式化函数处理
+    - [x] 13.B.2 检查所有空值是否兜底
+    - _需求: REQ-FMT-2, REQ-FMT-3, AC-FMT_
+  - [x] 13.C 页面专属功能点
+    - （无额外 P13 功能点）
+
+---
+
+- [x] 14. 【子代理】my-profile 页面审查修改
+  - [x] 14.A 通用规则审查
+    - [x] 14.A.1 G1 微信头像：如页面展示头像，确认从全局用户信息读取
+      - _需求: REQ-G1_
+  - [x] 14.B 数据格式统一审查
+    - [x] 14.B.1 检查所有展示数据是否通过格式化函数处理
+    - [x] 14.B.2 检查所有空值是否兜底
+    - _需求: REQ-FMT-2, REQ-FMT-3, AC-FMT_
+  - [x] 14.C 页面专属功能点
+    - （无额外 P13 功能点）
+
+---
+
+- [x] 15. 【子代理】login / apply / reviewing / no-permission 页面审查修改
+  - [x] 15.A 通用规则审查
+    - （无 G1~G4 适用项）
+  - [x] 15.B 数据格式统一审查
+    - [x] 15.B.1 检查所有展示数据是否通过格式化函数处理
+    - [x] 15.B.2 检查所有空值是否兜底
+    - _需求: REQ-FMT-2, REQ-FMT-3, AC-FMT_
+  - [x] 15.C 页面专属功能点
+    - （无额外 P13 功能点，这四个页面为认证流程页，数据展示极少）
+
+### 第二阶段：收尾验证
+
+- [x] 16. services/api.ts 接口字段对齐审查
+  - [x] 16.1 确认 `fetchMe()` 返回类型包含 `avatarUrl`、`nickName`、`role`、`storeName`
+  - [x] 16.2 确认 task 相关接口返回类型包含 `abandonReason`、`customerPhone`、`actionSuggestions`
+  - [x] 16.3 确认 performance-records 接口返回类型包含 `totalCount`、`hoursRaw`
+  - [x] 16.4 确认 customer 接口返回类型包含 `totalServiceCount`（无 `as any`）
+  - [x] 16.5 确认 coach-detail 接口返回类型包含 `taskStats`
+  - [x] 16.6 确认 board-finance 接口返回类型包含 `aiInsights`、`isEstimated`
+  - _需求: 全部 REQ-T* 接口字段对齐_
+
+- [x] 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` — 展示规范