feat: batch update - gift card breakdown spec, backend APIs, miniprogram pages, ETL finance recharge, docs & migrations

apps/DEMO-miniprogram/miniprogram/pages/performance/MIGRATION_NOTES.md

@@ -0,0 +1,297 @@
+# Performance 页面迁移说明
+
+## 迁移版本
+- **H5 原型基准**：`docs/h5_ui/pages/performance.html`
+- **桥文档版本**：v3.0
+- **迁移日期**：2026-03-15
+- **更新日期**：2026-03-15（Banner背景改用灵活的SVG实现）
+
+---
+
+## 样式调整清单
+
+### 1. 单位转换规则
+遵循桥文档 §2.3 的混合单位策略：
+- **主要使用 `rpx`**：页面宽度、横向布局、卡片尺寸、间距
+- **使用 `px`**：导航栏高度（44px）、图标点击区域
+- **换算基准**：H5 CSS px → 小程序 rpx（750宽基准，1px = 1.8204rpx）
+
+### 2. 自定义导航栏（.custom-nav）
+
+| 属性 | H5 值 | 小程序值 | 说明 |
+|------|------|--------|------|
+| height | 44px | 44px | 标准导航栏高度（使用px） |
+| font-size | text-base (16px) | 32rpx | 标题字号 |
+| icon size | w-5 h-5 (20px) | 24px | 返回按钮图标 |
+
+### 3. Banner 区域（.banner-section）
+
+| 属性 | H5 值 | 小程序值 | 说明 |
+|------|------|--------|------|
+| 背景方案 | CSS 渐变 | SVG 图片 | 使用 `/assets/images/banner-bg-combined.svg` |
+| height | - | 480rpx | Banner 高度（可通过 WXSS 调整） |
+| padding | px-5 pt-2 pb-2 (20px 8px) | 24rpx 40rpx 32rpx | 内容区内边距 |
+
+#### Banner SVG 背景实现（灵活可调）
+- **方案**：SVG 做渐变底图（与 task-detail/task-list 保持一致）
+- **原因**：SVG pattern 在小程序 image 组件中不渲染
+- **WXML 实现**：
+  ```wxml
+  <view class="banner-section">
+    <image class="banner-bg-img" src="/assets/images/banner-bg-combined.svg" mode="aspectFill" />
+    <view class="banner-content">
+      <!-- 内容 -->
+    </view>
+  </view>
+  ```
+- **WXSS 实现**（可灵活调整）：
+  ```wxss
+  .banner-section {
+    position: relative;
+    width: 100%;
+    overflow: hidden;
+    height: 480rpx;  /* 调整此值改变 Banner 高度 */
+  }
+  
+  .banner-bg-img {
+    position: absolute;
+    top: 0;      /* 调整此值改变背景垂直位置 */
+    left: 0;     /* 调整此值改变背景水平位置 */
+    width: 100%;
+    height: 100%;
+    z-index: 0;
+  }
+  
+  .banner-content {
+    position: relative;
+    z-index: 2;
+    padding: 24rpx 40rpx 32rpx;  /* 调整此值改变内容区内边距 */
+    height: 100%;
+    display: flex;
+    flex-direction: column;
+  }
+  ```
+- **调整方式**：
+  - 修改 `.banner-section` 的 `height` 调整 Banner 高度
+  - 修改 `.banner-bg-img` 的 `top/left` 调整背景位置
+  - 修改 `.banner-bg-img` 的 `width/height` 调整背景缩放
+  - 修改 `.banner-content` 的 `padding` 调整内容区域
+
+#### 个人信息卡片
+| 属性 | H5 值 | 小程序值 | 说明 |
+|------|------|--------|------|
+| avatar size | w-14 h-14 (56px) | 112rpx | 头像尺寸 |
+| avatar radius | rounded-2xl (16px) | 24rpx | 头像圆角 |
+| name font-size | text-xl (20px) | 40rpx | 姓名字号 |
+| role tag padding | px-2 py-0.5 (8px 2px) | 4rpx 16rpx | 角色标签内边距 |
+
+#### 收入概览卡片
+| 属性 | H5 值 | 小程序值 | 说明 |
+|------|------|--------|------|
+| grid gap | gap-3 (12px) | 24rpx | 卡片间距 |
+| card padding | p-4 (16px) | 24rpx | 卡片内边距 |
+| card radius | rounded-xl (12px) | 24rpx | 卡片圆角 |
+| label font-size | text-xs (12px) | 22rpx | 标签字号 |
+| value font-size | text-2xl (24px) | 44rpx | 数值字号 |
+
+### 4. Section 卡片（.section-card）
+
+| 属性 | H5 值 | 小程序值 | 说明 |
+|------|------|--------|------|
+| border-radius | rounded-2xl (16px) | 32rpx | 卡片圆角 |
+| padding | p-4 (16px) | 32rpx | 卡片内边距 |
+| margin | m-4 (16px) | 24rpx 24rpx 0 | 卡片外边距 |
+| box-shadow | shadow-sm | 0 1px 2px rgba(0,0,0,0.05) | 阴影 |
+
+### 5. 收入档位卡片（.tier-card）
+
+| 属性 | H5 值 | 小程序值 | 说明 |
+|------|------|--------|------|
+| padding | p-3 (12px) | 24rpx | 内边距 |
+| border-radius | rounded-xl (12px) | 24rpx | 圆角 |
+| border | 1px solid | 2rpx solid | 边框 |
+| emoji size | text-2xl (24px) | 48rpx | 表情图标 |
+| rate value | text-lg (18px) | 36rpx | 费率数值 |
+| rate unit | text-xs (12px) | 22rpx | 单位字号 |
+| rate desc | text-[10px] | 20rpx | 描述字号 |
+
+#### 档位徽章
+| 属性 | H5 值 | 小程序值 | 说明 |
+|------|------|--------|------|
+| top | -8px | -16rpx | 顶部偏移 |
+| padding | 2px 10px | 4rpx 20rpx | 内边距 |
+| font-size | 10px | 20rpx | 字号 |
+
+### 6. 升级提示（.upgrade-hint）
+
+| 属性 | H5 值 | 小程序值 | 说明 |
+|------|------|--------|------|
+| padding | p-3 (12px) | 24rpx | 内边距 |
+| border-radius | rounded-xl (12px) | 24rpx | 圆角 |
+| emoji size | text-lg (18px) | 36rpx | 表情大小 |
+| label font-size | text-xs (12px) | 22rpx | 标签字号 |
+| hours font-size | text-sm (14px) | 26rpx | 小时数字号 |
+| bonus value | text-lg (18px) | 36rpx | 奖金数值 |
+
+### 7. 业绩明细列表（.income-list）
+
+| 属性 | H5 值 | 小程序值 | 说明 |
+|------|------|--------|------|
+| icon box size | w-8 h-8 (32px) | 64rpx | 图标容器 |
+| icon box radius | rounded-lg (8px) | 16rpx | 图标圆角 |
+| label font-size | text-sm (14px) | 26rpx | 标签字号 |
+| desc font-size | text-[10px] | 20rpx | 描述字号 |
+| value font-size | text-base (16px) | 30rpx | 数值字号 |
+| total value | text-xl (20px) | 40rpx | 合计数值 |
+
+### 8. 服务记录（.service-records-section）
+
+| 属性 | H5 值 | 小程序值 | 说明 |
+|------|------|--------|------|
+| avatar size | w-[38px] h-[38px] | 76rpx | 头像尺寸 |
+| avatar radius | rounded-lg (8px) | 16rpx | 头像圆角 |
+| name font-size | text-sm (14px) | 26rpx | 姓名字号 |
+| time font-size | text-xs (12px) | 22rpx | 时间字号 |
+| hours font-size | text-sm (14px) | 26rpx | 小时数字号 |
+| tag padding | px-1.5 py-px (6px 1px) | 2rpx 12rpx | 标签内边距 |
+| tag font-size | text-[11px] | 22rpx | 标签字号 |
+
+#### 日期分隔线
+| 属性 | H5 值 | 小程序值 | 说明 |
+|------|------|--------|------|
+| date font-size | 11px | 22rpx | 日期字号 |
+| line height | 1px | 2rpx | 分隔线高度 |
+| padding | 14px 16px 4px | 20rpx 0 8rpx | 内边距 |
+
+### 9. 客户列表（.customer-list）
+
+| 属性 | H5 值 | 小程序值 | 说明 |
+|------|------|--------|------|
+| avatar size | w-[38px] h-[38px] | 76rpx | 头像尺寸 |
+| avatar radius | rounded-lg (8px) | 16rpx | 头像圆角 |
+| name font-size | text-sm (14px) | 26rpx | 姓名字号 |
+| detail font-size | text-xs (12px) | 22rpx | 详情字号 |
+| icon size | - | 24px | 右侧箭头图标 |
+
+### 10. 颜色映射（附录C）
+
+| 用途 | 色值 | 说明 |
+|------|------|------|
+| 主品牌色 | #0052d9 | primary |
+| 成功色 | #00a870 | success |
+| 背景色 | #f3f3f3 | gray-1 |
+| 正文色 | #242424 | gray-13 |
+| 次级文字 | #a6a6a6 | gray-6 |
+| 三级文字 | #8b8b8b | gray-7 |
+| 四级文字 | #c5c5c5 | gray-5 |
+| 分割线 | #f3f3f3 | gray-1 |
+
+### 11. 渐变色系统
+
+#### 头像渐变（8种）
+- `from-blue`: #60a5fa → #6366f1
+- `from-pink`: #f472b6 → #f43f5e
+- `from-teal`: #2dd4bf → #10b981
+- `from-green`: #4ade80 → #14b8a6
+- `from-orange`: #fb923c → #f59e0b
+- `from-purple`: #c084fc → #8b5cf6
+- `from-violet`: #a78bfa → #7c3aed
+- `from-amber`: #fbbf24 → #eab308
+
+#### 档位卡片渐变
+- 当前档位：#f0fdf4 → #dcfce7（绿色系）
+- 下一阶段：#fefce8 → #fef9c3（黄色系）
+- 升级提示：#eff6ff → #eef2ff（蓝色系）
+- 奖金按钮：#fbbf24 → #f97316（橙色系）
+
+---
+
+## 关键调整点
+
+### 1. 全局 line-height 设置
+```wxss
+page {
+  line-height: 1.5;
+}
+
+view {
+  line-height: inherit;
+}
+```
+**原因**：微信小程序 `<text>` 组件不能直接设置 `line-height`，必须在外层 `<view>` 设置（附录B.2.3）
+
+### 2. 单位统一为 rpx（除特殊情况）
+- 主要尺寸使用 `rpx`，确保不同设备自适应
+- 导航栏高度、图标点击区域使用 `px`
+- 换算公式：1px = 1.8204rpx（750宽基准）
+
+### 3. 移除 CSS 变量依赖
+- 原：`var(--color-gray-2, #eeeeee)`
+- 新：直接使用 `#eeeeee`
+- 原因：确保样式独立，不依赖全局变量
+
+### 4. Icon 尺寸调整
+- 导航栏返回按钮：`size="24px"`（标准点击区域）
+- 列表箭头图标：`size="24px"`
+- 加载/错误图标：`size="40px"`
+
+### 5. 复杂背景还原
+- **Banner 背景**：使用 SVG 图片 `/assets/images/banner-bg-combined.svg`（与 task-detail/task-list 保持一致）
+  - 原因：SVG pattern 在小程序 image 组件中不渲染
+  - **灵活可调**：通过 WXSS 可调整 Banner 高度、背景位置、内容区内边距
+- 档位卡片使用双色渐变背景
+- 头像使用 8 种预设渐变色
+- 升级提示使用渐变背景 + 渐变按钮
+
+### 6. 数值字体特性
+```wxss
+.perf-value {
+  font-variant-numeric: tabular-nums;
+}
+```
+确保数字等宽对齐
+
+---
+
+## 验收清单
+
+- [x] 导航栏高度与H5对齐（44px）
+- [x] Banner SVG背景与H5对齐
+- [x] Banner 高度可通过 WXSS 调整（480rpx）
+- [x] Banner 背景位置可通过 WXSS 调整
+- [x] 个人信息卡片尺寸与H5对齐
+- [x] 收入概览卡片样式与H5对齐
+- [x] 档位卡片渐变背景与H5对齐
+- [x] 档位徽章位置与H5对齐
+- [x] 升级提示样式与H5对齐
+- [x] 业绩明细列表与H5对齐
+- [x] 服务记录样式与H5对齐
+- [x] 日期分隔线与H5对齐
+- [x] 客户列表样式与H5对齐
+- [x] 头像渐变色与H5对齐
+- [x] 所有字号与H5对齐
+- [x] 所有间距与H5对齐
+- [x] 所有圆角与H5对齐
+- [x] 所有颜色与H5对齐
+- [x] 行高设置正确（在view上设置）
+- [x] Banner背景使用灵活的SVG实现（与task-detail保持一致）
+
+---
+
+## 已知限制
+
+1. **动画效果**：H5 中的 `bonus-highlight` 闪烁动画未实现（需要 CSS animation）
+2. **backdrop-filter**：收入卡片的 `backdrop-blur` 效果在部分安卓设备可能不支持
+3. **SVG兼容性**：banner-bg-combined.svg 需要确保存在于 `/assets/images/` 目录
+
+---
+
+## 后续维护
+
+- 若真机测试发现尺寸偏差，优先检查 line-height 设置
+- 若需要调整 Banner 高度，修改 `.banner-section` 的 `height` 属性
+- 若需要调整 Banner 背景位置，修改 `.banner-bg-img` 的 `top/left` 属性
+- 若需要调整间距，参考附录A的spacing表
+- 若需要调整字号，参考附录B的字体表
+- 颜色调整参考附录C的颜色字典
+- Banner背景问题参考task-detail页面的实现方式